From 0dbb7d9d98006963553cb3db88778b31593f3c05 Mon Sep 17 00:00:00 2001 From: Karl Matthias Date: Tue, 15 Jan 2019 13:42:18 +0000 Subject: [PATCH] Basic README --- README.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d8fd7a6 --- /dev/null +++ b/README.md @@ -0,0 +1,100 @@ +Shipspotter +=========== + +A remote port forwarding for accessing services inside Docker containers. +Private admin interface, JMX ports, or Erlang/Elixir distribution ports not +open to the outside world? No problem. + +Shipspotter automates some of the workflow of connecting to a remote Docker +host, finding the container you need to connect to, and then forwarding the +ports to the appropriate container on the Docker bridge network. + +Basic Usage +----------- + +``` +./shipspotter -h docker1 -n elixir -p 9001:9001 -p 7946:7946 -a 127.0.0.2 +``` + +This will open an SSH tunnel to the host `docker1`, leveraging either an SSH +agent, or prompting you for the passphrase to your SSHKey. Over the tunnel, +shipspotter will connect to Docker on the default Unix socket +`/var/run/docker.sock` and look for a container with an image name that +contains `elixir`. If more than one is present, it will list all of them and +then connect to the last one it finds. If you'd rather connect to a different +one you can supply the `--container-id` option and specify one of the others it +listed for you. You may specify any number of ports to forward. + +**Note**: only TCP forwarding is supported. + +The final `-a` argument tells shipspotter to bind on the local address +`127.0.0.2`. This is useful for remotely connecting Erlang/Elixir containers +using EPMD and distribution. The EPMD 4369 port is also forwarded by default. +If you don't want it to be you may specify `--no-forward-epmd`. + + +``` +usage: shipspotter --hostname=HOSTNAME [] + +Flags: + --help Show context-sensitive help (also try --help-long and --help-man). + -h, --hostname=HOSTNAME The remote hostname to connect to + -p, --port=8080:80 ... The local:remote port to connect to. e.g. 8080:80 + -a, --local-address="127.0.0.1" + The local IP address to listen on + -l, --username="youruser" The ssh username on the remote host + -s, --docker-sock="unix:///var/run/docker.sock" + The Docker socket address on the remote host + -n, --image-name=IMAGE-NAME The Docker image to match on for this application + -c, --container-id=CONTAINER-ID + The Docker container ID to match for this application + -i, --ssh-key="/Users/youruser/.ssh/id_rsa" + Path to the ssh private key to use + -P, --ssh-port="22" Port to connect to ssh on the remote host + -e, --forward-epmd Shall we also forward the EPMD port? + -d, --debug Turn on debug logging +``` + +Shipspotter attempts sane default values for most of the options. You should +only override them if you are sure you need to. + +Sample Output +------------- +``` +$ ./shipspotter -h docker1 -n elixir -p 9001:9001 -d -a 127.0.0.2 + + _ _ _ _ + | | (_) | | | | + ___| |__ _ _ __ ___ _ __ ___ | |_| |_ ___ _ __ +/ __| '_ \| | '_ \/ __| '_ \ / _ \| __| __/ _ \ '__| +\__ \ | | | | |_) \__ \ |_) | (_) | |_| || __/ | +|___/_| |_|_| .__/|___/ .__/ \___/ \__|\__\___|_| + | | | | + |_| |_| + +DEBU[0000] Turning on debug logging +INFO[0000] Found matching container: +INFO[0000] - id: 9b62e46debe1 + +INFO[0000] - image: elixir +INFO[0000] - name: /thirsty_keller +INFO[0000] - up: 22h34m30.789978s +INFO[0000] Using container: 9b62e46debe1 +INFO[0000] Container IP address: 172.17.0.4 +INFO[0000] Forwarding ports: +INFO[0000] - 9001:9001 +INFO[0000] Forwarding EPMD on 4369 +``` + +Requirements +------------ + +1. You must have read access to the Docker Unix socker on the remote system + with the user you are logging in with. This can usually be accomplished + by adding the user to the `docker` group on most distros. **If you do not** + you may also connect over TCP on the remote host, by specifying the + `--docker-sock` option. Note that this requires Docker to be listening + on the non-SSL TCP port (usually on 127.0.0.1 only). + +2. You must be using ssh key authentication, either with an agent or without. + It would not be hard to add password auth.