skip to content
Aidan Gallagher Aidan Gallagher

SSH ControlMaster

/ 2 min read

View more blogs with the tag ssh , View more blogs with the tag automation
Table of Contents

Introduction

Hardware security keys like YubiKeys are useful for SSH authentication. The private key is stored on a tamper-resistant device and requires physical touch to use. This prevents malware from stealing the key or signing requests without user interaction.

However the physical touch requirement can become tedious. Opening a terminal, fetching from git, and running deployment scripts all require separate authentications. This is especially problematic for automation scripts that make multiple SSH connections to the same host.

SSH ControlMaster solves this by allowing multiple SSH sessions to share a single network connection. Once you have authenticated, subsequent connections to the same host reuse the existing connection without additional authentication.

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

Comments