Registering servers

Registering a server tells Opafra how to reach a host: its address, the user to connect as, and which credential to use. Nothing is installed on the machine, and the host does not need to know it has been registered until the first connection.

Before you begin#

You need the Operator role or above to register a server.

• A hostname or IP that resolves from where Opafra runs, and an SSH port
• A user account on the host
• A credential that user can authenticate with

If the account needs elevated privilege for the plans you intend to run, it also needs sudo that does not prompt for a password. A run cannot answer a password prompt.

1. Add the server#

Open Inventory, choose Add server, and fill in the name, host, user and port. The name is how plans refer to the host, so it is worth making it the name your team already uses rather than the raw address.

Then choose how it authenticates. There are four methods:

2. Install the public half#

A managed key is generated as a keypair. Opafra keeps the private half; you install the public half on the host, the same way you would for any other key:

ssh-copy-id -i ~/Downloads/opafra-prod-deploy.pub [email protected]

Or append the authorized_keys line Opafra shows you directly, if you already have a way to push files to the host. Configuration management, a cloud-init template and a golden image all work: the line is ordinary and there is nothing Opafra-specific about it.

3. Read the connection check#

Saving a server runs a connection check immediately. It walks five stages in order and reports each one, so a failure names the thing that actually broke rather than saying the host is down:

The first three are hard failures and stop the walk. Sudo and facts are warnings: a server that cannot sudo is still registered and still usable, because plenty of plans never need it. Later stages that never ran are shown greyed rather than hidden, so the ladder always has the same shape.

The whole check is capped at 30 seconds, so a hung host fails rather than hanging the page.

The check also reads current host metrics: CPU, memory and disk usage, and the one, five and fifteen minute load averages. They are stored against the server and shown on it, so a connection check doubles as a snapshot of how the machine is doing. Any alert rules you have are evaluated against those numbers at the same time.

Hosts you cannot reach directly#

A host on a private network can name another registered server as its bastion, and Opafra connects through it. The bastion is itself a normal server in your inventory with its own credential.

Chains are allowed up to three hops. Beyond that Opafra refuses the configuration rather than attempting it, as does a chain that loops back on itself. If a connection check reports that the bastion was unreachable, the target may be perfectly healthy: what failed is the path to it.

An environment can also name a default bastion, which every host in it uses unless it names its own. That is usually the right way to configure a whole private subnet once instead of per host.

What Opafra stores#

The address, port, user, which credential to use, and what the last connection check observed. Credentials are stored encrypted or as references to a secret provider. A private key never appears in a plan, a command, a log, or an API response.

Verify it worked#

Open Inventory. The server appears in the list with a green status dot and its detected OS family. Open it and the connection check shows all five stages:

DNS resolves          ok
TCP :22 reachable     ok
auth accepted         ok
sudo available        ok
facts gathered        ok

sudo available and facts gathered may report a warning without the server being unusable. The first three must pass, or the host is not reachable and the server cannot run anything.

Next steps#

• Agentless SSH for what Opafra needs on the host, exactly
• Environments for grouping hosts and attaching policy