Giovanni

Giovanni

Docker Daemon API enablement and connection from another host

Pre-Requisite:

  • Docker installed on both your machines

Create the directory to store the configuration file.

sudo mkdir -p /etc/systemd/system/docker.service.d

Create a new file to store the daemon options.

sudo nano /etc/systemd/system/docker.service.d/options.conf

Now make it look like this and save the file when you’re done:

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H unix:// -H tcp://0.0.0.0:2375

Now, reload the systemd daemon and restart the docker service:

# Reload the systemd daemon.
sudo systemctl daemon-reload

# Restart Docker.
sudo systemctl restart docker

That’s going to let you continue to connect to the Docker daemon from within the VM thanks to -H unix://, but it also exposes the Docker Daemon with -H tcp://0.0.0.0:2375 so that anyone can connect to it over the non-encrypted port.

Let’s secure this port using TLS:

Use TLS (HTTPS) to protect the Docker daemon socket

If you need Docker to be reachable through HTTP rather than SSH in a safe manner, you can enable TLS (HTTPS) by specifying the tlsverify flag and pointing Docker’s tlscacert flag to a trusted CA certificate.

In the daemon mode, it only allows connections from clients authenticated by a certificate signed by that CA. In the client mode, it only connects to servers with a certificate signed by that CA.

Advanced topic

Using TLS and managing a CA is an advanced topic. Please familiarize yourself with OpenSSL, x509, and TLS before using it in production.

Create a CA, server, and client keys with OpenSSL

Note: Replace all instances of $HOST in the following example with the DNS name of your Docker daemon’s host.

First, on the Docker daemon’s host machine, generate CA private and public keys:

$ openssl genrsa -aes256 -out ca-key.pem 4096
$ openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem

Now that you have a CA, you can create a server key and certificate signing request (CSR). Make sure that “Common Name” matches the hostname you use to connect to Docker:

$ openssl genrsa -out server-key.pem 4096
$ openssl req -subj "/CN=$HOST" -sha256 -new -key server-key.pem -out server.csr

Next, sign the public key with our CA:

$ echo subjectAltName = DNS:$HOST,IP:10.10.10.20,IP:127.0.0.1 >> extfile.cnf
$ echo extendedKeyUsage = serverAuth >> extfile.cnf
$ openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -extfile extfile.cnf

For client authentication, create a client key and certificate signing request:

$ openssl genrsa -out key.pem 4096
$ openssl req -subj '/CN=client' -new -key key.pem -out client.csr

To make the key suitable for client authentication, create a new extensions config file:

$ echo extendedKeyUsage = clientAuth > extfile-client.cnf
$ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out cert.pem -extfile extfile-client.cnf

After generating cert.pem and server-cert.pem, you can safely remove the two certificate signing requests and extensions config files:

$ rm -v client.csr server.csr extfile.cnf extfile-client.cnf

With a default umask of 022, your secret keys are world-readable and writable for you and your group.

To protect your keys from accidental damage, remove their write permissions. To make them only readable by you, change file modes as follows:

$ chmod -v 0400 ca-key.pem key.pem server-key.pem
$ chmod -v 0444 ca.pem server-cert.pem cert.pem

Now you can make the Docker daemon only accept connections from clients providing a certificate trusted by your CA:

$ dockerd \
    --tlsverify \
    --tlscacert=ca.pem \
    --tlscert=server-cert.pem \
    --tlskey=server-key.pem \
    -H=0.0.0.0:2376

Run it on the client’s machine

This step should be run on your Docker client machine. As such, you need to copy your CA certificate, your server certificate, and your client certificate to that machine.

Note: Replace all instances of $HOST in the following example with the DNS name of your Docker daemon’s host.

$ docker --tlsverify \
    --tlscacert=ca.pem \
    --tlscert=cert.pem \
    --tlskey=key.pem \
    -H=$HOST:2376 version

Note: Docker over TLS should run on TCP port 2376.

Warning: As shown in the example above, you don’t need to run the docker client with sudo or the docker group when you use certificate authentication. That means anyone with the keys can give any instructions to your Docker daemon, giving them root access to the machine hosting the daemon. Guard these keys as you would a root password!

Secure by default

If you want to secure your Docker client connections by default, you can move the files to the .docker directory in your home directory and set the DOCKER_HOST and DOCKER_TLS_VERIFY variables as well (instead of passing -H=tcp://$HOST:2376 and –tlsverify on every call).

$ mkdir -pv ~/.docker
$ cp -v {ca,cert,key}.pem ~/.docker
$ export DOCKER_HOST=tcp://$HOST:2376 DOCKER_TLS_VERIFY=1

Docker now connects securely by default:

$ docker ps

Other modes

If you don’t want to have complete two-way authentication, you can run Docker in various other modes by mixing the flags.

Daemon modes

  • tlsverify, tlscacert, tlscert, tlskey set: Authenticate clients
  • tls, tlscert, tlskey: Do not authenticate clients

Client modes

  • tls: Authenticate server based on public/default CA pool
  • tlsverify, tlscacert: Authenticate server based on given CA
  • tls, tlscert, tlskey: Authenticate with client certificate, do not authenticate server based on given CA
  • tlsverify, tlscacert, tlscert, tlskey: Authenticate with client certificate and authenticate server based on given CA

If found, the client sends its client certificate, so you just need to drop your keys into ~/.docker/{ca,cert,key}.pem. Alternatively, if you want to store your keys in another location, you can specify that location using the environment variable DOCKER_CERT_PATH.

$ export DOCKER_CERT_PATH=~/.docker/zone1/
$ docker --tlsverify ps

Connecting to the secure Docker port using curl

To use curl to make test API requests, you need to use three extra command line flags:

$ curl https://$HOST:2376/images/json \
  --cert ~/.docker/cert.pem \
  --key ~/.docker/key.pem \
  --cacert ~/.docker/ca.pem

Configuring your dev box to connect to the remote Docker daemon:

 

$ docker context create \
    --description "remote host" \
    --docker "host=tcp://$HOST:2376,ca=~/.docker/ca.pem,cert=~/.docker/cert.pem,key=~/.docker/key.pem" \
    remote

$ docker context use remote

Congratulations, you can now connect to a remote Docker daemon securely.