Skip to content
SOCKS4/5 server library and command in Go
Branch: master
Clone or download
Latest commit ea18de2 Dec 25, 2018

GitHub release GoDoc CircleCI Go Report Card License

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.


  • 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.

  • 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.


Use Go 1.7 or better.

go get -u


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.

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

port = 1080
addresses = [""]          # List of listening IP addresses
allow_from = [""]        # CIDR network or IP address

allow_sites = [                    # List of FQDN to be granted.
    "",              # exact match
    "",                 # subdomain match
deny_sites = [                     # List of FQDN to be denied.
    "",                    # subdomain match
    "",              # deny a domain of *
    "",                            # "" matches non-FQDN (IP) requests.
deny_ports = [22, 25]              # Black list of outbound ports
addresses = [""]        # List of source IP addresses
dnsbl_domain = ""    # to exclude black listed IP addresses


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



You can’t perform that action at this time.