sshtun

package module
v1.0.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 5, 2024 License: MIT Imports: 11 Imported by: 0

README

sshtun

GoDoc

sshtun 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 locations and fallbacks to using ssh-agent, but a specific authentication method can be set.

The default locations are ~/.ssh/id_rsa, ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ecdsa_sk, ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519_sk.

Installation

go get github.com/rgzr/sshtun

Example

package main

import (
	"context"
	"log"
	"time"

	"github.com/rgzr/sshtun"
)

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

	// We print each tunneled state to see the connections status
	sshTun.SetTunneledConnState(func(tun *sshtun.SSHTun, state *sshtun.TunneledConnState) {
		log.Printf("%+v", state)
	})

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

	// We start the tunnel (and restart it every time it is stopped)
	go func() {
		for {
			if err := sshTun.Start(context.Background()); err != nil {
				log.Printf("SSH tunnel error: %v", err)
				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...")
		sshTun.Stop()
	}
}

Documentation

Overview

Package sshtun provides a SSH tunnel with port forwarding.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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

func NewTCPEndpoint 

func NewTCPEndpoint(host string, port int) *Endpoint

func NewUnixEndpoint 

func NewUnixEndpoint(socket string) *Endpoint

func (*Endpoint) String 

func (e *Endpoint) String() string

func (*Endpoint) Type 

func (e *Endpoint) Type() string

type ForwardType added in v1.0.7 

type ForwardType int
const (
	Local ForwardType = iota
	Remote
)

type SSHTun 

type SSHTun struct {
	// contains filtered or unexported fields
}

SSHTun represents a SSH tunnel

func New 

func New(localPort int, server string, remotePort int, forwardType ForwardType) *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.. 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 SetLocalEndpoint and SetRemoteEndpoint. The states of the tunnel can be received throgh a callback function with SetConnState. The states of the tunneled connections can be received through a callback function with SetTunneledConnState.

func NewUnix 

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

NewUnix does the same as New but using unix sockets.

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) 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 the file empty defaults to the default linux private key locations: `~/.ssh/id_rsa`, `~/.ssh/id_dsa`, `~/.ssh/id_ecdsa`, `~/.ssh/id_ecdsa_sk`, `~/.ssh/id_ed25519` and `~/.ssh/id_ed25519_sk`.

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.

func (*SSHTun) SetKeyFile 

func (tun *SSHTun) SetKeyFile(file string)

SetKeyFile changes the authentication to key-based and uses the specified file. Leaving the file empty defaults to the default linux private key locations: `~/.ssh/id_rsa`, `~/.ssh/id_dsa`, `~/.ssh/id_ecdsa`, `~/.ssh/id_ecdsa_sk`, `~/.ssh/id_ed25519` and `~/.ssh/id_ed25519_sk`.

func (*SSHTun) SetKeyReader 

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

SetKeyReader changes the authentication to key-based and uses the specified reader.

func (*SSHTun) SetLocalEndpoint 

func (tun *SSHTun) SetLocalEndpoint(endpoint *Endpoint)

SetLocalEndpoint sets the local endpoint to redirect.

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) SetRemoteEndpoint 

func (tun *SSHTun) SetRemoteEndpoint(endpoint *Endpoint)

SetRemoteEndpoint sets the remote endpoint to redirect.

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) SetTunneledConnState 

func (tun *SSHTun) SetTunneledConnState(tunneledConnStateFun func(*SSHTun, *TunneledConnState))

SetTunneledConnState specifies an optional callback function that is called when the underlying tunneled connections change state.

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(ctx context.Context) error

Start starts the SSH tunnel. It can be stopped by calling `Stop` or cancelling its context. This call will block until the tunnel is stopped either calling those methods or by an error. Note on SSH authentication: in case the tunnel's authType is set to AuthTypeAuto the following will happen: The default key files 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 all connections and makes Start exit gracefuly.

type TunneledConnState 

type TunneledConnState struct {
	// From is the address initating the connection.
	From string
	// Info holds a message with info on the state of the connection (useful for debug purposes).
	Info string
	// Error holds an error on the connection or nil if the connection is successful.
	Error error
	// Ready indicates if the connection is established.
	Ready bool
	// Closed indicates if the coonnection is closed.
	Closed bool
}

TunneledConnState represents the state of the final connections made through the tunnel.

func (*TunneledConnState) String 

func (s *TunneledConnState) String() string

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.