vbatts/registry
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Use daemon.json everywhere possible (#3252)

Browse source
This commit is contained in:
Misty Stanley-Jones 2017-05-15 10:44:40 -07:00 committed by GitHub
parent eb2763d826
commit ed56794d56
2 changed files with 91 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

91
docs/insecure.md
View file

@ -5,11 +5,9 @@ title: Test an insecure registry
--- ---
While it's highly recommended to secure your registry using a TLS certificate While it's highly recommended to secure your registry using a TLS certificate
issued by a known CA, you may alternatively decide to use self-signed issued by a known CA, you can choose to use self-signed certificates, or use
certificates, or even use your registry over plain http. your registry over an unencrypted HTTP connection. Either of these choices
involves security trade-offs and additional configuration steps.
You have to understand the downsides in doing so, and the extra burden in
configuration.
## Deploying a plain HTTP registry ## Deploying a plain HTTP registry
@ -17,31 +15,40 @@ configuration.
> it's not possible to use an insecure registry with basic authentication. > it's not possible to use an insecure registry with basic authentication.
{:.warning} {:.warning}
This basically tells Docker to entirely disregard security for your registry. This procedure configures Docker to entirely disregard security for your
While this is relatively easy to configure the daemon in this way, it is registry. This is **very** insecure and is not recommended. It exposes your
**very** insecure. It does expose your registry to trivial MITM. Only use this registry to trivial man-in-the-middle (MITM) attacks. Only use this solution for
solution for isolated testing or in a tightly controlled, air-gapped isolated testing or in a tightly controlled, air-gapped environment.
environment.
1. Open the `/etc/default/docker` file or `/etc/sysconfig/docker` for editing. 1. Edit the `daemon.json` file, whose default location is
`/etc/docker/daemon.json` on Linux or
`C:\ProgramData\docker\config\daemon.json` on Windows Server. If you use
Docker for Mac or Docker for Windows, click the Docker icon, choose
**Preferences**, and choose +**Daemon**.
Depending on your operating system, your Engine daemon start options. If the `daemon.json` file does not exist, create it. Assuming there are no
other settings in the file, it should have the following contents:
2. Edit (or add) the `DOCKER_OPTS` line and add the `--insecure-registry` flag. ```json
{
"insecure-registries" : ["myregistrydomain.com:5000"]
}
```
This flag takes the URL of your registry, for example. Substitute the address of your insecure registry for the one in the example.
`DOCKER_OPTS="--insecure-registry myregistrydomain.com:5000"` With insecure registries enabled, Docker goes through the following steps:
3. Close and save the configuration file. - First, try using HTTPS.
- If HTTPS is available but the certificate is invalid, ignore the error
about the certificate.
- If HTTPS is not available, fall back to HTTP.
4. Restart your Docker daemon
The command you use to restart the daemon depends on your operating system. 2. Restart Docker for the changes to take effect.
For example, on Ubuntu, this is usually the `service docker stop` and `service
docker start` command.
5. Repeat this configuration on every Engine host that wants to access your registry.
Repeat these steps on every Engine host that wants to access your registry.
## Using self-signed certificates ## Using self-signed certificates
@ -50,23 +57,51 @@ environment.
> using this along with basic authentication requires to **also** trust the certificate into the OS cert store for some versions of docker (see below) > using this along with basic authentication requires to **also** trust the certificate into the OS cert store for some versions of docker (see below)
{:.warning} {:.warning}
This is more secure than the insecure registry solution. You must configure every docker daemon that wants to access your registry This is more secure than the insecure registry solution.
1. Generate your own certificate: 1. Generate your own certificate:
mkdir -p certs && openssl req \ ```bash
$ mkdir -p certs
$ openssl req \
-newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \ -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
-x509 -days 365 -out certs/domain.crt -x509 -days 365 -out certs/domain.crt
```
2. Be sure to use the name `myregistrydomain.com` as a CN. Be sure to use the name `myregistrydomain.com` as a CN.
3. Use the result to [start your registry with TLS enabled](./deploying.md#get-a-certificate) 2. Use the result to [start your registry with TLS enabled](./deploying.md#get-a-certificate)
4. Instruct every docker daemon to trust that certificate. 3. Instruct every Docker daemon to trust that certificate. The way to do this
depends on your OS.
This is done by copying the `domain.crt` file to `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt`. - **Linux**: Copy the `domain.crt` file to
`/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt` on every Docker
host. You do not need to restart Docker.
- **Windows Server**:
1. Open Windows Explorer, right-click the `domain.crt`
file, and choose Install certificate. When prompted, select the following
options:
| Store location | local machine |
| Place all certificates in the following store | selected |
2. Click **Browser** and select **Trusted Root Certificate Authorities**.
3. Click **Finish**. Restart Docker.
- **Docker for Mac**: Follow the instructions on
[Adding custom CA certificates](/docker-for-mac/faqs.md#how-do-i-add-custom-ca-certificates){: target="_blank" class="_"}.
Restart Docker.
- **Docker for Windows**: Follow the instructions on
[Adding custom CA certificates](/docker-for-windows/faqs.md#how-do-i-add-custom-ca-certificates){: target="_blank" class="_"}.
Restart Docker.
5. Don't forget to restart the Engine daemon.
## Troubleshooting insecure registry ## Troubleshooting insecure registry

38
docs/recipes/mirror.md
View file

@ -54,7 +54,7 @@ remote fetch and local re-caching.
To ensure best performance and guarantee correctness the Registry cache should To ensure best performance and guarantee correctness the Registry cache should
be configured to use the `filesystem` driver for storage. be configured to use the `filesystem` driver for storage.
## Running a Registry as a pull through cache ## Run a Registry as a pull-through cache
The easiest way to run a registry as a pull through cache is to run the official The easiest way to run a registry as a pull through cache is to run the official
Registry image. Registry image.
@ -63,7 +63,7 @@ Multiple registry caches can be deployed over the same back-end. A single
registry cache will ensure that concurrent requests do not pull duplicate data, registry cache will ensure that concurrent requests do not pull duplicate data,
but this property will not hold true for a registry cache cluster. but this property will not hold true for a registry cache cluster.
### Configuring the cache ### Configure the cache
To configure a Registry to run as a pull through cache, the addition of a To configure a Registry to run as a pull through cache, the addition of a
`proxy` section is required to the config file. `proxy` section is required to the config file.
@ -71,26 +71,32 @@ To configure a Registry to run as a pull through cache, the addition of a
In order to access private images on the Docker Hub, a username and password can In order to access private images on the Docker Hub, a username and password can
be supplied. be supplied.
proxy: ```yaml
proxy:
remoteurl: https://registry-1.docker.io remoteurl: https://registry-1.docker.io
username: [username] username: [username]
password: [password] password: [password]
```
> :warn: if you specify a username and password, it's very important to understand that private resources that this user has access to on the Hub will be made available on your mirror. It's thus paramount that you secure your mirror by implementing authentication if you expect these resources to stay private! > **Warning**: If you specify a username and password, it's very important to
> understand that private resources that this user has access to Docker Hub will
> be made available on your mirror. **You must secure your mirror** by
> implementing authentication if you expect these resources to stay private!
> :warn: in order for the scheduler to clean up old entries, delete must be enabled in the registry configuration. See the [Registry Configuration Reference](../configuration.md) for more details. > **Warning**: In order for the scheduler to clean up old entries, `delete` must
> be enabled in the registry configuration. See
> [Registry Configuration](/registry/configuration.md) for more details.
### Configuring the Docker daemon ### Configure the Docker daemon
You will need to pass the `--registry-mirror` option to your Docker daemon on Either pass the `--registry-mirror` option when starting `dockerd` manually,
startup: or edit `/etc/docker/daemon.json` and add the `registry-mirrors` key and value,
to make the change persistent.
docker --registry-mirror=https://<my-docker-mirror-host> daemon ```json
{
"registry-mirrors": ["https://<my-docker-mirror-host>"]
}
```
For example, if your mirror is serving on `http://10.0.0.2:5000`, you would run: Save the file and restart Docker for the change to take effect.
docker --registry-mirror=https://10.0.0.2:5000 daemon
> NOTE: Depending on your local host setup, you may be able to add the
`--registry-mirror` option to the `DOCKER_OPTS` variable in
`/etc/default/docker`.