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/mabhi/ktunnel"
)
func main() {
cfg := &tunnel.ServerConfig{}
server, _ := tunnel.NewServer(cfg)
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/mabhi/ktunnel"
func main() {
cfg := &tunnel.ClientConfig{
Identifier: "1234",
ServerAddr: "203.0.113.0:80",
}
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
steps
-
When connecting to k8s cluster from outside => go run main/main.go --mode="c" --clcert ./certificates/out/client.crt --clkey ./certificates/out/client.key --cacert ./certificates/out/HomeCA.crt --host 1234.core-connector.tunnel.local --port=443
-
When connecting locally => go run main/main.go --mode="c" --clcert ./certificates/out/client.crt --clkey ./certificates/out/client.key --cacert ./certificates/out/HomeCA.crt --host 1234.core-connector.tunnel.local --port=3000
-
When connecting locally with kubeconfig => go run main/main.go --mode="c" --clcert ./certificates/out/client.crt --clkey ./certificates/out/client.key --cacert ./certificates/out/HomeCA.crt --host 1234.core-connector.tunnel.local --port=3000 --runproxy true --kubeconfig="/home/abhijeet/.kube/config"
-
Server start locally => go run main/main.go -mode="s" -host "*.core-connector.tunnel.local" -srvcert "./certificates/out/.core-connector.tunnel.local.crt" -srvkey="./certificates/out/.core-connector.tunnel.local.key" -cacert "./certificates/out/HomeCA.crt" -port 10443 -certopt 4
-
Connecting to local running server: curl -vi --cert ./certificates/out/client.crt --key ./certificates/out/client.key --cacert ./certificates/out/HomeCA.crt https://1234.core-connector.tunnel.local:10443
-
Sample curl requet into cluster: curl -vi --cert ./certificates/out/client.crt --key ./certificates/out/client.key --cacert ./certificates/out/HomeCA.crt https://1234.core-connector.tunnel.local/api/v1/namespaces/tunnel-system/pods?limit=500
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
- func Join(local, remote net.Conn, log logging.Logger)
- type Backoff
- type Client
- type ClientConfig
- type ClientState
- type ClientStateChange
- type HTTPProxy
- type ProxyConfig
- type ProxyFunc
- type ProxyFuncs
- type SOCKProxy
- type Server
- 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
- type TCPProxy
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultProxyFuncs holds global default proxy functions for all transport protocols. DefaultProxyFuncs = ProxyFuncs{ HTTP: new(HTTPProxy).Proxy, TCP: new(TCPProxy).Proxy, WS: new(HTTPProxy).Proxy, UX: new(TCPProxy).Proxy, } // DefaultProxy is a ProxyFunc that uses DefaultProxyFuncs. DefaultProxy = Proxy(ProxyFuncs{}) )
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.
Functions ¶
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) 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 ¶
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)
// Dial provides custom transport layer for client server communication.
//
// If nil, default implementation is to return net.Dial("tcp", address).
//
// It can be used for connection monitoring, setting different timeouts or
// securing the connection.
Dial func(network, address string) (net.Conn, error)
// Proxy defines custom proxing logic. This is optional extension point
// where you can provide your local server selection or communication rules.
Proxy ProxyFunc
// 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
// Log defines the logger. If nil a default logging.Logger is used.
Log logging.Logger
// Debug enables debug mode, enable only if you want to debug the server.
Debug bool
// for TLS/SSL connection, provide configs to include client certs and CA cert to be used during handshaking
TlsConfig *tls.Config
// LocalAddr is DEPRECATED please use ProxyHTTP.LocalAddr, see ProxyOverwrite for more details.
LocalAddr string
// FetchLocalAddr is DEPRECATED please use ProxyTCP.FetchLocalAddr, see ProxyOverwrite for more details.
FetchLocalAddr func(port int) (string, error)
// target port refers to the port to which client would like to forward request to
TargetPort int
// Kubeconfig location. If not provided, defaults to InCluster config
Kubeconfig string
// Indicate to run the proxy service else this will be plain tunnel connection catering to http request forwarding
RunProxy bool
}
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 HTTPProxy ¶
type HTTPProxy struct {
// LocalAddr defines the TCP address of the local server.
// This is optional if you want to specify a single TCP address.
LocalAddr string
// FetchLocalAddr is used for looking up TCP address of the server.
// This is optional if you want to specify a dynamic TCP address based on incommig port.
FetchLocalAddr func(port int) (string, error)
// ErrorResp is custom response send to tunnel server when client cannot
// establish connection to local server. If not set a default "no local server"
// response is sent.
ErrorResp *http.Response
// Log is a custom logger that can be used for the proxy.
// If not set a "http" logger is used.
Log logging.Logger
PConfig *ProxyConfig
}
HTTPProxy forwards HTTP traffic.
When tunnel server requests a connection it's proxied to 127.0.0.1:incomingPort where incomingPort is control message LocalPort. Usually this is tunnel server's public exposed Port. This behaviour can be changed by setting LocalAddr or FetchLocalAddr. FetchLocalAddr takes precedence over LocalAddr.
When connection to local server cannot be established proxy responds with http error message.
type ProxyConfig ¶
type ProxyConfig struct {
ServiceSNI string
}
type ProxyFunc ¶
type ProxyFunc func(remote net.Conn, msg *proto.ControlMessage)
ProxyFunc is responsible for forwarding a remote connection to local server and writing the response back.
func Proxy ¶
func Proxy(p ProxyFuncs) ProxyFunc
Proxy returns a ProxyFunc that uses custom function if provided, otherwise falls back to DefaultProxyFuncs.
type ProxyFuncs ¶
type ProxyFuncs struct {
// HTTP is custom implementation of HTTP proxing.
HTTP ProxyFunc
// TCP is custom implementation of TCP proxing.
TCP ProxyFunc
// WS is custom implementation of web socket proxing.
WS ProxyFunc
// UX is custom implementation of unix socket proxing.
UX ProxyFunc
}
ProxyFuncs is a collection of ProxyFunc.
type SOCKProxy ¶
type SOCKProxy struct {
// LocalAddr defines the TCP address of the local server.
// This is optional if you want to specify a single TCP address.
LocalAddr string
// FetchLocalAddr is used for looking up TCP address of the server.
// This is optional if you want to specify a dynamic TCP address based on incommig port.
FetchLocalAddr func(port int) (string, error)
// Log is a custom logger that can be used for the proxy.
// If not set a "tcp" logger is used.
Log logging.Logger
PConfig *ProxyConfig
}
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 ¶
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) DeleteAddr ¶
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 ¶
DeleteHost deletes the given virtual host. Once removed any request to this host is denied.
func (*Server) OnConnect ¶
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 ¶
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.
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
// This is the default protocol type to be used when communicating with remote address
// default is HTTP
DefaultRemoteProto proto.Type
}
ServerConfig defines the configuration for the Server
type TCPProxy ¶
type TCPProxy struct {
// LocalAddr defines the TCP address of the local server.
// This is optional if you want to specify a single TCP address.
LocalAddr string
// FetchLocalAddr is used for looking up TCP address of the server.
// This is optional if you want to specify a dynamic TCP address based on incommig port.
FetchLocalAddr func(port int) (string, error)
// Log is a custom logger that can be used for the proxy.
// If not set a "tcp" logger is used.
Log logging.Logger
PConfig *ProxyConfig
}
TCPProxy forwards TCP streams.
If port-based routing is used, LocalAddr or FetchLocalAddr 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 then tunnel server connection request is proxied to 127.0.0.1:incomingPort where incomingPort is control message LocalPort. Usually this is tunnel server's public exposed Port. This behaviour can be changed by setting LocalAddr or FetchLocalAddr. FetchLocalAddr takes precedence over LocalAddr.
Source Files
Directories