Skip to content
Nokku LogoNokku
GuidesLearn the concepts

What happens when you type ssh

A step-by-step walk through one Nokku connection, and the tricks that make it feel like plain ssh.

Last updated on

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 ubuntu

ssh 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:

  • nk keeps a copy of your access list and your certificates. While the certificate for a server is valid, ssh to it keeps working.
  • Each server with nokkud keeps 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 Host block sets ProxyCommand nk proxy <target-id> %p, HostKeyAlias <target-id>, CertificateFile, IdentityAgent and a UserKnownHostsFile that only nk writes. known_hosts entries are scoped to the target ID, never to *.
  • nk keeps one certificate per server. nk prepare renews it once half of its lifetime is over. If that fails the certificate keeps working until it expires, and nk proxy tries once more when it no longer does.
  • A certificate signed before a grant doesn’t name the new account. nk proxy fetches a new one when the access refresh shows such an account. ssh may 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 agent process 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, nk uses a software key that is wrapped with a key derived from the machine, so the file is useless on another machine. --require-tpm refuses this fallback.
  • Calls from nk and nokkud to the core are bound to a machine key with DPoP (RFC 9449). A stolen session token doesn’t work from another machine.