Jump hosts
Reach servers behind one or more bastions with chains that work like OpenSSH ProxyJump, and see what happens at each hop.
A jump host (or bastion) is a server you pass through to reach another one. Gatesys SSH chains any number of them, the same way OpenSSH’s ProxyJump does, and treats the whole chain as one connection.
How a chain works
Each hop is dialled through a direct-tcpip channel on the hop before it. That means:
- Intermediate hosts never see your traffic. The SSH session to the target is encrypted end to end; the bastion only forwards bytes.
- Nothing is needed on the bastion beyond SSH forwarding.
ncdoes not have to be installed. - Chains resolve recursively. A jump host can have jump hosts of its own. A chain that loops back on itself is rejected.
- One chain per host. The terminal, SFTP, tunnels and metrics for a host share one session, so the chain is negotiated once.
Set up a chain
- Save the bastion as a host first, for example
edge-bastion, and check that you can connect to it. - Open the target host in the editor, for example
db-primary, and go to Routing. - Choose the bastion from Add a jump host….
- Add more hops if needed and put them in order with Move earlier and Move later. The first hop is dialled first.
- Check the Route preview, for example
edge-bastion → db-primary, and click Save.
A host with no jump hosts shows Direct connection.
Two ways to build a longer chain
Say db-primary is reached through edge-bastion and then inner-bastion. Either works:
| Approach | How |
|---|---|
| List every hop on the target | On db-primary, add edge-bastion, then inner-bastion |
| Let each host carry its own route | On inner-bastion, add edge-bastion. On db-primary, add only inner-bastion |
The second approach keeps the route in one place: every host behind inner-bastion picks up a change to its route.
From ~/.ssh/config or a pasted command
- Importing ~/.ssh/config links
ProxyJumpentries, including comma-separated chains, into real jump chains. - Pasting
ssh -J edge-bastion [email protected]into the Hosts search box, or typing add 10.0.3.4 as deploy behind edge-bastion, drafts the host with its jump host set.
What happens at each hop
- Host keys. Each hop’s key is verified on its own. The first visit to each hop asks you to trust it. See Host keys.
- Logins. Each hop uses its own saved login and methods. Every prompt names the hop it is for.
- Time. Each hop gets 25 seconds from its TCP connect to a finished login. The clock stops while a host key or password prompt is on screen. A server that goes quiet part-way through the login is reported as a timeout, not a refusal.
- Cancelling. Closing the tab while it is still connecting stops the dial at once.
When a hop fails
Hop Doctor names the hop that broke and the step: DNS, TCP, SSH handshake, host key or login. It runs its checks from the hop in front of the broken one, while the earlier hops are still up.
The bastion’s own reason for refusing a channel is part of the evidence:
| Bastion says | Usually means |
|---|---|
connect failed: Connection refused | The bastion reached the next host, but nothing listens on that port |
administratively prohibited | The bastion’s SSH server does not let you open forwarding channels |
When the name of the next host does not resolve, Hop Doctor asks the bastion, with a read-only lookup. When a first hop’s name does not resolve on your computer, it can ask up to two related bastions you already have open, and offer one as a jump host. See Hop Doctor.
Good to know
- Deleting a jump host removes it from every chain that used it.
- Changing a bastion’s SSH config with Safe Change warns you, by name, about hosts that jump through it when a change would turn off forwarding.
- Facts and the service map are read over the same chained session, so a host behind two bastions is understood as well as one on your desk.
Something unclear or wrong? Tell us.