Punchabunch: A configurable SSH local forwarding proxy
Punchabunch is a simple tool for setting up multiple SSH local forwarding proxies without a lot of configuration. It simplifies the task of setting up a large number of connections that must be proxied through multiple SSH servers.
Punchabunch doesn't do anything that ssh(1)
and a well-written
wrapper script and ssh_config(5)
generator couldn't do -- but it saves
the user the burden of doing so. And it comes in a neatly packaged binary
with a very simple configuration format.
Build instructions
- Install Go, either from the official distribution or via Homebrew.
- Run
go get github.com/zendesk/punchabunch
cd $GOPATH/src/github.com/zendesk/punchabunch
make
Usage
punchabunch [-c config_file]
-c string
Path to configuration file (default "config.toml")
Configuration
Punchabunch uses a TOML configuration file to describe the desired set of SSH servers and forwarding configurations. It's as simple as a set of entries that look like this:
[app]
bastion = "bastion.example.com"
listen = "12345"
forward = "app.internal.example.com:80"
[db]
bastion = "bastion.example.com"
listen = "12345"
forward = "db.internal.example.com:3306"
Each entry must be preceded by an arbitrary [name]
header (including the
brackets).
The keys for each entry are as follows:
-
bastion
: The bastion host (server) to proxy the connection through. The value must be a string of the formathost[:port]
. If theport
value is not specified, port 22 will be used. -
listen
: The local port number to listen to for requests. The value must be a string of the format[interface:]port
. By default, the proxy will bind to the local IPv4 loopback address (127.0.0.1). If you prefer IPv6, set this value to[::1]:<port>
. -
forward
: The destination host:port pair that thelisten
port will forward incoming requests to. It must be a string of the formathost:port
.
You can have as many of these entries as your resources can accommodate. Punchabunch will start as many SSH sessions as required, in parallel. Only one SSH connection will be established per bastion host, even if multiple forwarders are configured across it.
Authentication
Currently, Punchabunch requires an active SSH Agent (see ssh-agent(1)
)
to operate, and it cannot be configured with other sources of
authentication information. If you have a working agent, no
configuration is needed -- Punchabunch will automatically locate its
local socket.
In the future, Punchabunch may be able to directly read SSH private keys.
Authors
- Michael S. Fischer, [email protected]
Reporting bugs
Please report bugs or other issues at https://github.com/zendesk/punchabunch/issues.