From 6fec6ef0c37bede7b4baf01e3f9c8c3103189162 Mon Sep 17 00:00:00 2001 From: Akihiro Suda Date: Wed, 3 Feb 2021 19:02:34 +0900 Subject: [PATCH] engine/security: add more description about ssh:// Previously, the `ssh://` helper was only mentioned in `engine/security/index.md`. The `ssh://` helper is now documented in "Protect the Docker daemon socket" (`engine/security/protect-access.md`, nee `engine/security/https.md`). Signed-off-by: Akihiro Suda --- _data/toc.yaml | 2 +- engine/install/linux-postinstall.md | 2 +- engine/security/certificates.md | 4 +- engine/security/https/README.md | 2 +- engine/security/https/parsedocs.sh | 2 +- engine/security/index.md | 2 +- .../security/{https.md => protect-access.md} | 89 ++++++++++++++++--- 7 files changed, 85 insertions(+), 18 deletions(-) rename engine/security/{https.md => protect-access.md} (77%) diff --git a/_data/toc.yaml b/_data/toc.yaml index aff885d2b9..f8f0a9e633 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -205,7 +205,7 @@ guides: title: Docker security - path: /engine/security/non-events/ title: Docker security non-events - - path: /engine/security/https/ + - path: /engine/security/protect-access/ title: Protect the Docker daemon socket - path: /engine/security/certificates/ title: Using certificates for repository client verification diff --git a/engine/install/linux-postinstall.md b/engine/install/linux-postinstall.md index 16cc8035e8..473b32248a 100644 --- a/engine/install/linux-postinstall.md +++ b/engine/install/linux-postinstall.md @@ -151,7 +151,7 @@ the [Docker CLI Reference](/engine/reference/commandline/dockerd/) article. > understand the security implications of opening docker to the network. If steps are not taken to secure the connection, > it is possible for remote non-root users to gain root access on the host. For more information on how to use TLS > certificates to secure this connection, check this article on -> [how to protect the Docker daemon socket](../security/https.md). +> [how to protect the Docker daemon socket](../security/protect-access.md). {: .warning} Configuring Docker to accept remote connections can be done with the `docker.service` diff --git a/engine/security/certificates.md b/engine/security/certificates.md index 77ebe3c761..3a2cbbb7be 100644 --- a/engine/security/certificates.md +++ b/engine/security/certificates.md @@ -6,7 +6,7 @@ redirect_from: title: Verify repository client with certificates --- -In [Running Docker with HTTPS](https.md), you learned that, by default, +In [Running Docker with HTTPS](protect-access.md), you learned that, by default, Docker runs via a non-networked Unix socket and TLS must be enabled in order to have the Docker client and the daemon communicate securely over HTTPS. TLS ensures authenticity of the registry endpoint and that traffic to/from registry is encrypted. @@ -92,4 +92,4 @@ If the Docker registry is accessed without a port number, do not add the port to ## Related information * [Use trusted images](trust/index.md) -* [Protect the Docker daemon socket](https.md) +* [Protect the Docker daemon socket](protect-access.md) diff --git a/engine/security/https/README.md b/engine/security/https/README.md index 8db187c76b..650c650a0f 100644 --- a/engine/security/https/README.md +++ b/engine/security/https/README.md @@ -2,7 +2,7 @@ published: false --- -This is an initial attempt to make it easier to test the examples in the https.md +This is an initial attempt to make it easier to test the TLS (HTTPS) examples in the protect-access.md doc. At this point, it is a manual thing, and I've been running it in boot2docker. diff --git a/engine/security/https/parsedocs.sh b/engine/security/https/parsedocs.sh index f9df33c337..f66705df59 100755 --- a/engine/security/https/parsedocs.sh +++ b/engine/security/https/parsedocs.sh @@ -1,7 +1,7 @@ #!/bin/sh echo "#!/bin/sh" -cat ../https.md | awk '{if (sub(/\\$/,"")) printf "%s", $0; else print $0}' \ +cat ../protect-access.md | awk '{if (sub(/\\$/,"")) printf "%s", $0; else print $0}' \ | grep ' $ ' \ | sed 's/ $ //g' \ | sed 's/2375/7777/g' \ diff --git a/engine/security/index.md b/engine/security/index.md index 532794b1a1..e9dc01fc91 100644 --- a/engine/security/index.md +++ b/engine/security/index.md @@ -116,7 +116,7 @@ Note that even if you have a firewall to limit accesses to the REST API endpoint from other hosts in the network, the endpoint can be still accessible from containers, and it can easily result in the privilege escalation. Therefore it is *mandatory* to secure API endpoints with -[HTTPS and certificates](https.md). +[HTTPS and certificates](protect-access.md). It is also recommended to ensure that it is reachable only from a trusted network or VPN. diff --git a/engine/security/https.md b/engine/security/protect-access.md similarity index 77% rename from engine/security/https.md rename to engine/security/protect-access.md index fdac1e6b10..54f3928ee3 100644 --- a/engine/security/https.md +++ b/engine/security/protect-access.md @@ -1,17 +1,84 @@ --- -description: How to setup and run Docker with HTTPS -keywords: docker, docs, article, example, https, daemon, tls, ca, certificate +description: How to setup and run Docker with SSH or HTTPS +keywords: docker, docs, article, example, ssh, https, daemon, tls, ca, certificate redirect_from: - /engine/articles/https/ - /articles/https/ +- /engine/https/ title: Protect the Docker daemon socket --- By default, Docker runs through a non-networked UNIX socket. It can also -optionally communicate using an HTTP socket. +optionally communicate using SSH or a TLS (HTTPS) socket. -If you need Docker to be reachable through the network in a safe manner, you can -enable TLS by specifying the `tlsverify` flag and pointing Docker's +## Use SSH to protect the Docker daemon socket + +> **Note** +> +> The given `USERNAME` must have permissions to access the docker socket on the +> remote machine. Refer to [manage Docker as a non-root user](../../install/linux-postinstall/#manage-docker-as-a-non-root-user) +> to learn how to give a non-root user access to the docker socket. + +The following example creates a [`docker context`](../../context/working-with-contexts.md) +to connect with a remote `dockerd` daemon on `host1.example.com` using SSH, and +as the `docker-user` user on the remote machine: + +```console +$ docker context create \ + --docker host=ssh://docker-user@host1.example.com \ + --description="Remote engine" \ + my-remote-engine + +my-remote-engine +Successfully created context "my-remote-engine" +``` + +After creating the context, use `docker context use` to switch the `docker` CLI +to use it, and to connect to the remote engine: + +```console +$ docker context use my-remote-engine +my-remote-engine +Current context is now "my-remote-engine" + +$ docker info + +``` + +Use the `default` context to switch back to the default (local) daemon: + +```console +$ docker context use default +default +Current context is now "default" +``` + +Alternatively, use the `DOCKER_HOST` environment variable to temporarily switch +the `docker` CLI to connect to the remote host using SSH. This does not require +creating a context, and can be useful to create an ad-hoc connection with a different +engine: + +```console +$ export DOCKER_HOST=ssh://docker-user@host1.example.com +$ docker info + +``` + +### SSH Tips + +For the best user experience with SSH, configure `~/.ssh/config` as follows to allow +reusing a SSH connection for multiple invocations of the `docker` CLI: + +``` +ControlMaster auto +ControlPath ~/.ssh/control-%C +ControlPersist yes +``` + +## Use TLS (HTTPS) to protect the Docker daemon socket + +If you need Docker to be reachable through HTTP rather than SSH in a safe manner, +you can enable TLS (HTTPS) by specifying the `tlsverify` flag and pointing Docker's `tlscacert` flag to a trusted CA certificate. In the daemon mode, it only allows connections from clients @@ -24,7 +91,7 @@ it only connects to servers with a certificate signed by that CA. > with OpenSSL, x509, and TLS before using it in production. {:.important} -## Create a CA, server and client keys with OpenSSL +### Create a CA, server and client keys with OpenSSL > **Note**: Replace all instances of `$HOST` in the following example with the > DNS name of your Docker daemon's host. @@ -177,7 +244,7 @@ certificates and trusted CA: > these keys as you would a root password! {:.warning} -## Secure by default +### Secure by default If you want to secure your Docker client connections by default, you can move the files to the `.docker` directory in your home directory --- and set the @@ -193,17 +260,17 @@ Docker now connects securely by default: $ docker ps -## Other modes +### Other modes If you don't want to have complete two-way authentication, you can run Docker in various other modes by mixing the flags. -### Daemon modes +#### Daemon modes - `tlsverify`, `tlscacert`, `tlscert`, `tlskey` set: Authenticate clients - `tls`, `tlscert`, `tlskey`: Do not authenticate clients -### Client modes +#### Client modes - `tls`: Authenticate server based on public/default CA pool - `tlsverify`, `tlscacert`: Authenticate server based on given CA @@ -220,7 +287,7 @@ location using the environment variable `DOCKER_CERT_PATH`. $ export DOCKER_CERT_PATH=~/.docker/zone1/ $ docker --tlsverify ps -### Connecting to the secure Docker port using `curl` +#### Connecting to the secure Docker port using `curl` To use `curl` to make test API requests, you need to use three extra command line flags: