SSH ControlMaster

Introduction

If you use a YubiKey or similar hardware token for SSH authentication, you’ll know the frustration of having to touch it every time you open a new connection to the same host. This becomes particularly painful when running automation scripts that make multiple SSH connections.

SSH ControlMaster solves this by allowing multiple SSH sessions to share a single network connection. Once you’ve authenticated once, subsequent connections to the same host reuse the existing connection—no additional authentication required.

Configuration

Add the following to your ~/.ssh/config file:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

Then create the sockets directory:

mkdir -p ~/.ssh/sockets

Configuration Explained

• ControlMaster auto: Automatically use an existing master connection if available, or create a new one.
• ControlPath: Where to store the socket file. %r is the remote username, %h is the host, and %p is the port.
• ControlPersist 600: Keep the master connection open for 600 seconds (10 minutes) after the last session closes.

Usage

With this configuration, SSH connection sharing happens automatically:

1. First connection to a host: authenticate as normal (touch YubiKey).
2. Subsequent connections within 10 minutes: instant connection, no authentication needed.

This works for all SSH-based commands including ssh, scp, rsync, and git over SSH.

Benefits for Automation

The main benefit is enabling automation scripts that make multiple SSH connections without requiring user interaction for each one.

For example, a deployment script that:

1. Copies files with scp
2. Runs remote commands with ssh
3. Syncs directories with rsync

Previously this would require touching your YubiKey three times. With ControlMaster, you authenticate once at the start, and all subsequent connections reuse that authentication.

Manual Control

You can manually manage connections if needed:

# Check if a master connection exists
ssh -O check user@host

# Terminate a master connection
ssh -O exit user@host