path: root/devdocs/docker/engine%2Fsecurity%2Fprotect-access%2Findex.html

<h1>Protect the Docker daemon socket</h1>

<p>By default, Docker runs through a non-networked UNIX socket. It can also optionally communicate using SSH or a TLS (HTTPS) socket.</p> <h2 id="use-ssh-to-protect-the-docker-daemon-socket">Use SSH to protect the Docker daemon socket</h2> <blockquote> <p><strong>Note</strong></p> <p>The given <code class="language-plaintext highlighter-rouge">USERNAME</code> must have permissions to access the docker socket on the remote machine. Refer to <a href="../../install/linux-postinstall/index#manage-docker-as-a-non-root-user">manage Docker as a non-root user</a> to learn how to give a non-root user access to the docker socket.</p> </blockquote> <p>The following example creates a <a href="../../context/working-with-contexts/index"><code class="language-plaintext highlighter-rouge">docker context</code></a> to connect with a remote <code class="language-plaintext highlighter-rouge">dockerd</code> daemon on <code class="language-plaintext highlighter-rouge">host1.example.com</code> using SSH, and as the <code class="language-plaintext highlighter-rouge">docker-user</code> user on the remote machine:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context create \
    --docker host=ssh://docker-user@host1.example.com \
    --description="Remote engine" \
    my-remote-engine

my-remote-engine
Successfully created context "my-remote-engine"
</pre></div> <p>After creating the context, use <code class="language-plaintext highlighter-rouge">docker context use</code> to switch the <code class="language-plaintext highlighter-rouge">docker</code> CLI to use it, and to connect to the remote engine:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context use my-remote-engine
my-remote-engine
Current context is now "my-remote-engine"

$ docker info
&lt;prints output of the remote engine&gt;
</pre></div> <p>Use the <code class="language-plaintext highlighter-rouge">default</code> context to switch back to the default (local) daemon:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context use default
default
Current context is now "default"
</pre></div> <p>Alternatively, use the <code class="language-plaintext highlighter-rouge">DOCKER_HOST</code> environment variable to temporarily switch the <code class="language-plaintext highlighter-rouge">docker</code> CLI to connect to the remote host using SSH. This does not require creating a context, and can be useful to create an ad-hoc connection with a different engine:</p> <div class="highlight"><pre class="highlight" data-language="">$ export DOCKER_HOST=ssh://docker-user@host1.example.com
$ docker info
&lt;prints output of the remote engine&gt;
</pre></div> <h3 id="ssh-tips">SSH Tips</h3> <p>For the best user experience with SSH, configure <code class="language-plaintext highlighter-rouge">~/.ssh/config</code> as follows to allow reusing a SSH connection for multiple invocations of the <code class="language-plaintext highlighter-rouge">docker</code> CLI:</p> <div class="highlight"><pre class="highlight" data-language="">ControlMaster     auto
ControlPath       ~/.ssh/control-%C
ControlPersist    yes
</pre></div> <h2 id="use-tls-https-to-protect-the-docker-daemon-socket">Use TLS (HTTPS) to protect the Docker daemon socket</h2> <p>If you need Docker to be reachable through HTTP rather than SSH in a safe manner, you can enable TLS (HTTPS) by specifying the <code class="language-plaintext highlighter-rouge">tlsverify</code> flag and pointing Docker’s <code class="language-plaintext highlighter-rouge">tlscacert</code> flag to a trusted CA certificate.</p> <p>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.</p> <blockquote class="important"> <p>Advanced topic</p> <p>Using TLS and managing a CA is an advanced topic. Please familiarize yourself with OpenSSL, x509, and TLS before using it in production.</p> </blockquote> <h3 id="create-a-ca-server-and-client-keys-with-openssl">Create a CA, server and client keys with OpenSSL</h3> <blockquote> <p><strong>Note</strong>: Replace all instances of <code class="language-plaintext highlighter-rouge">$HOST</code> in the following example with the DNS name of your Docker daemon’s host.</p> </blockquote> <p>First, on the <strong>Docker daemon’s host machine</strong>, generate CA private and public keys:</p> <div class="highlight"><pre class="highlight" data-language="">$ openssl genrsa -aes256 -out ca-key.pem 4096
Generating 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 -days 365 -key ca-key.pem -sha256 -out ca.pem
Enter pass phrase for ca-key.pem:
You are about to be asked to enter information that will be incorporated
into 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 blank
For 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]:Queensland
Locality Name (eg, city) []:Brisbane
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Docker Inc
Organizational Unit Name (eg, section) []:Sales
Common Name (e.g. server FQDN or YOUR name) []:$HOST
Email Address []:Sven@home.org.au
</pre></div> <p>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:</p> <blockquote> <p><strong>Note</strong>: Replace all instances of <code class="language-plaintext highlighter-rouge">$HOST</code> in the following example with the DNS name of your Docker daemon’s host.</p> </blockquote> <div class="highlight"><pre class="highlight" data-language="">$ openssl genrsa -out server-key.pem 4096
Generating 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
</pre></div> <p>Next, we’re going to sign the public key with our CA:</p> <p>Since TLS connections can be made through IP address as well as DNS name, the IP addresses need to be specified when creating the certificate. For example, to allow connections using <code class="language-plaintext highlighter-rouge">10.10.10.20</code> and <code class="language-plaintext highlighter-rouge">127.0.0.1</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ echo subjectAltName = DNS:$HOST,IP:10.10.10.20,IP:127.0.0.1 &gt;&gt; extfile.cnf
</pre></div> <p>Set the Docker daemon key’s extended usage attributes to be used only for server authentication:</p> <div class="highlight"><pre class="highlight" data-language="">$ echo extendedKeyUsage = serverAuth &gt;&gt; extfile.cnf
</pre></div> <p>Now, generate the signed certificate:</p> <div class="highlight"><pre class="highlight" data-language="">$ openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out server-cert.pem -extfile extfile.cnf
Signature ok
subject=/CN=your.host.com
Getting CA Private Key
Enter pass phrase for ca-key.pem:
</pre></div> <p><a href="../../extend/plugins_authorization/index">Authorization plugins</a> offer more fine-grained control to supplement authentication from mutual TLS. In addition to other information described in the above document, authorization plugins running on a Docker daemon receive the certificate information for connecting Docker clients.</p> <p>For client authentication, create a client key and certificate signing request:</p> <blockquote> <p><strong>Note</strong>: For simplicity of the next couple of steps, you may perform this step on the Docker daemon’s host machine as well.</p> </blockquote> <div class="highlight"><pre class="highlight" data-language="">$ openssl genrsa -out key.pem 4096
Generating RSA private key, 4096 bit long modulus
.........................................................++
................++
e is 65537 (0x10001)

