Documentation
¶
Overview ¶
Package tunnel provides APIs to create SSH tunnels to perform local port forwarding, leveraging the SSH configuration file (e.g. $HOME/.ssh/config) to find specific attributes of the target ssh server like user name, port, host name and key when not provided.
SSH Config File Support ¶
The module looks for the ssh config file stored on $HOME/.ssh/config only. There is no fallback support to try to use /etc/ssh/config.
The current API supports the following ssh config file options:
Host Hostname User Port IdentityKey
For more information about SSH Local Port Forwarding, please visit: https://www.ssh.com/ssh/tunneling/example#sec-Local-Forwarding
For more information about SSH Config File, please visit: https://www.ssh.com/ssh/config/
Example ¶
This example shows the basic usage of the package: define both the source and destination endpoints, the ssh server and then start the tunnel that will exchange data from the local address to the remote address through the established ssh channel.
package main
import (
"log"
"github.com/davrodpin/mole/tunnel"
)
func main() {
sourceEndpoints := []string{"127.0.0.1:8080"}
destinationEndpoints := []string{"user@example.com:80"}
// Initialize the SSH Server configuration providing all values so
// tunnel.NewServer will not try to lookup any value using $HOME/.ssh/config
server, err := tunnel.NewServer("user", "172.17.0.20:2222", "/home/user/.ssh/key", "", "/home/user/.ssh/config")
if err != nil {
log.Fatalf("error processing server options: %v\n", err)
}
t, err := tunnel.New("local", server, sourceEndpoints, destinationEndpoints, "/home/user/.ssh/key")
if err != nil {
log.Fatalf("error creating tunnel: %v\n", err)
}
// Start the tunnel
err = t.Start()
if err != nil {
log.Fatalf("error starting tunnel: %v\n", err)
}
}
Output:
Index ¶
Examples ¶
Constants ¶
const ( HostMissing = "server host has to be provided as part of the server address" RandomPortAddress = "127.0.0.1:0" NoDestinationGiven = "cannot create a tunnel without at least one remote address" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ForwardConfig ¶
ForwardConfig represents either a LocalForward or a RemoteForward configuration for SSHHost.
func (ForwardConfig) String ¶
func (f ForwardConfig) String() string
String returns a string representation of ForwardConfig.
type PemKey ¶
type PemKey struct {
// Data holds the data for a PEM private key
Data []byte
// contains filtered or unexported fields
}
PemKey holds data related to PEM keys
func (*PemKey) HandlePassphrase ¶
HandlePassphrase securely records a passphrase given by a callback to the memory.
func (PemKey) IsEncrypted ¶
IsEncrypted inspects the key data block to tell if it is whether encrypted or not.
type PemKeyParser ¶
type PemKeyParser interface {
// Parse returns a key signer to create signatures that verify against a
// public key.
Parse() (*ssh.Signer, error)
}
PemKeyParser translates pem keys to a signature signer.
type SSHChannel ¶
type SSHChannel struct {
ChannelType string
Source string
Destination string
// contains filtered or unexported fields
}
func (*SSHChannel) Accept ¶
func (ch *SSHChannel) Accept() error
Accept waits for and return the next connection to the SSHChannel.
func (*SSHChannel) Listen ¶
func (ch *SSHChannel) Listen(serverClient *ssh.Client) error
Listen creates tcp listeners for each channel defined.
func (SSHChannel) String ¶
func (ch SSHChannel) String() string
String returns a string representation of a SSHChannel
type SSHConfigFile ¶
type SSHConfigFile struct {
// contains filtered or unexported fields
}
SSHConfigFile finds specific attributes of a ssh server configured on a ssh config file.
func NewEmptySSHConfigStruct ¶
func NewEmptySSHConfigStruct() *SSHConfigFile
func NewSSHConfigFile ¶
func NewSSHConfigFile(configPath string) (*SSHConfigFile, error)
NewSSHConfigFile creates a new instance of SSHConfigFile based on the ssh config file from configPath
func (SSHConfigFile) Get ¶
func (r SSHConfigFile) Get(host string) *SSHHost
Get consults a ssh config file to extract some ssh server attributes from it, returning a SSHHost. Any attribute which its value is an empty string is an attribute that could not be found in the ssh config file.
type SSHHost ¶
type SSHHost struct {
Hostname string
Port string
User string
Key string
IdentityAgent string
LocalForward *ForwardConfig
RemoteForward *ForwardConfig
}
SSHHost represents a host configuration extracted from a ssh config file.
type Server ¶
type Server struct {
Name string
Address string
User string
Key *PemKey
// Insecure is a flag to indicate if the host keys should be validated.
Insecure bool
Timeout time.Duration
// SSHAgent is the path to the unix socket where an ssh agent is listening
SSHAgent string
}
Server holds the SSH Server attributes used for the client to connect to it.
type Tunnel ¶
type Tunnel struct {
// Type tells what kind of port forwarding this tunnel will handle: local or remote
Type string
// Ready tells when the Tunnel is ready to accept connections
Ready chan bool
// KeepAliveInterval is the time period used to send keep alive packets to
// the remote ssh server
KeepAliveInterval time.Duration
// ConnectionRetries is the number os attempts to reconnect to the ssh server
// when the current connection fails
ConnectionRetries int
// WaitAndRetry is the time waited before trying to reconnect to the ssh
// server
WaitAndRetry time.Duration
// contains filtered or unexported fields
}
Tunnel represents the ssh tunnel and the channels connecting local and remote endpoints.
func New ¶
func New(tunnelType string, server *Server, source, destination []string, config string) (*Tunnel, error)
New creates a new instance of Tunnel.
func (*Tunnel) Channels ¶
func (t *Tunnel) Channels() []*SSHChannel
Channels returns a copy of all channels configured for the tunnel.
Source Files