Build & Install

Optional Features

Memory Allocators

crates.io

# Install from crates.iocargo install shadowsocks-rust

Install using Homebrew

brew install shadowsocks-rust

Install using snap

# Install from snapstoresnap install shadowsocks-rust# List servicessnap services shadowsocks-rust# Enable and start shadowsocks-rust.sslocal-daemon snap servicesnap start --enable shadowsocks-rust.sslocal-daemon# Show generated systemd service statussystemctl status snap.shadowsocks-rust.sslocal-daemon.service# Override generated systemd service (configure startup options)systemctl edit snap.shadowsocks-rust.sslocal-daemon.service## NOTE: you can pass args to sslocal:##  [Service]##  ExecStart=##  ExecStart=/usr/bin/snap run shadowsocks-rust.sslocal-daemon -b "127.0.0.1:1080" --server-url "ss://...."# Restart generated systemd service to apply changessystemctl restart snap.shadowsocks-rust.sslocal-daemon.service# ... and show service statussystemctl status snap.shadowsocks-rust.sslocal-daemon.service

Download release

Docker

Pull from GitHub Container Registry

docker pull ghcr.io/shadowsocks/sslocal-rust:latestdocker pull ghcr.io/shadowsocks/ssserver-rust:latest

Build on the local machine（Optional）

docker buildx build -t shadowsocks/ssserver-rust:latest -t shadowsocks/ssserver-rust:v1.15.2 --target ssserver.docker buildx build -t shadowsocks/sslocal-rust:latest -t shadowsocks/sslocal-rust:v1.15.2 --target sslocal.

Run the container

docker run --name sslocal-rust \  --restart always \  -p 1080:1080/tcp \  -v /path/to/config.json:/etc/shadowsocks-rust/config.json \  -dit ghcr.io/shadowsocks/sslocal-rust:latestdocker run --name ssserver-rust \  --restart always \  -p 8388:8388/tcp \  -p 8388:8388/udp \  -v /path/to/config.json:/etc/shadowsocks-rust/config.json \  -dit ghcr.io/shadowsocks/ssserver-rust:latest

Deploy to Kubernetes

Usingkubectl

Usinghelm

# This is the shadowsocks config which will be mount to /etc/shadowocks-rust.# You can put arbitrary yaml here, and it will be translated to json before mounting.servers:-server:"::"server_port:8388service_port:80# the k8s service port, default to server_portpassword:mypasswordmethod:aes-256-gcmfast_open:truemode:tcp_and_udp# plugin: v2ray-plugin# plugin_opts: server;tls;host=github.com# Whether to download v2ray and xray plugin.downloadPlugins:false# Name of the ConfigMap with config.json configuration for shadowsocks-rust.configMapName:""service:# Change to LoadBalancer if you are behind a cloud provider like aws, gce, or tke.type:ClusterIP# Bind shadowsocks port port to host, i.e., we can use host:port to access shawdowsocks server.hostPort:falsereplicaCount:1image:repository:ghcr.io/shadowsocks/ssserver-rustpullPolicy:IfNotPresent# Overrides the image tag whose default is the chart appVersion.tag:"latest"

Build from source

cargo build --release

make install TARGET=release

target-cpu optimization

export RUSTFLAGS="-C target-cpu=native"

Build standalone binaries

./build/build-release

export CROSS_CONFIG=Cross-centos.toml

Getting Started

ssservice genkey -m"aes-128-gcm"

{"server":"my_server_ip","server_port":8388,"password":"rwQc8qPXVsRpGx3uW+Y3Lj4Y42yF9Bs0xg1pmx8/+bo=","method":"aes-256-gcm",// ONLY FOR `sslocal`// Delete these lines if you are running `ssserver` or `ssmanager`"local_address":"127.0.0.1","local_port":1080}

{"servers": [        {"server":"127.0.0.1","server_port":8388,"password":"rwQc8qPXVsRpGx3uW+Y3Lj4Y42yF9Bs0xg1pmx8/+bo=","method":"aes-256-gcm","timeout":7200        },        {"server":"127.0.0.1","server_port":8389,"password":"/dliNXn5V4jg6vBW4MnC1I8Jljg9x7vSihmk6UZpRBM=","method":"chacha20-ietf-poly1305"        },        {"disabled":true,"server":"eg.disable.me","server_port":8390,"password":"mGvbWWay8ueP9IHnV5F1uWGN2BRToiVCAWJmWOTLU24=","method":"chacha20-ietf-poly1305"        }    ],// ONLY FOR `sslocal`// Delete these lines if you are running `ssserver` or `ssmanager`"local_port":1080,"local_address":"127.0.0.1"}

sslocal -c config.jsonssserver -c config.json

cargo run --bin sslocal -- -c config.jsoncargo run --bin ssserver -- -c config.json

Usage

# Read local client configuration from filesslocal -c /path/to/shadowsocks.json

Socks5 Local client

# Pass all parameters via command linesslocal -b"127.0.0.1:1080" -s"[::1]:8388" -m"aes-256-gcm" -k"hello-kitty" --plugin"v2ray-plugin" --plugin-opts"server;tls;host=github.com"# Pass server with SIP002 URLsslocal -b"127.0.0.1:1080" --server-url"ss://YWVzLTI1Ni1nY206cGFzc3dvcmQ@127.0.0.1:8388/?plugin=v2ray-plugin%3Bserver%3Btls%3Bhost%3Dgithub.com"

HTTP Local client

sslocal -b"127.0.0.1:3128" --protocol http -s"[::1]:8388" -m"aes-256-gcm" -k"hello-kitty"

Tunnel Local client

# Set 127.0.0.1:8080 as the target for forwarding tosslocal --protocol tunnel -b"127.0.0.1:3128" -f"127.0.0.1:8080" -s"[::1]:8388" -m"aes-256-gcm" -k"hello-kitty"

Transparent Proxy Local client

sslocal -b"127.0.0.1:60080" --protocol redir -s"[::1]:8388" -m"aes-256-gcm" -k"hello-kitty" --tcp-redir"redirect" --udp-redir"tproxy"

Tun interface client

Linux

ip tuntap add mode tun tun0ifconfig tun0 inet 10.255.0.1 netmask 255.255.255.0 up

sslocal --protocol tun -s"[::1]:8388" -m"aes-256-gcm" -k"hello-kitty" --outbound-bind-interface lo0 --tun-interface-name tun0

macOS

sslocal --protocol tun -s"[::1]:8388" -m"aes-256-gcm" -k"hello-kitty" --outbound-bind-interface lo0 --tun-interface-address 10.255.0.1/24

Windows

sslocal--protocol tun-s"[::1]:8388"-m"aes-256-gcm"-k"hello-kitty"--outbound-bind-interface"Ethernet 0"--tun-interface-name"shadowsocks"

Local client for Windows Service

cargo build --release --bin"sswinservice" --features"winservice"

New-Service-Name"shadowsocks-local-service"`-DisplayName"Shadowsocks Local Service"`-BinaryPathName"<Path\to>\sswinservice.exe local -c <Path\to>\local_config.json"

Server

# Read server configuration from filessserver -c /path/to/shadowsocks.json# Pass all parameters via command linessserver -s"[::]:8388" -m"aes-256-gcm" -k"hello-kitty" --plugin"v2ray-plugin" --plugin-opts"server;tls;host=github.com"

Server Manager

# Start it just with --manager-address command line parameterssmanager --manager-address"127.0.0.1:6100"# For *nix system, manager can bind to unix socket addressssmanager --manager-address"/tmp/shadowsocks-manager.sock"# You can also provide a configuration file## `manager_address` key must be provided in the configuration filessmanager -c /path/to/shadowsocks.json# Create one server by UDPecho'add: {"server_port":8388,"password":"hello-kitty"}'| nc -u'127.0.0.1''6100'# Close one server by unix socketecho'remove: {"server_port":8388}'| nc -Uu'/tmp/shadowsocks-manager.sock'

{// Required option// Address that ssmanager is listening on"manager_address":"127.0.0.1","manager_port":6100,// Or bind to a Unix Domain Socket"manager_address":"/tmp/shadowsocks-manager.sock","servers": [// These servers will be started automatically when ssmanager is started    ],// Outbound socket binds to this IP address// For choosing different network interface on the same machine"local_address":"xxx.xxx.xxx.xxx",// Other options that may be passed directly to new servers}

Configuration

{// LOCAL: Listen address. This is exactly the same as `locals[0]`// SERVER: Bind address for remote sockets, mostly used for choosing interface//         Don't set it if you don't know what's this for."local_address":"127.0.0.1","local_port":1080,// Extended multiple local configuration"locals": [        {// Basic configuration, a SOCKS5 local server"local_address":"127.0.0.1","local_port":1080,// OPTIONAL. Setting the `mode` for this specific local server instance.// If not set, it will derive from the outer `mode`"mode":"tcp_and_udp",// OPTIONAL. Authentication configuration file// Configuration file document could be found in the next section."socks5_auth_config_path":"/path/to/auth.json",// OPTIONAL. Instance specific ACL"acl":"/path/to/acl/file.acl",// OPTIONAL. macOS launchd activate socket"launchd_tcp_socket_name":"TCPListener","launchd_udp_socket_name":"UDPListener"        },        {// SOCKS5, SOCKS4/4a local server"protocol":"socks",// Listen address"local_address":"127.0.0.1","local_port":1081,// OPTIONAL. Enables UDP relay"mode":"tcp_and_udp",// OPTIONAL. Customizing the UDP's binding address. Depending on `mode`, if// - TCP is enabled, then SOCKS5's UDP Association command will return this address// - UDP is enabled, then SOCKS5's UDP server will listen to this address."local_udp_address":"127.0.0.1","local_udp_port":2081,// OPTIONAL. macOS launchd activate socket"launchd_tcp_socket_name":"TCPListener","launchd_udp_socket_name":"UDPListener"        },        {// Tunnel local server (feature = "local-tunnel")"protocol":"tunnel",// Listen address"local_address":"127.0.0.1","local_port":5353,// Forward address, the target of this tunnel// In this example, this will build a `127.0.0.1:5353` -> `8.8.8.8:53` tunnel"forward_address":"8.8.8.8","forward_port":53,// OPTIONAL. Customizing whether to start TCP and UDP tunnel"mode":"tcp_only",// OPTIONAL. macOS launchd activate socket"launchd_tcp_socket_name":"TCPListener","launchd_udp_socket_name":"UDPListener"        },        {// HTTP local server (feature = "local-http")"protocol":"http",// Listen address"local_address":"127.0.0.1","local_port":3128,// OPTIONAL. macOS launchd activate socket"launchd_tcp_socket_name":"TCPListener",// OPTIONAL. Authentication configuration file// Configuration file document could be found in the next section."http_auth_config_path":"/path/to/auth.json",        },        {// DNS local server (feature = "local-dns")// This DNS works like China-DNS, it will send requests to `local_dns` and `remote_dns` and choose by ACL rules"protocol":"dns",// Listen address"local_address":"127.0.0.1","local_port":53,// OPTIONAL. DNS local server uses `tcp_and_udp` mode by default"mode":"udp_only",// Local DNS address, DNS queries will be sent directly to this address"local_dns_address":"114.114.114.114",// OPTIONAL. Local DNS's port, 53 by default"local_dns_port":53,// Remote DNS address, DNS queries will be sent through ssserver to this address"remote_dns_address":"8.8.8.8",// OPTIONAL. Remote DNS's port, 53 by default"remote_dns_port":53,// OPTIONAL. dns client cache size for fetching dns queries."client_cache_size":5,// OPTIONAL. macOS launchd activate socket"launchd_tcp_socket_name":"TCPListener","launchd_udp_socket_name":"UDPListener"        },        {// Tun local server (feature = "local-tun")"protocol":"tun",// Tun interface name"tun_interface_name":"tun0",// Tun interface address//// It has to be a host address in CIDR form"tun_interface_address":"10.255.0.1/24"        },        {// Transparent Proxy (redir) local server (feature = "local-redir")"protocol":"redir",// OPTIONAL: TCP type, may be different between platforms// Linux/Android: redirect (default), tproxy// FreeBSD/OpenBSD: pf (default), ipfw// NetBSD/macOS/Solaris: pf (default), ipfw"tcp_redir":"tproxy",// OPTIONAL: UDP type, may be different between platforms// Linux/Android: tproxy (default)// FreeBSD/OpenBSD: pf (default)"udp_redir":"tproxy"        },        {// FakeDNS local server (feature = "local-fake-dns")// FakeDNS is a DNS server that allocates an IPv4 / IPv6 address in a specific pool for each queries.// Subsequence requests from the other local interfaces that the target addresses includes those allocated IP addresses,// will be substituted back to their original domain name addresses.// This feature is useful mostly for transparent proxy, which will allow the proxied domain names to be resolved remotely."protocol":"fake-dns",// Listen address"local_address":"127.0.0.1","local_port":10053,// IPv4 address pool (for A records)"fake_dns_ipv4_network":"10.255.0.0/16",// IPv6 address pool (for AAAA records)"fake_dns_ipv6_network":"fdf2:e786:ab40:9d2f::/64",// Persistent storage for all allocated DNS records"fake_dns_database_path":"/var/shadowsocks/fakedns.db",// OPTIONAL: Record expire duration in seconds, 10s by default"fake_dns_record_expire_duration":10        }    ],// Server configuration// listen on :: for dual stack support, no need add [] around."server":"::",// Change to use your custom port number"server_port":8388,"method":"aes-256-gcm","password":"your-password","plugin":"v2ray-plugin","plugin_opts":"mode=quic;host=github.com","plugin_args": [// Each line is an argument passed to "plugin""--verbose"    ],"plugin_mode":"tcp_and_udp",// SIP003u, default is "tcp_only"// Server: TCP socket timeout in seconds.// Client: TCP connection timeout in seconds.// Omit this field if you don't have specific needs."timeout":7200,// Extended multiple server configuration// LOCAL: Choosing the best server to connect dynamically// SERVER: Creating multiple servers in one process"servers": [        {// Fields are the same as the single server's configuration// Individual servers can be disabled// "disabled": true,"address":"0.0.0.0","port":8389,"method":"aes-256-gcm","password":"your-password","plugin":"...","plugin_opts":"...","plugin_args": [],"plugin_mode":"...","timeout":7200,// Customized weight for local server's balancer//// Weight must be in [0, 1], default is 1.0.// The higher weight, the server may rank higher."tcp_weight":1.0,"udp_weight":1.0,// OPTIONAL. Instance specific ACL"acl":"/path/to/acl/file.acl",        },        {// Same key as basic format "server" and "server_port""server":"0.0.0.0","server_port":8388,"method":"chacha20-ietf-poly1305",// Read the actual password from environment variable PASSWORD_FROM_ENV"password":"${PASSWORD_FROM_ENV}"        },        {// AEAD-2022"server":"::","server_port":8390,"method":"2022-blake3-aes-256-gcm","password":"3SYJ/f8nmVuzKvKglykRQDSgg10e/ADilkdRWrrY9HU=",// For Server (OPTIONAL)// Support multiple users with Extensible Identity Header// https://github.com/Shadowsocks-NET/shadowsocks-specs/blob/main/2022-2-shadowsocks-2022-extensible-identity-headers.md"users": [                {"name":"username",// User's password must have the same length as server's password"password":"4w0GKJ9U3Ox7CIXGU4A3LDQAqP6qrp/tUi/ilpOR9p4="                }            ],// For Client (OPTIONAL)// If EIH enabled, then "password" should have the following format: iPSK:iPSK:iPSK:uPSK// - iPSK is one of the middle relay servers' PSK, for the last `ssserver`, it must be server's PSK ("password")// - uPSK is the user's PSK ("password")// Example:// "password": "3SYJ/f8nmVuzKvKglykRQDSgg10e/ADilkdRWrrY9HU=:4w0GKJ9U3Ox7CIXGU4A3LDQAqP6qrp/tUi/ilpOR9p4="        },        {"...":"Any other fields",// Some optional fields for this specific server// Outbound socket options// Linux Only (SO_MARK)"outbound_fwmark":255,// FreeBSD only (SO_USER_COOKIE)"outbound_user_cookie":255,// `SO_BINDTODEVICE` (Linux), `IP_BOUND_IF` (BSD), `IP_UNICAST_IF` (Windows) socket option for outbound sockets"outbound_bind_interface":"eth1",// Outbound socket bind() to this IP (choose a specific interface)"outbound_bind_addr":"11.22.33.44",// Outbound UDP socket allows IP fragmentation (default false)"outbound_udp_allow_fragmentation":false,        }    ],// Global configurations for UDP associations"udp_timeout":300,// Timeout for UDP associations (in seconds), 5 minutes by default"udp_max_associations":512,// Maximum UDP associations to be kept in one server, unlimited by default// Options for Manager"manager_address":"127.0.0.1",// Could be a path to UNIX socket, /tmp/shadowsocks-manager.sock"manager_port":5300,// Not needed for UNIX socket// DNS server's address for resolving domain names// For *NIX and Windows, it uses system's configuration by default//// Value could be IP address of DNS server, for example, "8.8.8.8".// DNS client will automatically request port 53 with both TCP and UDP protocol.//// - system, uses system provided API (`getaddrinfo` on *NIX)//// It also allows some pre-defined well-known public DNS servers:// - google (TCP, UDP)// - cloudflare (TCP, UDP)// - cloudflare_tls (TLS), enable by feature "dns-over-tls"// - cloudflare_https (HTTPS), enable by feature "dns-over-https"// - quad9 (TCP, UDP)// - quad9_tls (TLS), enable by feature "dns-over-tls"//// The field is only effective if feature "hickory-dns" is enabled."dns":"google",// Configure `cache_size` for "hickory-dns" ResolverOpts. Set to "0" to disable DNS cache."dns_cache_size":0,// Mode, could be one of the// - tcp_only// - tcp_and_udp// - udp_only"mode":"tcp_only",// TCP_NODELAY"no_delay":false,// Enables `SO_KEEPALIVE` and set `TCP_KEEPIDLE`, `TCP_KEEPINTVL` to the specified seconds"keep_alive":15,// Soft and Hard limit of file descriptors on *NIX systems"nofile":10240,// Try to resolve domain name to IPv6 (AAAA) addresses first"ipv6_first":false,// Set IPV6_V6ONLY for all IPv6 listener sockets// Only valid for locals and servers listening on `::`"ipv6_only":false,// Outbound socket options// Linux Only (SO_MARK)"outbound_fwmark":255,// FreeBSD only (SO_USER_COOKIE)"outbound_user_cookie":255,// `SO_BINDTODEVICE` (Linux), `IP_BOUND_IF` (BSD), `IP_UNICAST_IF` (Windows) socket option for outbound sockets"outbound_bind_interface":"eth1",// Outbound socket bind() to this IP (choose a specific interface)"outbound_bind_addr":"11.22.33.44",// Outbound UDP socket allows IP fragmentation (default false)"outbound_udp_allow_fragmentation":false,// Balancer customization"balancer": {// MAX Round-Trip-Time (RTT) of servers// The timeout seconds of each individual checks"max_server_rtt":5,// Interval seconds between each check"check_interval":10,// Interval seconds between each check for the best server// Optional. Specify to enable shorter checking interval for the best server only."check_best_interval":5    },// SIP008 Online Configuration Delivery// https://shadowsocks.org/doc/sip008.html"online_config": {"config_url":"https://path-to-online-sip008-configuration",// Optional. Seconds between each update to config_url. Default to 3600s"update_interval":3600,// Optional. Whitelist of plugins (RECOMMENDED for all users)// SECURITY: To avoid executing untrusted commands loaded from config_url"allowed_plugins": ["v2ray-plugin"        ]    },// Service configurations// Logger configuration"log": {// Default log level to use, if not overridden by `writers`, default is `0`// Equivalent to `-v` command line option"level":1,// Default log format to use, if not overridden by `writers`"format": {// Euiqvalent to `--log-without-time`, default is `false`"without_time":false,        },// Advanced logging configuration for configuring multiple writers// A console writer will be configured by default.// Set this to empty array `[]` to disable logging completely"writers": [            {// Configure a console writer// The inner fields are optional, if not set, it will use the default values// To minimally configure a console writer, simply write `"console": {}`."console": {"level":2,"format": {"without_time":false,                    }                }            },            {// Configure a file writer, useful when running as a Windows Service"file": {// `level` and `format` can also be set here, if not set, it will use the default values// Required. Directory to store log files"directory":"/var/log/shadowsocks-rust",// Optional. Log rotation frequency, must be one of the following:// - never (default): This will result in log file located at `directory/prefix.suffix`// - daily: A new log file in the format of `directory/prefix.yyyy-MM-dd.suffix` will be created daily// - hourly: A new log file in the format of `directory/prefix.yyyy-MM-dd-HH.suffix` will be created hourly"rotation":"never",// Optional. Prefix of log file, default is one of `sslocal`, `ssserver`, `ssmanager` depending on the service being run."prefix":"shadowsocks-rust",// Optional. Suffix of log file, default is `log`"suffix":"log",// Optional. If set, keeps the last N log files"max_files":5                }            },            {// Configure a syslog writer, only supported on *nix system"syslog": {// `level` and `format` can also be set here, if not set, it will use the default values// Optional. Set the "identity" when calling openlog(). Use current service name by default."identity":"identity_name",// Optional. Set the "facility" when calling openlog(). 1 (user-level messages) by default. See RFC5424."facility":1                }            }        ]    },// Runtime configuration"runtime": {// `single_thread` or `multi_thread`"mode":"multi_thread",// Worker threads that are used in multi-thread runtime"worker_count":10    }}

SOCKS5 Authentication Configuration

{// Password/Username Authentication (RFC1929)"password": {"users": [            {"user_name":"USERNAME in UTF-8","password":"PASSWORD in UTF-8"            }        ]    }}

HTTP Authentication Configuration

{// Basic Authentication (RFC9110)"basic": {"users": [            {"user_name":"USERNAME in UTF-8","password":"PASSWORD in UTF-8"            }        ]    }}

Environment Variables

Supported Ciphers

AEAD 2022 Ciphers

AEAD Ciphers

Stream Ciphers

ACL

Available sections

Example

# SERVERS# For ssserver, accepts requests from all clients by default[accept_all]# Blocks these clients[black_list]1.2.3.4127.0.0.1/8# Disallow these outbound addresses[outbound_block_list]127.0.0.1/8::1# Using regular expression^[a-z]{5}\.baidu\.com# Match exactly|baidu.com# Match with subdomains||google.com# An internationalized domain name should be converted to punycode# |☃-⌘.com - WRONG|xn----dqo34k.com# ||джpумлатест.bрфa - WRONG||xn--p-8sbkgc5ag7bhce.xn--ba-lmcq# CLIENTS# For sslocal, ..., bypasses all targets by default[bypass_all]# Proxy these addresses[proxy_list]||google.com8.8.8.8

Useful Tools

ss://YWVzLTI1Ni1jZmI6cGFzc3dvcmQ@127.0.0.1:8388/?plugin=obfs-local%3Bobfs%3Dhttp%3Bobfs-host%3Dwww.baidu.com

Notes

TODO

License

Stargazers over time