tunnel

README

Tunnel

Tunnel is a server/client package that enables to proxy public connections to your local machine over a tunnel connection from the local machine to the public server. What this means is, you can share your localhost even if it doesn't have a Public IP or if it's not reachable from outside.

It uses the excellent yamux package to multiplex connections between server and client.

The project is under active development, please vendor it if you want to use it.

Usage

The tunnel package consists of two parts. The server and the client.

Server is the public facing part. It's type that satisfies the http.Handler. So it's easily pluggable into existing servers.

Let assume that you setup your DNS service so all *.example.com domains route to your server at the public IP 203.0.113.0. Let us first create the server part:

package main

import (
	"net/http"

	"github.com/koding/tunnel"
)

func main() {
	server, _ := tunnel.NewServer(nil)
	server.AddHost("sub.example.com", "1234")
	http.ListenAndServe(":80", server)
}

Once you create the server, you just plug it into your server. The only detail here is to map a virtualhost to a secret token. The secret token is the only part that needs to be known for the client side.

Let us now create the client side part:

package main

import "github.com/koding/tunnel"

func main() {
	cfg := &tunnel.ClientConfig{
		Identifier: "1234",
		ServerAddr: "203.0.113.0",
	}

	client, err := tunnel.NewClient(cfg)
	if err != nil {
		panic(err)
	}

	client.Start()
}

The Start() method is by default blocking. As you see you, we just passed the server address and the secret token.

Now whenever someone hit sub.example.com, the request will be proxied to the machine where client is running and hit the local server running 127.0.0.1:80 (assuming there is one). If someone hits sub.example.com:3000 (assume your server is running at this port), it'll be routed to 127.0.0.1:3000

That's it.

There are many options that can be changed, such as a static local address for your client. Have alook at the documentation

Protocol

The server/client protocol is written in the spec.md file. Please have a look for more detail.

License

The BSD 3-Clause License - see LICENSE for more details

Documentation

Overview

Package tunnel is a server/client package that enables to proxy public connections to your local machine over a tunnel connection from the local machine to the public server.

Index

• Variables
• type Backoff
• type Client
  • func NewClient(cfg *ClientConfig) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Start()
  • func (c *Client) StartNotify() <-chan bool
• type ClientConfig
• type ClientState
  • func (i ClientState) String() string
• type ClientStateChange
  • func (cs *ClientStateChange) String() string
• type Server
  • func NewServer(cfg *ServerConfig) (*Server, error)
  • func (s *Server) AddAddr(l net.Listener, ip net.IP, identifier string)
  • func (s *Server) AddHost(host, identifier string)
  • func (s *Server) DeleteAddr(l net.Listener, ip net.IP)
  • func (s *Server) DeleteHost(host string)
  • func (s *Server) OnConnect(identifier string, fn func() error)
  • func (s *Server) OnDisconnect(identifier string, fn func() error)
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ServerConfig

Variables

var ErrRedialAborted = errors.New("unable to restore the connection, aborting")

ErrRedialAborted is emitted on ClientClosed event, when backoff policy used by a client decided no more reconnection attempts must be made.

Types

type Backoff

type Backoff interface {
	// Next returns the duration to sleep before retrying reconnections.
	// If the returned value is negative, the retry is aborted.
	NextBackOff() time.Duration

	// Reset is used to signal a reconnection was successful and next
	// call to Next should return desired time duration for 1st reconnection
	// attempt.
	Reset()
}

Backoff defines behavior of staggering reconnection retries.

type Client

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

Client is responsible for creating a control connection to a tunnel server, creating new tunnels and proxy them to tunnel server.

func NewClient

func NewClient(cfg *ClientConfig) (*Client, error)

NewClient creates a new tunnel that is established between the serverAddr and localAddr. It exits if it can't create a new control connection to the server. If localAddr is empty client will always try to proxy to a local port.

func (*Client) Close

func (c *Client) Close() error

Close closes the client and shutdowns the connection to the tunnel server

func (*Client) Start

func (c *Client) Start()

Start starts the client and connects to the server with the identifier. client.FetchIdentifier() will be used if it's not nil. It's supports reconnecting with exponential backoff intervals when the connection to the server disconnects. Call client.Close() to shutdown the client completely. A successful connection will cause StartNotify() to receive a value.

func (*Client) StartNotify

func (c *Client) StartNotify() <-chan bool

StartNotify returns a channel that receives a single value when the client established a successful connection to the server.

type ClientConfig

