sshtun

Documentation

Overview

Package sshtun / file sshconn.go: SSH I/O primitives for sshtun including connecting to remote SSH server and handling tunnel connections

Package sshtun / file sshmgmt.go: Management I/O channel for creating new tunnels and shutting down existing ones

Index

• Constants
• type Link
  • func NewLink(hostname string, username string, password string) (*Link, error)
  • func (l *Link) Check() error
  • func (l *Link) Close()
  • func (l *Link) TunnelIn(rport uint16, hostlocal string, lport uint16) (*Tun, error)
• type Tun
• type TunnelBroker
  • func NewTunnelBroker(l *Link) *TunnelBroker
  • func (tb *TunnelBroker) AddTunnel(rport uint16, lhost string, lport uint16) error
  • func (tb *TunnelBroker) CloseAll()
  • func (tb *TunnelBroker) CloseTunnel(rport uint16, lhost string, lport uint16) error
  • func (tb *TunnelBroker) Lock()
  • func (tb *TunnelBroker) MonitorLink() (chan<- string, error)
  • func (tb *TunnelBroker) ReattachTunnels(newlink *Link)
  • func (tb *TunnelBroker) Unlock()
• type TunnelError
  • func (t TunnelError) Append(s string) TunnelError
  • func (t TunnelError) Error() string

Constants

const BufferSize = 32768

BufferSize is the max size used for individual I/O transfers across live tunnel links

const SSHMgmtDefaultMonitorInterval = 15

SSHMgmtDefaultMonitorInterval is a constant used for the automatic SSH link reconnect feature (*TunnelBroker.MonitorLink())

Types

type Link

type Link struct {
	SSHHost              string
	SSHUser, SSHPassword string
	// contains filtered or unexported fields
}

Link is a handle to a live SSH link

func NewLink

func NewLink(hostname string, username string, password string) (*Link, error)

NewLink establishes a new SSH link

func (*Link) Check

func (l *Link) Check() error

Check will attempt to start an undifferentiated SSH protocol session within our connection to validate the connection is still available. Used by the TunnelBroker Link monitor to detect SSH connection failure for reconnect purposes.

func (*Link) Close

func (l *Link) Close()

Close will gracefully close the SSH connection

func (*Link) TunnelIn

func (l *Link) TunnelIn(rport uint16, hostlocal string, lport uint16) (*Tun, error)

TunnelIn establishes a new persistent tunnel that supports infinite connections.

type Tun

type Tun struct {
	LocalPort, RemotePort uint16
	LocalHost             string
	Closed                chan struct{}
	Control               chan string
	// contains filtered or unexported fields
}

Tun is a handle to a TCP tunnel over Link

type TunnelBroker

type TunnelBroker struct {
	Sshcon *Link

	Tunnels              []*Tun
	ReconTimeoutInterval uint
	ReconRetryInterval   uint
	// contains filtered or unexported fields
}

TunnelBroker is a registry of Tun's managed by another program or library

func NewTunnelBroker

func NewTunnelBroker(l *Link) *TunnelBroker

NewTunnelBroker creates a new tunnel broker out of an existing SSH link

func (*TunnelBroker) AddTunnel

func (tb *TunnelBroker) AddTunnel(rport uint16, lhost string, lport uint16) error

AddTunnel adds a new tunnel to a TunnelBroker registry. This should be run primarily by the TunnelBroker's REST API manager.

func (*TunnelBroker) CloseAll

func (tb *TunnelBroker) CloseAll()

CloseAll aborts all tunnels along with the SSH link

func (*TunnelBroker) CloseTunnel

func (tb *TunnelBroker) CloseTunnel(rport uint16, lhost string, lport uint16) error

CloseTunnel will find a tunnel with the specified parameters, and remove it. Compatible with REST APIs since it resolves the Tun object (out of Tunnels) for us.

func (*TunnelBroker) Lock

func (tb *TunnelBroker) Lock()

Lock the tunnel broker mutex in case we want to dig into the Sshcon

func (*TunnelBroker) MonitorLink

func (tb *TunnelBroker) MonitorLink() (chan<- string, error)

MonitorLink spawns a goroutine which autonomously watches an SSH link and reconnects/reattaches tunnels as needed. Returned is a control channel where you may shut down the link and with mutex protection, you can use the TunnelBroker methods to add new tunnels directly under the hood.

func (*TunnelBroker) ReattachTunnels

func (tb *TunnelBroker) ReattachTunnels(newlink *Link)

ReattachTunnels takes an old set of *Tun's and re-creates them onto a new SSH link.

func (*TunnelBroker) Unlock

func (tb *TunnelBroker) Unlock()

Unlock tunnel broker Sshcon (matches Lock())

type TunnelError

type TunnelError string

TunnelError is an error type specific to this sshtun package

const ListenFailed TunnelError = "Create listener failed"

ListenFailed would be an odd scenario but potential with SSH link down

const PortAlreadyInUse TunnelError = "Remote Port Already Has a Tunnel"

PortAlreadyInUse is typically used when a tunnel is requested for a remote port where we already have a configured tunnel

const SSHConnectError TunnelError = "SSH connect error"

SSHConnectError is self explanatory.

const StartTunnelOnNilConnection TunnelError = "Link.TunnelIn called with a nil ssh.Conn value"

StartTunnelOnNilConnection denotes a bug whereby a tunnel creation operation was attempted on a null ssh connection

const TunnelNotFound TunnelError = "Tunnel Request failed due to Tunnel Not Found"

TunnelNotFound only applies during CloseTunnel since its arguments include the set of rport/lhost/lport used for lookup

func (TunnelError) Append

func (t TunnelError) Append(s string) TunnelError

Append will construct a new TunnelError by appending the included text

func (TunnelError) Error

func (t TunnelError) Error() string