Browse Source

Merge pull request #6890 from huslage/tls-doc-fixes2

Clarification of TLS Docs
James Turnbull 11 years ago
parent
commit
2944d8ca3e
1 changed files with 32 additions and 11 deletions
  1. 32 11
      docs/sources/articles/https.md

+ 32 - 11
docs/sources/articles/https.md

@@ -17,7 +17,12 @@ will only connect to servers with a certificate signed by that CA.
 
 
 > **Warning**: 
 > **Warning**: 
 > Using TLS and managing a CA is an advanced topic. Please make you self
 > Using TLS and managing a CA is an advanced topic. Please make you self
-> familiar with openssl, x509 and tls before using it in production.
+> familiar with OpenSSL, x509 and TLS before using it in production.
+
+> **Warning**:
+> These TLS commands will only generate a working set of certificates on Linux.
+> Mac OS X comes with a version of OpenSSL that is incompatible with the 
+> certificates that Docker requires.
 
 
 ## Create a CA, server and client keys with OpenSSL
 ## Create a CA, server and client keys with OpenSSL
 
 
@@ -25,16 +30,15 @@ First, initialize the CA serial file and generate CA private and public
 keys:
 keys:
 
 
     $ echo 01 > ca.srl
     $ echo 01 > ca.srl
-    $ openssl genrsa -des3 -out ca-key.pem
+    $ openssl genrsa -des3 -out ca-key.pem 2048
     $ openssl req -new -x509 -days 365 -key ca-key.pem -out ca.pem
     $ openssl req -new -x509 -days 365 -key ca-key.pem -out ca.pem
 
 
 Now that we have a CA, you can create a server key and certificate
 Now that we have a CA, you can create a server key and certificate
-signing request. Make sure that "Common Name (e.g., server FQDN or YOUR
-name)" matches the hostname you will use to connect to Docker or just
-use `\*` for a certificate valid for any hostname:
+signing request. Make sure that "Common Name (e.g. server FQDN or YOUR
+name)" matches the hostname you will use to connect to Docker:
 
 
-    $ openssl genrsa -des3 -out server-key.pem
-    $ openssl req -new -key server-key.pem -out server.csr
+    $ openssl genrsa -des3 -out server-key.pem 2048
+    $ openssl req -subj '/CN=**<Your Hostname Here>**' -new -key server-key.pem -out server.csr
 
 
 Next we're going to sign the key with our CA:
 Next we're going to sign the key with our CA:
 
 
@@ -44,8 +48,8 @@ Next we're going to sign the key with our CA:
 For client authentication, create a client key and certificate signing
 For client authentication, create a client key and certificate signing
 request:
 request:
 
 
-    $ openssl genrsa -des3 -out client-key.pem
-    $ openssl req -new -key client-key.pem -out client.csr
+    $ openssl genrsa -des3 -out client-key.pem 2048
+    $ openssl req -subj '/CN=client' -new -key client-key.pem -out client.csr
 
 
 To make the key suitable for client authentication, create a extensions
 To make the key suitable for client authentication, create a extensions
 config file:
 config file:
@@ -67,13 +71,16 @@ Now you can make the Docker daemon only accept connections from clients
 providing a certificate trusted by our CA:
 providing a certificate trusted by our CA:
 
 
     $ sudo docker -d --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem \
     $ sudo docker -d --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem \
-      -H=0.0.0.0:2375
+      -H=0.0.0.0:2376
 
 
 To be able to connect to Docker and validate its certificate, you now
 To be able to connect to Docker and validate its certificate, you now
 need to provide your client keys, certificates and trusted CA:
 need to provide your client keys, certificates and trusted CA:
 
 
     $ docker --tlsverify --tlscacert=ca.pem --tlscert=client-cert.pem --tlskey=client-key.pem \
     $ docker --tlsverify --tlscacert=ca.pem --tlscert=client-cert.pem --tlskey=client-key.pem \
-      -H=dns-name-of-docker-host:2375
+      -H=dns-name-of-docker-host:2376
+
+> **Note**:
+> Docker over TLS should run on TCP port 2376.
 
 
 > **Warning**: 
 > **Warning**: 
 > As shown in the example above, you don't have to run the
 > As shown in the example above, you don't have to run the
@@ -84,6 +91,20 @@ need to provide your client keys, certificates and trusted CA:
 > machine hosting the daemon. Guard these keys as you would a root
 > machine hosting the daemon. Guard these keys as you would a root
 > password!
 > 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. Set the `DOCKER_HOST` variable as well.
+
+    $ cp ca.pem ~/.docker/ca.pem
+    $ cp client-cert.pem ~/.docker/cert.pem
+    $ cp client-key.pem ~/.docker/key.pem
+    $ export DOCKER_HOST=tcp://:2376
+
+Then you can just run docker with the `--tlsverify` option.
+
+    $ docker --tlsverify ps
+
 ## Other modes
 ## Other modes
 
 
 If you don't want to have complete two-way authentication, you can run
 If you don't want to have complete two-way authentication, you can run