tunnel

README

TCP tunnel

Go TCP tunnel is a TCP reverse tunnel proxy to expose your local backends behind a firewall to the public. The reverse tunnel is based on HTTP/2 with mutual TLS (mTLS). It enables you to share your localhost when you don't have a public IP.

Features:

• Easily expose a local server to the public
• Secure TCP tunnel
• Dynamic listeners on server by client commands

Common use cases:

• Exposing your local server behind a firewall to the public
• Hosting a game server from home
• Developing webhook integrations

NOTE:

This project is forked from https://github.com/mmatczuk/go-http-tunnel

Here are some of the updates from the original

• Focus on TCP proxy
• Remove some old dependencies
• Package as Docker image and support Kubernetes

This repository is activly maintained

Getting started

TODO

Client configuration

The tunnel Client 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.

Server do not have any configurations without TLS. But Client configuration is propagated to the Server and it configures the server to create TCP listeners and proxies dynamically.

Here is a sample configuration:

server_addr: SERVER_IP:5223
tunnels:
  ssh:
    proto: tcp
    addr: 192.168.0.5:22
  www:
    proto: tcp
    addr: localhost:8080
    remote_addr: 80

This creates 2 tunnels:

• Server exposes port 22, which proxies to the Client local address 192.168.0.5:22
• Server exposes port 80, which proxies to the Client local address localhost:8080

Configuration options:

• server_addr: server's tunnel listener TCP address, i.e. 54.12.12.45:5223. default port is 5223
• tunnels / [name]
  • proto: proxy listener protocol, currently only tcp can be set
  • addr: forward traffic to this local port number or network address, i.e. localhost:22
  • remote_addr: server listener TCP address, default: same as local port
• 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

How it works

A client opens TLS connection to a server. The server accepts connections from known clients only. The client is recognized by its TLS certificate ID. The server is publicly available and proxies incoming connections to the client. Then the connection is further proxied in the client's network.

The tunnel is based HTTP/2 for speed and security. There is a single TCP connection between client and server and all the proxied connections are multiplexed using HTTP/2.

License

Copyright (C) 2017 Michał Matczuk

Copyright (C) 2022 jlandowner

This project is distributed under the AGPL-3 license. See the LICENSE file for details. If you need an enterprice license contact me directly.

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

• Variables
• func NormalizeAddress(addr string) (string, error)
• type Backoff
• type Client
  • func NewClient(config *ClientConfig) (*Client, error)
  • func (c *Client) Start() error
  • func (c *Client) Stop()
• type ClientConfig
• type ProxyFunc
  • func Proxy(p ProxyFuncs) ProxyFunc
• type ProxyFuncs
• type RegistryItem
• type Server
  • func NewServer(config *ServerConfig) (*Server, error)
  • func (s *Server) Addr() string
  • func (r Server) IsSubscribed(identifier id.ID) bool
  • func (s *Server) Ping(identifier id.ID) (time.Duration, error)
  • func (s *Server) Start() error
  • func (s *Server) Stop()
  • func (r Server) Subscribe(identifier id.ID)
  • func (r Server) Subscriber(hostPort string) (id.ID, bool)
  • func (s *Server) Unsubscribe(identifier id.ID) *RegistryItem
• type ServerConfig
• type TCPProxy
  • func NewMultiTCPProxy(localAddrMap map[string]string, logger log.Logger) *TCPProxy
  • func NewTCPProxy(localAddr string, logger log.Logger) *TCPProxy
  • func (p *TCPProxy) Proxy(w io.Writer, r io.ReadCloser, msg *proto.ControlMessage)

Variables

var (
	// DefaultKeepAliveIdleTime specifies how long connection can be idle
	// before sending keepalive message.
	DefaultKeepAliveIdleTime = 15 * time.Minute
	// DefaultKeepAliveCount specifies maximal number of keepalive messages
	// sent before marking connection as dead.
	DefaultKeepAliveCount = 8
	// DefaultKeepAliveInterval specifies how often retry sending keepalive
	// messages when no response is received.
	DefaultKeepAliveInterval = 5 * time.Second
)

var (
	// DefaultTimeout specifies a general purpose timeout.
	DefaultTimeout = 10 * time.Second
	// DefaultPingTimeout specifies a ping timeout.
	DefaultPingTimeout = 500 * time.Millisecond
)

Functions

func NormalizeAddress

func NormalizeAddress(addr string) (string, error)

Types

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, error)

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
	// Proxy 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 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

Proxy returns a ProxyFunc that uses custom function if provided.

type ProxyFuncs

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

ProxyFuncs is a collection of ProxyFunc.

type RegistryItem

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

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

type Server

type Server struct {
	// 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) IsSubscribed

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

IsSubscribed returns true if client is subscribed.

func (*Server) Ping

func (s *Server) Ping(identifier id.ID) (time.Duration, error)

Ping measures the RTT response time.

func (*Server) Start

func (s *Server) Start() error

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, 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
	// AutoSubscribe if enabled will automatically subscribe new clients on
	// first call.
	AutoSubscribe bool
	// 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
}

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)

Proxy is a ProxyFunc.