SSH: Multiplexing
Tags: ssh
Published: 2020-01-11 22:37:22

## 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](https://en.wikipedia.org/wiki/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:

```ssh

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:


```ssh
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:

```bash
ssh -O forward -L 8080:localhost:80 jump-box.example.org
```

Removing a port forward:

```bash
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](https://jira.atlassian.com/browse/BCLOUD-13465)


You can remove hosts from the multiplex configuration by adjusting the Host line, for example:

```ssh
Host * !bitbucket.org
 
```

This would remove the bitbucket domain from this host configuration block





Happy Multiplexing ! .o/