Skip to content
Shell & TerminalHow-To Published Updated 4 min readViews unavailable

How to Configure SSH Connection Multiplexing

OpenSSH can reuse one authenticated transport for later sessions - configure a private control socket, bounded persistence, and explicit cleanup.

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. To force a fresh destination transport rather than reuse that host’s existing master, set ControlPath=none for that invocation:

ssh -o ControlPath=none host.example.net

ControlMaster=no alone is not sufficient: OpenSSH clients can still attach to a master at the configured ControlPath with ControlMaster left at its default no. With ProxyJump, the jump host is a separate SSH connection and may still use its own configured master. 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 release notes document connection multiplexing in version 3.9 (released August 18, 2004) and ControlPersist in version 5.6 (released August 23, 2010). If a client does not recognize these options, check its implementation and version rather than assuming current OpenBSD documentation applies to every SSH client or vendor build.

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

Unix-domain socket pathname limits are platform-specific kernel interface limits, not OpenSSH-specific restrictions. Linux provides a 108-byte sun_path array, while OpenBSD documents a maximum pathname of 104 characters; the usable Linux pathname must also account for its terminating NUL byte. A ControlPath built from a long username, hostname, and directory can exceed the platform limit. OpenSSH recommends %C as an alternative to including %h, %p, and %r literally; it expands to a fixed-size hash of connection parameters and helps keep the socket path short. It does not remove the need to keep the parent directory itself short enough.

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 can compose: the SSH process used to connect through a bastion can reuse that bastion’s master when its effective host configuration selects the same control socket and the master is still available. The destination connection has its own transport and control socket. Configure the bastion explicitly, then confirm the selected master with ssh -O check bastion; do not assume the destination host’s ControlPath also multiplexes the separate bastion connection.

The one server-side limit multiplexing can actually hit

sshd_config’s MaxSessions directive caps the number of open shell, login, or subsystem sessions permitted per network connection. The OpenSSH default is 10, but server configuration can override it. A workflow opening many simultaneous multiplexed sessions against the same host can hit that ceiling and fail to open additional sessions. Where you administer the server, adjust the configured limit deliberately; otherwise, reduce client-side concurrency. The latency benefit of multiplexing does not require raising the limit for ordinary interactive use.

Related:

Sources:

Comments