Multiplexing, sometimes referred to as muxing, is a way of making use of one connection for a number of signals.
The internet connection you're reading this on may have been multiplexed at some stage along its physical route to your building or local communications tower and can used to reduce the overall cost of having to lay multiple cables to endpoints.
There is an article on Wikipedia about multiplexing which goes in to more depth about what and where else in the world its used.
We can use multiplexing for our SSH connections to help speed up processes where multiple commands need to be executed on the same server or via the same jump host.
Your SSH client can create a control ( 'master' ) connection to the server which can then be used for multiple sessions without having to create a new TCP connection for each one. OpenSSH shares this connection via a socket that it can create on disk.
You can either do this via your command line by setting some options at run time or you can add some configuration options to your SSH client configuration file.
For ease and and some clarity; here's a quick configuration example for our jump-box:
Host jump-box HostName jump-box.example.org ControlPath ~/.ssh/controlmasters/%r@%h:%p ControlMaster auto ControlPersist 10m
Once this is in place the next connection you make to jump-box will create a control connection and then create a session within in it which will contain your terminal.
The important configuration bits here are the
Sets the place the socket file will be created. openSSH uses this to talk to the control process. The
%p tokens correspond to the remote username, remote host and the port of the remote host respectively. As per our example this will create the control socket at
This ensures you get a different socket for each connection you make.
man 5 ssh_config for more info on the different tokens you can use here.
Sets how SSH will use the multiplexing. Here we set it to
auto so that our client will first check for existing connection and make use of it if one is found and if none are present one will be created. see
man 5 ssh_config for info on other options.
This tells SSH how long it should keep a control session open for after the last session has closed. We're using 10m in case we've forgotten something or want to repeat a task.
You'll need to adjust the configuration you put in to your SSH configuration file like so:
Host * ControlPath ~/.ssh/controlmasters/%r@%h:%p ControlMaster auto ControlPersist 10m
All of your new SSH connections will now be multiplexed
Port forwarding and related controls are transferred to the control session. So restarting a SSH session with the same port forwarding options set will show an error message about the port already being in use.
The same controls you would expect to be accessible via the escape sequence are not present either.
Instead you have to control these features via the -O command line option. Here are some examples:
To add a new forward without starting a new session:
ssh -O forward -L 8080:localhost:80 jump-box.example.org
Removing a port forward:
ssh -O cancel -L 8080:localhost:80 jump-box.example.org
Note: If you specified a user on your initial connection ( user@server ) you also have to specify it here to find the control socket
Unfortunately there doesn't appear to be a way to list the existing forwarding options you may have set.
The only service I've been unable to use multiplexing with is bitbucket and the reasons for why are noted here
You can remove hosts from the multiplex configuration by adjusting the Host line, for example:
Host * !bitbucket.org
This would remove the bitbucket domain from this host configuration block
Happy Multiplexing ! .o/