mirror of https://github.com/docker/docs.git
357 lines
15 KiB
Markdown
357 lines
15 KiB
Markdown
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 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://<dhe-host>/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
|
|
|
|
|
|
|
|
* *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.
|
|
|
|
|
|
|
|
* *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.
|
|
|
|
|
|
|
|
* 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.
|
|
|
|
|
|
|
|
* *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).
|
|
|