simplesshtun

README

simplesshtun

simplesshtun is a Go package that provides a SSH tunnel with port forwarding supporting:

• TCP and unix socket connections
• Password authentication
• Un/encrypted key file authentication
• ssh-agent based authentication

By default it reads the default linux ssh private key location $HOME/.ssh/id_rsa and fallbacks to using ssh-agent, but a specific authentication method can be set.

Installation

go get github.com/ductrung-nguyen/simplesshtun

Example

package main

import (
    "log"
    "time"

    "github.com/ductrung-nguyen/simplesshtun"
)

func main() {
    // We want to connect to port 8080 on our machine to access port 80 on my.super.host.com
    simplesshtun := simplesshtun.New(8080, "my.super.host.com", 80)

    // We enable debug messages to see what happens
    simplesshtun.SetDebug(true)

    // We set a callback to know when the tunnel is ready
    simplesshtun.SetConnState(func(tun *simplesshtun.simplesshtun, state simplesshtun.ConnState) {
        switch state {
        case simplesshtun.StateStarting:
            log.Printf("STATE is Starting")
        case simplesshtun.StateStarted:
            log.Printf("STATE is Started")
        case simplesshtun.StateStopped:
            log.Printf("STATE is Stopped")
        }
    })

    // We start the tunnel (and restart it every time it is stopped)
    go func() {
        for {
            if err := simplesshtun.Start(); err != nil {
                log.Printf("SSH tunnel stopped: %s", err.Error())
                time.Sleep(time.Second) // don't flood if there's a start error :)
            }
        }
    }()

    // We stop the tunnel every 20 seconds (just to see what happens)
    for {
        time.Sleep(time.Second * time.Duration(20))
        log.Println("Lets stop the SSH tunnel...")
        simplesshtun.Stop()
    }
}

Documentation

Overview

Package sshtun provides a SSH tunnel with port forwarding. By default it reads the default linux ssh private key location ($HOME/.ssh/id_rsa).

Index

• type AuthType
• type ConnState
• type Endpoint
• type SSHTun
  • func New(localPort int, server string, remotePort int) *SSHTun
  • func NewUnix(localUnixSocket string, server string, remoteUnixSocket string) *SSHTun
  • func (tun *SSHTun) SetConnState(connStateFun func(*SSHTun, ConnState))
  • func (tun *SSHTun) SetDebug(debug bool)
  • func (tun *SSHTun) SetEncryptedKeyFile(file string, password string)
  • func (tun *SSHTun) SetEncryptedKeyReader(reader io.Reader, password string)
  • func (tun *SSHTun) SetKeyFile(file string)
  • func (tun *SSHTun) SetKeyReader(reader io.Reader)
  • func (tun *SSHTun) SetLocalHost(host string)
  • func (tun *SSHTun) SetPassword(password string)
  • func (tun *SSHTun) SetPort(port int)
  • func (tun *SSHTun) SetRemoteHost(host string)
  • func (tun *SSHTun) SetSSHAgent()
  • func (tun *SSHTun) SetTimeout(timeout time.Duration)
  • func (tun *SSHTun) SetUser(user string)
  • func (tun *SSHTun) Start() error
  • func (tun *SSHTun) Stop()

Types

type AuthType

type AuthType int

AuthType is the type of authentication to use for SSH.

const (
	// AuthTypeKeyFile uses the keys from a SSH key file read from the system.
	AuthTypeKeyFile AuthType = iota
	// AuthTypeEncryptedKeyFile uses the keys from an encrypted SSH key file read from the system.
	AuthTypeEncryptedKeyFile
	// AuthTypeKeyReader uses the keys from a SSH key reader.
	AuthTypeKeyReader
	// AuthTypeEncryptedKeyReader uses the keys from an encrypted SSH key reader.
	AuthTypeEncryptedKeyReader
	// AuthTypePassword uses a password directly.
	AuthTypePassword
	// AuthTypeSSHAgent will use registered users in the ssh-agent.
	AuthTypeSSHAgent
	// AuthTypeAuto tries to get the authentication method automatically. See SSHTun.Start for details on
	// this.
	AuthTypeAuto
)

type ConnState

type ConnState int

ConnState represents the state of the SSH tunnel. It's returned to an optional function provided to SetConnState.