type ClientConfig struct {
	// Identifier is the secret token that needs to be passed to the server.
	// Required if FetchIdentifier is not set.
	Identifier string

	// FetchIdentifier can be used to fetch identifier. Required if Identifier
	// is not set.
	FetchIdentifier func() (string, error)

	// ServerAddr defines the TCP address of the tunnel server to be connected.
	// Required if FetchServerAddr is not set.
	ServerAddr string

	// FetchServerAddr can be used to fetch tunnel server address.
	// Required if ServerAddress is not set.
	FetchServerAddr func() (string, error)

	// LocalAddr defines the TCP address of the local server. This is optional
	// if you want to specify a single TCP address. Otherwise the client will
	// always proxy to 127.0.0.1:incomingPort, where incomingPort is the
	// tunnelserver's public exposed Port.
	LocalAddr string

	// FetchLocalAddr is used for looking up TCP address of the server,
	// which an incoming connection should be proxied to.
	//
	// If port-based routing is used, this field is required for tunneling to
	// function properly. Otherwise you'll be forwarding traffic to random
	// ports and this is usually not desired.
	//
	// If IP-based routing is used this field may be nil, in that case
	// "127.0.0.1:port" will be used instead.
	//
	// It can be used for http tunneling provided that LocalAddr is "".
	FetchLocalAddr func(port int) (string, error)

	// Debug enables debug mode, enable only if you want to debug the server.
	Debug bool

	// Log defines the logger. If nil a default logging.Logger is used.
	Log logging.Logger

	Transport http.RoundTripper

	// StateChanges receives state transition details each time client
	// connection state changes. The channel is expected to be sufficiently
	// buffered to keep up with event pace.
	//
	// If nil, no information about state transitions are dispatched
	// by the library.
	StateChanges chan<- *ClientStateChange

	// Backoff is used to control behavior of staggering reconnection loop.
	//
	// If nil, default backoff policy is used which makes a client to never
	// give up on reconnection.
	//
	// If custom backoff is used, client will emit ErrRedialAborted set
	// with ClientClosed event when no more reconnection atttemps should
	// be made.
	Backoff Backoff

	// YamuxConfig defines the config which passed to every new yamux.Session. If nil
	// yamux.DefaultConfig() is used.
	YamuxConfig *yamux.Config
}

ClientConfig defines the configuration for the Client

type ClientState

type ClientState uint32

ClientState represents client connection state to tunnel server.

const (
	ClientUnknown ClientState = iota
	ClientStarted
	ClientConnecting
	ClientConnected
	ClientDisconnected
	ClientClosed // keep it always last
)

ClientState enumeration.

func (ClientState) String

func (i ClientState) String() string

type ClientStateChange

type ClientStateChange struct {
	Identifier string
	Previous   ClientState
	Current    ClientState
	Error      error
}

ClientStateChange represents single client state transition.

func (*ClientStateChange) String

func (cs *ClientStateChange) String() string

Strings implements the fmt.Stringer interface.

type Server

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

Server is responsible for proxying public connections to the client over a tunnel connection. It also listens to control messages from the client.

func NewServer

func NewServer(cfg *ServerConfig) (*Server, error)

NewServer creates a new Server. The defaults are used if config is nil.

func (*Server) AddAddr

func (s *Server) AddAddr(l net.Listener, ip net.IP, identifier string)

AddAddr starts accepting connections on listener l, routing every connection to a tunnel client given by the identifier.

When ip parameter is nil, all connections accepted from the listener are routed to the tunnel client specified by the identifier (port-based routing).

When ip parameter is non-nil, only those connections are routed whose local address matches the specified ip (ip-based routing).

If l listens on multiple interfaces it's desirable to call AddAddr multiple times with the same l value but different ip one.

func (*Server) AddHost

func (s *Server) AddHost(host, identifier string)

AddHost adds the given virtual host and maps it to the identifier.

func (*Server) DeleteAddr

func (s *Server) DeleteAddr(l net.Listener, ip net.IP)

DeleteAddr stops listening for connections on the given listener.

Upon return no more connections will be tunneled, but as the method does not close the listener, so any ongoing connection won't get interrupted.

func (*Server) DeleteHost

func (s *Server) DeleteHost(host string)

DeleteHost deletes the given virtual host. Once removed any request to this host is denied.

func (*Server) OnConnect

func (s *Server) OnConnect(identifier string, fn func() error)

OnConnect invokes a callback for client with given identifier, when it establishes a control session. After a client is connected, the associated function is also removed and needs to be added again.

func (*Server) OnDisconnect

func (s *Server) OnDisconnect(identifier string, fn func() error)

OnDisconnect calls the function when the client connected with the associated identifier disconnects from the server. After a client is disconnected, the associated function is also removed and needs to be added again.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP is a tunnel that creates an http/websocket tunnel between a public connection and the client connection.

type ServerConfig

type ServerConfig struct {
	// StateChanges receives state transition details each time client
	// connection state changes. The channel is expected to be sufficiently
	// buffered to keep up with event pace.
	//
	// If nil, no information about state transitions are dispatched
	// by the library.
	StateChanges chan<- *ClientStateChange

	// Director is a function that modifies HTTP request into a new HTTP request
	// before sending to client. If nil no modifications are done.
	Director func(*http.Request)

	// Debug enables debug mode, enable only if you want to debug the server
	Debug bool

	// Log defines the logger. If nil a default logging.Logger is used.
	Log logging.Logger

	// YamuxConfig defines the config which passed to every new yamux.Session. If nil
	// yamux.DefaultConfig() is used.
	YamuxConfig *yamux.Config
}

ServerConfig defines the configuration for the Server