SSH to a Machine Behind NAT

Reach a machine that has no public IP and no open inbound port: a box at home, a lab machine, a cloud VM with a closed firewall. The machine connects out to nfltr.xyz; your laptop's ssh goes through that connection.


Goal

nfltr cat ssh build-box.build-box/ssh from your laptop opens a shell on a machine called build-box behind NAT.

An ssh session to a machine behind NATbuild-box serves SSH through its one outgoing connection to the relay. Once, nfltr org trust writes the organisation issuer's key on the laptop from the laptop's own enrolment, never from the relay. nfltr cat ssh opens a session to build-box's ssh service through the relay; build-box presents an SSH host certificate signed by the issuer, which ssh checks for build-box's name and against the revocation list before it sends your key. The relay carries the encrypted session.build-box: nfltr cat serve --sshRelayLaptop: nfltr cat sshonce: nfltr org trust writes the issuer's key from this laptop's enrolmentnames build-box, signed by the issuer, not revoked? otherwise refuseone outgoing connection, serves sshsession to build-box's ssh servicesessionhost certificate for build-box, signed by the issueryour key, then the shell, encrypted end to end
An ssh session to a machine behind NAT

Prerequisites

1. Make a key pair on the laptop

Skip this if you already have one. The key is how build-box knows it is you.

$ mkdir -p ~/.ssh && chmod 700 ~/.ssh
$ [ -f ~/.ssh/id_ed25519 ] || ssh-keygen -q -t ed25519 -N '' -f ~/.ssh/id_ed25519
$ cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… you@laptop

2. Allow that key on build-box

On build-box, add the line cat printed to ~/.ssh/authorized_keys (paste it with an editor, or copy it over any channel you trust). When you try this tutorial with both ends on one machine, this does it:

$ cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys

3a. Serve the SSH service on build-box

Its host key is build-box's organisation key, presented with an SSH host certificate: it names the machine (build-box.<org id>.internal), is signed by the organisation's issuer and lasts as long as the machine's certificate (24 hours, renewed while nfltr runs there). There is no other host key, so a restart changes nothing for ssh. The agent is the machine's name in the organisation, and the service is named ssh:

$ nfltr cat serve ssh --ssh --authorized-keys ~/.ssh/authorized_keys

Leave it running (tmux, screen or a service manager). It has no listening port on build-box; the only way in is through nfltr, and only for keys in authorized_keys. The server accepts public keys only.

3b. Or expose an existing sshd

If build-box already runs OpenSSH on port 22, serve that port instead of the embedded server. That sshd has its own host key and no organisation certificate, so the organisation trust of step 4 does not cover it: nfltr cat ssh on an enrolled laptop expects that certificate, so connect with plain ssh, ssh -o ProxyCommand="nfltr cat pipe --plain build-box.build-box/ssh" you@build-box, and check its host key at ssh's first-connection prompt against the key on build-box (ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub there).

$ nfltr cat serve ssh --forward localhost:22 --agent build-box

4. Trust the organisation's host certificates on the laptop

Trust the organisation's machines once:

$ nfltr org trust
ssh now trusts organisation o-…'s machines (*.o-….internal) in /home/you/.ssh/known_hosts
revoked machines: RevokedHostKeys /home/you/.config/nfltr/org/machine/revoked-hosts.krl (nfltr cat ssh passes it; plain ssh: add the line to ~/.ssh/config)
per machine: nfltr cat ssh <agent>/<service>

