tunnel

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Dec 21, 2021 License: BSD-3-Clause Imports: 19 Imported by: 0

README

Tunnel GoDoc Go Report Card Build Status

Tunnel is fast and secure client/server package that enables proxying public connections to your local machine over a tunnel connection from the local machine to the public server. It enables you to share your localhost when you dont't have a public IP or you are hidden by a firewall.

It can help you:

  • Demo without deploying
  • Simplify mobile device testing
  • Build webhook integrations with ease
  • Run personal cloud services from your own private network

It is based on HTTP/2 for speed and security. Server accepts TLS connection from known clients, client is recognised by it's TLS certificate id. Server can protect HTTP tunnels with basic authentication.

Installation

Download latest release from here. The release contains two executables:

  • tunneld - the tunnel server, to be run on publicly available host like AWS or GCE
  • tunnel - the tunnel client, to be run on your local machine or in your private network

To get help on the command parameters run tunneld -h or tunnel -h.

Configuration

The tunnel client tunnel requires configuration file, by default it will try reading tunnel.yml in your current working directory. If you want to specify other file use -config flag.

Sample configuration that exposes:

  • localhost:8080 as webui.my-tunnel-host.com
  • host in private network for ssh connections

looks like this

    server_addr: SERVER_IP:4443
    insecure_skip_verify: true
    tunnels:
      webui:
        proto: http
        addr: localhost:8080
        auth: user:password
        host: webui.my-tunnel-host.com
      ssh:
        proto: tcp
        addr: 192.168.0.5:22
        remote_addr: 0.0.0.0:22

Configuration options:

  • server_addr: server TCP address, i.e. 54.12.12.45:4443
  • insecure_skip_verify: controls whether a client verifies the server's certificate chain and host name, if using self signed certificates must be set to true, default: false
  • tls_crt: path to client TLS certificate, default: client.crt in the config file directory
  • tls_key: path to client TLS certificate key, default: client.key in the config file directory
  • tunnels / [name]
    • proto: tunnel protocol, http or tcp
    • addr: forward traffic to this local port number or network address, for proto=http this can be full URL i.e. https://machine/sub/path/?plus=params, supports URL schemes http and https
    • auth: (proto=http) (optional) basic authentication credentials to enforce on tunneled requests, format user:password
    • host: (proto=http) hostname to request (requires reserved name and DNS CNAME)
    • remote_addr: (proto=tcp) bind the remote TCP address
  • backoff
    • interval: how long client would wait before redialing the server if connection was lost, exponential backoff initial interval, default: 500ms
    • multiplier: interval multiplier if reconnect failed, default: 1.5
    • max_interval: maximal time client would wait before redialing the server, default: 1m
    • max_time: maximal time client would try to reconnect to the server if connection was lost, set 0 to never stop trying, default: 15m

Running

Tunnel requires TLS certificates for both client and server.

$ openssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout client.key -out client.crt
$ openssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout server.key -out server.crt

Run client:

  • Install tunnel binary
  • Make .tunnel directory in your project directory
  • Copy client.key, client.crt to .tunnel
  • Create configuration file tunnel.yml in .tunnel
  • Start all tunnels
$ tunnel -config ./tunnel/tunnel.yml start-all

Run server:

  • Install tunneld binary
  • Make .tunneld directory
  • Copy server.key, server.crt to .tunneld
  • Get client identifier (tunnel -config ./tunnel/tunnel.yml id), identifier should look like this YMBKT3V-ESUTZ2Z-7MRILIJ-T35FHGO-D2DHO7D-FXMGSSR-V4LBSZX-BNDONQ4
  • Start tunnel server
$ tunneld -tlsCrt .tunneld/server.crt -tlsKey .tunneld/server.key -clients YMBKT3V-ESUTZ2Z-7MRILIJ-T35FHGO-D2DHO7D-FXMGSSR-V4LBSZX-BNDONQ4

This will run HTTP server on port 80 and HTTPS (HTTP/2) server on port 443. If you want to use HTTPS it's recommended to get a properly signed certificate to avoid security warnings.

Using as a library

Install the package:

$ go get -u github.com/myENA/go-http-tunnel

The tunnel package is designed to be simple, extensible, with little dependencies. It is based on HTTP/2 for client server connectivity, this avoids usage of third party tools for multiplexing tunneled connections. HTTP/2 is faster, more stable and much more tested then any other multiplexing technology. You may see benchmark comparing the tunnel package to a koding tunnel.

The tunnel package:

  • custom dialer and listener for Client and Server
  • easy modifications of HTTP proxy (based on ReverseProxy)
  • proxy anything, ProxyFunc architecture
  • structured logs with go-kit compatible minimal logger interface

See:

License

Copyright (C) 2017 Michał Matczuk

