Initial work
Removing references to regsitry 1.0, pointing to distribution Updating links and title Adding in comments Signed-off-by: Mary Anthony <mary@docker.com> Upstream-commit: d550d729e14d1a18d00b66a941da5b23b9a61bd3 Component: engine
This commit is contained in:
Mary Anthony
@ -11,111 +11,7 @@ weight = 7
|
||||
|
||||
# Using certificates for repository client verification
|
||||
|
||||
In [Running Docker with HTTPS](/articles/https), you learned that, by default,
|
||||
Docker runs via a non-networked Unix socket and TLS must be enabled in order
|
||||
to have the Docker client and the daemon communicate securely over HTTPS.
|
||||
|
||||
Now, you will see how to allow the Docker registry (i.e., *a server*) to
|
||||
verify that the Docker daemon (i.e., *a client*) has the right to access the
|
||||
images being hosted with *certificate-based client-server authentication*.
|
||||
|
||||
We will show you how to install a Certificate Authority (CA) root certificate
|
||||
for the registry and how to set the client TLS certificate for verification.
|
||||
|
||||
## Understanding the configuration
|
||||
|
||||
A custom certificate is configured by creating a directory under
|
||||
`/etc/docker/certs.d` using the same name as the registry's hostname (e.g.,
|
||||
`localhost`). All `*.crt` files are added to this directory as CA roots.
|
||||
|
||||
> **Note:**
|
||||
> In the absence of any root certificate authorities, Docker
|
||||
> will use the system default (i.e., host's root CA set).
|
||||
|
||||
The presence of one or more `<filename>.key/cert` pairs indicates to Docker
|
||||
that there are custom certificates required for access to the desired
|
||||
repository.
|
||||
|
||||
> **Note:**
|
||||
> If there are multiple certificates, each will be tried in alphabetical
|
||||
> order. If there is an authentication error (e.g., 403, 404, 5xx, etc.), Docker
|
||||
> will continue to try with the next certificate.
|
||||
|
||||
Our example is set up like this:
|
||||
|
||||
/etc/docker/certs.d/ <-- Certificate directory
|
||||
└── localhost <-- Hostname
|
||||
├── client.cert <-- Client certificate
|
||||
├── client.key <-- Client key
|
||||
└── localhost.crt <-- Registry certificate
|
||||
|
||||
## Creating the client certificates
|
||||
|
||||
You will use OpenSSL's `genrsa` and `req` commands to first generate an RSA
|
||||
key and then use the key to create the certificate.
|
||||
|
||||
$ openssl genrsa -out client.key 4096
|
||||
$ openssl req -new -x509 -text -key client.key -out client.cert
|
||||
|
||||
> **Warning:**:
|
||||
> Using TLS and managing a CA is an advanced topic.
|
||||
> You should be familiar with OpenSSL, x509, and TLS before
|
||||
> attempting to use them in production.
|
||||
|
||||
> **Warning:**
|
||||
> These TLS commands will only generate a working set of certificates on Linux.
|
||||
> The version of OpenSSL in Mac OS X is incompatible with the type of
|
||||
> certificate Docker requires.
|
||||
|
||||
## Testing the verification setup
|
||||
|
||||
You can test this setup by using Apache to host a Docker registry.
|
||||
For this purpose, you can copy a registry tree (containing images) inside
|
||||
the Apache root.
|
||||
|
||||
> **Note:**
|
||||
> You can find such an example [here](
|
||||
> http://people.gnome.org/~alexl/v1.tar.gz) - which contains the busybox image.
|
||||
|
||||
Once you set up the registry, you can use the following Apache configuration
|
||||
to implement certificate-based protection.
|
||||
|
||||
# This must be in the root context, otherwise it causes a re-negotiation
|
||||
# which is not supported by the TLS implementation in go
|
||||
SSLVerifyClient optional_no_ca
|
||||
|
||||
<Location /v1>
|
||||
Action cert-protected /cgi-bin/cert.cgi
|
||||
SetHandler cert-protected
|
||||
|
||||
Header set x-docker-registry-version "0.6.2"
|
||||
SetEnvIf Host (.*) custom_host=$1
|
||||
Header set X-Docker-Endpoints "%{custom_host}e"
|
||||
</Location>
|
||||
|
||||
Save the above content as `/etc/httpd/conf.d/registry.conf`, and
|
||||
continue with creating a `cert.cgi` file under `/var/www/cgi-bin/`.
|
||||
|
||||
#!/bin/bash
|
||||
if [ "$HTTPS" != "on" ]; then
|
||||
echo "Status: 403 Not using SSL"
|
||||
echo "x-docker-registry-version: 0.6.2"
|
||||
echo
|
||||
exit 0
|
||||
fi
|
||||
if [ "$SSL_CLIENT_VERIFY" == "NONE" ]; then
|
||||
echo "Status: 403 Client certificate invalid"
|
||||
echo "x-docker-registry-version: 0.6.2"
|
||||
echo
|
||||
exit 0
|
||||
fi
|
||||
echo "Content-length: $(stat --printf='%s' $PATH_TRANSLATED)"
|
||||
echo "x-docker-registry-version: 0.6.2"
|
||||
echo "X-Docker-Endpoints: $SERVER_NAME"
|
||||
echo "X-Docker-Size: 0"
|
||||
echo
|
||||
|
||||
cat $PATH_TRANSLATED
|
||||
|
||||
This CGI script will ensure that all requests to `/v1` *without* a valid
|
||||
certificate will be returned with a `403` (i.e., HTTP forbidden) error.
|
||||
The orginal content was deprecated. For information about configuring
|
||||
cerficates, see [deploying a registry
|
||||
server](http://docs.docker.com/registry/deploying/). To reach an older version
|
||||
of this content, refer to an older version of the documentation.
|
||||
|
||||
@ -11,81 +11,8 @@ weight = 8
|
||||
|
||||
# Run a local registry mirror
|
||||
|
||||
## Why?
|
||||
|
||||
If you have multiple instances of Docker running in your environment
|
||||
(e.g., multiple physical or virtual machines, all running the Docker
|
||||
daemon), each time one of them requires an image that it doesn't have
|
||||
it will go out to the internet and fetch it from the public Docker
|
||||
registry. By running a local registry mirror, you can keep most of the
|
||||
image fetch traffic on your local network.
|
||||
|
||||
## How does it work?
|
||||
|
||||
The first time you request an image from your local registry mirror,
|
||||
it pulls the image from the public Docker registry and stores it locally
|
||||
before handing it back to you. On subsequent requests, the local registry
|
||||
mirror is able to serve the image from its own storage.
|
||||
|
||||
## How do I set up a local registry mirror?
|
||||
|
||||
There are two steps to set up and use a local registry mirror.
|
||||
|
||||
### Step 1: Configure your Docker daemons to use the local registry mirror
|
||||
|
||||
You will need to pass the `--registry-mirror` option to your Docker daemon on
|
||||
startup:
|
||||
|
||||
docker daemon --registry-mirror=http://<my-docker-mirror-host>
|
||||
|
||||
For example, if your mirror is serving on `http://10.0.0.2:5000`, you would run:
|
||||
|
||||
docker daemon --registry-mirror=http://10.0.0.2:5000
|
||||
|
||||
**NOTE:**
|
||||
Depending on your local host setup, you may be able to add the
|
||||
`--registry-mirror` options to the `DOCKER_OPTS` variable in
|
||||
`/etc/default/docker`.
|
||||
|
||||
### Step 2: Run the local registry mirror
|
||||
|
||||
You will need to start a local registry mirror service. The
|
||||
[`registry` image](https://registry.hub.docker.com/_/registry/) provides this
|
||||
functionality. For example, to run a local registry mirror that serves on
|
||||
port `5000` and mirrors the content at `registry-1.docker.io`:
|
||||
|
||||
docker run -p 5000:5000 \
|
||||
-e STANDALONE=false \
|
||||
-e MIRROR_SOURCE=https://registry-1.docker.io \
|
||||
-e MIRROR_SOURCE_INDEX=https://index.docker.io \
|
||||
registry
|
||||
|
||||
## Test it out
|
||||
|
||||
With your mirror running, pull an image that you haven't pulled before (using
|
||||
`time` to time it):
|
||||
|
||||
$ time docker pull node:latest
|
||||
Pulling repository node
|
||||
[...]
|
||||
|
||||
real 1m14.078s
|
||||
user 0m0.176s
|
||||
sys 0m0.120s
|
||||
|
||||
Now, remove the image from your local machine:
|
||||
|
||||
$ docker rmi node:latest
|
||||
|
||||
Finally, re-pull the image:
|
||||
|
||||
$ time docker pull node:latest
|
||||
Pulling repository node
|
||||
[...]
|
||||
|
||||
real 0m51.376s
|
||||
user 0m0.120s
|
||||
sys 0m0.116s
|
||||
|
||||
The second time around, the local registry mirror served the image from storage,
|
||||
avoiding a trip out to the internet to refetch it.
|
||||
The orginal content was deprecated. [An archived
|
||||
version](https://docs.docker.com/v1.6/articles/registry_mirror) is available in
|
||||
the 1.7 documentation. For information about configuring mirrors with the latest
|
||||
Docker Registry version, please file a support request with [the Distribution
|
||||
project](https://github.com/docker/distribution/issues).
|
||||
|
||||
Reference in New Issue
Block a user