Dogcows Code - chaz/docker-connect/blob - README.md

   1 # NAME
   2
   3 docker-connect - Easily connect to Docker sockets over SSH
   4
   5 # VERSION
   6
   7 Version 0.81
   8
   9 # SYNOPSIS
  10
  11     docker-connect HOSTNAME [SHELL_ARGS]...
  12
  13     # launch a new shell wherein docker commands go to staging-01.acme.tld
  14     docker-connect staging-01.acme.tld
  15
  16     # list the docker processes running on staging-01.acme.tld
  17     docker-connect staging-01.acme.tld -c 'docker ps'
  18
  19     # connect as a specific user and a specific port
  20     docker-connect myusername@staging-01.acme.tld:2222
  21
  22 # DESCRIPTION
  23
  24 This script provides an alternative to Docker Machine for connecting your Docker client to a remote
  25 Docker daemon. Instead of connecting directly to a Docker daemon listening on an external TCP port,
  26 this script sets up a connection to the UNIX socket via SSH.
  27
  28 The main use case for this is when dealing with "permanent" app servers in an environment where you
  29 have a team of individuals who all need access.
  30
  31 Machine doesn't have a great way to support multiple concurrent users. You can add an existing
  32 machine to which you have SSH access using the generic driver on your computer, but if your
  33 colleague does the same then Machine will regenerate the Docker daemon TLS certificates, replacing
  34 the ones Machine set up for you.
  35
  36 Furthermore, the Docker daemon relies on TLS certificates for client authorization, which is all
  37 fine and good, but organizations are typically not as prepared to deal with the management of client
  38 TLS certificates as they are with the management of SSH keys. Worse, the Docker daemon doesn't
  39 support certificate revocation lists! So if a colleague leaves, you must replace the certificate
  40 authority and recreate and distribute certificates for each remaining member of the team. Ugh!
  41
  42 Much easier to just use SSH for authorization.
  43
  44 To be clear, this script isn't a full replacement for Docker Machine. For one thing, Machine has
  45 a lot more features and can actually create machines. This script just assists with a particular
  46 workflow that is currently underserved by Machine.
  47
  48 # HOW IT WORKS
  49
  50 What this script actually does is something similar to this sequence of commands:
  51
  52     ssh -L$PWD/docker.sock:/run/docker.sock $REMOTE_USER@$REMOTE_HOST -p$REMOTE_PORT -nNT &
  53     export DOCKER_HOST="unix://$PWD/docker.sock"
  54     unset DOCKER_CERT_PATH
  55     unset DOCKER_TLS_VERIFY
  56
  57 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
  58 the remote host. The benefit that `docker-connect` has over executing these commands directly is
  59 `docker-connect` doesn't require write access to the current directory since it puts its sockets in
  60 `$TMPDIR` (typically `/tmp`).
  61
  62 If your local system doesn't support UNIX sockets, you could use the following `ssh` command
  63 instead which uses a TCP socket:
  64
  65     ssh -L2000:/run/docker.sock $REMOTE_USER@$REMOTE_HOST -p$REMOTE_PORT -nNT &
  66     export DOCKER_HOST="tcp://localhost:2000"
  67
  68 An important drawback here is that any local user on the machine will then have unchallenged access
  69 to the remote Docker daemon by just connecting to localhost:2000. But this may be a reasonable
  70 alternative for use on non-multiuser machines only.
  71
  72 # REQUIREMENTS
  73
  74 - a Bourne-compatible, POSIX-compatible shell
  75
  76     This program is written in shell script.
  77
  78 - [OpenSSH](https://www.openssh.com) 6.7+
  79
  80     Needed to make the socket connection.
  81
  82 - [Docker](https://www.docker.com) client
  83
  84     Not technically required, but this program isn't useful without it.
  85
  86 # INSTALL
  87
  88 [![Build Status](https://travis-ci.org/chazmcgarvey/docker-connect.svg?branch=master)](https://travis-ci.org/chazmcgarvey/docker-connect)
  89
  90 To install, just copy `docker-connect` into your `PATH` and make sure it is executable.
  91
  92     # Assuming you have "$HOME/bin" in your $PATH:
  93     cp docker-connect ~/bin/
  94     chmod +x ~/bin/docker-connect
  95
  96 # ENVIRONMENT
  97
  98 The following environment variables may affect or will be set by this program:
  99
 100 - `DOCKER_CONNECT_SOCKET`
 101
 102     The absolute path to the local socket.
 103
 104 - `DOCKER_CONNECT_HOSTNAME`
 105
 106     The hostname of the remote peer.
 107
 108 - `DOCKER_CONNECT_PID`
 109
 110     The process ID of the SSH process maintaining the connection.
 111
 112 - `DOCKER_HOST`
 113
 114     The URI of the local socket.
 115
 116 # TIPS
 117
 118 If you run many shells and connections, having the hostname of the host that the Docker client is
 119 connected to in your prompt may be handy. Try something like this in your local shell config file:
 120
 121     if [ -n "$DOCKER_CONNECT_HOSTNAME" ]
 122     then
 123         PS1="[docker:$DOCKER_CONNECT_HOSTNAME] $PS1"
 124     fi
 125
 126 # AUTHOR
 127
 128 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 129
 130 # LICENSE
 131
 132 This software is copyright (c) 2017 by Charles McGarvey.
 133
 134 This is free software, licensed under:
 135
 136     The MIT (X11) License