This project is distributed under the BSD-3 license. See the LICENSE file for details.

GitHub star is always appreciated!

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

View Source 
var (
	// DefaultTimeout specifies general purpose timeout.
	DefaultTimeout = 10 * time.Second
)

Functions

This section is empty.

Types

type Auth 

type Auth struct {
	User     string
	Password string
}

Auth holds user and password.

func NewAuth 

func NewAuth(auth string) *Auth

NewAuth creates new auth from string representation "user:password".

type Backoff 

type Backoff interface {
	// Next returns the duration to sleep before retrying to reconnect.
	// 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 connection to the server, handling control messages. It uses ProxyFunc for transferring data between server and local services.

func NewClient 

func NewClient(config *ClientConfig) *Client

NewClient creates a new unconnected Client based on configuration. Caller must invoke Start() on returned instance in order to connect server.

func (*Client) Start 

func (c *Client) Start() error

Start connects client to the server, it returns error if there is a connection error, or server cannot open requested tunnels. On connection error a backoff policy is used to reestablish the connection. When connected HTTP/2 server is started to handle ControlMessages.

func (*Client) Stop 

func (c *Client) Stop()

Stop disconnects client from server.

type ClientConfig 

type ClientConfig struct {
	// ServerAddr specifies TCP address of the tunnel server.
	ServerAddr string
	// TLSClientConfig specifies the tls configuration to use with
	// tls.Client.
	TLSClientConfig *tls.Config
	// DialTLS specifies an optional dial function that creates a tls
	// connection to the server. If DialTLS is nil, tls.Dial is used.
	DialTLS func(network, addr string, config *tls.Config) (net.Conn, error)
	// Backoff specifies backoff policy on server connection retry. If nil
	// when dial fails it will not be retried.
	Backoff Backoff
	// Tunnels specifies the tunnels client requests to be opened on server.
	Tunnels map[string]*proto.Tunnel
	// p is ProxyFunc responsible for transferring data between server
	// and local services.
	Proxy ProxyFunc
	// Logger is optional logger. If nil logging is disabled.
	Logger log.Logger
}

ClientConfig is configuration of the Client.

type ConnDiscoNotifier 

type ConnDiscoNotifier interface {
	DiscoNotifier

	// ConnNotify is called on client connect.
	ConnNotify(tunnels map[string]*proto.Tunnel, identifier id.ID)
}

ConnDiscoNotifier - this interfaces implements the DiscoNotifier interface, as well as providing a ConnNotify method.

type ConnPool 

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

ConnPool - describes a connection pool

func (*ConnPool) AddConn 

func (p *ConnPool) AddConn(conn net.Conn, identifier id.ID) error

AddConn - This adds a connection to the pool.

func (*ConnPool) AddrToIdentifier 

func (p *ConnPool) AddrToIdentifier(addr string) id.ID

AddrToIdentifier - Converts an address, as generated from URL, back into an ID

func (*ConnPool) DeleteConn 

func (p *ConnPool) DeleteConn(identifier id.ID)

DeleteConn - This deletes a connection from the pool, sending a notification.

func (*ConnPool) GetClientConn 

func (p *ConnPool) GetClientConn(req *http.Request, addr string) (*http2.ClientConn, error)

GetClientConn - this implements http2.ClientConnPool

func (*ConnPool) MarkDead 

func (p *ConnPool) MarkDead(c *http2.ClientConn)

MarkDead - this implements http2.ClientConnPool

func (*ConnPool) URL 

func (p *ConnPool) URL(identifier id.ID) string

URL - this generates a URL from an identifier.

type DiscoNotifier 

type DiscoNotifier interface {
	// DiscoNotify is called on client disconnect.
	DiscoNotify(identifier id.ID)
}

DiscoNotifier - this interface provides a DiscoNotify method

type HTTPProxy 

type HTTPProxy struct {
	httputil.ReverseProxy
	// contains filtered or unexported fields
}

HTTPProxy forwards HTTP traffic.

func NewHTTPProxy 

func NewHTTPProxy(localURL *url.URL, logger log.Logger) *HTTPProxy

NewHTTPProxy creates a new direct HTTPProxy, everything will be proxied to localURL.

func NewMultiHTTPProxy 

func NewMultiHTTPProxy(localURLMap map[string]*url.URL, logger log.Logger) *HTTPProxy

NewMultiHTTPProxy creates a new dispatching HTTPProxy, requests may go to different backends based on localURLMap.

func (*HTTPProxy) Director 

func (p *HTTPProxy) Director(req *http.Request)

Director is ReverseProxy Director it changes request URL so that the request is correctly routed based on localURL and localURLMap. If no URL can be found the request is canceled.

func (*HTTPProxy) Proxy 

func (p *HTTPProxy) Proxy(w io.Writer, r io.ReadCloser, msg *proto.ControlMessage)

p is a ProxyFunc.

type HostAuth 

type HostAuth struct {
	Host string
	Auth *Auth
}

HostAuth holds host and authentication info.

type ProxyFunc 

type ProxyFunc func(w io.Writer, r io.ReadCloser, msg *proto.ControlMessage)

ProxyFunc is responsible for forwarding a remote connection to local server and writing the response.

func Proxy 

func Proxy(p ProxyFuncs) ProxyFunc

p returns a ProxyFunc that uses custom function if provided.

type ProxyFuncs 

type ProxyFuncs struct {
	// HTTP is custom implementation of HTTP proxing.
	HTTP ProxyFunc
	// TCP is custom implementation of TCP proxing.
	TCP ProxyFunc
}

ProxyFuncs is a collection of ProxyFunc.

type RegChecker 

type RegChecker interface {

	// CheckRegistration - if returns true, it will auto-register.
	// a client.  This allows us to hook into a registration database
	// instead of keeping all possible registrations in memory.
	CheckRegistration(id.ID) bool
}

RegChecker - this interface allows us to plug in an external checker for a registry on client connect.

type RegistryItem 

type RegistryItem struct {
	Hosts     []*HostAuth
	Listeners []net.Listener
}

RegistryItem holds information about hosts and listeners associated with a client.

type Server 

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

Server is responsible for proxying public connections to the client over a tunnel connection.

func NewServer 

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

NewServer creates a new Server.

func (*Server) Addr 

func (s *Server) Addr() string

Addr returns network address clients connect to.

func (*Server) DiscoNotify 

func (s *Server) DiscoNotify(identifier id.ID)

DiscoNotify clears resources used by client, it's invoked by connection pool when client goes away. This is the default DiscoNotifier, and is called in the absence of one. If you set DiscoNotifier to something other than this method, you will need to have that method call this DiscoNotify or cleanup will not occur.

func (Server) IsSubscribed 

func (r Server) IsSubscribed(identifier id.ID) bool

IsSubscribed returns true if client is subscribed.

func (Server) Item 

func (r Server) Item(identifier id.ID) *RegistryItem

Item - fetch RegistryItem by ID. If it doesn't exist, or has a void registration, return nil

func (*Server) RoundTrip 

func (s *Server) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip is http.RoundTriper implementation.

func (*Server) ServeHTTP 

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

ServeHTTP proxies http connection to the client.

func (*Server) Start 

func (s *Server) Start()

Start starts accepting connections form clients. For accepting http traffic from end users server must be run as handler on http server.

func (*Server) Stop 

func (s *Server) Stop()

Stop closes the server.

func (Server) Subscribe 

func (r Server) Subscribe(identifier id.ID)

Subscribe allows to connect client with a given identifier.

func (Server) Subscriber 

func (r Server) Subscriber(hostPort string) (id.ID, *Auth, bool)

Subscriber returns client identifier assigned to given host.

func (*Server) Unsubscribe 

func (s *Server) Unsubscribe(identifier id.ID) *RegistryItem

Unsubscribe removes client from registry, disconnects client if already connected and returns it's RegistryItem.

type ServerConfig 

type ServerConfig struct {
	// Addr is TCP address to listen for client connections. If empty ":0"
	// is used.
	Addr string
	// TLSConfig specifies the tls configuration to use with tls.Listener.
	TLSConfig *tls.Config
	// Listener specifies optional listener for client connections. If nil
	// tls.Listen("tcp", Addr, TLSConfig) is used.
	Listener net.Listener
	// Logger is optional logger. If nil logging is disabled.
	Logger log.Logger
	// Notifier is optional notification on disconnects.  If it additionally
	// implements ConnDiscoNotifier interface, ConnNotify will be called
	// when a client connects.
	Notifier DiscoNotifier

	// Optional RegChecker implementation, for doing dynamic registrations.
	RegChecker RegChecker
}

ServerConfig defines configuration for the Server.

type TCPProxy 

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

TCPProxy forwards TCP streams.

func NewMultiTCPProxy 

func NewMultiTCPProxy(localAddrMap map[string]string, logger log.Logger) *TCPProxy

NewMultiTCPProxy creates a new dispatching TCPProxy, connections may go to different backends based on localAddrMap.

func NewTCPProxy 

func NewTCPProxy(localAddr string, logger log.Logger) *TCPProxy

NewTCPProxy creates new direct TCPProxy, everything will be proxied to localAddr.

func (*TCPProxy) Proxy 

func (p *TCPProxy) Proxy(w io.Writer, r io.ReadCloser, msg *proto.ControlMessage)

p is a ProxyFunc.

Source Files

View all Source files

Directories

Path Synopsis
cmd
tunnel
tunneld

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.