8 docker
-connect - Easily connect to Docker sockets over SSH
16 docker
-connect HOSTNAME
[SHELL_ARGS
]...
18 # launch a new shell wherein docker commands go to staging-01.acme.tld
19 docker
-connect staging
-01.acme.tld
21 # list the docker processes running on staging-01.acme.tld
22 docker
-connect staging
-01.acme.tld
-c 'docker ps'
26 This
script provides an alternative to Docker Machine
for connecting your Docker client to a remote
27 Docker daemon. Instead of connecting directly to a Docker daemon listening on an external TCP port
,
28 this
script sets up a connection to the UNIX socket via SSH.
32 The main use
case for this is when dealing with
"permanent" app servers
in an environment where you
33 have a team of individuals who all need access.
35 Machine doesn
't have a great way to support multiple concurrent users. You can add an existing
36 machine to which you have SSH access using the generic driver on your computer, but if your
37 colleague does the same then Machine will regenerate the Docker daemon TLS certificates, replacing
38 the ones Machine set up for you.
40 Furthermore, the Docker daemon relies on TLS certificates for client authorization, which is all
41 fine and good, but organizations are typically not as prepared to deal with the management of client
42 TLS certificates as they are with the management of SSH keys. Worse, the Docker daemon doesn't
43 support certificate revocation lists
! So
if a colleague leaves
, you must replace the certificate
44 authority and recreate and distribute certificates
for each remaining member of the team. Ugh
!
46 Much easier to just use SSH
for authorization.
48 To be
clear, this
script isn
't a full replacement for Docker Machine. For one thing, Machine has
49 a lot more features and can actually create machines. This script just assists with a particular
50 workflow that is currently underserved by Machine.
56 =item * a Bourne-compatible, POSIX-compatible shell
58 This program is written in shell script.
60 =item * L<OpenSSH|https://www.openssh.com> 6.7+
62 Needed to make the socket connection.
64 =item * L<Docker|https://www.docker.com> client
66 Not technically required, but this program isn't useful without it.
72 =for markdown
[![Build Status
](https
://travis
-ci.org
/chazmcgarvey
/docker
-connect.svg?branch
=master
)](https
://travis
-ci.org
/chazmcgarvey
/docker
-connect)
74 To
install, just copy F
<docker
-connect> into your C
<PATH
> and
make sure it is executable.
76 # Assuming you have "$HOME/bin" in your $PATH:
77 cp docker
-connect ~
/bin
/
78 chmod +x ~
/bin
/docker
-connect
82 The following environment variables may affect or will be
set by this program
:
86 =item
* C
<DOCKER_CONNECT_SOCKET
>
88 The absolute path to the
local socket.
90 =item
* C
<DOCKER_CONNECT_HOSTNAME
>
92 The hostname of the remote peer.
94 =item
* C
<DOCKER_CONNECT_PID
>
96 The PID of the SSH process maintaining the connection.
98 =item
* C
<DOCKER_HOST
>
100 The URI of the
local socket.
106 If you run many shells and connections
, having the hostname of the
host that the Docker client is
107 connected to
in your prompt may be handy. Try something like this
in your
local shell config
file:
109 if [ -n "$DOCKER_CONNECT_HOSTNAME" ]
111 PS1
="[docker:$DOCKER_CONNECT_HOSTNAME] $PS1"
116 Charles McGarvey
<chazmcgarvey@brokenzipper.com
>
120 This software is copyright
(c
) 2017 by Charles McGarvey.
122 This is free software
, licensed under
:
124 The MIT
(X11
) License
130 prog
=$(basename "$0")
133 socket
="$DOCKER_CONNECT_SOCKET"
134 remote_socket
=${REMOTE_SOCKET:-/run/docker.sock}
135 timeout
=${TIMEOUT:-15}
139 $prog [OPTIONS]... HOSTNAME [SHELL_ARGS]...
140 Easily connect to Docker sockets over SSH.
143 -h Show this help info and exit.
144 -q Be less verbose; can be repeated to enhance effect.
145 -r STR Specify the absolute path of the remote socket.
146 -s STR Specify the absolute path of the local socket.
147 -v Show the program version.
154 if [ "$_l" -ge "$quiet" ]
160 while getopts "hqr:s:v" opt
164 quiet
=$(expr $quiet + 1)
170 remote_socket
="$OPTARG"
177 echo "docker-connect $version"
186 shift $(expr $OPTIND - 1)
191 echo >&2 "Missing HOSTNAME."
199 socket_dir
="${TMPDIR:-/tmp}/docker-connect-$(id -u)"
200 mkdir -p "$socket_dir"
201 chmod 0700 "$socket_dir"
202 socket
="$socket_dir/docker-$$.sock"
207 if [ -n "$DOCKER_CONNECT_HOSTNAME" ]
209 log
2 "Docker is already connected to $DOCKER_CONNECT_HOSTNAME in this shell."
212 log
2 "Docker socket already exists."
213 log
1 "To force a new connection, first remove the file: $socket"
216 elif [ -e "$socket" ]
218 log
2 "Cannot create socket because another file is in the way."
219 log
1 "To create a new connection, you may first remove the file: $socket"
227 if echo "$connect" |grep -q ':'
229 hostname
=$(echo "$connect" |cut -d: -f1)
230 port
=$(echo "$connect" |cut -d: -f2)
235 if echo "$hostname" |grep -q '@'
237 user
=$(echo "$hostname" |cut -d@ -f1)
238 hostname
=$(echo "$hostname" |cut -d@ -f2)
241 ssh_connect
="$hostname"
245 ssh_connect
="$user@$ssh_connect"
250 ssh_connect
="$ssh_connect -p$port"
253 ${SSH:-ssh} $ssh_connect -L"$socket:$remote_socket" \
254 -oControlPath=none
-oConnectTimeout="$timeout" -nNT &
259 log
2 "The connection could not be established."
260 log
1 "Please ensure that you can execute this command successfully:"
261 log
1 " ${SSH:-ssh} $ssh_connect -oControlPath=none echo OK"
265 handle_disconnect
() {
266 kill $ssh_pid 2>/dev
/null
|| true
268 log
0 "Disconnected docker from $hostname."
271 # Wait for the socket connection to be made.
272 for i
in $(seq 1 "${timeout}0")
279 if ! kill -s 0 $ssh_pid 2>/dev
/null
286 if [ -z "$ssh_connected" ]
291 trap handle_disconnect EXIT
293 export DOCKER_CONNECT_HOSTNAME
="$hostname"
294 export DOCKER_CONNECT_PID
="$ssh_pid"
295 export DOCKER_CONNECT_SOCKET
="$socket"
296 export DOCKER_HOST
="unix://$socket"
298 # Remove incompatible variables set by Docker Machine.
299 unset DOCKER_MACHINE_NAME
300 unset DOCKER_CERT_PATH
301 unset DOCKER_TLS_VERIFY
303 log
1 "Executing new shell with docker connected to $hostname."
304 log
0 "This connection will be terminated when the shell exits."
305 ${SHELL:-/bin/sh} "$@"