Shane Rainville
Posted on

How to Run Remote Docker Commands using SSH

Overview

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.

Network Security

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. 

ssh-keygen

With the key-pair, copy your public key to the user of the remote host using the ssh-copy-id command.

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] 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.

docker info

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

Conslusion

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.

Related Posts: