See all OpenBSD related FAQ
How do I reuse ssh connection using multiplexing to speed up remote login procedure with OpenSSH client under Linux, macOS, *BSD and Unix-like operating systems?

Using SSH Multiplexing on Linux or Unix to Speed Up Login
You can reuse the connection to the remote server using controlmaster directive. To enables the sharing of multiple sessions over a single network connection to add controlmaster after host directive. When set to yes ssh client will listen for connections on a control socket specified using the ControlPath argument. These sessions will try to reuse the master instance’s network connection rather than initiating new ones, but will fall back to connecting normally if the control socket does not exist, or is not listening. Multiplexing is nothing but the ability to send more than one signal over a single line or connection. OpenSSH can reuse an existing ssh TCP connection using multiplexing.
Tutorial details
Difficulty level Easy
Root privileges No
Requirements Linux or Unix terminal
Category Terminal/ssh
Prerequisites OpenSSH
OS compatibility AIX AlmaLinux Alpine Arch Debian Fedora FreeBSD HP-UX Linux macOS Mint NetBSD OpenBSD openSUSE Pop!_OS RHEL Rocky Stream SUSE Ubuntu Unix WSL
Est. reading time 7 minutes

Setting up ssh multiplexing to reuse SSH connection

WARNING! These examples requires OpenSSH version 4.0 or higher.

Open ~/.ssh/config file (ssh client configuration file). If you need system wide settings add to the /etc/ssh/ssh_config file:
$ vi ~/.ssh/config
Append following code to reuse ssh connection for all hosts:

host *
    controlmaster auto
    controlpath /tmp/ssh-%r@%h:%p

Where,

  1. controlmaster auto: Set controlmaster to auto
  2. controlpath /tmp/ssh-%r@%h:%p: Specify the path to the control socket used for connection sharing. In the path, %h will be substituted by the target host name, %p the port, and %r by the remote login username. It is recommended that any ControlPath used for opportunistic connection sharing include at least %h, %p, and %r. This ensures that shared connections are uniquely identified.

A note about ControlPath tokens

The ControlPath directive accepts the tokens %%, %C, %h, %i, %L, %l, %n, %p, %r, and %u. The

Table 1: Token keywords
Keywords Description
%% A literal ‘%’.
%C Hash of %l%h%p%r.
%d Local user’s home directory.
%h The remote hostname.
%i The local user ID.
%L The local hostname.
%l The local hostname, including the domain name.
%n The original remote hostname, as given on the command line.
%p The remote port.
%r The remote username.
%T The local tun(4) or tap(4) network interface assigned if tunnel forwarding was requested, or “NONE” otherwise.
%u The local username.

You can also match any host in the 192.168.0.[0-9] network range with following pattern:

Host 192.168.0.?
    controlmaster auto
    controlpath ~/.ssh/ssh-%r@%h:%p

For any host in the “.co.in” set of domains, reuse the connection:

Host *.co.in
    controlmaster auto
    controlpath ~/.ssh/private/master-%r@%h:%p

Reuse ALL SSH Connection To Speed Up Remote Login Process Using Multiplexing

Append as follows in your ~/.ssh/config file:

Host *
  IdentitiesOnly yes
  ControlPath ~/.ssh/controlmasters/%r@%h:%p
  ControlMaster auto
  ControlPersist yes

Save and close the file when using vi/vim text editor. Make sure directory set in the ControlPath such as ~/.ssh/controlmasters/ exists on the machine. Otherwise, use the mkdir command to make it:
$ mkdir -pv ~/.ssh/controlmasters/

Now connect as usual using the ssh command:
$ ssh vivek@vpn.nixcraft.co.in

Dealing with Bad owner or permissions message

You may be greeted with the following message:

Bad owner or permissions on /home/vivek/.ssh/config

Make sure ~/.ssh/config file is owned by a correct user account with permission. For example, I will only allow vivek users to read and write ~/.ssh/config file. No other groups and users on the system can read or write the ~/.ssh/config file using the chmod command and chown command:
$ chown vivek:vivek ~/.ssh/config
$ chmod 0600 ~/.ssh/config
# verify permissions #
$ ls -l ~/.ssh/config
$ stat ~/.ssh/config

ssh bad owner or permissions on .ssh_config file

Fixing ssh command “bad owner or permissions” on .ssh_config file message

