diff --git a/docker-for-mac/faqs.md b/docker-for-mac/faqs.md index 180457d2d1..acd7d7bed0 100644 --- a/docker-for-mac/faqs.md +++ b/docker-for-mac/faqs.md @@ -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/:/client.cert` and +`~/.docker/certs.d/:/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? diff --git a/docker-for-mac/index.md b/docker-for-mac/index.md index 30c2e6bb43..63fab44550 100644 --- a/docker-for-mac/index.md +++ b/docker-for-mac/index.md @@ -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 ![Uninstall or reset Docker Edge features](images/settings-uninstall-edge.png) +## 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/:/client.cert` and +`~/.docker/certs.d/:/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//.docker/certs.d/ +└── : + ├── 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//.docker/certs.d/ +└── : + ├── 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 diff --git a/docker-for-mac/troubleshoot.md b/docker-for-mac/troubleshoot.md index f5ca95db4a..64b5707f4f 100644 --- a/docker-for-mac/troubleshoot.md +++ b/docker-for-mac/troubleshoot.md @@ -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`. diff --git a/docker-for-windows/faqs.md b/docker-for-windows/faqs.md index 7af16ef954..fb9ac65168 100644 --- a/docker-for-windows/faqs.md +++ b/docker-for-windows/faqs.md @@ -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/:/client.cert` and +`~/.docker/certs.d/:/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)? diff --git a/docker-for-windows/index.md b/docker-for-windows/index.md index db476ad250..5ca905341f 100644 --- a/docker-for-windows/index.md +++ b/docker-for-windows/index.md @@ -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. - +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 diff --git a/docker-for-windows/troubleshoot.md b/docker-for-windows/troubleshoot.md index 66e013443c..946d8b52db 100644 --- a/docker-for-windows/troubleshoot.md +++ b/docker-for-windows/troubleshoot.md @@ -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