This page follows one connection from your keyboard to a shell on the server. It is the last page of this section, so it assumes you’ve read Principals.
The goal behind everything here: you type the same ssh command you always did, and Nokku does its work where you don’t see it.
The setup nk does once
When you run nk login, nk fetches the list of servers you can reach and writes a regular OpenSSH config file for them in its own folder. It adds one Include line at the top of your own ~/.ssh/config so ssh reads it. Your own settings stay untouched.
For every server there’s a normal Host block. The interesting lines are two hooks that let nk step in at the right moments.
The connection, step by step
Say you run ssh ubuntu@web-01.
Here is the whole flow at a glance. The steps below explain each part.
sequenceDiagram
participant ssh
participant nk
participant Core as Nokku core
participant Server as web-01 (nokkud)
ssh->>nk: nk prepare
nk->>Core: Renew certificate, if needed
Core-->>nk: Fresh certificate
ssh->>nk: nk proxy
par Direct
nk->>Server: Connect to port 4022
and Relay, a moment later
nk->>Core: Open relay
Core->>Server: Over the daemon's connection
end
Note over nk,Server: The first path to connect wins
ssh->>Server: SSH login with the certificate
Note over Server: Checks CA, expiry and access list
Server-->>ssh: Shell as ubuntussh reads the config
OpenSSH finds the web-01 block that nk generated. It learns which certificate file to use, which server key to trust, and that it should reach the server through nk.
nk renews the certificate if needed
Before ssh reads the certificate file, a Match ... exec line runs nk prepare. If your certificate is missing or about to expire, nk gets a fresh one from the core right now.
The trick: ssh loads the certificate before it opens the connection. Renewing in the connection step would be too late for this login, so nk hooks in earlier.
nk finds a way to the server
ssh hands the network part to nk proxy. It first refreshes your access list if it is a little old, so new grants work immediately.
Then it tries every address of the server at the same time. For servers running nokkud it also starts a relay through the core a moment later. Whichever connects first wins, and the others are dropped.
The trick: a server behind NAT or a firewall still works, without a VPN and without opening ports. And a reachable server never waits for the relay.
Your client checks the server
The server presents its host certificate. nk wrote the workspace CA into its
own known_hosts file, so ssh can verify the server on the spot. No “are
you sure?” prompt.
Your laptop proves who you are
The server sends its challenge. A small background agent started by nk
signs it. On machines with a TPM chip, the private key lives inside the chip
and can’t be copied off the laptop. With a security key, ssh asks the key
itself, and you touch it.
The server decides
The server checks that the certificate is signed by the workspace CA and still valid, then checks that it names you, this server and ubuntu, and that the same entry is in its list for ubuntu. Both pass, so it starts a shell as ubuntu. If recording is on, the session is recorded.
The relay can’t read your session
The relay only passes bytes along. The SSH connection is encrypted from your laptop to the server, exactly as with a direct connection, so the core sees scrambled data it cannot decrypt. It’s the same idea as a letter in a sealed envelope traveling through a post office.
Servers set up without the daemon have no relay. They are always reached directly.
When the core is down
Nokku is built so an outage of the core doesn’t lock anyone out:
nkkeeps a copy of your access list and your certificates. While the certificate for a server is valid,sshto it keeps working.- Each server with
nokkudkeeps its list of who may log in. Logins are checked against that list, not against the core. - What stops working until the core is back: new certificates, access changes, and the relay.
Under the hood
- The generated
Hostblock setsProxyCommand nk proxy <target-id> %p,HostKeyAlias <target-id>,CertificateFile,IdentityAgentand aUserKnownHostsFilethat onlynkwrites.known_hostsentries are scoped to the target ID, never to*. nkkeeps one certificate per server.nk preparerenews it once half of its lifetime is over. If that fails the certificate keeps working until it expires, andnk proxytries once more when it no longer does.- A certificate signed before a grant doesn’t name the new account.
nk proxyfetches a new one when the access refresh shows such an account.sshmay have read the old file by then, so the first login as a new account can need a second try. - Direct dials start right away, each with a short timeout. The relay joins after a small head start, or at once when every direct dial has failed.
- A session through the relay has an upper time limit. A direct session has none.
- The agent is a hidden
nk agentprocess on a unix socket (a named pipe on Windows). It stops after a while without use and starts again on the next connection. - Without a TPM,
nkuses a software key that is wrapped with a key derived from the machine, so the file is useless on another machine.--require-tpmrefuses this fallback. - Calls from
nkandnokkudto the core are bound to a machine key with DPoP (RFC 9449). A stolen session token doesn’t work from another machine.