with-ssh-docker-socket

README

with-ssh-docker-socket

Access a remote Docker daemon over SSH.

More precisely, this tool does the following:

1. Establish an SSH connection
2. Forward the remote Docker socket to a local TCP port
3. Run the given command (e.g. docker build or docker-compose up) with the DOCKER_HOST environment variable set to the forwarded socket
4. Close the SSH connection after the command exits

Contents

• Contents
• Example
  • Basic usage
  • Running a shell
  • External SSH client applications
• Get it
  • Using go get
  • Pre-built binary
• Use it

Example

Basic usage

The following command runs docker ps against the Docker daemon on host remote-host. Note that the docker CLI client being run here is the local one, whereas the daemon dockerd is running remotely on remote-host.

$ with-ssh-docker-socket -i key.pem -a user@remote-host docker ps

CONTAINER ID  IMAGE                       COMMAND               CREATED      STATUS
4b56090ce1bb  google/cadvisor:v0.31.0     "/usr/bin/cadvisor…"  1 hour ago   Up 1 hour

If ssh-agent is running and unlocked, its keyring will be used:

$ ssh-add key.pem

$ with-ssh-docker-socket -a user@remote-host docker ps

CONTAINER ID  IMAGE                       COMMAND               CREATED      STATUS
4b56090ce1bb  google/cadvisor:v0.31.0     "/usr/bin/cadvisor…"  1 hour ago   Up 1 hour

Running a shell

If no command is specified, the current $SHELL will be run as a child process of with-ssh-docker-socket:

$ with-ssh-docker-socket -a user@remote-host

$ docker ps

CONTAINER ID  IMAGE                       COMMAND               CREATED      STATUS
4b56090ce1bb  google/cadvisor:v0.31.0     "/usr/bin/cadvisor…"  1 hour ago   Up 1 hour

$ exit

$ docker ps
Cannot connect to the Docker daemon at localhost. Is the docker daemon running?

Of course, you can also just explicitly specify a shell as the command to run:

$ with-ssh-docker-socket -a user@remote-host bash

bash-3.2$ docker ps

CONTAINER ID  IMAGE                       COMMAND               CREATED      STATUS
4b56090ce1bb  google/cadvisor:v0.31.0     "/usr/bin/cadvisor…"  1 hour ago   Up 1 hour

External SSH client applications

Note: Using an external ssh client introduces additional dependencies - the client itself, as well its configuration (e.g. the contents of ~/.ssh/config). This makes the tool no longer self-contained, and its effect less obvious. For these reasons I'd recommend against the usage of this feature for automation puproses.

If you wish to use a pre-installed external ssh client (such as openssh or PuTTY), you may use the -ssh-app options. There are two shortcut flags specifically for openssh and PuTTY, as well as a way to call a custom client application:

• -ssh-app-openssh:
  • ssh -nNT -L "{{.LocalIP}}:{{.LocalPort}}:{{.RemoteAddr}}" -p "{{.SSHPort}}" "{{.User}}@{{.SSHHost}}" {{.ExtraArgs}}"
• -ssh-app-putty:
  • putty -ssh -NT "{{.User}}@{{.SSHHost}}" -P "{{.SSHPort}}" -L "{{.LocalIP}}:{{.LocalPort}}:{{.RemoteAddr}}" {{.ExtraArgs}}
• -ssh-app=<TEMPLATE>, where :
  • TEMPLATE is a go template that may refer to the same variables as the built-in templates -ssh-app-openssh and -ssh-app-putty.

$ with-ssh-docker-socket -ssh-app-openssh -a user@remote-host docker ps

CONTAINER ID  IMAGE                       COMMAND               CREATED      STATUS
4b56090ce1bb  google/cadvisor:v0.31.0     "/usr/bin/cadvisor…"  1 hour ago   Up 1 hour

The same result using a custom template:

$ with-ssh-docker-socket -ssh-app='ssh -nNT -L "{{.LocalPort}}:{{.RemoteSocketAddr}}" "{{.RemoteHost}}"' -a user@remote-host docker ps

CONTAINER ID  IMAGE                       COMMAND               CREATED      STATUS
4b56090ce1bb  google/cadvisor:v0.31.0     "/usr/bin/cadvisor…"  1 hour ago   Up 1 hour

Get it

Using go get

go get -u github.com/sgreben/with-ssh-docker-socket

Pre-built binary

Or download a binary from the releases page, or from the shell:

# Linux
curl -L https://github.com/sgreben/with-ssh-docker-socket/releases/download/1.3.13/with-ssh-docker-socket_1.3.13_linux_x86_64.tar.gz | tar xz

# OS X
curl -L https://github.com/sgreben/with-ssh-docker-socket/releases/download/1.3.13/with-ssh-docker-socket_1.3.13_osx_x86_64.tar.gz | tar xz

# Windows
curl -LO https://github.com/sgreben/with-ssh-docker-socket/releases/download/1.3.13/with-ssh-docker-socket_1.3.13_windows_x86_64.zip
unzip with-ssh-docker-socket_1.3.13_windows_x86_64.zip

Use it

with-ssh-docker-socket [OPTIONS] [COMMAND [ARGS...]]

Usage of with-ssh-docker-socket:
  -a string
    	(alias for -ssh-server-addr)
  -e string
    	(alias for -env-var-name) (default "DOCKER_HOST")
  -env-var-name string
    	environment variable to set (default "DOCKER_HOST")
  -i string
    	(alias for -ssh-key-file)
  -listen-ip string
    	local IP to listen on (default "127.0.0.1")
  -listen-port int
    	local TCP port to listen on (set to 0 to assign a random free port)
  -p int
    	(alias for -listen-port)
  -remote-socket-path string
    	remote socket path (default "/var/run/docker.sock")
  -s string
    	(alias for -remote-socket-path) (default "/var/run/docker.sock")
  -ssh-app string
    	use an external ssh client application (default: use native (go) ssh client)
  -ssh-app-extra-args string
    	extra CLI arguments for external ssh clients
  -ssh-app-openssh ssh
    	use the openssh ssh CLI ("ssh -nNT -L \"{{.LocalIP}}:{{.LocalPort}}:{{.RemoteAddr}}\" -p \"{{.SSHPort}}\"  \"{{.User}}@{{.SSHHost}}\" {{.ExtraArgs}}") (default: use native (go) ssh client)
  -ssh-app-putty
    	use the PuTTY CLI ("putty -ssh -NT \"{{.User}}@{{.SSHHost}}\" -P \"{{.SSHPort}}\"  -L \"{{.LocalIP}}:{{.LocalPort}}:{{.RemoteAddr}}\" {{.ExtraArgs}}")  (default: use native (go) ssh client)
  -ssh-auth-sock string
    	ssh-agent socket address ($SSH_AUTH_SOCK)
  -ssh-key-file string
    	path of an ssh key file
  -ssh-key-pass -i
    	passphrase for the ssh key file given via -i
  -ssh-max-attempts int
    	maximum number of ssh re-connection attempts (default 10)
  -ssh-max-delay duration
    	maximum re-connection attempt delay (default 15s)
  -ssh-min-delay duration
    	minimum re-connection attempt delay (default 250ms)
  -ssh-server-addr string
    	(remote) ssh server address [user@]host[:port]
  -v	(alias for -verbose)
  -verbose
    	print more logs
  -version
    	print version and exit