transocks

README

transocks - a transparent SOCKS5/HTTP proxy

transocks is a background service to redirect TCP connections transparently to a SOCKS5 server or a HTTP proxy server like Squid.

Currently, transocks supports only Linux iptables with DNAT/REDIRECT target.

Features

• IPv4 and IPv6

  Both IPv4 and IPv6 are supported. Note that nf_conntrack_ipv4 or nf_conntrack_ipv6 kernel modules must be loaded beforehand.

• SOCKS5 and HTTP proxy (CONNECT)

  We recommend using SOCKS5 server if available. Take a look at our SOCKS server usocksd if you are looking for.

  HTTP proxies often prohibits CONNECT method to make connections to ports other than 443. Make sure your HTTP proxy allows CONNECT to the ports you want.

• Graceful stop & restart

  • On SIGINT/SIGTERM, transocks stops gracefully.
  • On SIGHUP, transocks restarts gracefully.

• Library and executable

  transocks comes with a handy executable. You may use the library to create your own.

Install

Use Go 1.7 or better.

go get -u github.com/cybozu-go/transocks/...

Usage

transocks [-h] [-f CONFIG]

The default configuration file path is /etc/transocks.toml.

In addition, transocks implements the common spec from cybozu-go/cmd.

transocks does not have daemon mode. Use systemd to run it as a background service.

Configuration file format

transocks.toml is a TOML file.

proxy_url is mandatory. Other items are optional.

# listening address of transocks.
listen = "localhost:1081"    # default is "localhost:1081"

proxy_url = "socks5://10.20.30.40:1080"  # for SOCKS5 server
#proxy_url = "http://10.20.30.40:3128"   # for HTTP proxy server

[log]
filename = "/path/to/file"   # default to stderr
level = "info"               # critical", error, warning, info, debug
format = "json"              # plain, logfmt, json

Redirecting connections by iptables

Use DNAT or REDIRECT target in OUTPUT chain of the nat table.

Save the following example to a file, then execute: sudo iptables-restore < FILE

*nat
:PREROUTING ACCEPT [0:0]
:INPUT ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]
:POSTROUTING ACCEPT [0:0]
:TRANSOCKS - [0:0]
-A OUTPUT -p tcp -j TRANSOCKS
-A TRANSOCKS -d 0.0.0.0/8 -j RETURN
-A TRANSOCKS -d 10.0.0.0/8 -j RETURN
-A TRANSOCKS -d 127.0.0.0/8 -j RETURN
-A TRANSOCKS -d 169.254.0.0/16 -j RETURN
-A TRANSOCKS -d 172.16.0.0/12 -j RETURN
-A TRANSOCKS -d 192.168.0.0/16 -j RETURN
-A TRANSOCKS -d 224.0.0.0/4 -j RETURN
-A TRANSOCKS -d 240.0.0.0/4 -j RETURN
-A TRANSOCKS -p tcp -j REDIRECT --to-ports 1081
COMMIT

Use ip6tables to redirect IPv6 connections.

Library usage

Read the documentation.

License

MIT

Documentation

Index

• Constants
• func GetOriginalDST(conn *net.TCPConn) (*net.TCPAddr, error)
• func Listeners(c *Config) ([]net.Listener, error)
• type Config
  • func NewConfig() *Config
• type Mode
  • func (m Mode) String() string
• type Server
  • func NewServer(c *Config) (*Server, error)

Constants

const (
	// SO_ORIGINAL_DST is a Linux getsockopt optname.
	SO_ORIGINAL_DST = 80

	// IP6T_SO_ORIGINAL_DST a Linux getsockopt optname.
	IP6T_SO_ORIGINAL_DST = 80
)

const (
	// ModeNAT is mode constant for NAT.
	ModeNAT = Mode("nat")
)

Functions

func GetOriginalDST

func GetOriginalDST(conn *net.TCPConn) (*net.TCPAddr, error)

GetOriginalDST retrieves the original destination address from NATed connection. Currently, only Linux iptables using DNAT/REDIRECT is supported. For other operating systems, this will just return conn.LocalAddr().

Note that this function only works when nf_conntrack_ipv4 and/or nf_conntrack_ipv6 is loaded in the kernel.

func Listeners

func Listeners(c *Config) ([]net.Listener, error)

Listeners returns a list of net.Listener.

Types

type Config

type Config struct {
	// Addr is the listening address.
	Addr string

	// ProxyURL is the URL for upstream proxy.
	//
	// For SOCKS5, URL looks like "socks5://USER:PASSWORD@HOST:PORT".
	//
	// For HTTP proxy, URL looks like "http://USER:PASSWORD@HOST:PORT".
	// The HTTP proxy must support CONNECT method.
	ProxyURL *url.URL

	// Mode determines how clients are routed to transocks.
	// Default is ModeNAT.  No other options are available at this point.
	Mode Mode

	// ShutdownTimeout is the maximum duration the server waits for
	// all connections to be closed before shutdown.
	//
	// Zero duration disables timeout.  Default is 1 minute.
	ShutdownTimeout time.Duration

	// Dialer is the base dialer to connect to the proxy server.
	// The server uses the default dialer if this is nil.
	Dialer *net.Dialer

	// Logger can be used to provide a custom logger.
	// If nil, the default logger is used.
	Logger *log.Logger

	// Env can be used to specify a well.Environment on which the server runs.
	// If nil, the server will run on the global environment.
	Env *well.Environment
}

Config keeps configurations for Server.

func NewConfig

func NewConfig() *Config

NewConfig creates and initializes a new Config.

type Mode

type Mode string

Mode is the type of transocks mode.

func (Mode) String

func (m Mode) String() string

type Server

type Server struct {
	well.Server
	// contains filtered or unexported fields
}

Server provides transparent proxy server functions.

func NewServer

func NewServer(c *Config) (*Server, error)

NewServer creates Server. If c is not valid, this returns non-nil error.