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.

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 to remotely 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

• 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

You can download the CLI from the releases tab or compile it your self by building ./cmd/localrelay. All releases hashed with SHA256 and signed.

Once you've downloaded the CLI you will need to give it execute permission if you're on a Unix based system. This is done with chmod +x localrelay. You don't need root permission to run the relay nor should you use it even if you want to run on a privileged port. Use sudo setcap CAP_NET_BIND_SERVICE=+eip /path/to/localrelay instead.

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

# 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

Run Relay

Now you have your relay config toml files we can now launch them using the CLI.

Syntax

# Run 1 relay
localrelay run <relay_config>

# Run 2 relays
localrelay run <relay_config1> <relay_config2>

# Run more than 2
# Keep adding the config files to the command
localrelay run <relay_config1> <relay_config2>...

Examples

# Run 1 relay
localrelay run onion.toml

# Run 2 relays
localrelay run onion.toml bitwarden.toml

# Run more than 2
# Keep adding the config files to the command
localrelay run onion.toml bitwarden.toml nextcloud.toml piped.toml

Build

This repository contains two code bases. The Localrelay package in the root and the CLI app in ./cmd/localrelay. To compile the CLI you have two options. Compile for all targets (via the Makefile) or compile directly.

Compile For All Targets

Open a terminal in the root of the repository and execute:

make

The binaries will be placed in ./bin/.

Compile For One Platform

Open a terminal and cd into ./cmd/localrelay.

go build -trimpath -ldflags="-s -w"

The binary will be created in the current directory (./cmd/localrelay).

Cross Compile

GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -trimpath -o ./bin/localrelay-linux-64 ./cmd/localrelay

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) Upload() int
• 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) 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) 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 = errors.New("failed to dial remote")
)

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) Upload

func (m *Metrics) Upload() int

Upload returns the amount of bytes uploaded through the relay

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

	// VERSION uses semantic versioning
	VERSION = "v1.0.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

	// 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 AVALIABLE FOR FAIL OVER TCP PROXY TYPE!

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