Skip to content
Terminalia

Guide · SSH

ProxyJump: SSH through a bastion host

Updated · 5 min read

ProxyJump makes SSH connect to an intermediate server first (the bastion, or jump host) and open the connection to the private server from there, in a single command: ssh -J user@bastion user@10.0.1.20. In ~/.ssh/config you add ProxyJump bastion to the private host. You authenticate to the final server from your Mac, so your private key is never copied to the bastion.

On this page

How it works

Your Mac ──SSH──▶ bastion.example.com ──TCP──▶ 10.0.1.20 (private network)
   └──────────── SSH, encrypted end to end ────────────┘

The bastion only relays traffic. Your session with the final server is encrypted end to end between your Mac and that server. You need OpenSSH 7.3 or later, which macOS has shipped for years.

1. From the command line

Terminal
ssh -J ubuntu@bastion.example.com deploy@10.0.1.20

If the bastion runs on another port:

Terminal
ssh -J ubuntu@bastion.example.com:2222 deploy@10.0.1.20

Several hops, comma-separated and in order:

Terminal
ssh -J ubuntu@bastion-1.example.com,ubuntu@bastion-2.internal deploy@10.0.2.15

2. In ~/.ssh/config

~/.ssh/config
Host bastion
  HostName bastion.example.com
  User ubuntu
  IdentityFile ~/.ssh/id_ed25519

Host app-1
  HostName 10.0.1.20
  User deploy
  ProxyJump bastion

Now it’s just:

Terminal
ssh app-1

ProxyJump bastion uses the Host bastion block (the bastion’s user, port and key), so you don’t repeat anything.

A whole subnet behind the same bastion

~/.ssh/config
Host 10.0.1.*
  User deploy
  ProxyJump bastion

Older OpenSSH on your side (before 7.3)

~/.ssh/config
Host app-1
  HostName 10.0.1.20
  ProxyCommand ssh -W %h:%p bastion

3. Files and tunnels through the bastion

Anything that runs over SSH honours the alias’s ProxyJump:

Terminal
scp backup.sql app-1:/tmp/
rsync -av ./dist/ app-1:/srv/app/
sftp app-1

A tunnel to a database on the private network:

Terminal
ssh -N -L 5433:localhost:5432 app-1

If the database lives on another machine the bastion can reach directly, you don’t even need app-1:

Terminal
ssh -N -L 5433:db.internal:5432 bastion

(→ SSH tunnel guide)

4. Why not ForwardAgent

Before ProxyJump, the usual move was to log into the bastion with ForwardAgent yes and ssh onward from there. That lets anyone with root on the bastion use your agent while you’re connected. ProxyJump makes it unnecessary: your key and your agent stay on your Mac.

Common errors

  • channel 0: open failed: administratively prohibited: open failed. The bastion has AllowTcpForwarding no in sshd_config. ProxyJump needs forwarding allowed on the bastion; whoever runs it has to change that.
  • Permission denied (publickey) on the final server. Your public key isn’t in that server’s ~/.ssh/authorized_keys, or the user is wrong. Getting into the bastion fine doesn’t help: the second hop is a separate login.
  • It logs into the bastion as your Mac user. With -J bastion.example.com and no user@, SSH uses your local username. Put the user in -J or in the Host bastion block.
  • Could not resolve hostname app-1.internal. The bastion resolves that name, not your Mac. Use a name the bastion knows, or the private IP.
  • Connection loops or hangs. A Host * with ProxyJump bastion also applies to the bastion itself. Exclude it with Host * !bastion, or set ProxyJump none in Host bastion (above the Host *).
  • Host key verification failed. It’s your first connection to that private server, or its host key changed. Check the fingerprint before accepting; for a legitimately changed key, run ssh-keygen -R 10.0.1.20.

To see which hop fails: ssh -v app-1.

FAQ

What’s the difference between ProxyJump and ProxyCommand?

ProxyJump (-J) is the short, modern way to hop through a bastion, available since OpenSSH 7.3. ProxyCommand runs whatever command you give it to open the connection, usually ssh -W %h:%p bastion. In the common case they do the same thing; use ProxyJump unless you need a custom command.

Do I need to copy my private key to the bastion?

No, and you shouldn’t. With ProxyJump you authenticate to both the bastion and the final server from your Mac; the bastion only relays encrypted traffic. What you do need is your public key in the authorized_keys of both the bastion and the final server.

Can I use different keys for the bastion and the server?

Yes. Set one IdentityFile in the Host bastion block and another in the private server’s block. SSH uses each key for its own hop. Add IdentitiesOnly yes so it doesn’t offer every other key in your agent and trip the too-many-authentication-failures limit.

Related guides