mirror of https://github.com/docker/docs.git
Add d4mac client side FAQ (#3671)
* add d4mac client side FAQ Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * added link to FAQs from Getting Started Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * added FAQs re: installing client certificates Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * added more detail on client and server side certs Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * fixed Mac and Windows specific topics Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * fixed formatting so that content renders properly Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * incorporated review comments Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * updated Windows FAQ to clarify directories copy, remove refs to db Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * change ref from Mac to Windows on Win side Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * added certificate topic to Win getting started Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * review comments, remove 'entities' clarify meaning Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
This commit is contained in:
Victoria Bialas
GitHub
parent
59f1eceb8e
commit
a3bbadb7ed
|
|
@ -169,21 +169,20 @@ in the Networking topic.
|
|||
Starting with Docker for Mac Beta 27 and Stable 1.12.3, all trusted certificate
|
||||
authorities (CAs) (root or intermediate) are supported.
|
||||
|
||||
Docker for Mac creates a certificate bundle of all user-trusted CAs based on the
|
||||
Mac Keychain, and appends it to Moby trusted certificates. So if an enterprise
|
||||
SSL certificate is trusted by the user on the host, it will be trusted by Docker
|
||||
for Mac.
|
||||
For full information on adding server and client side certs, see [Adding
|
||||
TLS certificates](/docker-for-mac/index.md#adding-tls-certificates) in
|
||||
the Getting Started topic.
|
||||
|
||||
To manually add a custom, self-signed certificate, start by adding
|
||||
the certificate to the Mac’s keychain, which will be picked up by Docker for
|
||||
Mac. Here is an example.
|
||||
### How do I add client certificates?
|
||||
|
||||
```bash
|
||||
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt
|
||||
```
|
||||
Starting with Docker for Mac 17.06.0-ce, you do not have to push your
|
||||
certificates with `git` commands anymore. You can put your client certificates
|
||||
in `~/.docker/certs.d/<MyRegistry>:<Port>/client.cert` and
|
||||
`~/.docker/certs.d/<MyRegistry>:<Port>/client.key`.
|
||||
|
||||
For a complete explanation of how to do this, see the blog post
|
||||
[Adding Self-signed Registry Certs to Docker & Docker for Mac](http://container-solutions.com/adding-self-signed-registry-certs-docker-mac/).
|
||||
For full information on adding server and client side certs, see [Adding
|
||||
TLS certificates](/docker-for-mac/index.md#adding-tls-certificates) in
|
||||
the Getting Started topic.
|
||||
|
||||
### How do I reduce the size of Docker.qcow2?
|
||||
|
||||
|
|
|
|||
|
|
@ -277,9 +277,12 @@ As an alternative to using [Docker Hub](https://hub.docker.com/) to store your
|
|||
public or private images or [Docker Trusted
|
||||
Registry](/datacenter/dtr/2.1/guides/index.md), you can use Docker to set up
|
||||
your own insecure [registry](/registry/introduction.md). Add URLs for insecure
|
||||
registries and registry mirrors on which to host your images. (See also,
|
||||
[How do I add custom CA certificates?](/docker-for-mac/faqs.md#how-do-i-add-custom-ca-certificates)
|
||||
in the FAQs.)
|
||||
registries and registry mirrors on which to host your images.
|
||||
|
||||
See also, [How do I add custom CA
|
||||
certificates?](/docker-for-mac/faqs.md#how-do-i-add-custom-ca-certificates) and
|
||||
[How do I add client
|
||||
certificates](/docker-for-mac/faqs.md#how-do-i-client-certificates) in the FAQs.
|
||||
|
||||
#### Edit the daemon configuration file
|
||||
|
||||
|
|
@ -331,14 +334,115 @@ This option removes/resets all Docker data _without_ a reset to factory defaults
|
|||
|
||||
|
||||
|
||||
## Adding TLS certificates
|
||||
|
||||
You can add trusted Certificate Authorities (CAs) (used to verify registry
|
||||
server certificates) and client certificates (used to authenticate to
|
||||
registries) to your Docker daemon.
|
||||
|
||||
### Adding custom CA certificates (server side)
|
||||
|
||||
All trusted CAs (root or intermediate) are supported.
|
||||
Docker for Mac creates a certificate bundle of all user-trusted CAs based on the
|
||||
Mac Keychain, and appends it to Moby trusted certificates. So if an enterprise
|
||||
SSL certificate is trusted by the user on the host, it will be trusted by Docker
|
||||
for Mac.
|
||||
|
||||
To manually add a custom, self-signed certificate, start by adding
|
||||
the certificate to the Mac’s keychain, which will be picked up by Docker for
|
||||
Mac. Here is an example.
|
||||
|
||||
```bash
|
||||
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt
|
||||
```
|
||||
|
||||
Or, if you prefer to add the certificate to your own local keychain only (rather
|
||||
than for all users), run this command instead:
|
||||
|
||||
```
|
||||
security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain ca.crt
|
||||
```
|
||||
|
||||
See also, [Directory structures for
|
||||
certificates](#directory-structures-for-certificates).
|
||||
|
||||
> **Note:** You need to restart Docker for Mac after making any changes to
|
||||
the keychain or to the `~/.docker/certs.d` directory in order for
|
||||
the changes to take effect.
|
||||
|
||||
For a complete explanation of how to do this, see the blog post [Adding
|
||||
Self-signed Registry Certs to Docker & Docker for
|
||||
Mac](http://container-solutions.com/adding-self-signed-registry-certs-docker-mac/).
|
||||
|
||||
### Adding client certificates
|
||||
|
||||
You can put your client certificates in
|
||||
`~/.docker/certs.d/<MyRegistry>:<Port>/client.cert` and
|
||||
`~/.docker/certs.d/<MyRegistry>:<Port>/client.key`.
|
||||
|
||||
When the Docker for Mac application starts up, it copies the `~/.docker/certs.d`
|
||||
folder on your Mac to the `/etc/docker/certs.d` directory on Moby (the Docker
|
||||
for Mac `xhyve` virtual machine).
|
||||
|
||||
> * You need to restart Docker for Mac after making any changes to
|
||||
the keychain or to the `~/.docker/certs.d` directory in order for
|
||||
the changes to take effect.
|
||||
>
|
||||
> * The registry cannot be listed as an _insecure registry_ (see [Docker
|
||||
Daemon](/docker-for-mac/index.md#docker-daemon)). Docker for Mac will ignore
|
||||
certificates listed under insecure registries, and will not send client
|
||||
certificates. Commands like `docker run` that attempt to pull from
|
||||
the registry will produce error messages on the command line, as well as on the
|
||||
registry.
|
||||
|
||||
### Directory structures for certificates
|
||||
|
||||
If you have this directory structure, you do not need to manually add the CA
|
||||
certificate to your Mac OS system login:
|
||||
|
||||
```
|
||||
/Users/<user>/.docker/certs.d/
|
||||
└── <MyRegistry>:<Port>
|
||||
├── ca.crt
|
||||
├── client.cert
|
||||
└── client.key
|
||||
```
|
||||
|
||||
The following further illustrates and explains a configuration with custom
|
||||
certificates:
|
||||
|
||||
```
|
||||
/etc/docker/certs.d/ <-- Certificate directory
|
||||
└── localhost:5000 <-- Hostname:port
|
||||
├── client.cert <-- Client certificate
|
||||
├── client.key <-- Client key
|
||||
└── ca.crt <-- Certificate authority that signed
|
||||
the registry certificate
|
||||
```
|
||||
|
||||
You can also have this directory structure, as long as the CA certificate is
|
||||
also in your keychain.
|
||||
|
||||
```
|
||||
/Users/<user>/.docker/certs.d/
|
||||
└── <MyRegistry>:<Port>
|
||||
├── client.cert
|
||||
└── client.key
|
||||
```
|
||||
|
||||
To learn more about how to install a CA root certificate for the registry and
|
||||
how to set the client TLS certificate for verification, see [Verify repository
|
||||
client with certificates](/engine/security/certificates.md) in the Docker Engine
|
||||
topics.
|
||||
|
||||
## Installing bash completion
|
||||
|
||||
If you are using
|
||||
[bash completion](https://www.debian-administration.org/article/316/An_introduction_to_bash_completion_part_1),
|
||||
such as
|
||||
[homebrew bash-completion on Mac](http://davidalger.com/development/bash-completion-on-os-x-with-brew/)
|
||||
bash completion scripts for the following commands may be found inside
|
||||
`Docker.app`, in the `Contents/Resources/etc/` directory:
|
||||
If you are using [bash
|
||||
completion](https://www.debian-administration.org/article/316/An_introduction_to_bash_completion_part_1),
|
||||
such as [homebrew bash-completion on
|
||||
Mac](http://davidalger.com/development/bash-completion-on-os-x-with-brew/) bash
|
||||
completion scripts for the following commands may be found inside `Docker.app`,
|
||||
in the `Contents/Resources/etc/` directory:
|
||||
|
||||
- docker
|
||||
- docker-machine
|
||||
|
|
|
|||
|
|
@ -118,6 +118,28 @@ auto-generated reports on packages.
|
|||
|
||||
## Troubleshooting
|
||||
|
||||
### Make sure certificates are set up correctly
|
||||
|
||||
Docker for Mac will ignore certificates listed under insecure registries, and
|
||||
will not send client certificates to them. Commands like `docker run` that
|
||||
attempt to pull from the registry will produce error messages on the command
|
||||
line, like this:
|
||||
|
||||
```bash
|
||||
Error response from daemon: Get http://192.168.203.139:5858/v2/: malformed HTTP response "\x15\x03\x01\x00\x02\x02"
|
||||
```
|
||||
|
||||
As well as on the registry. For example:
|
||||
|
||||
```config
|
||||
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52882: tls: client didn't provide a certificate
|
||||
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52883: tls: first record does not look like a TLS handshake
|
||||
```
|
||||
|
||||
For more about using client and server side certificates, see [Adding
|
||||
TLS certificates](/docker-for-mac/index.md#adding-tls-certificates) in
|
||||
the Getting Started topic.
|
||||
|
||||
### Docker for Mac will not start if Mac user account and home folder are renamed after installing the app
|
||||
|
||||
If, after installing Docker for Mac, you [change the name of your macOS user
|
||||
|
|
@ -210,7 +232,11 @@ in the Apple Hypervisor Framework documentation about supported hardware:
|
|||
To check if your Mac supports the Hypervisor framework, run this command in a
|
||||
terminal window.
|
||||
|
||||
``` sysctl kern.hv_support ``` If your Mac supports the Hypervisor Framework,
|
||||
```bash
|
||||
sysctl kern.hv_support
|
||||
```
|
||||
|
||||
If your Mac supports the Hypervisor Framework,
|
||||
the command will print `kern.hv_support: 1`.
|
||||
|
||||
If not, the command will print `kern.hv_support: 0`.
|
||||
|
|
|
|||
|
|
@ -161,17 +161,44 @@ To learn more about the reasons for this limitation, see the following discussio
|
|||
### How do I add custom CA certificates?
|
||||
|
||||
Starting with Docker for Windows 1.12.1, 2016-09-16 (Stable) and Beta 26
|
||||
(2016-09-14 1.12.1-beta26), all trusted CAs (root or intermediate) are
|
||||
supported. Docker recognizes certs stored under Trust Root Certification
|
||||
Authorities or Intermediate Certification Authorities.
|
||||
(2016-09-14 1.12.1-beta26), all trusted Certificate Authorities (CA) (root or
|
||||
intermediate) are supported. Docker recognizes certs stored under Trust Root
|
||||
Certification Authorities or Intermediate Certification Authorities.
|
||||
|
||||
Docker for Windows creates a certificate bundle of all user-trusted CAs based on
|
||||
the Windows certificate store, and appends it to Moby trusted certificates. So
|
||||
if an enterprise SSL certificate is trusted by the user on the host, it will be
|
||||
trusted by Docker for Windows.
|
||||
|
||||
To learn more, see the GitHub issue [Allow user to add custom Certificate
|
||||
Authorities](https://github.com/docker/for-win/issues/48).
|
||||
To learn more about how to install a CA root certificate for the registry, see
|
||||
[Verify repository client with certificates](/engine/security/certificates.md)
|
||||
in the Docker Engine topics.
|
||||
|
||||
### How do I add client certificates?
|
||||
|
||||
Starting with Docker for Windows 17.06.0-ce, you do not have to push your
|
||||
certificates with `git` commands anymore. You can put your client certificates
|
||||
in `~/.docker/certs.d/<MyRegistry>:<Port>/client.cert` and
|
||||
`~/.docker/certs.d/<MyRegistry>:<Port>/client.key`.
|
||||
|
||||
When the Docker for Windows application starts up, it copies the
|
||||
`~/.docker/certs.d` folder on your Windows system to the `/etc/docker/certs.d`
|
||||
directory on Moby (the Docker for Windows virtual machine running on Hyper-V).
|
||||
|
||||
> * You need to restart Docker for Windows after making any changes to
|
||||
the keychain or to the `~/.docker/certs.d` directory in order for
|
||||
the changes to take effect.
|
||||
>
|
||||
> * The registry cannot be listed as an _insecure registry_ (see [Docker
|
||||
Daemon](/docker-for-windows/index.md#docker-daemon)). Docker for Windows will
|
||||
ignore certificates listed under insecure registries, and will not send client
|
||||
certificates. Commands like `docker run` that attempt to pull from
|
||||
the registry will produce error messages on the command line, as well as on the
|
||||
registry.
|
||||
|
||||
To learn more about how to set the client TLS certificate for verification, see
|
||||
[Verify repository client with certificates](/engine/security/certificates.md)
|
||||
in the Docker Engine topics.
|
||||
|
||||
### Why does Docker for Windows sometimes lose network connectivity (e.g., `push`/`pull` doesn't work)?
|
||||
|
||||
|
|
|
|||
|
|
@ -564,7 +564,7 @@ public or private images or [Docker Trusted
|
|||
Registry](/datacenter/dtr/2.1/guides/index.md), you can use Docker to set up
|
||||
your own insecure [registry](/registry/introduction.md). Add URLs for insecure
|
||||
registries and registry mirrors on which to host your images. (See also, [How do
|
||||
I add custom CA certificates?](faqs.md#how-do-i-add-custom-ca-certificates) in
|
||||
I add custom CA certificates?](faqs.md#how-do-i-add-custom-ca-certificates) and [How do I add client certificates?](faqs.md#how-do-i-add-client-certificates) in
|
||||
the FAQs.)
|
||||
|
||||
#### Edit the daemon configuration file
|
||||
|
|
@ -751,11 +751,17 @@ behavior, and steps to reproduce the issue.
|
|||
* **Reset to factory defaults** - Resets Docker to factory defaults. This is
|
||||
useful in cases where Docker stops working or becomes unresponsive.
|
||||
|
||||
<!-- ### Going back to Toolbox
|
||||
## Adding TLS certificates
|
||||
|
||||
If you want to go back to using Docker Toolbox, you have to disable the Hyper-V Windows feature. To do this, go to the Windows **Control Panel -> Programs and Features -> Turn Windows Features on or off**, uncheck Hyper-V, and click **OK**. You can then use `docker-machine` and VirtualBox to run Docker containers.
|
||||
You can add trusted Certificate Authorities (CAs) (used to verify registry
|
||||
server certificates) and client certificates (used to authenticate to
|
||||
registries) to your Docker daemon.
|
||||
|
||||
[These instructions](https://msdn.microsoft.com/en-us/virtualization/hyperv_on_windows/quick_start/walkthrough_install), which explain how to *enable* Hyper-V, show you how to get to the on/off controls for the Hyper-V feature. -->
|
||||
To learn more, see [How do I add custom CA
|
||||
certificates?](/docker-for-windows/faqs.md#how-do-i-add-custom-ca-certificates)
|
||||
and [How do I add client
|
||||
certificates?](/docker-for-windows/faqs.md#how-do-i-add-client-certificates) in
|
||||
the FAQs.
|
||||
|
||||
## Where to go next
|
||||
|
||||
|
|
|
|||
|
|
@ -46,6 +46,30 @@ can use in email or the forum to reference the upload.
|
|||
|
||||
## Troubleshooting
|
||||
|
||||
### Make sure certificates are set up correctly
|
||||
|
||||
Docker for Windows will ignore certificates listed under insecure registries,
|
||||
and will not send client certificates to them. Commands like `docker run` that
|
||||
attempt to pull from the registry will produce error messages on the command
|
||||
line, like this:
|
||||
|
||||
```
|
||||
Error response from daemon: Get http://192.168.203.139:5858/v2/: malformed HTTP response "\x15\x03\x01\x00\x02\x02"
|
||||
```
|
||||
|
||||
As well as on the registry. For example:
|
||||
|
||||
```
|
||||
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52882: tls: client didn't provide a certificate
|
||||
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52883: tls: first record does not look like a TLS handshake
|
||||
```
|
||||
|
||||
For more about using client and server side certificates, see [How do I add
|
||||
custom CA certificates?](/docker-for-windows/index.md#how-do-i-add-custom-ca
|
||||
certificates) and [How do I add client
|
||||
certificates?](/docker-for-windows/index.md#how-do-i-add-client-certificates) in
|
||||
the Getting Started topic.
|
||||
|
||||
### Permissions errors on data directories for shared volumes
|
||||
|
||||
Docker for Windows sets permissions on [shared
|
||||
|
|
|
|||
Loading…
Reference in New Issue