By default, Docker runs through a non-networked UNIX socket. It can alsooptionally communicate using SSH or a TLS (HTTPS) socket.

Use SSH to protect the Docker daemon socket

Note

The givenUSERNAME must have permissions to access the docker socket on theremote machine. Refer tomanage Docker as a non-root userto learn how to give a non-root user access to the docker socket.

The following example creates adocker contextto connect with a remotedockerd daemon onhost1.example.com using SSH, andas thedocker-user user on the remote machine:

$ docker context create\    --docker host=ssh://docker-user@host1.example.com \    --description="Remote engine" \    my-remote-enginemy-remote-engineSuccessfully created context "my-remote-engine"

After creating the context, usedocker context use to switch thedocker CLIto use it, and to connect to the remote engine:

$ docker context use my-remote-enginemy-remote-engineCurrent context is now "my-remote-engine"$ docker info<prints output of the remote engine>

Use thedefault context to switch back to the default (local) daemon:

$ docker context use defaultdefaultCurrent context is now "default"

Alternatively, use theDOCKER_HOST environment variable to temporarily switchthedocker CLI to connect to the remote host using SSH. This does not requirecreating a context, and can be useful to create an ad-hoc connection with a differentengine:

$exportDOCKER_HOST=ssh://docker-user@host1.example.com$ docker info<prints output of the remote engine>

SSH Tips

For the best user experience with SSH, configure~/.ssh/config as follows to allowreusing a SSH connection for multiple invocations of thedocker CLI:

ControlMaster     autoControlPath       ~/.ssh/control-%CControlPersist    yes

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 thetlsverify flag and pointing Docker'stlscacert flag to a trusted CA certificate.

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

Important

Using TLS and managing a CA is an advanced topic. Familiarize yourselfwith 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 theDNS 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.pem4096Generating RSA private key, 4096 bit long modulus..............................................................................++........++e is 65537 (0x10001)Enter pass phrase for ca-key.pem:Verifying - Enter pass phrase for ca-key.pem:$ openssl req -new -x509 -days365 -key ca-key.pem -sha256 -out ca.pemEnter pass phrase for ca-key.pem:You are about to be asked to enter information that will be incorporatedinto your certificate request.What you are about to enter is what is called a Distinguished Name or a DN.There are quite a few fields but you can leave some blankFor some fields there will be a default value,If you enter '.', the field will be left blank.-----Country Name (2 letter code) [AU]:State or Province Name (full name) [Some-State]:QueenslandLocality Name (eg, city) []:BrisbaneOrganization Name (eg, company) [Internet Widgits Pty Ltd]:Docker IncOrganizational Unit Name (eg, section) []:SalesCommon Name (e.g. server FQDN or YOUR name) []:$HOSTEmail Address []:Sven@home.org.au

Now that you have a CA, you can create a server key and certificatesigning request (CSR). Make sure that "Common Name" matches the hostname you useto connect to Docker:

Note

Replace all instances of$HOST in the following example with theDNS name of your Docker daemon's host.

$ openssl genrsa -out server-key.pem4096Generating RSA private key, 4096 bit long modulus.....................................................................++.................................................................................................++e is 65537 (0x10001)$ openssl req -subj"/CN=$HOST" -sha256 -new -key server-key.pem -out server.csr

Next, we're going to sign the public key with our CA:

Since TLS connections can be made through IP address as well as DNS name, the IP addressesneed to be specified when creating the certificate. For example, to allow connectionsusing10.10.10.20 and127.0.0.1:

$echosubjectAltName= DNS:$HOST,IP:10.10.10.20,IP:127.0.0.1 >> extfile.cnf

Set the Docker daemon key's extended usage attributes to be used only forserver authentication:

$echoextendedKeyUsage= serverAuth >> extfile.cnf

Now, generate the signed certificate:

$ openssl x509 -req -days365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem\  -CAcreateserial -out server-cert.pem -extfile extfile.cnfSignature oksubject=/CN=your.host.comGetting CA Private KeyEnter pass phrase for ca-key.pem:

Authorization plugins offer morefine-grained control to supplement authentication from mutual TLS. In additionto other information described in the above document, authorization pluginsrunning on a Docker daemon receive the certificate information for connectingDocker clients.

For client authentication, create a client key and certificate signingrequest:

Note

For simplicity of the next couple of steps, you may perform thisstep on the Docker daemon's host machine as well.

$ openssl genrsa -out key.pem4096Generating RSA private key, 4096 bit long modulus.........................................................++................++e is 65537 (0x10001)$ openssl req -subj'/CN=client' -new -key key.pem -out client.csr

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

$echoextendedKeyUsage= clientAuth > extfile-client.cnf

Now, generate the signed certificate:

$ openssl x509 -req -days365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem\  -CAcreateserial -out cert.pem -extfile extfile-client.cnfSignature oksubject=/CN=clientGetting CA Private KeyEnter pass phrase for ca-key.pem:

After generatingcert.pem andserver-cert.pem you can safely remove thetwo certificate signing requests and extensions config files:

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

With a defaultumask of 022, your secret keys areworld-readable andwritable for you and your group.

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

$ chmod -v0400 ca-key.pem key.pem server-key.pem

Certificates can be world-readable, but you might want to remove write access toprevent accidental damage:

$ chmod -v0444 ca.pem server-cert.pem cert.pem

Now you can make the Docker daemon only accept connections from clientsproviding 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

To connect to Docker and validate its certificate, provide your client keys,certificates and trusted CA:

Tip

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

Note

Replace all instances of$HOST in the following example with theDNS 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 thedocker clientwithsudo or thedocker group when you use certificate authentication.That means anyone with the keys can give any instructions to your Dockerdaemon, giving them root access to the machine hosting the daemon. Guardthese keys as you would a root password!

Secure by default

If you want to secure your Docker client connections by default, you can movethe files to the.docker directory in your home directory --- and set theDOCKER_HOST andDOCKER_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$exportDOCKER_HOST=tcp://$HOST:2376DOCKER_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 runDocker 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 notauthenticate server based on given CA
• tlsverify,tlscacert,tlscert,tlskey: Authenticate with clientcertificate and authenticate server based on given CA

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

$exportDOCKER_CERT_PATH=~/.docker/zone1/$ docker --tlsverify ps

Connecting to the secure Docker port usingcurl

To usecurl to make test API requests, you need to use three extra command lineflags:

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

Related information

• Using certificates for repository client verification
• Use trusted images