usocksd

README

Micro SOCKS server

usocksd is a SOCKS server written in Go.

usocksd/socks is a general purpose SOCKS server library. usocksd is built on it.

Features

• Support for SOCKS4, SOCKS4a, SOCK5

  • Only CONNECT is supported (BIND and UDP associate is missing).

• Graceful stop & restart

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

• Access log

  Thanks to cybozu-go/log, usocksd can output access logs in structured formats including JSON.

• Specific network interface

  usocksd can be configured to use specific network interface for outgoing connections.

  It is extremely useful if you want to send all traffic to VPN/Wireguard device or you have multiple network cards.

• Multiple external IP addresses

  usocksd can be configured to use multiple external IP addresses for outgoing connections.

  usocksd keeps using the same external IP address for a client as much as possible. This means usocksd can proxy passive FTP connections reliably.

  Moreover, you can use a DNSBL service to exclude dynamically from using some undesirable external IP addresses.

• White- and black- list of sites

  usocksd can be configured to grant access to the sites listed in a white list, and/or to deny access to the sites listed in a black list.

  usocksd can block connections to specific TCP ports, too.

Install

Use a recent version of Go.

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

Usage

usocksd [-h] [-f CONFIG]

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

In addition, usocksd implements the common spec from cybozu-go/well.

usocksd does not have daemon mode. Use systemd to run it on your background.

Configuration file format

usocksd.toml is a TOML file. All fields are optional.

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

[incoming]
port = 1080
metrics_port = 1081                # Port number to serve metrics
addresses = ["127.0.0.1"]          # List of listening IP addresses
allow_from = ["10.0.0.0/8"]        # CIDR network or IP address

[outgoing]
allow_sites = [                    # List of FQDN to be granted.
    "www.amazon.com",              # exact match
    ".google.com",                 # subdomain match
]
deny_sites = [                     # List of FQDN to be denied.
    ".2ch.net",                    # subdomain match
    "bad.google.com",              # deny a domain of *.google.com
    "",                            # "" matches non-FQDN (IP) requests.
]
deny_ports = [22, 25]              # Black list of outbound ports
iface = tun0                       # Outgoing traffic binds to specific network interface
addresses = ["12.34.56.78"]        # List of source IP addresses
dnsbl_domain = "some.dnsbl.org"    # to exclude black listed IP addresses

Tuning

If you see usocksd consumes too much CPU, try setting GOGC to higher value, say 300.

License

MIT

Documentation

Index

• func Listeners(c *Config) ([]net.Listener, error)
• func MetricsListener(c *Config) (net.Listener, error)
• func NewMetricsServer(_ *Config) *metrics.Server
• func NewServer(c *Config) *socks.Server
• type AddressGroup
  • func NewAddressGroup(addresses []net.IP, dnsblDomain string) *AddressGroup
  • func (a *AddressGroup) PickAddress(hint uint32) net.IP
• type Config
  • func NewConfig() *Config
  • func (c *Config) Load(path string) error
• type IncomingConfig
• type OutgoingConfig

Functions

func Listeners

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

Listeners returns a list of net.Listener.

func MetricsListener

func MetricsListener(c *Config) (net.Listener, error)

MetricsListener returns a listener for the metrics server.

func NewMetricsServer

func NewMetricsServer(_ *Config) *metrics.Server

NewMetricsServer creates a new metrics.Server.

func NewServer

func NewServer(c *Config) *socks.Server

NewServer creates a new socks.Server.

Types

type AddressGroup

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

AddressGroup is a group of external IP addresses to be used for outgoing connections. With the help of associated goroutines, IP addresses listed on DNSBL will be checked and excluded.

func NewAddressGroup

func NewAddressGroup(addresses []net.IP, dnsblDomain string) *AddressGroup

NewAddressGroup initializes a new AddressGroup and starts helper goroutines.

func (*AddressGroup) PickAddress

func (a *AddressGroup) PickAddress(hint uint32) net.IP

PickAddress returns a local IP address for outgoing connection. hint should be an integer calculated from client and/or target IP addresses.

type Config

type Config struct {
	Log      well.LogConfig `toml:"log"`
	Incoming IncomingConfig `toml:"incoming"`
	Outgoing OutgoingConfig `toml:"outgoing"`
}

Config is a struct tagged for TOML for usocksd.

func NewConfig

func NewConfig() *Config

NewConfig creates and initializes Config.

func (*Config) Load

func (c *Config) Load(path string) error

Load loads a TOML file from path.

type IncomingConfig

type IncomingConfig struct {
	Port        int
	MetricsPort int `toml:"metrics_port"`
	Addresses   []net.IP
	AllowFrom   []string `toml:"allow_from"`
	// contains filtered or unexported fields
}

IncomingConfig is a set of configurations to accept clients.

type OutgoingConfig

type OutgoingConfig struct {
	AllowSites  []string `toml:"allow_sites"`
	DenySites   []string `toml:"deny_sites"`
	DenyPorts   []int    `toml:"deny_ports"`
	IFace       string   `toml:"iface"`
	Addresses   []net.IP
	DNSBLDomain string `toml:"dnsbl_domain"`
}

OutgoingConfig is a set of configurations to connect to destinations.