SSH and docker-compose

Vanya Yani
Feb 5 · 3 min read

If you’re using OS X and encrypt ssh keys using ssh-protected resources in containers is going to be PITA. Here are the steps I went through figuring out the solution.

Straightforward approach

One might think that there’s no problem. Just mount your ssh folder:

- ~/.ssh:/root/.ssh:ro

This should be working, right?

User problem

Next thing we’ll notice is that we’re using the wrong user id. Fine, we’ll write a script to copy and change the owner of ssh keys. We’ll also set ssh user in config so that ssh server knows who’s connecting.

- ~/.ssh:/root/.ssh-keys:ro
command: sh -c ‘./ && ...’
mkdir -p ~/.ssh
cp -r /root/.ssh-keys/* ~/.ssh/
chown -R $(id -u):$(id -g) ~/.ssh
cat <<EOF >> ~/.ssh/config

SSH key passphrase problem

Often we protect SSH keys using a passphrase. That wouldn’t work in docker since it’s impractical to enter a passphrase each time we start a container. We could remove a passphrase (see example below), but there’s a security concern.

openssl rsa -in id_rsa -out id_rsa2
# enter passphrase
# replace passphrase-encrypted key with plaintext key:
mv id_rsa2 id_rsa

With compose secrets you can put your passphrase to a file, but that defeats the purpose of ssh key encryption.

SSH agent solution

You may have noticed that locally you don’t need to enter a passphrase each time you need ssh access. Why is that? That’s what SSH agent is for. SSH agent is basically a server which listens to a special file, unix socket, called “ssh auth sock”. You can see its location on your system:

# /run/user/1000/keyring-AvTfL3/ssh

SSH client communicates with SSH agent through this file so that you’d enter passphrase only once. Once it’s unencrypted, SSH agent will store it in memory and send to SSH client on request. Can we use that in Docker? Sure, just mount that special file and specify a corresponding environment variable:


We don’t even need to copy keys in this case. To confirm that keys are available we can use ssh-add utility:

if [ -z "$SSH_AUTH_SOCK" ]; then
echo "No ssh agent detected"
ssh-add -l

The problem of unix socket mount support in Docker for Mac

Unfortunately for OS X users, Docker for Mac has a number of shortcomings, one of which is its inability to share Unix sockets between Mac and Linux. There’s an open issue in D4M Github. As of February 2019 it’s still open.

So, is that a dead end? No, there is a hacky workaround.

SSH agent forwarding solution

Luckily, this issue isn’t new. Long before Docker there was a way to use local ssh keys within a remote ssh session. This is called ssh agent forwarding. The idea is simple: you connect to a remote server through ssh and you can use all the same remote servers there, thus sharing your keys.

With Docker for Mac we can use a smart trick: share ssh agent to the docker virtual machine using TCP ssh connection, and mount that file from virtual machine to another container where we need that SSH connection. Here’s a picture to demonstrate the solution:

First, we create an ssh session to the ssh server inside a container inside a linux VM through a TCP port. We use a real ssh auth sock here.

Next, ssh server forwards our ssh keys to ssh agent on that container. SSH agent has a Unix socket which uses a location mounted to Linux VM. I.e. Unix socket works in Linux. Non-working Unix socket file in Mac has no effect.

After that we create our useful container with an SSH client. We share the Unix socket file which our local SSH session uses.

There’s a bunch of scripts that simplifies that process:


Getting SSH to work in Docker could’ve been easier. But it can be done. And it’ll likely to be improved in the future. At least Docker developers are aware of this issue. And even solved it for Dockerfiles with build time secrets. And there’s a suggestion how it could support Unix domain sockets.