explain how the script works in the documentation

diff --git a/README.md b/README.md
index f157b75723d7fda6f0c16f2ff85ec5928bb5d289..84f8a30841cf953210090e829fd222dbaa26d714 100644 (file)
--- 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 93c5bac3ada0f9f5925a4993d785abeb53e75363..04ae80a8a0501e634129cfd76fa26da7143e8860 100755 (executable)
--- 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<ssh(1)> to create a UNIX socket that forwards to the Docker daemon's own UNIX socket on
+the remote host. The benefit that C<docker-connect> has over executing these commands directly is
+C<docker-connect> doesn't require write access to the current directory since it puts its sockets in
+C<$TMPDIR> (typically F</tmp>).
+
+If your local system doesn't support UNIX sockets, you could use the following C<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.
+
 =head1 REQUIREMENTS
 
 =over
@@ -93,7 +118,7 @@ The hostname of the remote peer.
 
 =item * C<DOCKER_CONNECT_PID>
 
-The PID of the SSH process maintaining the connection.
+The process ID of the SSH process maintaining the connection.
 
 =item * C<DOCKER_HOST>