---
description: Security configuration for Docker Trusted Registry
keywords:
- docker, documentation, about, technology, understanding, configuration, security,
  enterprise, hub, registry
menu:
  main:
    identifier: dtr_configure_security
    parent: workw_dtr_configure
    weight: 4
title: Security configuration
---

# Security configuration

This document describes the security settings you need to configure.

* *SSL Certificate*: Used to enter the hash (string) from the SSL Certificate.
This cert must be accompanied by its private key, entered below.
* *SSL Private Key*: The hash from the private key associated with the provided
SSL Certificate (as a standard x509 key pair).

In order to run, the Trusted Registry requires encrypted communications through HTTPS/SSL between (a) the Trusted Registry and your Docker Engine(s), and (b) between your web browser and the Trusted Registry admin server. There are a few options for setting this up:

1. You can use the self-signed certificate Docker Trusted Registry generates by default.
2. You can generate your own certificates using a public service or your enterprise's infrastructure. See the [Generating SSL certificates](config-security.md#generating-ssl-certificates) section for the options available.

If you are generating your own certificates, you can install them by following the instructions for
[Adding your own registry certificates to Docker Trusted Registry](config-security.md#adding-your-own-registry-certificates-to-dtr).

However, if you choose to use the Trusted Registry-generated certificates, or
the certificates you generate yourself are not trusted by your client Docker
hosts, you will need to do one of the following:

* [Install](config-security.md#installing-registry-certificates-on-client-docker-daemons) a registry certificate on all of your client Docker daemons, or

* Set your [client Docker daemons](config-security.md#if-you-can-t-install-the-certificates) to run with an unconfirmed connection to the registry.

### Generate SSL certificates

There are three basic approaches to generating certificates:

1.  Most enterprises will have private key infrastructure (PKI) in place to
generate keys. Consult with your security team or whomever manages your private
key infrastructure. If you have this resource available, Docker recommends you
use it.

2. If your enterprise can't provide keys, you can use a public Certificate
Authority (CA) like "InstantSSL.com" or "RapidSSL.com" to generate a
certificate. If your certificates are generated using a globally trusted
Certificate Authority, you won't need to install them on all of your
client Docker daemons.

3. Use the self-signed registry certificate generated by Docker Trusted
Registry, and install it onto the client Docker daemon hosts as seen in the
following section.


### Add your own registry certificates

Whichever method you use to generate certificates, once you have them you can
set up your Trusted Registry server to use them.

1. Navigate to Settings > Security, and put the SSL Certificate text
(including all intermediate Certificates, starting with the host) into the "SSL
Certificate" edit box, and the previously generated Private key into the "SSL
Private Key" edit box.

2. Click Save, and then wait for the Trusted Registry Admin site to restart
and reload. It should now be using the new certificate. Once the Security page has reloaded, it displays `#` hashes instead of the
certificate text you pasted.

If your certificate is signed by a chain of Certificate Authorities that are
already trusted by your Docker daemon servers, you can skip the following
"Install registry certificates" step.


### Install registry certificates on client Docker daemons

If your certificates do not have a trusted Certificate Authority, you will need
to install them on each client Docker daemon host.

The procedure for installing the Trusted Registry certificates on each
Linux distribution has slightly different steps.

You can test this certificate using `curl`:

```
$ curl https://dtr.yourdomain.com/v2/
curl: (60) SSL certificate problem: self signed certificate
```

For details see: http://curl.haxx.se/docs/sslcerts.html

Curl performs SSL certificate verification by default, using a "bundle" of
Certificate Authority (CA) public keys (CA certs). If the default bundle file
isn't adequate, you can specify an alternate file using the `--cacert` option.
If this HTTPS server uses a certificate signed by a CA represented in the
bundle, the certificate verification probably failed due to a problem with the
certificate. For example, it might be expired, or the name might not match the
domain name in the URL.

If you'd like to turn off curl's verification of the certificate, use
 the -k (or --insecure) option.

```
$ curl --cacert /usr/local/etc/dtr/ssl/server.pem https://dtr.yourdomain.com/v2/
{"errors":[{"code":"UNAUTHORIZED","message":"access to the requested resource is not authorized","detail":null}]}
```

Continue by following the steps corresponding to your chosen OS. Run the following commands on the Trusted Registry host.

#### Ubuntu/Debian

```
$ export DOMAIN_NAME=dtr.yourdomain.com
$ openssl s_client -connect $DOMAIN_NAME:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | sudo tee /usr/local/share/ca-certificates/$DOMAIN_NAME.crt
$ sudo update-ca-certificates
Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d....done.
$ sudo service docker restart
docker stop/waiting
docker start/running, process 29291
```

#### RHEL/Centos

```
$ export DOMAIN_NAME=dtr.yourdomain.com
$ openssl s_client -connect $DOMAIN_NAME:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | sudo tee /etc/pki/ca-trust/source/anchors/$DOMAIN_NAME.crt
$ sudo update-ca-trust
$ sudo /bin/systemctl restart docker.service
```

#### Docker Machine and Boot2Docker

You'll need to make some persistent changes using `bootsync.sh` in your
Boot2Docker-based virtual machine (as documented in [local customization](https://github.com/boot2docker/boot2docker/blob/master/doc/FAQ.md#local-customisation-with-persistent-partition)). To do this:

1.  `docker-machine ssh dev` to enter the VM
2.  `vi /var/lib/boot2docker/bootsync.sh` creates it if it doesn't exist, or edit it if it does.
3.  Install the CA cert (or the auto-generated cert) by adding the following code to your `/var/lib/boot2docker/bootsync.sh`:

    ```
    #!/bin/sh

    cat /var/lib/boot2docker/server.pem >> /etc/ssl/certs/ca-certificates.crt
    ```

4.  Next get the certificate from the new Docker Trusted Registry server using:

    ```
    $ openssl s_client -connect dtr.yourdomain.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | sudo tee -a /var/lib/boot2docker/server.pem
    ```

    If your certificate chain is complicated, you can use the changes in [Pull request 807](https://github.com/boot2docker/boot2docker/pull/807/files)

5.  Either reboot your virtual machine, or run the following commands to
install the server certificate. Restart the Docker daemon.

    ```
    $ sudo chmod 755 /var/lib/boot2docker/bootsync.sh
    $ sudo /var/lib/boot2docker/bootsync.sh
    $ sudo /etc/init.d/docker restart`.
    ```

### If you can't install the certificates

If for some reason you can't install the certificate chain on a client Docker
host, or your certificates do not have a global CA, you can configure your
Docker daemon to run in "insecure" mode. This is done by adding an extra flag,
`--insecure-registry host-ip|domain-name`, to your client Docker daemon startup
flags. You'll need to restart the Docker daemon for the change to take effect.

This flag means that the communications between your Docker client and the Trusted Registry server are still encrypted, but the client Docker daemon is not
confirming that the Registry connection is not being hijacked or diverted.

If you enter a "Domain Name" into the Security settings, it needs to be DNS
resolvable on any client daemons that are running in `insecure-registry`
mode.

To set the flag, perform the following directions for your operating system.

#### Ubuntu

On Ubuntu 14.04 LTS, customize the Docker daemon configuration with the
`/etc/defaults/docker` file.

Open or create the `/etc/defaults/docker` file, and add the
`--insecure-registry` flag to the `DOCKER_OPTS` setting (which may need to be
added or uncommented) as follows:

```
DOCKER_OPTS="--insecure-registry dtr.yourdomain.com"
```

Then restart the Docker daemon with `sudo service docker restart`.

#### RHEL/Centos

On RHEL/Centos, customize the Docker daemon configuration with the
`/etc/sysconfig/docker` file.

Open or create the `/etc/sysconfig/docker` file, and add the
`--insecure-registry` flag to the `OPTIONS` setting (which may need to be
added or uncommented) as follows:

```
OPTIONS="--insecure-registry dtr.yourdomain.com"
```

Then restart the Docker daemon with `sudo service docker restart`.

### Docker Machine and Boot2Docker

In your Boot2Docker-based virtual machine, customize the Docker daemon
configuration with the `/var/lib/boot2docker/profile` file.

Open or create the `/var/lib/boot2docker/profile` file, and add an `EXTRA_ARGS`
setting as follows:

```
EXTRA_ARGS="--insecure-registry dtr.yourdomain.com"
```

Then restart the Docker daemon with `sudo /etc/init.d/docker restart`.


## See also

* [Configure storage options](config-storage.md)