Manual SSH Setup

Manual mode is for servers where you cannot install nokkud, or where you want to integrate the core into your own provisioning system. It uses standard OpenSSH certificate configuration on the system sshd.

Unlike daemon-managed targets, which are served by nokkud’s embedded SSH server on port 4022, manual targets keep using the system sshd. The system sshd on port 22 is never touched by nokkud.

Requirements

• Root access to the target server.
• An SSH certificate authority public key from the workspace.
• The Nokku user UUIDs that should be allowed to log in.
• A manually created target with a reachable endpoint and a target ID.

Configure sshd

Copy the SSH CA public key to the target, for example:

sudo install -d -m 755 /etc/ssh/auth_principals
sudo tee /etc/ssh/nokku_ca.pub >/dev/null <<'EOF'
ssh-ed25519 AAAA...
EOF

Add a drop-in or equivalent settings to sshd_config:

TrustedUserCAKeys /etc/ssh/nokku_ca.pub
AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

The %u value is the requested Linux username.

Add authorized principals

Create one file per Linux username. Put one Nokku user UUID per line:

sudo tee /etc/ssh/auth_principals/ubuntu >/dev/null <<'EOF'
<USER-UUID>
EOF

The UUID is the principal embedded in the user’s SSH certificate. It is not the Linux username.

Validate and reload

sudo sshd -t
sudo systemctl reload sshd

Some distributions use the service name ssh instead:

sudo systemctl reload ssh

Limitations

Manual mode does not receive principal updates automatically. You can maintain AuthorizedPrincipalsFile yourself, or automate target synchronization and certificate handling with the core API.

Manual mode does not obtain host certificates automatically. You can configure normal SSH host verification, or use the signing endpoint to obtain a host certificate for the target.