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.

[ 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

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

# 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

Install/Download

Download the appropriate release for you platform.

Operating System/Distro	Recommended File
Windows	localrelay_Windows_x86_64.zip
Debian/Ubuntu	localrelay_1.3.5_amd64.deb
RHEL Based (CentOs, Redhat)	localrelay-1.3.5.x86_64.rpm
Arch linux	localrelay-1.3.5-1-x86_64.pkg.tar.zst
Linux Other	localrelay_Linux_x86_64.tar.gz
Android	localrelay_Linux_arm64.tar.gz
Macos	localrelay_Darwin_x86_64.tar.gz
Macos (M1)	localrelay_Darwin_arm64.tar.gz

More Operating Systems and Architectures Available on Release Page

Debian/Ubuntu:

Download the deb file and open a terminal in the same directory.

sudo dpkg -i <localrelay_VERSION_REVISION_ARCH.deb>

Linux Generic:

Download the binary file and open a terminal in the same directory.

# Extract the archive
tar -xvf localrelay_Linux_x86_64.tar.gz
# Give executable permissions
chmod +x localrelay
# Move to PATH
sudo mv ./localrelay /usr/bin

Install With Go:

go install github.com/go-compile/localrelay/cmd/localrelay

Windows Manual Install:

Steps for Windows 10. The Environment Variables Settings app will be slightly different if you're on Windows 8 or 7.

1. Download the windows build (ends in .zip)
2. Extract ZIP Archive
3. Create a bin directory in documents (or anywhere else). md %USERPROFILE%\Documents\bin
4. Copy the binary file to your new directory
5. Open Environment variables settings. Use Windows search to type: "Edit environment variables" and open the application.
6. On the user section (top) click the variable "Path" and then the button "Edit..."
7. Then click new on the top right corner
8. A input field will apear in the listbox. Input: %USERPROFILE%\Documents\bin then press enter.
9. Finally open a NEW cmd window and type localrelay version.

Verify Binary Signature

Make sure to check the binary SHA256 checksum with the signed checksums on the release page against my public GPG key.

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

# Specify dial timeout (for none proxied remotes)
# <num>s  seconds
# <num>ms  milliseconds
# <num>m  minute
localrelay run onion.toml -timeout=5s

# 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 from Source

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.

Install

git clone github.com/go-compile/localrelay
cd localrelay

make install

localrelay version

Daemon/Service

If you want Localrelay to start with system boot or just run in the background you can install the daemon. The daemon can be installed on either Windows, Mac or Linux. Currently only Windows and Linux have been tested.

When interfacing with the Daemon elevated privileges are required for security. Either run in a administrator CMD window or run with SUDO on Unix based systems.

Installing Daemon/Service

# On Unix systems run with sudo
# On Linux the daemon will be installed as a systemd service
sudo localrelay install

# On Windows open a administrator CMD
# On Windows localrelay will be installed as a windows service
# as LocalSystem.
localrelay install

Uninstalling Daemon/Service

# On Unix systems run with sudo
sudo localrelay stop
sudo localrelay uninstall

# On Windows open a administrator CMD
localrelay stop
localrelay uninstall

Starting a Relay

To run a relay in the background a relay config can be ran with:

# Add new relay to the Daemon
sudo localrelay run <relay.toml> -detach

Remember on Windows use a admin CMD window

Auto Start Relay

If you want relays to auto start when the Daemon starts, you can add the relay configs into the appropriate directory.

Windows

C:\ProgramData\localrelay\

Unix

/etc/localrelay/

Note elevated privileges may be required.

Now when your system starts or you run localrelay start these relays will start too.

Stop/Restart/Status

To manage the daemon you can use the following commands:

# Stop the relay and prevent it from auto restarting
sudo localrelay stop

# Stop a single relay
sudo localrelay stop <relay-name>

# Restart the whole service processes
sudo localrelay restart

# Monitor live auto updated metrics
sudo localrelay monitor

# Monitor live auto updated metrics with a custom refresh rate
# ms Micro Seconds
# s Seconds
# m Minutes
# h Hours
# d Days
sudo localrelay monitor -interval=5s

# Monitor live auto updated metrics for specific relays
sudo localrelay monitor <relay-name-(1)> <relay-name-(2)>...

# View relay stats and running relays
sudo localrelay status

localrelay status

localrelay monitor

View Daemon Output/Logs

# View all logs
journalctl -u localrelayd

# Follow log output
journalctl -u localrelayd -f

Daemon logs: Linux Only

Docker

View on Dockerhub. Supported arches: amd64,arm64,arm/v7. Compressed image size: <3mb. Super small light weight, low CPU, RAM and disk usage container perfect for low power devices.

docker-compose.yaml

version: "3"
services:
  localrelay:
    container_name: localrelay
    image: gocompile/localrelay:latest
    network_mode: "host"
    restart: unless-stopped
    volumes:
      - ./localrelay:/etc/localrelay:ro

docker-compose up -d

Place your relay configs in ./localrelay/. The configs will be loaded when the relay starts.

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 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) 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 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.3.4"
)

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