Some servers can’t run extra software, or you’d simply rather keep them plain. For those, nk sync sets up the normal OpenSSH server (sshd) to accept Nokku certificates. Nothing is installed on the server.
Daemon or not?
With nokkud | With nk sync | |
|---|---|---|
| Software on the server | The daemon | Nothing, only two config files |
| New access works | Right away | Right away |
| Removed access stops | Right away | When the last certificate runs out |
| Open sessions on a removal | Closed | Run on until they end |
| Reachable behind NAT (relay) | Yes | No, must be reachable directly |
| Session recording | Yes | No |
| Port and agent forwarding | Set per daemon | The server’s own sshd_config |
| Server verified by | Host certificate | The server’s own key, remembered at sync |
If you can install the daemon, do that. nk sync is for the rest.
Before you start
- You can already log in to the server as
rootwith your normal SSH setup.nk syncuses your ownssh, so your keys and~/.ssh/configapply. - You are signed in with
nk loginand have the editor role or higher in the workspace.
Add the server
nk sync 10.0.0.5
You can also pass root@host or a name from your ~/.ssh/config. Want to see what would change first? Add --dry-run.
nk sync then:
- Connects to the server as
rootand reads its Linux accounts and its SSH host key. - Creates the target in your workspace, remembering that host key.
- Writes the workspace CA and a small
sshdconfig file that trusts it. - Checks the new config with
sshd -t. Ifsshdrejects it, every file is rolled back and nothing changes. - Reloads
sshdand tells Nokku the server is set up.
flowchart LR
probe["Read accounts<br>and host key"] --> write["Stage the CA<br>and sshd config"]
write --> test{"sshd -t<br>happy?"}
test -- no --> rollback["Put every file back"]
test -- yes --> reload["Reload sshd"] --> report["Tell Nokku"]Give people access
A new server can start with access in place. Say who may log in when you add it:
nk sync 10.0.0.5 --grant root=me --grant deploy=team:ops,alice@example.com
Each --grant names a Linux account and who may use it: me, an email, team:<name>, or sa:<name> for a service account. The account has to be a login account on the server, otherwise nothing is written.
These grants are set once, when the server is added. From then on the web app is where access changes, like for any other server. See Grant access. Access changes need no new sync.
Removing access
These servers never hear about a removal. Access ends when the person’s last certificate runs out, which is soon, and an open session stays until it ends. See Revoking access. If that is not good enough for a server, use the daemon.
When to run nk sync again
- After a CA rollover. The server only trusts the CA key it was given. Until you sync it, nobody gets in through Nokku. See Roll over the CA.
- When the server’s accounts change. A sync reports them to Nokku, so they show up in the web app for granting.
What it writes
Everything goes to standard OpenSSH locations. Your existing sshd config stays as it is.
/etc/ssh/
- nokku_ca.pub
sshd_config.d/
- 60-nokku.conf
nokku_ca.pubis the workspace CA.sshdtrusts certificates it signed.60-nokku.confsetsTrustedUserCAKeysand one fixed rule: accept a certificate that names this server and the account asked for.
nk sync --dry-run --json prints the exact files for a server.
Under the hood
- The changes are applied by one shell script over your
sshsession. It refuses to touch a server whosesshdconfig is already broken, stages every file first, then swaps them in. - The rule is an
AuthorizedPrincipalsCommandthat prints<server ID>:<account>. A certificate for this server carries that principal for every account the person was granted. See Principals. - The host key is read on the first sync.
nkpins it in its ownknown_hosts, so users are never asked to confirm it. When a later sync sees a different key, it stops and writes nothing. If you reinstalled the server, runnk syncagain with--accept-host-keyto pin the new one. - By design, Nokku never pushes anything to these servers and keeps no credentials for them. Every change comes from someone running
nk sync.
Remove the server
nk rm undoes what nk sync did:
nk rm my-server
It connects as root like nk sync, removes the files listed above, and reloads sshd. Only then does it delete the target in Nokku. If sshd rejects its config without the Nokku file, everything is put back and the target stays.
Is the server already gone? Add --keep-host to delete only the target and skip the cleanup.
The nk README has the details, and its command list has every flag.