const (
	// StateStopped represents a stopped tunnel. A call to Start will make the state to transition to StateStarting.
	StateStopped ConnState = iota

	// StateStarting represents a tunnel initializing and preparing to listen for connections.
	// A successful initialization will make the state to transition to StateStarted, otherwise it will transition to StateStopped.
	StateStarting

	// StateStarted represents a tunnel ready to accept connections.
	// A call to stop or an error will make the state to transition to StateStopped.
	StateStarted
)

type Endpoint

type Endpoint struct {
	Host       string
	Port       int
	UnixSocket string
}

type SSHTun

type SSHTun struct {
	*sync.Mutex
	// contains filtered or unexported fields
}

SSHTun represents a SSH tunnel

func New

func New(localPort int, server string, remotePort int) *SSHTun

New creates a new SSH tunnel to the specified server redirecting a port on local localhost to a port on remote localhost. By default the SSH connection is made to port 22 as root and using automatic detection of the authentication method (see Start for details on this). Calling SetPassword will change the authentication to password based. Calling SetKeyFile will change the authentication to keyfile based with an optional key file. The SSH user and port can be changed with SetUser and SetPort. The local and remote hosts can be changed to something different than localhost with SetLocalHost and SetRemoteHost. The states of the tunnel can be received throgh a callback function with SetConnState.

func NewUnix

func NewUnix(localUnixSocket string, server string, remoteUnixSocket string) *SSHTun

func (*SSHTun) SetConnState

func (tun *SSHTun) SetConnState(connStateFun func(*SSHTun, ConnState))

SetConnState specifies an optional callback function that is called when a SSH tunnel changes state. See the ConnState type and associated constants for details.

func (*SSHTun) SetDebug

func (tun *SSHTun) SetDebug(debug bool)

SetDebug enables or disables log messages (disabled by default).

func (*SSHTun) SetEncryptedKeyFile

func (tun *SSHTun) SetEncryptedKeyFile(file string, password string)

SetEncryptedKeyFile changes the authentication to encrypted key-based and uses the specified file and password. Leaving it empty defaults to the default linux private key location ($HOME/.ssh/id_rsa).

func (*SSHTun) SetEncryptedKeyReader

func (tun *SSHTun) SetEncryptedKeyReader(reader io.Reader, password string)

SetEncryptedKeyReader changes the authentication to encrypted key-based and uses the specified reader and password. Leaving it empty defaults to the default linux private key location ($HOME/.ssh/id_rsa).

func (*SSHTun) SetKeyFile

func (tun *SSHTun) SetKeyFile(file string)

SetKeyFile changes the authentication to key-based and uses the specified file. Leaving it empty defaults to the default linux private key location ($HOME/.ssh/id_rsa).

func (*SSHTun) SetKeyReader

func (tun *SSHTun) SetKeyReader(reader io.Reader)

SetKeyReader changes the authentication to key-based and uses the specified reader. Leaving it empty defaults to the default linux private key location ($HOME/.ssh/id_rsa).

func (*SSHTun) SetLocalHost

func (tun *SSHTun) SetLocalHost(host string)

SetLocalHost sets the local host to redirect (defaults to localhost)

func (*SSHTun) SetPassword

func (tun *SSHTun) SetPassword(password string)

SetPassword changes the authentication to password-based and uses the specified password.

func (*SSHTun) SetPort

func (tun *SSHTun) SetPort(port int)

SetPort changes the port where the SSH connection will be made.

func (*SSHTun) SetRemoteHost

func (tun *SSHTun) SetRemoteHost(host string)

SetRemoteHost sets the remote host to redirect (defaults to localhost)

func (*SSHTun) SetSSHAgent

func (tun *SSHTun) SetSSHAgent()

SetSSHAgent changes the authentication to ssh-agent.

func (*SSHTun) SetTimeout

func (tun *SSHTun) SetTimeout(timeout time.Duration)

SetTimeout sets the connection timeouts (defaults to 15 seconds).

func (*SSHTun) SetUser

func (tun *SSHTun) SetUser(user string)

SetUser changes the user used to make the SSH connection.

func (*SSHTun) Start

func (tun *SSHTun) Start() error

Start starts the SSH tunnel. After this call, all Set* methods will have no effect until Close is called. Note on SSH authentication: in case the tunnel's authType is set to AuthTypeAuto the following will happen: The default key file will be used, if that doesn't succeed it will try to use the SSH agent. If that fails the whole authentication fails. That means if you want to use password or encrypted key file authentication, you have to specify that explicitly.

func (*SSHTun) Stop

func (tun *SSHTun) Stop()

Stop closes the SSH tunnel and its connections. After this call all Set* methods will have effect and Start can be called again.