nfltr org trust writes one @cert-authority line: the issuer's key, read from this machine's own organisation files and checked there first (the issuer's log on the owner's Mac, else this laptop's enrolment, its chain and the current CRL). It never takes the key from the relay. Plain ssh, scp, rsync -e ssh and VS Code Remote-SSH can use the same path through an entry in ~/.ssh/config:

Host build-box
    ProxyCommand nfltr cat pipe --plain build-box.build-box/ssh
    User you
    IdentityFile ~/.ssh/id_ed25519
    HostKeyAlias build-box.o-….internal
    StrictHostKeyChecking yes
    RevokedHostKeys /home/you/.config/nfltr/org/machine/revoked-hosts.krl
No first-use prompt

nfltr cat ssh checks the host certificate of the machine the target names, and in the config entry HostKeyAlias build-box.<org id>.internal and StrictHostKeyChecking yes make ssh accept only a certificate for that name signed by the organisation's issuer, and never offer a new key: a machine that registered the name build-box with a key of your account, or a LAN host also called build-box, cannot impersonate it. The organisation id is the laptop's own enrolment's.

5. Connect

$ nfltr cat ssh build-box.build-box/ssh -- 'echo hello from $(hostname)'
hello from build-box

There is no prompt: ssh checked the certificate. Drop the quoted command for an interactive shell; arguments after -- go to ssh, as in nfltr cat ssh admin@build-box.build-box/ssh -- -L 8080:localhost:80.

Alternative: a local port with nfltr cat forward

For tools that want a host and a port instead of an ssh config entry, forward a local port to build-box's SSH port:

$ nfltr cat forward --plain build-box.build-box/ssh --listen 127.0.0.1:2222

Then connect with ssh, checking the certificate's name:

$ ssh -o HostKeyAlias=build-box.o-….internal -o StrictHostKeyChecking=yes -o RevokedHostKeys=/home/you/.config/nfltr/org/machine/revoked-hosts.krl -p 2222 -i ~/.ssh/id_ed25519 localhost

The same works for any TCP service on build-box: nfltr cat serve db --forward localhost:5432 --agent build-box there and nfltr cat forward --plain build-box.build-box/db --listen 127.0.0.1:5432 here gives you psql -h 127.0.0.1.

Without an organisation: ssh and rsync over an address

A machine that is not in an organisation can serve its existing sshd under a capability address (nf1…): whoever holds the address reaches the service, end to end encrypted, with no account on the client. On build-box, serve port 22 and save the address to a file only you can read:

$ nfltr cat serve ssh --forward 127.0.0.1:22 --address --address-file ~/ssh.addr
Address of build-box/ssh written to /home/you/ssh.addr (mode 0600; anyone who has it can open the service; keep it secret)

--address-file writes the file with mode 0600 at every start; the address is never printed, so it stays out of terminal scrollback and logs. (nfltr cat serve ssh --show-address --address-file ~/ssh.addr writes it again later; a shell's > file would create a file others can read.) The address is a password: copy the file to the laptop over a channel you trust, keep it mode 0600 there (chmod 600 ~/ssh.addr), and revoke it by serving with --new-address.

On the laptop, an entry in ~/.ssh/config uses nfltr cat pipe as the proxy. Its stdout carries only the session's bytes and its events go to stderr, so it needs no other flag (--plain is refused: an address is always end to end):

Host build-box
    ProxyCommand nfltr cat pipe --address-file ~/ssh.addr
    User you
    IdentityFile ~/.ssh/id_ed25519

sshd keeps its own host key, so ssh asks to confirm it at the first connection: check it against the key on build-box (ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub there). Then ssh, scp and rsync work as on a LAN:

$ ssh build-box true
$ rsync -a --delete ~/project/ build-box:project/
$ rsync -a --delete build-box:project/ ~/project-copy/

Where the bytes go depends on the serving machine's account:

Where an address's session runsnfltr cat pipe reads the address and asks the relay to introduce it to the serving machine. Both try a direct path. If one forms, the session runs on it, end to end encrypted. If none forms, a serving machine with an account has the relay carry the session, still end to end encrypted; with no account, nfltr cat pipe stops with exit 12 and the relay carries no byte.yesnoyesnoLaptop: nfltr cat pipe--address-fileRelay introduces the twomachinesA direct path forms?Session on the directpath, end to endServing machine has anaccount?Relay carries thesession, still end to endnfltr cat pipe stops: exit12
Where an address's session runs

After a rotation, and revocation

Run nfltr org trust again after a root rotation: the new issuer has a new key, and ssh trusts the old one until then (a known_hosts CA line has no expiry). A monthly nfltr org issuer renew keeps the key, so nothing changes. A revoked machine is refused by ssh as soon as the organisation's CRL reaches the laptop: the laptop keeps the CRL's OpenSSH key revocation list (the RevokedHostKeys file nfltr org trust printed), and nfltr cat ssh and the config entry above pass it to ssh. If the CRL lapses (nothing served the issuer for an hour), the list keeps the last revocations, and a machine revoked after that is refused by ssh only when its certificate ends, at most 24 hours later.

6. Clean up

Stop nfltr cat forward with Ctrl+C, remove the ssh config block if you added one, then stop nfltr cat serve on build-box with Ctrl+C.

# Ctrl+C in the nfltr cat serve terminal on build-box

If it goes wrong

You seeMeaning and fix
"event":"error","code":"not_found" from nfltr cat pipe, then Connection closed by UNKNOWN port 65535No machine called build-box is connected for your account: nfltr cat serve ssh --ssh is not running there, it runs under another name, or it uses a key of a different account. Check the name in its agent-id: line.
Permission denied (publickey)build-box does not have your public key in the file passed to --authorized-keys, or ssh offers a different key: name it with -i after -- (nfltr cat ssh build-box.build-box/ssh -- -i ~/.ssh/id_ed25519).
kex_exchange_identification: read: Connection reset by peer through nfltr cat forwardThe tunnel reached nfltr but not an SSH server: build-box is not connected under that name, or nothing listens on the remote port.
Host key verification failed. (with Certificate invalid: name is not a listed principal or No ED25519 host key is known)What answered as build-box has no certificate of your organisation for that name: another machine uses the name, the laptop has not run nfltr org trust (or not since a root rotation), or build-box runs a plain sshd (step 3b). ssh refuses rather than ask.
Error: this machine is not enrolled in an organisationnfltr cat serve ssh --ssh on a machine with no enrolment: enrol it with nfltr org join.
nfltr: direct_required: … (exit 12) through an nf1… addressbuild-box serves the address with no account and no direct path formed between the two networks (two symmetric or filtering NATs). Enrol build-box in an account (nfltr config login) so the relay can carry the session, or connect from a network where a direct path forms (IPv6, or a NAT that allows hole punching).
ssh: Could not resolve hostname build-boxPlain ssh build-box needs the config entry of step 4; nfltr cat ssh does not.

Next