$ openssl req -subj '/CN=client' -new -key key.pem -out client.csr
</pre></div> <p>To make the key suitable for client authentication, create a new extensions config file:</p> <div class="highlight"><pre class="highlight" data-language="">$ echo extendedKeyUsage = clientAuth &gt; extfile-client.cnf
</pre></div> <p>Now, generate the signed certificate:</p> <div class="highlight"><pre class="highlight" data-language="">$ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out cert.pem -extfile extfile-client.cnf
Signature ok
subject=/CN=client
Getting CA Private Key
Enter pass phrase for ca-key.pem:
</pre></div> <p>After generating <code class="language-plaintext highlighter-rouge">cert.pem</code> and <code class="language-plaintext highlighter-rouge">server-cert.pem</code> you can safely remove the two certificate signing requests and extensions config files:</p> <div class="highlight"><pre class="highlight" data-language="">$ rm -v client.csr server.csr extfile.cnf extfile-client.cnf
</pre></div> <p>With a default <code class="language-plaintext highlighter-rouge">umask</code> of 022, your secret keys are <em>world-readable</em> and writable for you and your group.</p> <p>To protect your keys from accidental damage, remove their write permissions. To make them only readable by you, change file modes as follows:</p> <div class="highlight"><pre class="highlight" data-language="">$ chmod -v 0400 ca-key.pem key.pem server-key.pem
</pre></div> <p>Certificates can be world-readable, but you might want to remove write access to prevent accidental damage:</p> <div class="highlight"><pre class="highlight" data-language="">$ chmod -v 0444 ca.pem server-cert.pem cert.pem
</pre></div> <p>Now you can make the Docker daemon only accept connections from clients providing a certificate trusted by your CA:</p> <div class="highlight"><pre class="highlight" data-language="">$ dockerd \
    --tlsverify \
    --tlscacert=ca.pem \
    --tlscert=server-cert.pem \
    --tlskey=server-key.pem \
    -H=0.0.0.0:2376
</pre></div> <p>To connect to Docker and validate its certificate, provide your client keys, certificates and trusted CA:</p> <blockquote> <p>Run it on the client machine</p> <p>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.</p> </blockquote> <blockquote> <p><strong>Note</strong>: Replace all instances of <code class="language-plaintext highlighter-rouge">$HOST</code> in the following example with the DNS name of your Docker daemon’s host.</p> </blockquote> <div class="highlight"><pre class="highlight" data-language="">$ docker --tlsverify \
    --tlscacert=ca.pem \
    --tlscert=cert.pem \
    --tlskey=key.pem \
    -H=$HOST:2376 version
