How does OpenSSH's ProxyJump (ssh -J) carry a connection through a bastion, and how does it differ from a ProxyCommand?
answer
- two sessions, one inside the other
- a TCP forwarding opened on the bastion
- the bastion relays ciphertext
- any command speaking stdin and stdout
basics
~20 sssh -J logs in to the bastion, asks it to open a TCP forwarding to the target's SSH port, and runs a second, end-to-end SSH session through it. ProxyCommand instead runs any command whose stdin and stdout reach the server.
solid answer
~50 sWith `ssh -J [email protected] [email protected]`, the client first makes an SSH connection to the bastion, then asks it for a TCP forwarding to `app.internal.example:22`, a `direct-tcpip` channel. Over that channel the client runs a **complete second SSH session**: key exchange, the target's host-key check and user authentication all happen between the laptop and the target, so the bastion relays only ciphertext and needs no keys. The bastion's `sshd` must allow local TCP forwarding (`AllowTcpForwarding yes` or `local`, with `PermitOpen` covering the target), so `DisableForwarding yes` there breaks `-J`. Hops chain with commas. `ProxyCommand` is the general hook: any command whose stdin and stdout end up at an `sshd`, such as a helper through an HTTP proxy or the older `ssh -W %h:%p` idiom. In one configuration the two compete, and whichever is specified first wins.
code
bash · 5 lines# ProxyJump: client -> bastion, then an end-to-end session to the target
ssh -J [email protected] [email protected]
# The older equivalent, written as a ProxyCommand around stdio forwarding (-W)
ssh -o 'ProxyCommand ssh -W %h:%p [email protected]' [email protected]go deeper
Know that ssh -J reaches a private host through a bastion in one command, and that the login to the target happens from your own machine.
Walk through the two sessions: a login to the bastion, a direct-tcpip forwarding to port 22, then a full SSH session inside it, and how ProxyCommand generalises the pipe.
Diagnose jump failures by layer: bastion login, the bastion's AllowTcpForwarding, PermitOpen and DisableForwarding, then the target's host key and authentication, and say what the bastion can observe.
Argue the bastion's role: a choke point that authenticates and restricts destinations but cannot inspect sessions, and decide whether that meets the audit requirement or something else must record sessions.
## The problem Production hosts often have no public address. The only way in is a **bastion** (jump host) that accepts SSH from outside and can reach the private network. The naive approach is to log in to the bastion and run `ssh` again from its shell. That works, but the second login happens *on the bastion*: whatever credentials the second hop needs must be there or be lent to it, and the bastion sees the inner session in clear text. `ProxyJump` (`ssh -J` on the command line) solves this by turning the bastion into a pipe. ## What ProxyJump does, step by step ```bash ssh -J [email protected] [email protected] ``` 1. The client opens an SSH connection to `bastion.example.com` and authenticates as `alice`. 2. Over that connection it opens a **TCP forwarding** to `app.internal.example` port 22: a `direct-tcpip` channel (RFC 4254 section 7.2), the same mechanism as a `-L` connection. This is what `ssh -W host:port` exposes on its own: the client's standard input and output forwarded to one host and port. 3. The client runs a **second, complete SSH session** through that channel, as if it were a direct TCP connection: version exchange, key exchange, the **target's host-key check** against the laptop's `known_hosts`, and user authentication as `deploy`. 4. Several bastions can be chained: `-J [email protected],[email protected]`; each hop is visited in order. The inner session is encrypted end to end between the laptop and the target. Keys and agent stay on the laptop, which is the main reason ProxyJump replaced agent forwarding for this pattern; the material on the SSH agent covers that side. ## What the bastion sees and controls - It sees **who** logged in to it and **which host and port** the client asked to reach, because those travel in the channel open. - It relays the inner session as **opaque encrypted bytes**; even root on the bastion cannot read commands or output. - It enforces policy through its own `sshd_config`: `AllowTcpForwarding` must permit local forwarding (`yes`, the default, or `local`), and `PermitOpen` can restrict the destinations to, say, port 22 on the private range's hosts. `DisableForwarding yes` or `AllowTcpForwarding no` on the bastion makes `-J` fail. ## ProxyCommand: the general hook `ProxyCommand` names a command that `ssh` runs, using the user's shell with `exec`; the command reads its standard input and writes its standard output, and it must eventually reach an `sshd`. `%h` and `%p` expand to the target host and port. That covers cases ProxyJump cannot: - connecting **through an HTTP proxy** with a helper that speaks the proxy's CONNECT method; - any custom transport that can carry a byte stream; - the older bastion idiom `ProxyCommand ssh -W %h:%p bastion.example.com`, which has the same effect as `ProxyJump bastion.example.com` and is what people wrote before it existed. Host-key checks use the target's `Hostname`, so the proxy does not change whose key is verified. `CheckHostIP` is unavailable with a proxy command. | | Nested ssh on the bastion | `ProxyJump` / `-J` | `ProxyCommand` | |---|---|---|---| | Where the inner session ends | the bastion's shell | the laptop | the laptop | | Bastion sees inner traffic | yes | no, ciphertext only | depends on the command; no for `ssh -W` | | Credentials needed on the bastion | yes, or lent | none | none for `ssh -W` | | Transport | a shell session | `direct-tcpip` channel | whatever the command provides | | Needs bastion forwarding | no | yes | for `ssh -W`, yes | ## Failure modes, layer by layer Because a jump is two sessions stacked, a failure belongs to exactly one layer, and the error tells you which: 1. **Bastion login fails**: an ordinary authentication or host-key problem with `bastion.example.com`; the target is never contacted. 2. **Channel open refused or the connection to the target fails**: the bastion logged you in but would not or could not reach `app.internal.example:22`. Look at the bastion's forwarding settings and at whether the bastion can route to the target at all. 3. **Target host-key warning or authentication failure**: the pipe works; the problem lies between the laptop and the target, exactly as it would on a direct connection. ## Gotchas - `ProxyJump` and `ProxyCommand` **compete**: whichever is specified first prevents later instances of the other from taking effect. `ProxyJump none` disables it. - Options given on the command line generally apply to the **destination**, not the jump hosts. Per-jump-host settings belong in `~/.ssh/config`, which the material on client configuration covers. - A refused forwarding on the bastion surfaces as a failed channel open, after the bastion login has already succeeded, so check the bastion's forwarding settings before blaming the target.
- Why does `ssh -J` fail with a channel-open error even though logging in to the bastion works?The jump needs the bastion's `sshd` to open a TCP forwarding to the target. If the bastion sets `DisableForwarding yes`, `AllowTcpForwarding no` or `remote`, or a `PermitOpen` list without that host and port, the `direct-tcpip` open is refused after a successful login. The fix is on the bastion, not the target.
- When would you still choose ProxyCommand over ProxyJump?When the path is not an SSH hop: reaching `sshd` through an HTTP proxy's CONNECT method, or through any other command that can carry a byte stream on stdin and stdout. For a plain SSH bastion, ProxyJump does the same job as `ProxyCommand ssh -W %h:%p` with less to get wrong.
- What does `ssh -W app.internal.example:22 [email protected]` do on its own?It forwards the client's standard input and output to that host and port over the secure channel. The man page notes it implies `-N`, `-T`, `ExitOnForwardFailure` and `ClearAllForwardings`. On its own it prints the target's SSH banner; as a ProxyCommand it becomes the pipe another `ssh` runs its session through.
A sealed envelope passed through a company mailroom: the mailroom sees the name on the outside and decides whether to deliver it, but cannot read the letter inside. The bastion likewise sees the target's address and port and relays ciphertext it cannot read.
- Thinks the bastion decrypts and re-encrypts the session to the target.
- Says ProxyJump needs the user's private key copied to the bastion.
- Believes the bastion verifies the target's host key on the client's behalf.
- Claims ProxyJump works on a bastion with DisableForwarding yes.
- Assumes command-line options always apply to the jump hosts too.