This guide adds a Linux server to Nokku with nokkud, the Nokku daemon. It’s the recommended way: access changes reach the server right away, sessions can be recorded, and the server can be reached without opening ports. Can’t install software on a server? See Servers without the daemon.
What the daemon does
nokkud runs its own small SSH server on port 4022, next to your normal sshd. It checks Nokku certificates, keeps the list of who may log in, and runs each session as the right Linux user.
Your system sshd on port 22 is never touched. It keeps working exactly as before, as a way back in if you ever need one.
Install
On the server:
curl -fsSL https://get.nokku.sh/nokkud | sudo sh
The installer uses your distro’s package when it can. Manual installs are covered in the nokkud README.
Enroll
In the web app, open Servers and enroll a server. That creates an enroll token and needs the admin role. The web app shows the commands with your address filled in, so copy them from there:
sudo nokkud --api https://nokku.example.com enroll # paste the token, it is not shown
sudo systemctl restart nokkud
The server appears in your workspace under its hostname. You can rename it in the web app. Unless the token approves servers automatically, someone with the editor role or higher approves it there first.
More about enroll tokens
- Many servers, one token: one token can enroll a whole fleet. You can give it an expiry or a limit on how many servers it may add.
- Grants on the token: a token can carry Linux accounts and who may use them, plus tags. Every server it enrolls starts with them. They are copied once, and what you change under the server later stays.
- Unattended installs: set
NOKKUD_ENROLL_TOKENin the environment instead of answering the prompt. The service enrolls itself on start when the variable is set and nothing is enrolled yet. The token is never accepted as a command-line argument, because other users on the machine could read it there. - Names: a default hostname from a cloud image, like
ip-10-0-1-23, gets a readable generated name instead. - Enrolling again is safe. Enrolling in another workspace moves the server there and drops everything the old workspace trusted.
- Containers are covered in SSH into containers.
Network
Nokku sessions reach the server in one of two ways, and nk tries both at once:
- Through the relay. Works out of the box. The daemon keeps an outbound connection to the core, and sessions travel over it, encrypted end to end. Nothing needs to be opened.
- Directly on port
4022. Faster. Open it for the networks your users connect from:
sudo ufw allow nokkudsudo firewall-cmd --permanent --add-service=nokkud
sudo firewall-cmd --reloadOn cloud servers, also allow TCP 4022 in the provider’s firewall or security group.
Restarts and upgrades
A restart ends the sessions that are open on the daemon. A package upgrade is gentler: under systemd the daemon keeps serving and switches to the new binary once the open sessions end, or after a while at the latest.
Where its files live
Everything the daemon owns is under /var/lib/nokkud/. It never writes to /etc/ssh. Treat the directory as sensitive: it holds the server’s identity in Nokku and its SSH host key.
Under the hood
- One file holds the enrollment and the synced access: the access list, the trusted CA keys and the session rules.
- The daemon’s identity toward the core is a separate key. With a TPM it never leaves the chip. Without one it is a software key wrapped to the machine, and
--require-tpmrefuses that fallback. - The SSH host key is a normal OpenSSH key file, readable by root only, like
sshd’s own. Every enrollment makes a new one. The host certificate sits next to it. - Recordings that are not uploaded yet wait in a folder next to them.
- Logins, commands and forwards are written to the service log as
auditlines, sojournalctl -u nokkudhas them. - Password and plain-key logins are refused. Only certificates work.
Remove a server
sudo nokkud reset
sudo systemctl disable --now nokkud
reset removes the server from Nokku and deletes all local daemon state. Uninstall the package afterwards if you like.
Next steps
- Grant access to the new server.
- Choose what sessions may do: Session rules.
- Every flag and environment variable: nokkud README.