Skip to content
Nokku LogoNokku
GuidesLearn the concepts

Servers without the daemon

Use nk sync to set up a server with plain OpenSSH, for machines where you can't or don't want to install nokkud.

Last updated on

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 nokkudWith nk sync
Software on the serverThe daemonNothing, only two config files
New access worksRight awayRight away
Removed access stopsRight awayWhen the last certificate runs out
Open sessions on a removalClosedRun on until they end
Reachable behind NAT (relay)YesNo, must be reachable directly
Session recordingYesNo
Port and agent forwardingSet per daemonThe server’s own sshd_config
Server verified byHost certificateThe 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 root with your normal SSH setup. nk sync uses your own ssh, so your keys and ~/.ssh/config apply.
  • You are signed in with nk login and 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:

  1. Connects to the server as root and reads its Linux accounts and its SSH host key.
  2. Creates the target in your workspace, remembering that host key.
  3. Writes the workspace CA and a small sshd config file that trusts it.
  4. Checks the new config with sshd -t. If sshd rejects it, every file is rolled back and nothing changes.
  5. Reloads sshd and 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.pub is the workspace CA. sshd trusts certificates it signed.
  • 60-nokku.conf sets TrustedUserCAKeys and 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 ssh session. It refuses to touch a server whose sshd config is already broken, stages every file first, then swaps them in.
  • The rule is an AuthorizedPrincipalsCommand that 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. nk pins it in its own known_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, run nk sync again with --accept-host-key to 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.