SSH through the Relay

What this gives you

A machine behind a router — an office PC, a NAS, a Raspberry Pi — can make its SSH server reachable through your Relay without opening any port on its own network. You then log in to it from anywhere with a normal ssh command.

The Relay supports this with private aliases: the machine publishes its SSH port under a name that exists only inside the Relay. Nobody on the internet can connect to it directly. Only a person who first logs in to the Relay with an approved key can reach it, and they then still have to log in to the machine itself.

  Your laptop                    Relay                       The machine
  ssh mybox  ---- SSH :2222 ---> alias "mybox:22" <=== SSH :2222 ---- ssh -R mybox:22:localhost:22
                (laptop logs in)        |              (machine logs in, keeps
                                        |               the connection open)
             <====== inner SSH session, encrypted laptop <-> machine ======>

The inner SSH session runs from your laptop to the machine’s own SSH server. The Relay only copies its bytes and cannot read them.

Before you start

• Both the machine and your laptop need an SSH key that the Relay approves. Add each public key as described in Access Control and Security — through the public keys folder or the Users tab of /_relay/dashboard.
• The machine needs a running SSH server (for example OpenSSH on port 22).
• Ask the Relay operator to turn off random alias names, so the alias keeps the name you choose:

# config.yml on the Relay
bind-random-aliases: false
force-requested-aliases: true

With --bind-random-aliases on (the default), the Relay replaces the name with a random three-character one — TCP Alias: k3x:22 — and gives a new one on every reconnect. --force-requested-aliases makes the machine’s request fail instead of silently taking a random name when the name is already in use.

The examples use relay.example.com for your Relay, mybox for the alias, and alice for the user account on the machine.

Step 1: publish the machine’s SSH server as a private alias

A remote forward with a name and a port other than 80 or 443 becomes a private alias. Run one of these on the machine.

With OpenSSH

ssh -p 2222 -N -R mybox:22:localhost:22 relay.example.com

-N keeps the connection open without asking for a session. Leave it out to see the Relay’s welcome text, which includes the line TCP Alias: mybox:22 (or the random name, when random aliases are on).

To keep it permanent, put it in the machine’s ~/.ssh/config:

# On the machine: publish SSH as the private alias "mybox"
Host relay-publish
    HostName relay.example.com
    Port 2222
    IdentityFile ~/.ssh/id_ed25519
    RemoteForward mybox:22 localhost:22
    ExitOnForwardFailure yes
    ServerAliveInterval 15
    ServerAliveCountMax 3
    SessionType none

Then start it with ssh relay-publish. OpenSSH does not reconnect by itself: run that command under your service manager with automatic restart. (SessionType none needs OpenSSH 8.7 or newer; on older versions remove the line and start it with ssh -N relay-publish.)

With the built-in client

The Relay binary contains a client that reconnects by itself:

viaalink-relay connect --server relay.example.com:2222 --no-auth \
  --key ~/.ssh/id_ed25519 -F mybox:22:localhost:22

• Use the four-part form name:port:host:port. The short forms mybox:22 and mybox:localhost:22 mean a web address pointing at local port 22, not an alias.
• --no-auth skips any online sign-in, so your SSH key is the only credential — the right choice for your own Relay.
• --reconnect is on by default; keepalive and reconnect timing are described in How the Relay Works.

Step 2: connect from your laptop

One-off command

ssh -J relay.example.com:2222 alice@mybox

-J (ProxyJump) logs in to the Relay first, then asks it for a connection to mybox port 22 — the alias — and runs your SSH session through it.

Copy-paste ~/.ssh/config

# On your laptop: the Relay as jump host
Host relay
    HostName relay.example.com
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

# The machine, reached through the Relay
Host mybox
    HostName mybox
    User alice
    ProxyJump relay

Now ssh mybox, scp file mybox: and rsync -a dir/ mybox:dir/ all work. HostName mybox is the alias name, not a DNS name: the Relay resolves it, not your laptop. When the machine published a port other than 22 (-R mybox:2200:localhost:22), add Port 2200 to the mybox entry.

For OpenSSH versions without ProxyJump, use the older equivalent:

Host mybox
    HostName mybox
    User alice
    ProxyCommand ssh -p 2222 -W %h:%p relay.example.com

Alternative: a local port

If a tool cannot use a jump host, forward a local port to the alias and connect to that:

ssh -p 2222 -N -L 2200:mybox:22 relay.example.com
# in a second terminal:
ssh -p 2200 alice@localhost

Limiting who can reach an alias

By default, every key the Relay approves can open a connection to every alias. The machine’s own SSH login is then the second lock.

To allow only specific keys, the operator turns on --tcp-aliases-allowed-users (tcp-aliases-allowed-users: true in config.yml), and the machine lists the allowed keys when it connects, as a remote command:

ssh -p 2222 -R mybox:22:localhost:22 relay.example.com \
  tcp-aliases-allowed-users=SHA256:AbCdEf...,SHA256:GhIjKl...

Each entry is a key’s SHA256 hash as printed by ssh-keygen -lf ~/.ssh/id_ed25519.pub. The machine’s own key is added automatically; any allows every approved key. This works with OpenSSH only — the built-in client cannot send remote commands.

Option: a public TCP port (not recommended)

A remote forward to localhost with a port other than 80 or 443 opens a public TCP port on the Relay instead of an alias:

ssh -p 2222 -R 2200:localhost:22 relay.example.com

With --bind-random-ports on (the default), the Relay picks a random port from --port-bind-range and prints it in the welcome text (for example tcp: relay.example.com:41285). Anyone on the internet can then try to log in on that port, and your router or firewall has to let it through to the Relay. Prefer a private alias.

What is and is not supported

Troubleshooting

• The connection closes right after logging in to the Relay, before the machine asks for a password: no alias with that exact name and port exists (or your key is not on its allowed list). Check the machine’s connection and the alias name it got (leave out -N to see the welcome text).
• Permission denied at the Relay: the key you use for the jump is not approved on the Relay. The laptop’s key must be approved too, not only the machine’s.
• Host key warning for mybox after the machine was reinstalled: that is the machine’s own SSH host key, stored in your ~/.ssh/known_hosts under the alias name. Remove the old entry with ssh-keygen -R mybox.