Container image for Mutual TLS access to Docker Daemon
A secure, easier-to-use alternative to enabling Docker daemon's built-in mutual TLS settings that works on default daemon installations.
Mutual TLS connections from docker clients are securely terminated at a container with a process that proxies to a docker daemon via a bind-mounted docker socket.
Requirements
- Docker daemon with default settings (Linux or Windows)
- Note: daemon does not need to be listing on network port, only needs default socket listener
- Hostname or IP for your docker daemon host machine
Usage
Start your container
This will start the process and generate self-signed certificates (or re-use previously generated ones).
Linux/MacOS AMD64
hostname=<"my-docker-host" or "10.1.2.3">
docker run --detach \
--name tlsproxy \
--publish 2376:2376 \
--volume tlsproxy-certs:/certs \
--volume /var/run/docker.sock:/var/run/docker.sock \
--restart=always \
--memory 256m \
ghcr.io/micahyoung/docker-mtls-socket-proxy:alpine-amd64 \
-hostname $hostname
- ARM64 image at:
ghcr.io/micahyoung/docker-mtls-socket-proxy:alpine-arm64
Windows
$hostname=<"my-docker-host" or "10.1.2.3">
docker run --detach `
--name tlsproxy `
--publish 2376:2376 `
--volume tlsproxy-certs:c:/certs `
--volume \\.\pipe\docker_engine:\\.\pipe\docker_engine `
--restart always `
--memory 256m `
--isolation process `
ghcr.io/micahyoung/docker-mtls-socket-proxy:nanoserver-amd64 `
-hostname $hostname
Note: if you generate incorrect certs, you must remove the volume or they will not regenerate:
docker volume rm tlsproxy-certs
Copy client credentials to your client
To copy client certs from your container to your client machine, there's a helpful Bash script that is output in the logs.
When run, it will write certs to ~/.docker/$hostname/
along with a helper env.sh
script you can source
.
-
On Docker host, print the logs from the container
docker logs tlsproxy
-
On Docker host, copy/paste all output between
COPY BELOW
andCOPY BELOW
##### COPY BELOW ##### <highlight and copy these lines between, usually ~100> ##### COPY ABOVE #####
-
On client, Follow
INSTRUCTIONS
from logs to check and execute clipboard contents# MacOS pbpaste | shasum # Should match "Expected SHA1:" from logs pbpaste | bash # Linux xclip -o -selection clipboard | shasum xclip -o -selection clipboard | bash
- Note: You can also copy paste data just each certs/key from the logs if preferred
~/.docker/$hostname/cert.pem
~/.docker/$hostname/key.pem
~/.docker/$hostname/ca.pem
- Note: You can also copy paste data just each certs/key from the logs if preferred
-
On client, source your
env.sh
to set yourDOCKER_HOST
DOCKER_TLS_VERIFY
andDOCKER_CERT_PATH
.source ~/.docker/$hostname/env.sh
Avoid your tlsproxy container
If you stop the tlsproxy
container, you'll lose connectivity to your daemon and have to connect over SSH to restart it (docker start tlsproxy
).
To avoid docker
CLI operations effecting your tlsproxy
container, use filters like:
- List all containers besides
tlsproxy
docker ps -f since=tlsproxy
- Remove all containers besides
tlsproxy
docker rm -f $(docker ps -q -f since=tlsproxy)
Build the image locally on a Docker daemon
Linux/MacOS
Note: no certs are included in the image. It generates self-signed certs on container start.
docker build --tag docker-mtls-socket-proxy -f Dockerfile.linux .
Windows
docker build --tag docker-mtls-socket-proxy -f Dockerfile.windows .