skip to content

Client Config and Multiplexing

~/.ssh/config turns long command lines into Host aliases with per-host User, Port and IdentityFile, and ControlMaster reuses one connection for many sessions. It comes up as a fleet-speed question.

on this pageshow

explore

questions

6

In OpenSSH, how do ControlMaster, ControlPath and ControlPersist make hundreds of repeat ssh sessions to the same host fast?

level: middleimportance: must knowfreq 34%

answer

  1. one connection, many channels
  2. a Unix socket on the client
  3. skip the handshake on reuse
  4. keep the master after logout
  5. -O check and -O exit

basics

~20 s

The first ssh becomes a master that keeps the authenticated connection and listens on a local socket at ControlPath; later sessions to the same destination open channels through it, skipping TCP setup, key exchange and authentication. ControlPersist keeps the master alive afterwards.

solid answer

~40 s

SSH already carries many channels over one connection, and OpenSSH's multiplexing exposes that to separate `ssh` processes. With `ControlMaster auto`, the first connection to a destination becomes the **master** and listens on a Unix-domain socket named by `ControlPath`; later `ssh` runs find the socket and ask the master to open a new session, so they skip the TCP connect, key exchange and user authentication. `ControlPath ~/.ssh/cm/%C` gives each destination its own socket, since `%C` hashes the local host, remote host, port, user and ProxyJump. `ControlPersist 10m` keeps the master in the background for ten idle minutes after the first session ends. `ssh -O check web1` and `ssh -O exit web1` inspect or stop it. Since OpenSSH 10.0, `scp` and `sftp` reuse an existing master but no longer create one.

code

ini · 4 lines
ini
Host *.prod.internal.example
    ControlMaster auto
    ControlPath ~/.ssh/cm/%C
    ControlPersist 10m

go deeper

for a junior

Recall that multiplexing reuses one SSH connection for later sessions so they start instantly.

for a middle

Explain how ControlMaster auto, a %C-based ControlPath and ControlPersist work together, and how ssh -O check and exit manage the master.

for a senior

Show how you size parallel automation against MaxSessions, clear stale masters and keep the socket directory private.

for a principal

Weigh connection reuse speed against audit that expects one authentication per action, and decide where sharing is allowed.

## Why repeat sessions are slow without it Every fresh `ssh` run does the full setup: a TCP connection (through a bastion if `ProxyJump` is set), the key exchange, host-key verification and user authentication. On a nearby host that is a noticeable pause; through a bastion it happens twice. An automation run that opens hundreds of short sessions to the same sixty hosts pays it every time, and the servers' authentication logs fill with logins. SSH's connection protocol already multiplexes: one authenticated connection carries many **channels** (sessions, forwarded ports, subsystems). OpenSSH's **connection sharing** lets separate `ssh` processes on the client use one connection's channels. ## The three directives | Directive | Values | What it does | |---|---|---| | `ControlMaster` | `no` (default), `yes`, `ask`, `auto`, `autoask` | `yes` makes this ssh a master listening on the control socket; `auto` uses an existing master or becomes one if none exists | | `ControlPath` | a path with tokens, or `none` | where the control socket lives; must identify the destination uniquely | | `ControlPersist` | `no` (default), `yes` or `0`, or a time | keeps the master in the background after its first session closes; a time is an idle timeout | ```ini Host *.prod.internal.example ControlMaster auto ControlPath ~/.ssh/cm/%C ControlPersist 10m ``` Key points from the manual: - A client with `ControlMaster no` still **uses** a master if the socket at its `ControlPath` exists, and falls back to a normal connection when the socket is missing or not listening. - `ControlPath` should include at least `%h`, `%p` and `%r`, or `%C`, and sit in a **directory other users cannot write**. `%C` is a hash of the local host, remote host, port, remote user and ProxyJump value, which also keeps the path short; Unix-domain socket paths have a small length limit. - With `ControlPersist` set to a time, the master exits after that long with no client sessions; `yes` keeps it until it is killed or told to exit. ## Controlling a running master ```bash ssh -O check web1 # is a master running for this destination? ssh -O exit web1 # ask the master to exit ssh -O stop web1 # stop accepting new multiplexed sessions ssh -O conninfo web1 # connection details (added in 10.3) ``` `ssh -S path` names a control socket on the command line, and `-S none` disables sharing for one run. ## What sharing changes, and the traps 1. **Agent and X11 forwarding belong to the master.** The manual notes that the display and agent forwarded are those of the master connection, so a later session cannot forward a different agent. 2. **The server caps sessions per connection.** sshd's `MaxSessions` defaults to 10, so the eleventh simultaneous session on one master is refused. Parallel automation should keep concurrency per host below that or accept more masters. 3. **A master can go stale.** After a network change or a server restart, sessions can hang on a dead master; `ssh -O exit` (or removing the socket once no master is listening) clears it. 4. **Since OpenSSH 10.0, `scp` and `sftp` pass `ControlMaster no` to ssh.** With `ControlMaster auto` in the config, they no longer create a master as a side effect, but they still use one that already exists. ## When to use it Turn it on for hosts you hit repeatedly: automation fan-out, editors and file managers that open many sessions, and anything behind a bastion. Leave it off where every session must authenticate on its own, for example when audit expects one login per action, because the shared connection reuses the first authentication for every session that rides on it. ## Sizing it for an automation run For a run that opens hundreds of sessions across sixty hosts: - keep **per-host parallelism below the server's session limit**, since every multiplexed session counts against the one connection; - choose a `ControlPersist` long enough to bridge the gaps between tasks on the same host, but short enough that idle masters do not linger for days; - point `ControlPath` at a private directory that exists before the run starts, because ssh will not create it; - end the run with `ssh -O exit` for each host, or let `ControlPersist` expire them, so a changed bastion or key is picked up next time.

  • An automation run multiplexes forty parallel sessions to one host over a single master and some fail immediately. Why?
    sshd's `MaxSessions` limits sessions per network connection and defaults to 10. Every multiplexed session is a channel on the master's one connection, so sessions beyond the limit are refused. Cap per-host parallelism below the limit, or let separate connections carry the excess.
  • Why must `ControlPath` live in a directory other users cannot write?
    The socket is a door into an already authenticated connection. If another user could plant or replace the socket at your path, your later ssh runs could talk to their process instead of your master. A private directory such as `~/.ssh/cm` keeps the path under your control.
  • You enable `ForwardAgent` for one later session but the remote side sees no agent; why?
    With connection sharing, agent and X11 forwarding are those of the master connection. If the master was started without agent forwarding, later sessions cannot add a different agent; exit the master with `ssh -O exit` and reconnect with the setting you need.

  • Each multiplexed session repeats the key exchange over the same socket
  • A fixed ControlPath like ~/.ssh/sock is fine for every host
  • ControlPersist keeps the master alive after it is explicitly told to exit
  • Every multiplexed session can forward its own separate agent
  • scp with ControlMaster auto still starts a master in OpenSSH 10

Assumes OpenSSH 10.5; since 10.0 scp and sftp pass ControlMaster no and only reuse an existing master, and 10.3 added ssh -O conninfo and -O channels.

open as a page

Why does OpenSSH's client ignore `User alice` in a Host block placed after a `Host *` block, and how do you prove which value won?

level: middleimportance: must knowfreq 46%

basics

~20 s

ssh keeps the first value it obtains for each directive, reading every matching block top to bottom, so a User set earlier under Host * cannot be overridden later. Put specific blocks first, Host * last, and check with ssh -G.

open as a page

In OpenSSH's ~/.ssh/config, how does a Host block with HostName, User, Port and IdentityFile turn a long ssh command into `ssh web1`?

level: juniorimportance: should knowfreq 55%

basics

~20 s

A Host block names an alias pattern; when the name typed after ssh matches it, the client applies that block's HostName (the real address), User, Port and IdentityFile, so ssh web1 expands into the full connection.

open as a page

An OpenSSH client whose agent holds six keys is disconnected with 'Too many authentication failures'; why, and which ssh_config lines fix it?

level: middleimportance: should knowfreq 38%

basics

~20 s

Without IdentitiesOnly the client offers every key the agent holds as well as its configured files, and each key the server rejects counts toward sshd's MaxAuthTries (6 by default). Set IdentityFile and IdentitiesOnly yes in that host's block.

open as a page

Why do idle OpenSSH sessions through a NAT gateway or firewall freeze and drop, and how does ServerAliveInterval differ from TCPKeepAlive?

level: middleimportance: should knowfreq 27%

basics

~20 s

Stateful middleboxes drop idle TCP flows, so the next keystroke goes nowhere. ServerAliveInterval sends an encrypted request inside the SSH connection every N idle seconds and disconnects after ServerAliveCountMax (3) unanswered; TCPKeepAlive uses spoofable kernel probes.

open as a page

When does OpenSSH's ssh_config need a Match block instead of Host, and why must Match exec never see an attacker-chosen user or host name?

level: seniorimportance: nice to knowfreq 12%

basics

~20 s

Host matches only the typed name; Match tests other facts, such as the host after HostName substitution, the user, the local network or a command's exit status. Match exec expands tokens unquoted into a shell command, so a crafted name can inject commands.

open as a page