Test an insecure registry

Estimated reading time: 4 minutes

While it’s highly recommended to secure your registry using a TLS certificate issued by a known CA, you can choose to use self-signed certificates, or use your registry over an unencrypted HTTP connection. Either of these choices involves security trade-offs and additional configuration steps.

Deploy a plain HTTP registry

Warning: It’s not possible to use an insecure registry with basic authentication.

This procedure configures Docker to entirely disregard security for your registry. This is very insecure and is not recommended. It exposes your registry to trivial man-in-the-middle (MITM) attacks. Only use this solution for isolated testing or in a tightly controlled, air-gapped environment.

  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.

    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:

    {
  "insecure-registries" : ["myregistrydomain.com:5000"]
}

    Substitute the address of your insecure registry for the one in the example.

    With insecure registries enabled, Docker goes through the following steps:

    • 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.

  2. Restart Docker for the changes to take effect.

Repeat these steps on every Engine host that wants to access your registry.

Use self-signed certificates

Warning: Using this along with basic authentication requires to also trust the certificate into the OS cert store for some versions of docker (see below)

This is more secure than the insecure registry solution.

  1. Generate your own certificate:

    $ mkdir -p certs

$ openssl req \
  -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
  -x509 -days 365 -out certs/domain.crt

    Be sure to use the name myregistrydomain.com as a CN.

  2. Use the result to start your registry with TLS enabled.

  3. Instruct every Docker daemon to trust that certificate. The way to do this depends on your OS.

    • 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. Restart Docker.

    • Docker for Windows: Follow the instructions on Adding custom CA certificates. Restart Docker.

Troubleshoot insecure registry

This sections lists some common failures and how to recover from them.

Failing…

Failing to configure the Engine daemon and trying to pull from a registry that is not using TLS will results in the following message:

FATA[0000] Error response from daemon: v1 ping attempt failed with error:
Get https://myregistrydomain.com:5000/v1/_ping: tls: oversized record received with length 20527.
If this private registry supports only HTTP or HTTPS with an unknown CA certificate,please add
`--insecure-registry myregistrydomain.com:5000` to the daemon's arguments.
In the case of HTTPS, if you have access to the registry's CA certificate, no need for the flag;
simply place the CA certificate at /etc/docker/certs.d/myregistrydomain.com:5000/ca.crt

Docker still complains about the certificate when using authentication?

When using authentication, some versions of Docker also require you to trust the certificate at the OS level.

Ubuntu

$ cp certs/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt
update-ca-certificates

Red Hat Enterprise Linux

cp certs/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
update-ca-trust

Oracle Linux

$ update-ca-trust enable

Restart Docker for the changes to take effect.

Windows

Open Windows Explorer, right-click the certificate, and choose Install certificate.

Then, select the following options:

  • Store location: local machine
  • Check place all certificates in the following store
  • Click Browser, and select Trusted Root Certificate Authorities
  • Click Finish

Learn more about managing TLS certificates.

After adding the CA certificate to Windows, restart Docker for Windows.

registry, on-prem, images, tags, repository, distribution, insecure