How to Configure SSH Connection Multiplexing

SSH connection multiplexing lets later sessions reuse an existing encrypted and authenticated connection. It reduces repeated key exchange and login latency, which is especially noticeable for Git operations or many short administrative commands.

Configure a safe control path

Host *.example.net
    ControlMaster auto
    ControlPersist 5m
    ControlPath ~/.ssh/control/%C

Create ~/.ssh/control with permissions accessible only to your user. %C expands to a hash of connection parameters, avoiding long Unix-socket paths and collisions better than a handwritten hostname pattern. Confirm token support in the OpenSSH version you deploy.

ControlMaster auto asks the client to use an existing master or create one. ControlPersist 5m allows that master to remain briefly after the initiating client exits. Choose a lifetime based on the workstation’s threat model rather than leaving masters alive indefinitely.

Observe and control the master

ssh -O check host.example.net
ssh -O exit host.example.net

These commands query or terminate the master selected by the same host configuration. Verbose mode, ssh -vv, shows whether a control socket was found and whether a new connection was negotiated.

Understand the security boundary

Anyone who can access the control socket as its owner may be able to open additional channels over the authenticated connection. Protect the socket directory and do not place it in a shared /tmp path without a private subdirectory and strict permissions.

Multiplexing reuses transport; it does not disable host-key verification, bypass server authorization, or forward an authentication agent automatically. Options are resolved from SSH configuration before the control connection is selected, and materially different connection settings may require a distinct control path or a fresh master.

Avoid surprising automation

Long-lived masters can outlast changed credentials, routing, port forwards, or server policy. For reproducible diagnostics, run with ControlMaster=no or an isolated configuration to force a fresh handshake. Use multiplexing as a latency optimization, not as hidden session state that jobs require for correctness.

How long this capability has actually been available

OpenSSH has supported connection multiplexing since version 3.9, released August 18, 2004 — over two decades of availability by now, though ControlPersist specifically (letting a master connection outlive the client that created it, rather than only being reusable while that original client remains running) arrived somewhat later. Given how long-standing and stable this feature is, an OpenSSH version genuinely too old to support ControlMaster/ControlPath is now a rare thing to actually encounter — if multiplexing isn’t working as documented, a client configuration issue or an incompatible ControlPath value is a far more likely cause than the client software itself lacking the feature.

Why “too long for Unix domain socket” is a real, specific error to expect

Unix domain socket paths are capped at 108 bytes on Linux (104 on some BSD-derived systems) — a genuine kernel-level limit, not an OpenSSH-specific restriction. A ControlPath built from a long username, a long hostname, and a deeply nested directory can exceed that limit and fail with exactly this error, which is precisely why %C (a hash of the connection parameters, rather than the literal hostname and username concatenated) is the recommended token: it keeps the resulting path short and fixed-length regardless of how long the actual hostname or username happens to be, sidestepping the limit entirely rather than requiring you to manually shorten paths as you connect to longer-named hosts.

Combining multiplexing with a jump host

Host bastion
    HostName bastion.example.net
    ControlMaster auto
    ControlPersist 5m
    ControlPath ~/.ssh/control/%C

Host internal-*
    ProxyJump bastion
    ControlMaster auto
    ControlPersist 5m
    ControlPath ~/.ssh/control/%C

ProxyJump and connection multiplexing compose cleanly: once a master connection to the bastion itself exists, every subsequent jump through it reuses that same authenticated transport rather than renegotiating a fresh connection to the bastion for each internal host. Configure ControlMaster/ControlPath on both the bastion’s own Host block and the internal hosts that jump through it — some tooling built on top of SSH does not reliably keep the bastion’s control socket open across jumps on its own, so an explicit master for the bastion host specifically is worth confirming with ssh -O check bastion rather than assuming it’s automatically covered by the internal host’s own multiplexing configuration.

The one server-side limit multiplexing can actually hit

sshd_config’s MaxSessions directive caps how many multiplexed sessions a single TCP connection may carry — 10 by default on most OpenSSH server installations. A workflow opening many simultaneous multiplexed sessions against the same host (parallel Git operations, several terminal tabs, a tool spawning many short-lived connections concurrently) can hit that ceiling and start failing new sessions while existing ones continue working normally, which is a genuinely confusing failure mode if you don’t already know the limit exists — it looks like an authentication or network problem rather than a simple counter. Raising MaxSessions server-side (where you control the server) or simply reducing how many concurrent sessions a client-side workflow opens against one multiplexed connection are the two available fixes; multiplexing’s latency benefit doesn’t require raising the limit for typical interactive use, only for workflows deliberately parallelizing many sessions against one host at once.

Related:

Sources: