github.com/jogo/docker@v1.7.0-rc1/docs/sources/docker-hub-enterprise/configuration.md

page_title: Docker Hub Enterprise: Configuration options
page_description: Configuration instructions for Docker Hub Enterprise
page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry

# Configuring DHE

## Overview

This page will help you properly configure Docker Hub Enterprise (DHE) so it can
run in your environment. 

Start with DHE loaded in your browser and click  the "Settings" tab to view
configuration options. You'll see options for configuring:

* Domains and ports
* Security settings
* Storage settings
* Authentication settings
* Your DHE license

## Domains and Ports

![Domain and Ports page</admin/settings#http>](../assets/admin-settings-http.png)

* *Domain Name*: **required** defaults to an empty string, the fully qualified domain name assigned to the DHE host.
* *Load Balancer HTTP Port*: defaults to 80, used as the entry point for the image storage service. To see load balancer status, you can query
http://&lt;dhe-host&gt;/load_balancer_status.
* *Load Balancer HTTPS Port*: defaults to 443, used as the secure entry point
for the image storage service.
* *HTTP_PROXY*: defaults to an empty string, proxy server for HTTP requests.
* *HTTPS_PROXY*: defaults to an empty string, proxy server for HTTPS requests.
* *NO_PROXY*: defaults to an empty string, proxy bypass for HTTP and HTTPS requests.


> **Note**: If you need DHE to re-generate a self-signed certificate at some
> point, you'll need to first delete `/usr/local/etc/dhe/ssl/server.pem`, and
> then restart the DHE containers, either by changing and saving the "Domain Name",
> or using `bash -c "$(docker run dockerhubenterprise/manager restart)"`.


## Security

![Security settings page</admin/settings#security>](../assets/admin-settings-security.png)

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

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

1. You can use the self-signed certificate DHE generates by default.
2. You can generate your own certificates using a public service or your enterprise's infrastructure. See the [Generating SSL certificates](#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 DHE](#adding-your-own-registry-certificates-to-dhe).

On the other hand, if you choose to use the DHE-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 a registry certificate on all of your client Docker daemons](#installing-registry-certificates-on-client-docker-daemons),

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

### Generating 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 DHE, and install it
onto the client Docker daemon hosts as shown below.

### Adding your own Registry certificates to DHE

Whichever method you use to generate certificates, once you have them
you can set up your DHE server to use them by navigating to the "Settings" page,
going to "Security," and putting 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.

Click the "Save" button, and then wait for the DHE Admin site to restart and
reload. It should now be using the new certificate.

Once the "Security" page has reloaded, it will show `#` hashes instead of the
certificate text you pasted in.

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

### Installing 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 DHE certificates on each Linux distribution has
slightly different steps, as shown below.

You can test this certificate using `curl`:

```
$ curl https://dhe.yourdomain.com/v2/
curl: (60) SSL certificate problem: self signed certificate
More details here: 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 (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/dhe/ssl/server.pem https://dhe.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.

#### Ubuntu/Debian

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

#### RHEL

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

#### Boot2Docker 1.6.0

Install the CA cert (or the auto-generated cert) by adding the following to
your `/var/lib/boot2docker/bootsync.sh`:

```
#!/bin/sh

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


Then get the certificate from the new DHE server using:

```
$ openssl s_client -connect dhe.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 may want to use the changes in
[Pull request 807](https://github.com/boot2docker/boot2docker/pull/807/files)

Now you can either reboot your Boot2Docker virtual machine, or run the following to
install the server certificate, and then 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 DHE
Registry server are still encrypted, but the client Docker daemon is not
confirming that the Registry connection is not being hijacked or diverted.

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

To set the flag, follow the directions below for your operating system.

#### Ubuntu

On Ubuntu 14.04 LTS, you 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 dhe.yourdomain.com"
```

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

#### RHEL

On RHEL, you 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 dhe.yourdomain.com"
```

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

### Boot2Docker

On Boot2Docker, you 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 dhe.yourdomain.com"
```

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

## Image Storage Configuration

DHE offers multiple methods for image storage, which are defined using specific
storage drivers. Image storage can be local, remote, or on a cloud service such
as S3. Storage drivers can be added or customized via the DHE storage driver
API.

![Storage settings page</admin/settings#storage>](../assets/admin-settings-storage.png)

* *Yaml configuration file*: This file (`/usr/local/etc/dhe/storage.yml`) is
used to configure the image storage services. The editable text of the file is
displayed in the dialog box. The schema of this file is identical to that used
by the [Registry 2.0](http://docs.docker.com/registry/configuration/).
* If you are using the file system driver to provide local image storage, you will need to specify a root directory which will get mounted as a sub-path of
`/var/local/dhe/image-storage`. The default value of this root directory is
`/local`, so the full path to it is `/var/local/dhe/image-storage/local`.

> **Note:**
> Saving changes you've made to settings will restart the Docker Hub Enterprise
> instance. The restart may cause a brief interruption for users of the image
> storage system.

## Authentication

The "Authentication" settings tab lets DHE administrators control access
to the DHE web admin tool and to the DHE Registry.

The current authentication methods are `None`, `Basic` and `LDAP`.

> **Note**: if you have issues logging into the DHE admin web interface after changing the authentication
> settings, you may need to use the [emergency access to the DHE admin web interface](./adminguide.md#Emergency-access-to-the-dhe-admin-web-interface).

### No authentication

No authentication means that everyone that can access your DHE web administration
site. This is not recommended for any use other than testing.


### Basic authentication

The `Basic` authentication setting allows the admin to provide username/password pairs local to DHE.
Any user who can successfully authenticate can use DHE to push and pull Docker images.
You can optionally filter the list of users to a subset of just those users with access to the DHE
admin web interface.

![Basic authentication settings page</admin/settings#auth>](../assets/admin-settings-authentication-basic.png)

* A button to add one user, or to upload a CSV file containing username,
password pairs
* A DHE website Administrator Filter, allowing you to either
* * *Allow all authenticated users*: to log into the DHE admin web interface, or
* * *Whitelist usernames*: which allows you to restrict access to the web interface to a listed set of users.

### LDAP authentication

Using LDAP authentication allows you to integrate your DHE registry into your
organization's existing user and authentication database.

As this involves existing infrastructure external to DHE and Docker, you will need to
gather the details required to configure DHE for your organization's particular LDAP
implementation.

You can test that you have the necessary LDAP server information by using it from
inside a Docker container running on the same server as your DHE:

> **Note**: if the LDAP server is configured to use *StartTLS*, then you need to add `-Z` to the
> `ldapsearch` command examples below.

```
docker run --rm -it svendowideit/ldapsearch -h <LDAP Server hostname> -b <User Base DN> -D <Search User DN> -w <Search User Password>
```

or if the LDAP server is set up to allow anonymous access (which means your *Search User DN* and *Search User Password* settings can remain empty):

```
docker run --rm -it svendowideit/ldapsearch -h <LDAP Server hostname> -b <User Base DN> -x
```

The result of these queries should be a (very) long list - if you get an authentication error,
then the details you have been given are not sufficient.

The *User Login Attribute* key setting must match the field used in the LDAP server
for the user's login-name. On OpenLDAP, it's generally `uid`, and on Microsoft Active Directory
servers, it's `sAMAccountName`. The `ldapsearch` output above should allow you to
confirm which setting you need.

![LDAP authentication settings page</admin/settings#auth>](../assets/admin-settings-authentication-ldap.png)

* *Use StartTLS*: defaults to unchecked, check to enable StartTLS
* *LDAP Server URL*: **required** defaults to null, LDAP server URL (e.g., - ldap://example.com)
* *User Base DN*: **required** defaults to null, user base DN in the form (e.g., - dc=example,dc=com)
* *User Login Attribute*: **required** defaults to null, user login attribute (e.g., - uid or sAMAccountName)
* *Search User DN*: **required** defaults to null, search user DN (e.g., - domain\username)
* *Search User Password*: **required** defaults to null, search user password
* A *DHE Registry User filter*: allowing you to either
* * *Allow all authenticated users* to push or pull any images, or
* * *Filter LDAP search results*: which allows you to restrict DHE registry pull and push to users matching the LDAP filter,
* * *Whitelist usernames*: which allows you to restrict DHE registry pull and push to the listed set of users.
* A *DHE website Administrator filter*, allowing you to either
* * *Allow all authenticated users*: to log into the DHE admin web interface, or
* * *Filter LDAP search results*: which allows you to restrict DHE admin web access to users matching the LDAP filter,
* * *Whitelist usernames*: which allows you to restrict access to the web interface to the listed set of users.


## Next Steps

For information on getting support for DHE, take a look at the
[Support information](./support.md).