localrelay

README

LocalRelay

A cross platform CLI & lib which acts as a reverse proxy allowing the destination address to be customised and allows the use of a SOCKS5 proxy. Supporting both raw TCP connections and HTTP/HTTPS connections with options such as; IP locking, Certificate pinning. This app allows you to host services e.g. Nextcloud on Tor and access it on your mobile or laptop anywhere.

[ Wiki & Guide ] [ Download Release ] [ Docker Image ]

Use Cases

If you self host a service for example; Bitwarden, Nextcloud, Syncthing, Grafana, Gitea... You may not want to expose your public IP address to the internet. Especially considering some self-hosted platforms such as Plex has been exploited with code execution vulnerabilities. You may consider to protect it behind Tor (however this isn't full proof).

Access your local or remote services securely over Tor without needing to port forward.

Many apps such as Nextcloud, Termis and Bitwarden do not allow you to specify a proxy when connecting to your self-hosted server. Localrelay allows you to host a local reverse proxy on your devices loopback. This relay then encrypts the outgoing traffic through your set SOCKS5 proxy (Tor: 127.0.0.1:9050).

When at home connect locally, when away connect over Tor. Securely connect remotely over Tor without port forwarding AND when at home connect directly with high speeds.

This Repository

This repository contains the library written in Go, for it's cross platform capabilities, and contains the CLI application which can be ran on all major operating systems including Android via Termux.

For examples of API usage visit examples/.

Library Features

Min Go version: v1.17

• Create relays with custom remote address
• Proxy remote address through SOCKS5 proxy
• Close relay concurrently
• Verbose logging with custom output (io.Writer)
• Multiple failover proxies for TCP relay
• Failovers for TCP relays
• Select which remote will connect via a proxy
• HTTP relay
  • Http to https
  • Header modification
  • Useragent spoofing
  • Accept language spoofing
  • Proxy using socks5
• Metrics
  • Upload/Download
  • Total connections
  • Active connections
  • Dialler: successes/failures
  • Concurrent safe
  • Dialler 10 point average response time
    • When using Tor this is the circuit build time

Privacy Proxies

Proxy your services whilst stripping personal information such as User-Agent, accept language or even cookies. Route the traffic through Tor to access the service anywhere in the word even behind a firewall.

CLI Usage

This is a basic overview, view the wiki for more detailed information.

Create Relay

To run a relay you must first create a relay config, this allows for permanent storage of relay configuration and easy management. You can create as many of these as you like.

Syntax

# Create a simple TCP relay
localrelay new <relay_name> -host <bind_addr> -destination <remote_addr>

# Create HTTP relay
localrelay new <relay_name> -host <bind_addr> -destination <remote_addr> -http

# Create HTTPS relay
localrelay new <relay_name> -host <bind_addr> -destination <remote_addr> -https -certificate=cert.pem key=key.pem

# Use proxy
localrelay new <relay_name> -host <bind_addr> -destination <remote_addr> -proxy <proxy_url>

# Set custom output config file
localrelay new <relay_name> -host <bind_addr> -destination <remote_addr> -output ./config.toml

# Create a failover TCP relay
localrelay new <relay_name> -host <bind_addr> -destination <remote_addr_(1)>,<remote_addr_(2)> -failover

Examples

# Create a simple TCP relay
localrelay new example.com -host 127.0.0.1:8080 -destination example.com:80

# Create HTTP relay
localrelay new example.com -host 127.0.0.1:8080 -destination http://example.com -http

# Create HTTPS relay
localrelay new example.com -host 127.0.0.1:8080 -destination https://example.com -https -certificate=cert.pem key=key.pem

# Create a TCP relay and store it in the config dir to auto start on system boot (daemon required)
sudo localrelay new example.com -host 127.0.0.1:8080 -destination example.com:80 -store

# Use proxy
localrelay new onion -host 127.0.0.1:8080 -destination 2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion:80 -proxy socks5://127.0.0.1:9050

# Create a failover TCP relay with one remote accessed via Tor
localrelay new onion -host 127.0.0.1:8080 -destination 192.168.1.240:80,2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion:80 -failover -ignore_proxy=0 -proxy socks5://127.0.0.1:9050

localrelay status

localrelay monitor

Installation And Usage Guide On The Wiki

Documentation

Index

• Variables
• func HandleHTTP(relay *Relay) http.HandlerFunc
• type Logger
  • func NewLogger(w io.Writer, name string) *Logger
• type Metrics
  • func (m *Metrics) Connections() (active int, total uint64)
  • func (m *Metrics) Dialer() (success, failed uint64)
  • func (m *Metrics) DialerAvg() (milliseconds int)
  • func (m *Metrics) Download() int
  • func (m *Metrics) Requests() uint64
  • func (m *Metrics) Upload() int
• type PooledConn
• type ProxyType
• type Relay
  • func New(name, host, destination string, logger io.Writer) *Relay
  • func (r *Relay) Close() error
  • func (r *Relay) DisableProxy(remoteIndex ...int)
  • func (r *Relay) GetConns() []*PooledConn
  • func (r *Relay) ListenServe() error
  • func (r *Relay) Running() bool
  • func (r *Relay) Serve(l net.Listener) error
  • func (r *Relay) SetClient(client *http.Client)
  • func (r *Relay) SetFailOverTCP()
  • func (r *Relay) SetHTTP(server http.Server) error
  • func (r *Relay) SetProtocolSwitch(index int, protocol string)
  • func (r *Relay) SetProxy(dialer ...*proxy.Dialer)
  • func (r *Relay) SetTLS(certificateFile, keyFile string)

Variables

var (
	// ErrUnknownProxyType is returned when a relay has a proxy type which is invalid
	ErrUnknownProxyType = errors.New("unknown proxytype used in creation of relay")
	// ErrAddrNotMatch is returned when a server object has a addr which is not nil
	// and does not equal the relay's address
	ErrAddrNotMatch = errors.New("addr does not match the relays host address")
)

var (
	// ErrFailConnect will be returned if the remote failed to dial
	ErrFailConnect = errors.New("failed to dial remote")
	// Timeout is only used when dialling without a proxy
	Timeout = time.Second * 5
)

Functions

func HandleHTTP

func HandleHTTP(relay *Relay) http.HandlerFunc

HandleHTTP is to be used as the HTTP relay's handler set in the http.Server object

Types

type Logger

type Logger struct {
	Info    *log.Logger
	Warning *log.Logger
	Error   *log.Logger
}

Logger is used for logging debug information such as connections being created, dropped etc

func NewLogger

func NewLogger(w io.Writer, name string) *Logger

NewLogger creates a new logging system

type Metrics

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

Metrics stores information such as bandwidth usage conn stats etc

func (*Metrics) Connections

func (m *Metrics) Connections() (active int, total uint64)

Connections returns the amount of active and total connections

func (*Metrics) Dialer

func (m *Metrics) Dialer() (success, failed uint64)

Dialer returns the successful dials and failed dials

func (*Metrics) DialerAvg

func (m *Metrics) DialerAvg() (milliseconds int)

DialerAvg returns the 10 point average dial time this average includes failed dials

func (*Metrics) Download

func (m *Metrics) Download() int

Download returns the amount of bytes downloaded through the relay

func (*Metrics) Requests

func (m *Metrics) Requests() uint64

Requests returns the amount of requests made via http

func (*Metrics) Upload

func (m *Metrics) Upload() int

Upload returns the amount of bytes uploaded through the relay

type PooledConn

type PooledConn struct {
	Conn       net.Conn
	RemoteAddr string
	Opened     time.Time
}

PooledConn allows meta data to be attached to a connection

type ProxyType

type ProxyType uint8

ProxyType represents what type of proxy the relay is.

Raw TCP is used for just forwarding the raw connection to the remote address.

const (
	// ProxyTCP is for raw TCP forwarding
	ProxyTCP ProxyType = iota
	// ProxyHTTP creates a HTTP server and forwards the traffic to
	// either a HTTP or HTTPs server
	ProxyHTTP
	// ProxyHTTPS is the same as HTTP but listens on TLS
	ProxyHTTPS

	// ProxyFailOverTCP acts like the TCP proxy however if it cannot connect
	// it will use a failover address instead.
	ProxyFailOverTCP

	// ProxyUDP forwards UDP traffic
	ProxyUDP

	// VERSION uses semantic versioning
	// this version number is for the library not the CLI
	VERSION = "v1.4.0"
)

type Relay

type Relay struct {
	// Name is a generic name which can be assigned to this relay
	Name string
	// Host is the address to listen on
	Host string

	// ForwardAddr is the destination to send the connection.
	// When using a relay type which accept multipule destinations
	// use a comma seperated list.
	ForwardAddr string
	// ProxyType is used to forward or manipulate the connection
	ProxyType ProxyType

	// ProxyEnabled is set to true when a proxy has been set for this relay
	ProxyEnabled bool

	// Metrics is used to store information such as upload/download
	// and other statistics
	*Metrics
	// contains filtered or unexported fields
}

Relay represents a reverse proxy and all of its settings

func New

func New(name, host, destination string, logger io.Writer) *Relay

New creates a new TCP relay

func (*Relay) Close

func (r *Relay) Close() error

Close will close the relay's listener

func (*Relay) DisableProxy

func (r *Relay) DisableProxy(remoteIndex ...int)

DisableProxy will disable the proxy settings when connecting to the remote at the index provided.

OPTION ONLY AVAILABLE FOR FAIL OVER TCP PROXY TYPE!

func (*Relay) GetConns

func (r *Relay) GetConns() []*PooledConn

GetConns returns all the active connections to this relay

func (*Relay) ListenServe

func (r *Relay) ListenServe() error

ListenServe will start a listener and handle the incoming requests

func (*Relay) Running

func (r *Relay) Running() bool

Running returns true if relay is running

func (*Relay) Serve

func (r *Relay) Serve(l net.Listener) error

Serve lets you set your own listener and then serve on it

func (*Relay) SetClient

func (r *Relay) SetClient(client *http.Client)

SetClient will set the http client used by the relay

func (*Relay) SetFailOverTCP

func (r *Relay) SetFailOverTCP()

SetFailOverTCP will make the relay type TCP and support multipule destinations. If one destination fails to dial the next will be attempted.

func (*Relay) SetHTTP

func (r *Relay) SetHTTP(server http.Server) error

SetHTTP is used to set the relay as a type HTTP relay addr will auto be set in the server object if left blank

func (*Relay) SetProtocolSwitch

func (r *Relay) SetProtocolSwitch(index int, protocol string)

SetProtocolSwitch allows you to switch the outgoing protocol NOTE: If a proxy is enabled protocol switching is disabled

func (*Relay) SetProxy

func (r *Relay) SetProxy(dialer ...*proxy.Dialer)

SetProxy sets the proxy dialer to be used proxy.SOCKS5() can be used to setup a socks5 proxy or a list of proxies

func (*Relay) SetTLS

func (r *Relay) SetTLS(certificateFile, keyFile string)

SetTLS sets the TLS certificates for use in the ProxyHTTPS relay. This function will upgrade this relay to a HTTPS relay