An enterprise-grade, high-performance SOCKS5 server written in Rust and built on Tokio. It implements the full SOCKS5 protocol (RFC 1928 / RFC 1929) with a clean, modular, dependency-injected architecture designed for millions of concurrent connections, low latency, and low memory overhead.
Status: the core proxy, authentication, security, DNS, database, REST API, metrics, CLI, Docker, and systemd integration are implemented and covered by unit + integration tests.
- Full SOCKS5 protocol —
CONNECT,BIND, andUDP ASSOCIATE. - Address types — IPv4, IPv6, and domain names with remote DNS resolution.
- Authentication — no-auth, username/password (RFC 1929), and GSSAPI negotiation framing (RFC 1961).
- DNS — caching resolver with Happy Eyeballs (RFC 8305) connection racing.
- Security by default — ACLs (source/destination CIDR, port), IP allow/deny, Geo-IP filtering, per-IP rate limiting, and brute-force bans with fail2ban log integration.
- User & tenant management — quotas, expiry, concurrency and speed limits, usage accounting, tags/notes, and multi-tenant (SaaS) support.
- Persistence — repository pattern over SQLite / PostgreSQL / MySQL via a
single sqlx
Anybackend with automatic migrations. - REST API — JWT + API-key auth, user/tenant CRUD, live sessions, stats, config hot-reload, and dashboard hosting.
- Observability — Prometheus
/metricsplus/healthz,/readyz,/livez. - Structured logging — JSON/pretty/compact via
tracing, optional rolling files. - Linux performance —
SO_REUSEPORTmulti-worker accept loops, TCP keepalive/nodelay tuning, pooled relay buffers, and lock-light concurrency. - Operations — CLI (
start/stop/reload/validate-config/migrate/users/stats/hash-password/version), Docker, docker-compose, and a hardened systemd unit. - TLS — SOCKS-over-TLS and mutual TLS (mTLS) via rustls.
Full install from GitHub Releases: binary, config, secrets, firewall, systemd/launchd, optional SOCKS5 user.
Public repo (no token):
curl -fsSL https://raw.githubusercontent.com/zamibd/socks5-rs/main/install.sh | sudo bashGitHub API (private fork, higher rate limits, or pinned ref):
export GITHUB_TOKEN='ghp_token_here' # optional for public repos
export SOCKS5_ADMIN_PASSWORD='your-admin-pass' # optional — random if omitted
export SOCKS5_PROXY_USER='proxy' # optional SOCKS5 client user
export SOCKS5_PROXY_PASSWORD='proxy-pass' # optional — random if user set
export SOCKS5_VERSION='1.0.1' # optional — default: latest release
curl -fsSL \
-H "Authorization: Bearer ${GITHUB_TOKEN}" \
-H "Accept: application/vnd.github.raw" \
"https://api.github.com/repos/zamibd/socks5-rs/contents/install.sh?ref=main" \
| sudo bash -sFrom a local clone:
make setup
# or with options:
make setup VERSION=1.0.1 PROXY_USER=proxy ADMIN_PASS='secret'Pass installer flags after bash -s -- when piping from curl:
# Dashboard behind an HTTPS reverse proxy (nginx + Let's Encrypt) on your domain:
curl -fsSL https://raw.githubusercontent.com/zamibd/socks5-rs/main/install.sh \
| sudo bash -s -- --proxy-domain proxy.example.com --proxy-email admin@example.com
# Dashboard behind a plain-HTTP reverse proxy on port 80 (no domain/TLS):
curl -fsSL https://raw.githubusercontent.com/zamibd/socks5-rs/main/install.sh \
| sudo bash -s -- --reverse-proxy
# Create a SOCKS5 user and enable UDP/VoIP (WhatsApp calls) behind NAT:
curl -fsSL https://raw.githubusercontent.com/zamibd/socks5-rs/main/install.sh \
| sudo bash -s -- --proxy-user alice --udp-advertised-ip 203.0.113.10
# Encrypt the SOCKS5 protocol itself (SOCKS-over-TLS). Self-signed by default;
# reuses the Let's Encrypt cert automatically when --proxy-domain is also given:
curl -fsSL https://raw.githubusercontent.com/zamibd/socks5-rs/main/install.sh \
| sudo bash -s -- --proxy-domain proxy.example.com --proxy-email admin@example.com --socks-tls
# Everything at once: HTTPS dashboard + SOCKS5 user + VoIP:
curl -fsSL https://raw.githubusercontent.com/zamibd/socks5-rs/main/install.sh \
| sudo bash -s -- \
--proxy-domain proxy.example.com --proxy-email admin@example.com \
--proxy-user alice --udp-advertised-ip 203.0.113.10Installer flags:
| Flag | Env var | Purpose |
|---|---|---|
--version TAG |
SOCKS5_VERSION |
Release to install (default: latest) |
--admin-password PASS |
SOCKS5_ADMIN_PASSWORD |
Dashboard admin password (default: random) |
--proxy-user NAME |
SOCKS5_PROXY_USER |
Create a SOCKS5 user |
--proxy-password PASS |
SOCKS5_PROXY_PASSWORD |
Password for --proxy-user (default: random) |
--socks-port PORT |
SOCKS5_PORT |
SOCKS5 listen port (default: 1080) |
--reverse-proxy |
SOCKS5_REVERSE_PROXY=1 |
Install nginx reverse proxy for the dashboard |
--proxy-domain DOMAIN |
SOCKS5_PROXY_DOMAIN |
Serve dashboard on DOMAIN + HTTPS via Let's Encrypt |
--proxy-email EMAIL |
SOCKS5_PROXY_EMAIL |
Let's Encrypt registration email |
--proxy-http-port PORT |
SOCKS5_PROXY_HTTP_PORT |
nginx HTTP port (default: 80) |
--socks-tls |
SOCKS5_SOCKS_TLS=1 |
Wrap the SOCKS5 listener in TLS; auto-provisions cert (LE with --proxy-domain, else self-signed) |
--socks-tls-cert FILE / --socks-tls-key FILE |
SOCKS5_SOCKS_TLS_CERT / _KEY |
Bring-your-own SOCKS TLS cert/key (PEM) |
--socks-tls-client-ca FILE |
SOCKS5_SOCKS_TLS_CLIENT_CA |
Require + verify client certs (mTLS) |
--udp-advertised-ip IP |
SOCKS5_UDP_ADVERTISED_IP |
Public IP for UDP/VoIP behind NAT |
--udp-port-min N / --udp-port-max N |
SOCKS5_UDP_RELAY_PORT_MIN / _MAX |
UDP relay port range (default: 41000–41010) |
--skip-firewall |
— | Don't touch ufw/firewalld/iptables |
--skip-service |
— | Install files only; don't start the service |
--dry-run |
— | Print actions without changing the system |
After install, credentials are saved to /var/lib/socks5/install-credentials.txt.
| Service | Default |
|---|---|
| Dashboard | http://127.0.0.1:8080/ (localhost) — public URL with --reverse-proxy; user admin |
| SOCKS5 proxy | 0.0.0.0:1080 — user from --proxy-user if set |
| UDP/VoIP relay | 41000–41010/udp — set --udp-advertised-ip behind NAT |
See docs/NATIVE.md for the full native A→Z guide (reverse proxy, VoIP, troubleshooting), docs/INSTALL.md for Docker, and docs/CONFIG.md for configuration reference.
# Build (Rust 1.75+).
cargo build --release
# Generate an admin password hash for the dashboard/API.
export SOCKS5_ADMIN_PASSWORD_HASH="$(./target/release/socks5-rs hash-password 'admin-password')"
# Validate configuration.
./target/release/socks5-rs --config config.example.yaml validate-config
# Run.
./target/release/socks5-rs --config config.example.yaml startTest it:
# No-auth is disabled by default; add a user first:
./target/release/socks5-rs --config config.example.yaml users add alice 's3cret'
curl --socks5 alice:s3cret@127.0.0.1:1080 https://example.comClean, layered, and free of global mutable state. Services are constructed once
and injected through a single ServerContext.
src/
├── protocol/ SOCKS5 wire types (handshake, request, reply, address, udp)
├── config/ typed config, multi-format load, validation, hot reload
├── auth/ method negotiation + user/pass + gssapi framing
├── security/ ACL, rate limiting, brute-force, GeoIP
├── dns/ caching resolver + Happy Eyeballs
├── net/ buffer pool, socket tuning, bidirectional relay
├── users/ user/tenant models, Argon2 hashing, auth manager
├── db/ repository traits + sqlx (SQLite/Postgres/MySQL) impl
├── metrics/ Prometheus registry
├── tls/ rustls server config (TLS / mTLS)
├── server/ listeners, connection lifecycle, tcp/udp/bind handlers
├── api/ axum REST API + health/metrics + dashboard host
└── cli/ command-line interface + process control
See the docs/ directory for detailed guides:
| Document | Contents |
|---|---|
| INSTALL.md | Building and installing from source, Docker, packages |
| CONFIG.md | Every configuration field, formats, env overrides |
| API.md | REST API reference with examples |
| PERFORMANCE.md | Tuning for throughput and scale |
| SECURITY.md | Hardening, threat model, secure defaults |
| DEPLOYMENT.md | systemd, Docker, Kubernetes, scaling |
cargo test # unit + integration tests
cargo bench # criterion micro-benchmarks
cargo test -- --nocaptureDual-licensed under MIT or Apache-2.0.