Next, time you connect again it will use connection socket /tmp/ssh-vivek@vpn.nixcraft.in:22 to speed up things. You don’t have to input password or anything else. You need one connection to be active for the second to be accelerated. This also works with scp / sftp etc:
$ scp /path/to/file.txt vivek@vpn.nixcraft.co.in:/tmp

Compare ssh command with and without multiplexing

You can compare the time it takes to run command on a slow remote server, using time. First, run time command without multiplexing (remove entries from ~/.ssh/config file):
$ time ssh vivek@vpn.nixcraft.co.in /path/to/command
$ time ssh -o 'ControlMaster=no' vivek@vpn.nixcraft.co.in /bin/true

Sample outputs:

real	0m3.546s
user	0m0.016s
sys	0m0.008s

Now, run same command with multiplexing (add entries to ~/.ssh/config):
$ time ssh vivek@vpn.nixcraft.co.in /path/to/command
$ time ssh vivek@vpn.nixcraft.co.in true

Sample outputs:

real	0m0.621s
user	0m0.006s
sys	0m0.004s

How to disable multiplexing for a single ssh command session?

Run command as follows with ControlMaster set to no:
$ ssh -o 'ControlMaster=no' vivek@vpn.nixcraft.co.in
If a master is already present, then try:
$ ssh -o 'ControlPath=no' vivek@vpn.nixcraft.co.in
The string none is used to disable connection sharing as described by the ControlMaster directive.

How to find out or check the status of multiplexing

$ ssh -O check vivek@vpn.nixcraft.co.in
Sample outputs:

Master running (pid=64134)

How to stop multiplexed connections

To gracefully shutdown multiplexing pass the -O stop option to the ssh command:
$ ssh -O stop vivek@ vivek@vpn.nixcraft.co.in
Sample outputs:

Stop listening request sent.

Pass the -O exit option to remove the control socket and immediately terminates all existing connections, run:
$ ssh -O exit vivek@vivek@vpn.nixcraft.co.in
Sample outputs:

Exit request sent.

And all of your ssh session will terminated with the following message:

Shared connection to vpn.nixcraft.co.in closed.

A sample session output

Fig.01: How To Reuse SSH Connection To Speed Up Remote Login Process Using Multiplexingn

Fig.01: A sample session that shows how to reuse SSH connection to speed up login with multiplexing

Using ssh multiplexing with ProxyCommand

You can go through one host to reach another server. In this example, you reach to internal host called 10.70.203.66 via vpn.nixcraft.co.in:

Host internal
  HostName 10.70.203.66
  User vivek
  ProxyCommand ssh vivek@vpn.nixcraft.co.in -W %h:%p
  ControlPath ~/.ssh/controlmasters/%r@%h:%p
  ControlMaster auto

Just type the following command to go through ‘vpn.nixcraft.co.in’ to reach another server called ‘internal’:
$ ssh internal

Say hello ControlPersist option

