tunnel

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 local and remote 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() {
	sshChan := &tunnel.SSHChannel{Local: "127.0.0.1:8080", Remote: "user@example.com:22"}

	// 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")
	if err != nil {
		log.Fatalf("error processing server options: %v\n", err)
	}

	t, err := tunnel.New(server, []*tunnel.SSHChannel{sshChan})
	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)
	}
}

Index

• Constants
• type LocalForward
  • func (f LocalForward) String() string
• type PemKey
  • func NewPemKey(keyPath, passphrase string) (*PemKey, error)
  • func (k *PemKey) HandlePassphrase(handler func() ([]byte, error)) error
  • func (k PemKey) IsEncrypted() (bool, error)
  • func (k *PemKey) Parse() (ssh.Signer, error)
• type PemKeyParser
• type SSHChannel
  • func BuildSSHChannels(serverName string, local, remote []string) ([]*SSHChannel, error)
  • func (ch SSHChannel) String() string
• type SSHConfigFile
  • func NewEmptySSHConfigStruct() *SSHConfigFile
  • func NewSSHConfigFile() (*SSHConfigFile, error)
  • func (r SSHConfigFile) Get(host string) *SSHHost
• type SSHHost
  • func (h SSHHost) String() string
• type Server
  • func NewServer(user, address, key string) (*Server, error)
  • func (s Server) String() string
• type Tunnel
  • func New(server *Server, channels []*SSHChannel) (*Tunnel, error)
  • func (t *Tunnel) Listen() error
  • func (t *Tunnel) Start() error
  • func (t Tunnel) Stop()
  • func (t Tunnel) String() string

Examples

• Package

Constants

const (
	HostMissing       = "server host has to be provided as part of the server address"
	RandomPortAddress = "127.0.0.1:0"
	NoRemoteGiven     = "cannot create a tunnel without at least one remote address"
)

Types

type LocalForward

type LocalForward struct {
	Local  string
	Remote string
}

LocalForward represents a LocalForward configuration for SSHHost.

func (LocalForward) String

func (f LocalForward) String() string

String returns a string representation of LocalForward.

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 NewPemKey

func NewPemKey(keyPath, passphrase string) (*PemKey, error)

func (*PemKey) HandlePassphrase

func (k *PemKey) HandlePassphrase(handler func() ([]byte, error)) error

HandlePassphrase securely records a passphrase given by a callback to the memory.

func (PemKey) IsEncrypted

func (k PemKey) IsEncrypted() (bool, error)

IsEncrypted inspects the key data block to tell if it is whether encrypted or not.

func (*PemKey) Parse

func (k *PemKey) Parse() (ssh.Signer, error)

Parse translates a pem key to a signer to create signatures that verify against a public key.

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 {
	Local  string
	Remote string
	// contains filtered or unexported fields
}

func BuildSSHChannels

func BuildSSHChannels(serverName string, local, remote []string) ([]*SSHChannel, error)

BuildSSHChannels normalizes the given set of local and remote addresses, combining them to build a set of ssh channel objects.

func (SSHChannel) String

func (ch SSHChannel) String() string

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() (*SSHConfigFile, error)

NewSSHConfigFile creates a new instance of SSHConfigFile based on the ssh config file from $HOME/.ssh/config.

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
	LocalForward *LocalForward
}

SSHHost represents a host configuration extracted from a ssh config file.

func (SSHHost) String

func (h SSHHost) String() string

String returns a string representation of a SSHHost.

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
}

Server holds the SSH Server attributes used for the client to connect to it.

func NewServer

func NewServer(user, address, key string) (*Server, error)

NewServer creates a new instance of Server using $HOME/.ssh/config to resolve the missing connection attributes (e.g. user, hostname, port and key) required to connect to the remote server, if any.

func (Server) String

func (s Server) String() string

String provided a string representation of a Server.

type Tunnel

type Tunnel struct {
	// 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(server *Server, channels []*SSHChannel) (*Tunnel, error)

New creates a new instance of Tunnel.

func (*Tunnel) Listen

func (t *Tunnel) Listen() error

Listen creates tcp listeners for each channel defined.

func (*Tunnel) Start

func (t *Tunnel) Start() error

Start creates the ssh tunnel and initialized all channels allowing data exchange between local and remote enpoints.

func (Tunnel) Stop

func (t Tunnel) Stop()

Stop cancels the tunnel, closing all connections.

func (Tunnel) String

func (t Tunnel) String() string

String returns a string representation of a Tunnel.