X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fdocker-connect;a=blobdiff_plain;f=README.md;h=84f8a30841cf953210090e829fd222dbaa26d714;hp=f157b75723d7fda6f0c16f2ff85ec5928bb5d289;hb=1802015a09c1311f7815c6e1ee95b3dbdbc33107;hpb=2016d571fa22fc4660d9227cb94d799b2946ff7e;ds=sidebyside

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`