From 1802015a09c1311f7815c6e1ee95b3dbdbc33107 Mon Sep 17 00:00:00 2001 From: Charles McGarvey Date: Sun, 10 Dec 2017 11:17:43 -0700 Subject: [PATCH] explain how the script works in the documentation --- README.md | 31 ++++++++++++++++++++++++++++--- docker-connect | 31 ++++++++++++++++++++++++++++--- 2 files changed, 56 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index f157b75..84f8a30 100644 --- a/README.md +++ b/README.md @@ -16,14 +16,15 @@ Version 0.80 # list the docker processes running on staging-01.acme.tld docker-connect staging-01.acme.tld -c 'docker ps' + # connect as a specific user and a specific port + docker-connect myusername@staging-01.acme.tld:2222 + # DESCRIPTION This script provides an alternative to Docker Machine for connecting your Docker client to a remote Docker daemon. Instead of connecting directly to a Docker daemon listening on an external TCP port, this script sets up a connection to the UNIX socket via SSH. -Why? - The main use case for this is when dealing with "permanent" app servers in an environment where you have a team of individuals who all need access. @@ -44,6 +45,30 @@ To be clear, this script isn't a full replacement for Docker Machine. For one th a lot more features and can actually create machines. This script just assists with a particular workflow that is currently underserved by Machine. +# HOW IT WORKS + +What this script actually does is something similar to this sequence of commands: + + ssh -L$PWD/docker.sock:/run/docker.sock $REMOTE_USER@$REMOTE_HOST -p$REMOTE_PORT -nNT & + export DOCKER_HOST="unix://$PWD/docker.sock" + unset DOCKER_CERT_PATH + unset DOCKER_TLS_VERIFY + +This uses [ssh(1)](http://man.he.net/man1/ssh) to create a UNIX socket that forwards to the Docker daemon's own UNIX socket on +the remote host. The benefit that `docker-connect` has over executing these commands directly is +`docker-connect` doesn't require write access to the current directory since it puts its sockets in +`$TMPDIR` (typically `/tmp`). + +If your local system doesn't support UNIX sockets, you could use the following `ssh` command +instead which uses a TCP socket: + + ssh -L2000:/run/docker.sock $REMOTE_USER@$REMOTE_HOST -p$REMOTE_PORT -nNT & + export DOCKER_HOST="tcp://localhost:2000" + +An important drawback here is that any local user on the machine will then have unchallenged access +to the remote Docker daemon by just connecting to localhost:2000. But this may be a reasonable +alternative for use on non-multiuser machines only. + # REQUIREMENTS - a Bourne-compatible, POSIX-compatible shell @@ -82,7 +107,7 @@ The following environment variables may affect or will be set by this program: - `DOCKER_CONNECT_PID` - The PID of the SSH process maintaining the connection. + The process ID of the SSH process maintaining the connection. - `DOCKER_HOST` diff --git a/docker-connect b/docker-connect index 93c5bac..04ae80a 100755 --- a/docker-connect +++ b/docker-connect @@ -21,14 +21,15 @@ Version 0.80 # list the docker processes running on staging-01.acme.tld docker-connect staging-01.acme.tld -c 'docker ps' + # connect as a specific user and a specific port + docker-connect myusername@staging-01.acme.tld:2222 + =head1 DESCRIPTION This script provides an alternative to Docker Machine for connecting your Docker client to a remote Docker daemon. Instead of connecting directly to a Docker daemon listening on an external TCP port, this script sets up a connection to the UNIX socket via SSH. -Why? - The main use case for this is when dealing with "permanent" app servers in an environment where you have a team of individuals who all need access. @@ -49,6 +50,30 @@ To be clear, this script isn't a full replacement for Docker Machine. For one th a lot more features and can actually create machines. This script just assists with a particular workflow that is currently underserved by Machine. +=head1 HOW IT WORKS + +What this script actually does is something similar to this sequence of commands: + + ssh -L$PWD/docker.sock:/run/docker.sock $REMOTE_USER@$REMOTE_HOST -p$REMOTE_PORT -nNT & + export DOCKER_HOST="unix://$PWD/docker.sock" + unset DOCKER_CERT_PATH + unset DOCKER_TLS_VERIFY + +This uses L to create a UNIX socket that forwards to the Docker daemon's own UNIX socket on +the remote host. The benefit that C has over executing these commands directly is +C doesn't require write access to the current directory since it puts its sockets in +C<$TMPDIR> (typically F). + +If your local system doesn't support UNIX sockets, you could use the following C command +instead which uses a TCP socket: + + ssh -L2000:/run/docker.sock $REMOTE_USER@$REMOTE_HOST -p$REMOTE_PORT -nNT & + export DOCKER_HOST="tcp://localhost:2000" + +An important drawback here is that any local user on the machine will then have unchallenged access +to the remote Docker daemon by just connecting to localhost:2000. But this may be a reasonable +alternative for use on non-multiuser machines only. + =head1 REQUIREMENTS =over @@ -93,7 +118,7 @@ The hostname of the remote peer. =item * C -The PID of the SSH process maintaining the connection. +The process ID of the SSH process maintaining the connection. =item * C -- 2.43.0