16 02 | 2012

OpenSSH tip: connection sharing

Written by Tanguy

Classified in : Homepage, Debian, Command line, To remember

The last versions of OpenSSH brought an interesting feature: sharing multiple sessions over a single connection. When enabled, this is how it works:

  1. The first time you open an SSH connection to a server (including anything that works on top of SSH, like SCP, SFTP, rsync or Git), it opens a network connection as usual. It also opens a local Unix socket and listens to it for later use.
  2. The next times you open an SSH connection to that server while the first one is still open, instead of opening a new network connection, it connects to that local Unix socket and lets the first SSH client carry its new session.


  • By reusing an existing connection, it saves file descriptors, thus power, baby seals and kittens, and most of all it is faster than opening new ones.
  • It does not require a new authentication, so it saves you the time to type your password or you key passphrase, and the time for the challenge-response to take place.
  • Since you do not have to authenticate again, you can take advantage of you shell's power features to auto-complete remote paths for SCP, SFTP or rsync over SSH. That is, if you use a powerful shell, of course.


Just like SSH agents, there is one major side-effect to take into account: new remote sessions can be opened without a password. Never use such a feature on a public computer if you are used to temporarily leave running sessions: here, locking them would not protect other people to get a shell access to your remote account!


In ~/.ssh/config or /etc/ssh/ssh_config:

ControlPath ~/.ssh/control-%r@%h:%p
ControlMaster auto
ControlPersist 1
The name template for the session sharing Unix sockets. See the ssh_config(5) manpage for the syntax.
Lets the SSH client use the session sharing socket if it exists or create it and listen otherwise.
Usually, the first client to a given server is in charge of the connection sharing. It will then stay in foreground even if you terminate the session it is used for, until every other clients using its socket has finished, and forcefully terminating it will have the effect of terminating these clients! With that option, the master connection is put in background and will only terminate when no client needs it any more (one second after that, in fact), and you will be able to terminate the first session without kicking the other ones.

Try it! Apply this configuration and connect several times to a single host, to see the difference…


friday 17 february 2012 à 00:14 Timo Juhani Lindfors said : #1

The "Disadvantages" section is bit misleading. You can already open new remote sessions if you use the sshjack tool (it attaches to the ssh client using ptrace and forces it to open a new session for you).

friday 17 february 2012 à 02:18 Daniel Kahn Gillmor said : #2

Also, if you use:

ControlMaster autoask

instead, you can make it so you're prompted (via ssh-askpass, typically) when another process tries to make use of the channel.

The same is true for ssh-agent -- you can ask the ssh-agent to prompt you when a key is used as long as you inject the key to the agent with the -c option to ssh-add.

There are ways around these prompting techniques if an attacker has full control over your local machine, but they're more difficult to pull off, and many of them don't work at all if the attacker is running as a process that is isolated in any meaningful way.

friday 17 february 2012 à 03:01 anonymous said : #3

Let's extend the disadvantages a bit:
* If you scp a file, it reuses your interactive connection and now sends your file using IPQos lowdelay clogging your bandwidth. Say good bye to interactive typing.
* You just started scp and then log in interactively? Now your scp never finishes.

This not only "works" with scp, but also with git, rsync and other tools. So maybe turning on this feature isn't that a good idea.

friday 17 february 2012 à 11:49 rjc said : #4

anonymous, +1

I used to use this feature myself and the main disadvantage is the first connection being locked until the last one exits. Scenario:

I logged on to a machine to do a quick maintenance task, then connected with another (this time under tmux) to do one lasting a bit longer. Not wanting to interrupt the latter I had to leave my screen locked as the first one wasn't run under tmux or screen. If only there was a way of the second (or third, fourth...) connection to take over as the main one, or better yet, for it to automatically "jump" until the last connection.
Otherwise it's only useful as a detached job or interactive one locking one of your terminals.

friday 17 february 2012 à 16:38 Tanguy said : #5

@rjc : Well, this is exactly why I introduced the option “ControlPersist”, which forks and backgrounds the connection sharing thread. This way, the first client can terminate without bothering the other ones.

friday 17 february 2012 à 16:38 Tanguy said : #6

@Timo Juhani Lindfors : Excellent, I did not notice that option!

sunday 19 february 2012 à 00:37 Marius Gedminas said : #7

Thank you for mentioning ControlPersist -- without it ControlMaster is just unusable (killing all the sessions when your randomly close the one xterm that just happens to contain the first one? Ouch).

@friday: Ubuntu ships with a kernel security module (yama) that doesn't allow random processes ptrace each other (tweakable by a sysctl setting, if you have legitimate debugging needs). Fedora recently announced plans to reinvent that using a SELinux policy.

monday 20 february 2012 à 09:39 rjc said : #8

@Tanguy: That's great! Finally! I guess I should've read it all the way through before I opened my mouth ;^)

friday 24 february 2012 à 18:53 Marius Gedminas said : #9

I've discovered another con not mentioned here that made me turn ControlMaster off: it disables the use of the ~C escape to add new port forwardings and whatnot.

friday 06 july 2012 à 17:01 Tanguy said : #10

@Marius Gedminas : I think this is new, but it is now possible to use port forwarding options with new clients that use an existing master connection, with the effect of adding these port forwards to the master connection.

Write a comment

What is the fifth letter of the word hedryz? :