When ControlPersist used in conjunction with ControlMaster, specifies that the master connection should remain open in the background (waiting for future client connections) after the initial client connection has been closed. You can set it as follows:

  1. ControlPersist no : The master connection will not be placed into the background, and will close as soon as the initial client connection is closed.
  2. ControlPersist yes : The master connection will remain in the background indefinitely (until killed or closed via a mechanism such as the ssh -O exit user@host option. Further, if set to yes then, if set to a time in seconds, or a time in any of the formats documented in sshd_config(5), then the backgrounded master connection will automatically terminate after it has remained idle (with no client connections) for the specified time. For example, ControlPersist 10m.

Here is an updated config file:

Host internal
  HostName 10.70.203.66
  User vivek
  ProxyCommand ssh vivek@vpn.nixcraft.co.in -W %h:%p
  ControlPath ~/.ssh/controlmasters/%r@%h:%p
  ControlMaster auto
  ControlPersist yes

A note about X11, ssh-agent and port forwarding

Please note that X11 and ssh-agent forwarding is supported over these multiplexed connections, however the display and agent forwarded will be the one belonging to the master connection i.e. it is not possible to forward multiple displays or agents. However, you can create new session as follows for port forwarding:
$ ssh -M -S /tmp/3001.port.forwording -L 3001:localhost:3001 -N -f vivek@vpn.nixcraft.co.in

Summing up

You learned about SSH multiplexing on Linux or Unix-like systems. The main advantage is that the burden of creating new TCP connections and negotiating the secure connection is reduced. In addition, by using this simple trick, we can speed up our ssh session. See ssh man pages using the man command:
$ man ssh
$ man ssh_config

See “OpenSSH Config File Examples For Linux / Unix Users” and “OpenSSH security tips” for more info.

This entry is 14 of 23 in the Linux/Unix OpenSSH Tutorial series. Keep reading the rest of the series:
  1. Top 20 OpenSSH Server Best Security Practices
  2. How To Set up SSH Keys on a Linux / Unix System
  3. OpenSSH Config File Examples For Linux / Unix Users
  4. Audit SSH server and client config on Linux/Unix
  5. How to install and upgrade OpenSSH server on FreeBSD
  6. Ubuntu Linux install OpenSSH server
  7. Install OpenSSH server on Alpine Linux (including Docker)
  8. Debian Linux Install OpenSSH SSHD Server
  9. Configure OpenSSH To Listen On an IPv6 Address
  10. OpenSSH Server connection drops out after few minutes of inactivity
  11. Display banner/message before OpenSSH authentication
  12. Force OpenSSH (sshd) to listen on selected multiple IP address only
  13. OpenSSH Change a Passphrase With ssh-keygen command
  14. Reuse SSH Connection To Speed Up Remote Login Process Using Multiplexing
  15. Check Syntax Errors before Restarting SSHD Server
  16. Change the ssh port on Linux or Unix server
  17. OpenSSH Deny or Restrict Access To Users and Groups
  18. Linux OpenSSH server deny root user access / log in
  19. Disable ssh password login on Linux to increase security
  20. SSH ProxyCommand example: Going through one host to reach server
  21. OpenSSH Multiplexer To Speed Up OpenSSH Connections
  22. Install / Append SSH Key In A Remote Linux / UNIX Servers Authorized_keys
  23. Use ssh-copy-id with an OpenSSH Server Listening On a Different Port

🥺 Was this helpful? Please add a comment to show your appreciation or feedback.

nixCrat Tux Pixel Penguin
Hi! 🤠
I'm Vivek Gite, and I write about Linux, macOS, Unix, IT, programming, infosec, and open source. Subscribe to my RSS feed or email newsletter for updates.

17 comments… add one
  • didZ Feb 9, 2022 @ 15:40
    ssh -o 'ControlMaster=no' vivek@vpn.nixcraft.co.in

    does not disable multiplexing if a master is already present.

    ssh -o 'ControlPath=none' vivek@vpn.nixcraft.co.in

    does.

    • 🛡️ Vivek Gite (Author and Admin) Vivek Gite Feb 9, 2022 @ 18:55

      yes, thanks for the heads up. I updated the page.

  • Jonathan Feb 9, 2022 @ 21:50

    Hmm, I get “Bad owner or permissions on /home//.ssh/config. It looks like this:
    [redacted@redacted .ssh]$ vim config

    Host *
      IdentitiesOnly yes
      ControlPath ~/.ssh/controlmasters/%r@%h:%p
      ControlMaster auto
      ControlPersist yes

    /etc/ssh/ssh_config looks like this:

    host *
            controlmaster auto
            controlpath /tmp/ssh-%r@%h:%p
    • 🛡️ Vivek Gite (Author and Admin) Vivek Gite Feb 10, 2022 @ 7:02

      Your ~/.ssh/config has bad permissions. List it as follows

      ls -l ~/.ssh/config

      Use the chown command to own the file (say user and group is vivek):

      chown vivek:vivek ~/.ssh/config

      Then make sure only vivek user and vivek group can read the file:

      chmod 0640 ~/.ssh/config

      You can also take away group permission (only vivek user can read and write):

      chmod 0600 ~/.ssh/config
  • Lost in the Forest Aug 4, 2023 @ 16:35

    If the server has a limit to the number of connections, does this have the side effect of getting around that limit? Say the server is configured to only allow 5 SSH connections. Could you use this to start 10 separate scp sessions?

    • 🛡️ Vivek Gite (Author and Admin) Vivek Gite Aug 4, 2023 @ 18:11

      The MaxSessions in /etc/ssh/sshd_config (server side) specifies the maximum number of open shell, login or subsystem (e.g. sftp) sessions permitted per network connection. Multiple sessions may be established by clients that support connection multiplexing. Setting MaxSessions to 1 will effectively disable session multiplexing, whereas setting it to 0 will prevent all shell, login and subsystem sessions while still permitting forwarding. The default is 10. I hope this helps!

Leave a Reply

Your email address will not be published. Required fields are marked *

Use HTML <pre>...</pre> for code samples. Your comment will appear only after approval by the site admin.