Documentation

Pelican

Pelican runs your game servers: an egg describes what a server is built from, a node carries it, an allocation gives it its address. Provibr reaches it from an agent inside your own network, so the panel needs no inbound port and nothing is installed on it.

Two API keys

Pelican has two APIs with two different keys, and Provibr needs both. They come from two different screens, and both must belong to an account with administrator rights.

The application key, from Admin → API Keys. It starts with papp_ and manages servers: create, suspend, reinstall, delete. Give it read and write access to Server, Node, Allocation, User and Egg.
The client key, from your own Profile → API Keys. It starts with pacc_ and carries power commands, live usage figures and the console.

Copy the client key the moment it appears. Pelican shows it once and the list keeps only a short identifier afterwards. That identifier is accepted as a key, so pasting it gives you a plain authentication error rather than a hint that you copied the wrong thing. The application key can be read back from the list in full.

There is no command-line alternative: Pelican ships no artisan command for API keys, so both are created through the web interface.

What you fill in

Four fields, and only the last one is optional.

The address of the panel, for example https://panel.example.com. Add a port only if the panel really runs on one; behind a reverse proxy it answers on the default port of its scheme.
The application key starting with papp_.
The client key starting with pacc_.
The TLS fingerprint of the panel, needed only when its certificate is self-signed.

Mind which key goes in which field. Pelican accepts a client key on the management API as well, so swapping the two does not produce an error you can see. The prefix is the only thing that tells them apart, and Provibr checks it on both sides for exactly that reason.

Self-signed certificate

If the panel presents a self-signed certificate, fill in its fingerprint. The agent then trusts that one certificate instead of turning verification off. Read it with:

shell

openssl s_client -connect <host>:443 </dev/null 2>/dev/null | \
  openssl x509 -noout -fingerprint -sha256

Commands and terminal output are in English everywhere, in the panel and in these pages. One text, one truth: what you read here is literally what your host will print back.

Leave the field empty for a certificate from a public authority, and also when the panel is reachable over http only. A fingerprint next to an http address is refused, because there is no certificate to pin. A panel on plain http does work, but both keys then travel unencrypted over your network.

Eggs and their variables

A server is built from an egg: a Docker image, a start command and a set of variables the egg defines itself. Provibr reads the list from your panel, so the order form offers the eggs you actually have instead of asking for a number.

Provibr refuses an order when a variable the egg marks as required is left empty, even though the panel itself would accept it. That is deliberate: Pelican creates the server anyway and the container then crashes on its first start, which is a much worse answer than a field that turns red.

Plans

A game plan holds the egg, the image, the start command and the limits a server gets. Link it to one or more Pelican integrations and it becomes orderable.

Memory, disk and CPU accept 0 for unlimited, and the CPU limit counts in percent of one core: 100 is one full core, 200 is two. The IO weight runs from 0 to 1000 and 500 is the usual value.

Which node a server lands on

Pelican reports how much memory and how much CPU each node has, and how much of it is already handed out. Provibr uses both: a new server goes to a node with room for it, and is refused with a reason when no node has any.

The figures the panel reports are its own bookkeeping, not a measurement: they add up the limits of the servers on a node, including ones that are still installing. A node can therefore look full while little is actually running.

What you can do with a server

The whole life of a game server, from the panel or through the API:

Create it from a plan, and remove it when the customer leaves.
Start, stop, restart and kill it.
Suspend and unsuspend it. This is also what happens automatically when an account goes over its limit.
Reinstall it, which runs the installation script of its egg again.

The console

A game server is driven from its console: commands, players, and the log line that explains a crash. It runs in the panel over the same outbound connection as everything else, so there is no separate port and no second login.

Servers that are already there

Servers you created outside Provibr are left alone. You can import them so they appear in the panel and count towards your capacity, which is the way to move an existing panel across without rebuilding anything.

Importing does not touch the server; it only starts counting it. Until you import it, Provibr will neither manage nor charge for it.

What this integration does not do

Files, backups, databases and schedules stay in the Pelican panel, and so does managing the panel and its nodes themselves. Provibr covers the life of a server and its console, not the administration of your panel.

Pelican is itself still in beta and its API changes between releases. Provibr is tested against 1.0.0, and the panel offers no way to ask which version it runs, so an upgrade that changes an answer shows up as an error rather than as a warning beforehand. Read the release notes before upgrading a panel Provibr talks to.

PreviousPterodactyl NextPufferPanel