In this tutorial, you will learn how to run remote Docker commands over an SSH connection.
Docker is usually administered locally on the host it is running. The Docker client, by default, will connect to the Unix socket when communicating with the daemon. In this tutorial, you will learn how to connect the client to a remote host using SSH.
Before opening your Docker host to remote SSH connections, it is strongly advised to allow only trusted traffic.
A firewall or network policy should block all traffic to the Docker host, and whitelist traffic to trusted IPs or Subnets.
SSH Public RSA Key
Accessing a system via SSH requires a user with privileges to the Docker daemon. It also requires a public RSA key from your local user. The key should not be protected by a passphrase, as you will not be prompted to enter one.
If a RSA key-pair has a passphrase, the remote Docker host connection will fail.
Create a new RSA key-pair by running the following command.
With the key-pair, copy your public key to the user of the remote host using the
ssh-copy-id [email protected]
Verify your public key was successfully added to user1‘s profile by SSHing into the remote host. If you successfully login without being prompted for a password or a passphrase, you are ready for executing remote docker commands.
Remote Docker client SSH Connection
You are finally ready to remotely administer your Docker host. Verify your access to the remote by listing running containers.
docker -H ssh://[email protected].host ps
If everything was done successfully you will see a table of running containers.
Having to use the
-H flag every time you connect could be a pain, especially if you find yourself working with a remote host frequently. Docker will look for a
DOCKER_HOST environment variable when executing commands. If it is set and exported you can avoid having to specify the remote host.
For example, let’s set the
DOCKER_HOST environment variable to use our SSH connection.
export DOCKER_HOST=ssh://[email protected]
To verify you are indeed executing commands to a remote Docker host, run the
docker info command. This will output information about the host you’re connected to.
In our case we are running the command from a MacBook. However, when we execute the command above we can see it was done against our Ubuntu 20.04 server.
Client: Debug Mode: false Server: Containers: 1 Running: 0 Paused: 0 Stopped: 1 Images: 1 Server Version: 19.03.12 Storage Driver: overlay2 Backing Filesystem: extfs Supports d_type: true Native Overlay Diff: true Logging Driver: json-file Cgroup Driver: cgroupfs Plugins: Volume: local Network: bridge host ipvlan macvlan null overlay Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog Swarm: inactive Runtimes: runc Default Runtime: runc Init Binary: docker-init containerd version: 7ad184331fa3e55e52b890ea95e65ba581ae3429 runc version: dc9208a3303feef5b3839f4323d9beb36df0a9dd init version: fec3683 Security Options: apparmor seccomp Profile: default Kernel Version: 5.4.0-42-generic Operating System: Ubuntu 20.04.1 LTS OSType: linux Architecture: x86_64 CPUs: 2 Total Memory: 3.844GiB Name: hackbox ID: BN37:5UCL:2DMY:WO2Z:KJRA:XU3F:VZXW:OKRL:ISIK:24OX:TANH:QDGK Docker Root Dir: /var/lib/docker Debug Mode: false Registry: https://index.docker.io/v1/ Labels: Experimental: false Insecure Registries: 127.0.0.0/8 Live Restore Enabled: false
In this tutorial, you learned how to connect to a remote Docker host using SSH. This a very secure and common way of connecting with remote hosts, and it allows you to control your containers remotely.
This setup is very useful for Jenkins CI\CD pipelines, as the Jenkins server can perform actions against a remote host. This could be the spin-up containers for integration testing, or it could be to deploy a new Docker container into production.