explain how the script works in the documentation

[chaz/docker-connect] / docker-connect

diff --git a/docker-connect b/docker-connect
index ca2f3f24b427308abebdeb105f7e9094c1f700f2..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>
 
@@ -236,8 +261,6 @@ if echo "$hostname" |grep -q '@'
 then
     user=$(echo "$hostname" |cut -d@ -f1)
     hostname=$(echo "$hostname" |cut -d@ -f2)
-else
-    user=$(cat ansible.cfg 2>/dev/null |sed -ne 's/^remote_user[[:space:]]*=[[:space:]]*//p')
 fi
 
 ssh_connect="$hostname"