explain how the script works in the documentation
authorCharles McGarvey <chazmcgarvey@brokenzipper.com>
Sun, 10 Dec 2017 18:17:43 +0000 (11:17 -0700)
committerCharles McGarvey <chazmcgarvey@brokenzipper.com>
Sun, 10 Dec 2017 18:18:37 +0000 (11:18 -0700)
README.md
docker-connect

index f157b75..84f8a30 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`
 
index 93c5bac..04ae80a 100755 (executable)
@@ -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>
 
This page took 0.027486 seconds and 4 git commands to generate.