README
¶
tunnel
Note that the state of this library is experimental.
tunnel is a very simple library that allows you to create multi-hop SSH tunnels. From the endpoint
of the tunnel you can then Dial() to create network connections, or you can Listen() for
incoming connections.
You are responsible for closing any connections or listeners you make. The tunnel doesn't keep track of any connections you might have opened.
You can create multiple connections through the same tunnel.
Typical use
Import
Add the folliwing import and run go mod tidy to add tunnel to your project.
import "github.com/borud/tunnel"
Creating the tunnel
tunnel, err := tunnel.Create(tunnel.Config{
Hops: []string{
"bob@bastion.example.com:22",
"alice@inside.example.com:22",
},
})
Dial
You can Dial to create a new connection over the tunnel like so:
conn, err := tunnel.Dial("tcp", "service.example.com:4711")
If everything went according to plan you now have a tunnel that terminates at inside.example.com (since it is the last hop) and connects from there to port 4711 on service.example.com
Listen
You can also listen on the remote endpoint.
listener, err := tunnel.Listen("tcp", ":80")
A note on Listen ports
When you want to Listen to remote ports that should be externally available, you have to make sure
that the SSH daemon is configured to allow this. Please review the GatewayPorts configuration
option in sshd_config. If you were too lazy to read this paragraph and are just looking for a cut
and paste, the config is:
GatewayPorts yes
Documentation
¶
Overview ¶
Package tunnel implements a tunnel to another machine from which we can Dial other machines or Listen to remote ports. For now this library won't check host keys (it just accepts all) and for simplicity it assumes that you are using an ssh-agent to access your ssh keys.
Typical use:
First we create the tunnel
tunnel, err := tunnel.Create(tunnel.Config{
Hops: []string{
"bob@bastion.example.com:22",
"alice@inside.example.com:22",
},
})
...
Then we connect using the tunnel
conn, err := tunnel.Dial("tcp", "service.example.com:4711")
...
If everything went according to plan you now have a tunnel that terminates at inside.example.com (since it is the last hop) and connects from there to port 4711 on service.example.com
You can also listen on the remote endpoint.
listener, err := tunnel.Listen("tcp", ":80")
...
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrConnectAgent indicates that we failed to connect to the ssh-agent ErrConnectAgent = errors.New("failed to connect to ssh-agent") // ErrNoHopsSpecified indicates that the caller did not supply any hops. We need at least one hop. ErrNoHopsSpecified = errors.New("no hops specified") // ErrParsingHops indicates that at least one hop had an improper format ErrParsingHops = errors.New("error parsing hops") // ErrOpeningAuthSock indicates that we failed to open the ssh-agent socket ErrOpeningAuthSock = errors.New("error opening ssh-agent socket") // ErrCreatingConnection indicates we were unable to create a connection when building the tunnel ErrCreatingConnection = errors.New("error creating connection") // ErrClosingHop indicates that we got an error while trying to close a connection when tearing // down the tunnel. ErrClosingHop = errors.New("error closing hop") )
var (
ErrInvalidFormat = errors.New("invalid format")
)
errors
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Hops is a list of user@host:port elements, the last of which defines
// the target host. We need at least one entry, but we support an arbitrary
// number of hops.
Hops []string
}
Config for Tunnel.
Source Files