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() {
	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 := tunnel.New(local, server, remote)

	// Start the tunnel
	err = t.Start()
	if err != nil {
		log.Fatalf("error starting tunnel: %v\n", err)
	}
}

Index

• type ResolvedHost
  • func (rh ResolvedHost) String() string
• type Resolver
  • func NewResolver(configPath string) (*Resolver, error)
  • func (r Resolver) Resolve(host string) *ResolvedHost
• type Server
  • func NewServer(user, address, key string) (*Server, error)
  • func (s Server) String() string
• type Tunnel
  • func New(localAddress string, server *Server, remoteAddress string) *Tunnel
  • func (t *Tunnel) Start() error
  • func (t Tunnel) Stop()
  • func (t Tunnel) String() string

Examples

• Package

Types

type ResolvedHost

type ResolvedHost struct {
	Hostname string
	Port     string
	User     string
	Key      string
}

ResolvedHost holds information extracted from a ssh config file.

func (ResolvedHost) String

func (rh ResolvedHost) String() string

String returns a string representation of a ResolvedHost.

type Resolver

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

Resolver finds specific attributes of a ssh server configured on a ssh config file.

func NewResolver

func NewResolver(configPath string) (*Resolver, error)

NewResolver creates a new instance of Resolver based on the given ssh config file path.

func (Resolver) Resolve

func (r Resolver) Resolve(host string) *ResolvedHost

Resolve consults a ssh config file to extract some ssh server attributes from it, returning a ResolvedHost. Any attribute which its value is an empty string is an attribute that could not be found in the ssh config file.

type Server

type Server struct {
	Name    string
	Address string
	User    string
	Key     string
}

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 os a Server.

type Tunnel

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

Tunnel represents the ssh tunnel used to forward a local connection to a a remote endpoint through a ssh server.

func New

func New(localAddress string, server *Server, remoteAddress string) *Tunnel

New creates a new instance of Tunnel.

func (*Tunnel) Start

func (t *Tunnel) Start() error

Start creates a new ssh tunnel, allowing data exchange between the local and remote endpoints.

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.