</pre></div> <blockquote> <p><strong>Note</strong>: Docker over TLS should run on TCP port 2376.</p> </blockquote> <blockquote class="warning"> <p><strong>Warning</strong>: As shown in the example above, you don’t need to run the <code class="language-plaintext highlighter-rouge">docker</code> client with <code class="language-plaintext highlighter-rouge">sudo</code> or the <code class="language-plaintext highlighter-rouge">docker</code> 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!</p> </blockquote> <h3 id="secure-by-default">Secure by default</h3> <p>If you want to secure your Docker client connections by default, you can move the files to the <code class="language-plaintext highlighter-rouge">.docker</code> directory in your home directory --- and set the <code class="language-plaintext highlighter-rouge">DOCKER_HOST</code> and <code class="language-plaintext highlighter-rouge">DOCKER_TLS_VERIFY</code> variables as well (instead of passing <code class="language-plaintext highlighter-rouge">-H=tcp://$HOST:2376</code> and <code class="language-plaintext highlighter-rouge">--tlsverify</code> on every call).</p> <div class="highlight"><pre class="highlight" data-language="">$ mkdir -pv ~/.docker
$ cp -v {ca,cert,key}.pem ~/.docker

$ export DOCKER_HOST=tcp://$HOST:2376 DOCKER_TLS_VERIFY=1
</pre></div> <p>Docker now connects securely by default:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker ps
</pre></div> <h3 id="other-modes">Other modes</h3> <p>If you don’t want to have complete two-way authentication, you can run Docker in various other modes by mixing the flags.</p> <h4 id="daemon-modes">Daemon modes</h4> <ul> <li>
<code class="language-plaintext highlighter-rouge">tlsverify</code>, <code class="language-plaintext highlighter-rouge">tlscacert</code>, <code class="language-plaintext highlighter-rouge">tlscert</code>, <code class="language-plaintext highlighter-rouge">tlskey</code> set: Authenticate clients</li> <li>
<code class="language-plaintext highlighter-rouge">tls</code>, <code class="language-plaintext highlighter-rouge">tlscert</code>, <code class="language-plaintext highlighter-rouge">tlskey</code>: Do not authenticate clients</li> </ul> <h4 id="client-modes">Client modes</h4> <ul> <li>
<code class="language-plaintext highlighter-rouge">tls</code>: Authenticate server based on public/default CA pool</li> <li>
<code class="language-plaintext highlighter-rouge">tlsverify</code>, <code class="language-plaintext highlighter-rouge">tlscacert</code>: Authenticate server based on given CA</li> <li>
<code class="language-plaintext highlighter-rouge">tls</code>, <code class="language-plaintext highlighter-rouge">tlscert</code>, <code class="language-plaintext highlighter-rouge">tlskey</code>: Authenticate with client certificate, do not authenticate server based on given CA</li> <li>
<code class="language-plaintext highlighter-rouge">tlsverify</code>, <code class="language-plaintext highlighter-rouge">tlscacert</code>, <code class="language-plaintext highlighter-rouge">tlscert</code>, <code class="language-plaintext highlighter-rouge">tlskey</code>: Authenticate with client certificate and authenticate server based on given CA</li> </ul> <p>If found, the client sends its client certificate, so you just need to drop your keys into <code class="language-plaintext highlighter-rouge">~/.docker/{ca,cert,key}.pem</code>. Alternatively, if you want to store your keys in another location, you can specify that location using the environment variable <code class="language-plaintext highlighter-rouge">DOCKER_CERT_PATH</code>.</p> <div class="highlight"><pre class="highlight" data-language="">$ export DOCKER_CERT_PATH=~/.docker/zone1/
$ docker --tlsverify ps
</pre></div> <h4 id="connecting-to-the-secure-docker-port-using-curl">Connecting to the secure Docker port using <code class="language-plaintext highlighter-rouge">curl</code>
</h4> <p>To use <code class="language-plaintext highlighter-rouge">curl</code> to make test API requests, you need to use three extra command line flags:</p> <div class="highlight"><pre class="highlight" data-language="">$ curl https://$HOST:2376/images/json \
  --cert ~/.docker/cert.pem \
  --key ~/.docker/key.pem \
  --cacert ~/.docker/ca.pem
</pre></div> <h2 id="related-information">Related information</h2> <ul> <li><a href="../certificates/index">Using certificates for repository client verification</a></li> <li><a href="../trust/index">Use trusted images</a></li> </ul> 
<p><a href="https://docs.docker.com/search/?q=docker">docker</a>, <a href="https://docs.docker.com/search/?q=docs">docs</a>, <a href="https://docs.docker.com/search/?q=article">article</a>, <a href="https://docs.docker.com/search/?q=example">example</a>, <a href="https://docs.docker.com/search/?q=ssh">ssh</a>, <a href="https://docs.docker.com/search/?q=https">https</a>, <a href="https://docs.docker.com/search/?q=daemon">daemon</a>, <a href="https://docs.docker.com/search/?q=tls">tls</a>, <a href="https://docs.docker.com/search/?q=ca">ca</a>, <a href="https://docs.docker.com/search/?q=certificate">certificate</a></p>
<div class="_attribution">
  <p class="_attribution-p">
    &copy; 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
    <a href="https://docs.docker.com/engine/security/protect-access/" class="_attribution-link">https://docs.docker.com/engine/security/protect-access/</a>
  </p>
</div>