SSH: Multiplexing

What is it ?

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.

What is the link to SSH ?

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.

How does SSH do this ?

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.

How can I do it ?

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 ControlPath ControlMaster and ControlPersist options.

ControlPath

Sets the place the socket file will be created. openSSH uses this to talk to the control process. The %r %h and %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 ~/.ssh/controlmasters/user@jump-box.example.org:22.
This ensures you get a different socket for each connection you make.
See man 5 ssh_config for more info on the different tokens you can use here.

ControlMaster

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.

ControlPersist

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.

How can I use this for all of my SSH connections ?

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

Controlling Port forwarding when multiplexing

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.

Server side support

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/