A remote port forwarding tool for accessing services inside Docker containers. Those private admin interfaces, JMX ports, or Erlang/Elixir distribution ports not open to the outside world? No problem.
Shipspotter automates 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.
- Binaries: On the releases page
- From Source:
go get github.com/Shimmur/shipspotter
./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
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.
-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
usage: shipspotter --hostname=HOSTNAME [<flags>] 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.
$ ./shipspotter -h docker1 -n elixir -p 9001:9001 -d -a 127.0.0.2 _ _ _ _ | | (_) | | | | ___| |__ _ _ __ ___ _ __ ___ | |_| |_ ___ _ __ / __| '_ \| | '_ \/ __| '_ \ / _ \| __| __/ _ \ '__| \__ \ | | | | |_) \__ \ |_) | (_) | |_| || __/ | |___/_| |_|_| .__/|___/ .__/ \___/ \__|\__\___|_| | | | | |_| |_| DEBU Turning on debug logging INFO Found matching container: INFO - id: 9b62e46debe1 INFO - image: elixir INFO - name: /thirsty_keller INFO - up: 22h34m30.789978s INFO Using container: 9b62e46debe1 INFO Container IP address: 172.17.0.4 INFO Forwarding ports: INFO - 9001:9001 INFO Forwarding EPMD on 4369
You must have read access to the Docker Unix socket on the remote system with the user you are logging in with. This can usually be accomplished by adding the user to the
dockergroup on most distros. If you do not you may also connect over TCP on the remote host, by specifying the
--docker-sockoption. Note that this requires Docker to be listening on the non-SSL TCP port (usually on 127.0.0.1 only). Specify TCP sockets prefixed with
tcp://according to the manner that Docker would normally expect.
You must be using ssh key authentication, either with an agent or without. It would not be hard to add password auth.
For some use cases it's helpful to add an aliased address locally. This is true
when, for example, you need to connect an Erlang VM up to a remote container
to do distribution or run remote Observer. There is an
alias.sh script provided
to do that, with support for macOS and Linux.
Elixir/Erlang Remote Observer
One good use case for Shipspotter is connecting to a remote Erlang VM and running a remote observer process there. To do this you must:
- Set the remote node name to
- Run the
alias.shscript from this distribution
- Start shipspotter:
shipspotter -h docker1 -n <your image> -p 9001:9001 -d -a 127.0.0.2
- Start a local
iex --name firstname.lastname@example.org --cookie <your cookie>
- Then in the iex session:
If you don't get
iex(1)> Node.connect :"<your process>@127.0.0.2" true
trueback, look for error output from shipspotter.
- Start Observer
:observer.start. The select the remote node from the menu.
Contributions are more than welcome. Bug reports with specific reproduction steps are great. If you have a code contribution you'd like to make, open a pull request with suggested code.
Pull requests should:
- Clearly state their intent in the title
- Have a description that explains the need for the changes
- Not break the public API
Ping us to let us know you're working on something interesting by opening a GitHub Issue on the project.