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.80
   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 # DESCRIPTION
  20
  21 This script provides an alternative to Docker Machine for connecting your Docker client to a remote
  22 Docker daemon. Instead of connecting directly to a Docker daemon listening on an external TCP port,
  23 this script sets up a connection to the UNIX socket via SSH.
  24
  25 Why?
  26
  27 The main use case for this is when dealing with "permanent" app servers in an environment where you
  28 have a team of individuals who all need access.
  29
  30 Machine doesn't have a great way to support multiple concurrent users. You can add an existing
  31 machine to which you have SSH access using the generic driver on your computer, but if your
  32 colleague does the same then Machine will regenerate the Docker daemon TLS certificates, replacing
  33 the ones Machine set up for you.
  34
  35 Furthermore, the Docker daemon relies on TLS certificates for client authorization, which is all
  36 fine and good, but organizations are typically not as prepared to deal with the management of client
  37 TLS certificates as they are with the management of SSH keys. Worse, the Docker daemon doesn't
  38 support certificate revocation lists! So if a colleague leaves, you must replace the certificate
  39 authority and recreate and distribute certificates for each remaining member of the team. Ugh!
  40
  41 Much easier to just use SSH for authorization.
  42
  43 To be clear, this script isn't a full replacement for Docker Machine. For one thing, Machine has
  44 a lot more features and can actually create machines. This script just assists with a particular
  45 workflow that is currently underserved by Machine.
  46
  47 # REQUIREMENTS
  48
  49 - a Bourne-compatible, POSIX-compatible shell
  50
  51     This program is written in shell script.
  52
  53 - [OpenSSH](https://www.openssh.com) 6.7+
  54
  55     Needed to make the socket connection.
  56
  57 - [Docker](https://www.docker.com) client
  58
  59     Not technically required, but this program isn't useful without it.
  60
  61 # INSTALL
  62
  63 [![Build Status](https://travis-ci.org/chazmcgarvey/docker-connect.svg?branch=master)](https://travis-ci.org/chazmcgarvey/docker-connect)
  64
  65 To install, just copy `docker-connect` into your `PATH` and make sure it is executable.
  66
  67     # Assuming you have "$HOME/bin" in your $PATH:
  68     cp docker-connect ~/bin/
  69     chmod +x ~/bin/docker-connect
  70
  71 # ENVIRONMENT
  72
  73 The following environment variables may affect or will be set by this program:
  74
  75 - `DOCKER_CONNECT_SOCKET`
  76
  77     The absolute path to the local socket.
  78
  79 - `DOCKER_CONNECT_HOSTNAME`
  80
  81     The hostname of the remote peer.
  82
  83 - `DOCKER_CONNECT_PID`
  84
  85     The PID of the SSH process maintaining the connection.
  86
  87 - `DOCKER_HOST`
  88
  89     The URI of the local socket.
  90
  91 # TIPS
  92
  93 If you run many shells and connections, having the hostname of the host that the Docker client is
  94 connected to in your prompt may be handy. Try something like this in your local shell config file:
  95
  96     if [ -n "$DOCKER_CONNECT_HOSTNAME" ]
  97     then
  98         PS1="[docker:$DOCKER_CONNECT_HOSTNAME] $PS1"
  99     fi
 100
 101 # AUTHOR
 102
 103 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 104
 105 # LICENSE
 106
 107 This software is copyright (c) 2017 by Charles McGarvey.
 108
 109 This is free software, licensed under:
 110
 111     The MIT (X11) License