Merge pull request #9937 from SvenDowideit/add-https-test

Add a containerised test for the https cert doc

docs/sources/articles/https.md

@@ -1,8 +1,8 @@
-page_title: Running Docker with HTTPS
+page_title: Protecting the Docker daemon Socket with HTTPS
 page_description: How to setup and run Docker with HTTPS
 page_keywords: docker, docs, article, example, https, daemon, tls, ca, certificate
 
-# Running Docker with https
+# Protecting the Docker daemon Socket with HTTPS
 
 By default, Docker runs via a non-networked Unix socket. It can also
 optionally communicate using a HTTP socket.
@@ -26,6 +26,9 @@ it will only connect to servers with a certificate signed by that CA.
 
 ## 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 generate CA private and public keys:
 
     $ openssl genrsa -aes256 -out ca-key.pem 2048
@@ -49,19 +52,22 @@ First generate CA private and public keys:
      Locality Name (eg, city) []:Brisbane
      Organization Name (eg, company) [Internet Widgits Pty Ltd]:Docker Inc
      Organizational Unit Name (eg, section) []:Boot2Docker
-     Common Name (e.g. server FQDN or YOUR name) []:your.host.com
+     Common Name (e.g. server FQDN or YOUR name) []:$HOST
      Email Address []:Sven@home.org.au
 
 Now that we have a CA, you can create a server key and certificate
 signing request (CSR). Make sure that "Common Name" (i.e. server FQDN or YOUR
 name) matches the hostname you will use to connect to Docker:
 
+> **Note:** replace all instances of `$HOST` in the following example with the
+> DNS name of your Docker daemon's host.
+
     $ openssl genrsa -out server-key.pem 2048
     Generating RSA private key, 2048 bit long modulus
     ......................................................+++
     ............................................+++
     e is 65537 (0x10001)
-    $ openssl req -subj '/CN=<Your Hostname Here>' -new -key server-key.pem -out server.csr
+    $ openssl req -subj "/CN=$HOST" -new -key server-key.pem -out server.csr
 
 Next, we're going to sign the key with our CA:
 
@@ -105,8 +111,11 @@ providing a certificate trusted by our CA:
 To be able to connect to Docker and validate its certificate, you now
 need to provide your client keys, certificates and trusted CA:
 
+> **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=dns-name-of-docker-host:2376 version
+      -H=$HOST:2376 version
 
 > **Note**:
 > Docker over TLS should run on TCP port 2376.
@@ -125,6 +134,7 @@ 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://:2376` and `--tlsverify` on every call).
 
+    $ mkdir -p ~/.docker
     $ cp ca.pem ~/.docker/ca.pem
     $ cp cert.pem ~/.docker/cert.pem
     $ cp key.pem ~/.docker/key.pem
@@ -167,7 +177,7 @@ location using the environment variable `DOCKER_CERT_PATH`.
 To use `curl` to make test API requests, you need to use three extra command line
 flags:
 
-    $ curl https://boot2docker:2376/images/json \
+    $ curl https://$HOST:2376/images/json \
       --cert ~/.docker/cert.pem \
       --key ~/.docker/key.pem \
       --cacert ~/.docker/ca.pem

docs/sources/articles/https/Dockerfile

@@ -0,0 +1,10 @@
+FROM debian
+
+RUN apt-get update && apt-get install -yq openssl
+
+ADD make_certs.sh /
+
+
+WORKDIR /data
+VOLUMES ["/data"]
+CMD /make_certs.sh

docs/sources/articles/https/Makefile

@@ -0,0 +1,23 @@
+
+HOST:=boot2docker
+
+makescript:
+	./parsedocs.sh > make_certs.sh
+
+build: makescript
+	docker build -t makecerts .
+
+cert: build
+	docker run --rm -it -v $(CURDIR):/data -e HOST=$(HOST) makecerts
+
+certs: cert
+
+run:
+	docker -d -D --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem -H=0.0.0.0:6666 --pidfile=$(pwd)/docker.pid --graph=$(pwd)/graph
+
+client:
+	docker --tls --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem   -H=$(HOST):6666 version
+	docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem   -H=$(HOST):6666 info
+
+clean:
+	rm ca-key.pem ca.pem ca.srl cert.pem client.csr extfile.cnf key.pem server-cert.pem server-key.pem server.csr

docs/sources/articles/https/README.md

@@ -0,0 +1,26 @@
+
+
+This is an initial attempt to make it easier to test the examples in the https.md
+doc
+
+at this point, it has to be a manual thing, and I've been running it in boot2docker
+
+so my process is
+
+$ boot2docker ssh
+$$ git clone https://github.com/docker/docker
+$$ cd docker/docs/sources/articles/https
+$$ make cert
+lots of things to see and manually answer, as openssl wants to be interactive
+**NOTE:** make sure you enter the hostname (`boot2docker` in my case) when prompted for `Computer Name`)
+$$ sudo make run
+
+start another terminal
+
+$ boot2docker ssh
+$$ cd docker/docs/sources/articles/https
+$$ make client
+
+the last will connect first with `--tls` and then with `--tlsverify`
+
+both should succeed

docs/sources/articles/https/make_certs.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+openssl genrsa -aes256 -out ca-key.pem 2048
+
+echo "enter your Docker daemon's hostname as the 'Common Name'= ($HOST)"
+
+#TODO add this as an ENV to docker run?
+openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem
+
+
+# server cert
+openssl genrsa -out server-key.pem 2048
+openssl req -subj "/CN=$HOST" -new -key server-key.pem -out server.csr
+openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem \
+  -CAcreateserial -out server-cert.pem
+
+#client cert
+openssl genrsa -out key.pem 2048
+openssl req -subj '/CN=client' -new -key key.pem -out client.csr
+
+echo extendedKeyUsage = clientAuth > extfile.cnf
+openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca-key.pem \
+  -CAcreateserial -out cert.pem -extfile extfile.cnf

docs/sources/articles/https/parsedocs.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+echo "#!/bin/sh"
+cat ../https.md | awk '{if (sub(/\\$/,"")) printf "%s", $0; else print $0}' | grep '   $ ' | sed 's/    $ //g' | sed 's/2375/7777/g' | sed 's/2376/7778/g'