Skip to content
    OpafraDocs

    SSH credentials

    Generate a key in Opafra, install its public half, and attach it to as many servers as you like. The private half is shown once and never again.

    View as MarkdownOpen in ClaudeOpen in ChatGPT

    An SSH key in Opafra is a named, reusable object. Create prod-deploy once, attach it to twenty servers, and rotate it in one place.

    Generating a key is the default and importing one you already have is supported. The difference matters more than it looks.

    Before you begin#

    You need the Operator role or above to create or import an SSH key.

    Generate rather than upload#

    Uploading an existing key usually means uploading the key you already use, which is usually your personal one. That key opens everything it was ever trusted for, and now a copy of its private half has travelled from your laptop, through a browser, to a server.

    A generated key starts with no trust at all. You decide which hosts accept it, and revoking it affects exactly those hosts and nothing else.

    1. Create the key#

    Open Inventory, then SSH keys, and choose Generate key. Give it a name that says what it is for, because the name is what you will pick from when registering servers.

    Opafra generates an Ed25519 keypair, keeps the private half encrypted, and shows you:

    • The public key, to install on your hosts
    • The authorized_keys line, ready to paste
    • The private key, once

    You do not need to save the private key at all if Opafra is the only thing using it, which is the common case. Save it only if you also need to connect with it yourself.

    2. Install the public half#

    Any way you already distribute keys works. The line is ordinary and nothing about it is Opafra-specific:

    on your machine
    ssh-copy-id -i ./opafra-prod-deploy.pub [email protected]

    For a fleet, put the line in your image, your cloud-init template, or whatever configuration management already manages authorized_keys.

    3. Attach it to servers#

    When registering or editing a server, pick the key by name. One key can serve any number of servers, which is the point: the alternative is a credential per host and no way to rotate them together.

    Setting a key clears any other credential on that server, so there is never ambiguity about which one is live.

    Importing a key you already have#

    Some teams have a provisioning key already trusted across a fleet, and re-keying everything to adopt Opafra is not reasonable. Import is there for that.

    Two things happen on import that are worth knowing:

    • The public half is re-derived from the private key rather than trusted from what you paste. Pairing private-A with public-B would otherwise misrepresent what you are authorising on a host.
    • A duplicate is rejected by fingerprint, so the same key cannot quietly exist twice under two names.

    Passphrase-protected keys are not supported. Storing the passphrase alongside the key it protects is theatre, so Opafra declines rather than pretending. Remove it first:

    ssh-keygen -p -f ./id_ed25519

    Deleting a key#

    A key in use cannot be deleted. Opafra names the servers still using it and refuses, rather than leaving those servers with no credential and an authentication failure discovered mid-run.

    Detach it from those servers first, then delete.

    Rotating#

    Generate the new key, install its public half alongside the old one, move servers to it, then remove the old public half from the hosts and delete the old key.

    Doing it in that order means no window where a host trusts neither key. The reusable-key model is what makes this a handful of steps rather than one per host.

    The other credential types#

    Keys are the common case. Servers can also authenticate by password, by SSH certificate from a CA you run, or through Vault SSH. All four are described under registering servers.

    Whichever you use, the credential is stored encrypted or as a reference, and never appears in a plan, a log, or an API response.

    Verify it worked#

    Open Inventory, then SSH keys. The key is listed with its type and fingerprint, and the server you attached it to shows a key-count of at least one:

    ssh keys
    prod-deploy    ed25519    SHA256:9f2a...c41d    2 servers

    Then open one of those servers and run its connection check. auth accepted passing is the proof the public half is installed correctly on that host.

    Next steps#