3proxy

3proxy

Overview

3proxy is a tiny proxy server: one binary (3proxy, about 330 KB in the 1.0.0 package) that starts HTTP(S), SOCKS4/5, SNI, FTP, POP3/SMTP and TCP/UDP port-mapping services from a single config file. The config is a script executed top to bottom — each line is a command, and a service line (proxy, socks, tcppm) starts with whatever auth, ACL and limits are in force at that point. This skill covers installation, the packaged file layout, users, ACLs, parent proxies, traffic limits and hardening.

Instructions

Step 1: Installation

Debian and Ubuntu do not ship a 3proxy package. The project publishes its own signed apt and dnf repositories (channels: current = 1.0, lts = 0.9.9.x).

# Debian 12+ / Ubuntu 22.04+
curl -fsSLO https://3proxy.org/repo/3proxy-release-key.asc
# verify the signing key's fingerprint before trusting it; stop if this prints nothing
gpg --show-keys --with-colons 3proxy-release-key.asc \
  | grep -q '^fpr:::::::::FC12214499FCC7BA1CFF6CDC0312384E3A73940B:' && echo "key fingerprint OK"
sudo install -m 644 3proxy-release-key.asc /usr/share/keyrings/3proxy.asc
sudo tee /etc/apt/sources.list.d/3proxy.sources <<EOF
Types: deb
URIs: https://3proxy.org/repo/deb
Suites: current
Components: main
Signed-By: /usr/share/keyrings/3proxy.asc
EOF
sudo apt update && sudo apt install 3proxy

RHEL, AlmaLinux, Rocky and CentOS Stream 8–10 use the dnf repository described at https://3proxy.org/repo/. A container image is on Docker Hub as 3proxy/3proxy (tags latest, 1.0.0, lts, busybox, minimal):

docker run -d --name 3proxy --read-only -p 3128:3128 -p 1080:1080 \
  -v /srv/3proxy/3proxy.cfg:/etc/3proxy/3proxy.cfg:ro 3proxy/3proxy:1.0.0

In the container, use a bare log line so records go to stdout (docker logs 3proxy).

What the package installs:

Because of the chroot, every path inside the editable config is relative to /usr/local/3proxy: /conf/passwd, /logs/3proxy.log, /count/3proxy.3cf. The package enables 3proxy.service and tries to start it, but the packaged config reads /conf/passwd, which does not exist until the first add3proxyuser call — until then 3proxy exits with a parse error. Manage the service with systemctl restart 3proxy; systemctl reload 3proxy (sends SIGUSR1) re-reads the config of a running service.

Step 2: Basic Configuration

/etc/3proxy/conf/3proxy.cfg — authenticated HTTP and SOCKS5 proxy:

nscache 65536
nserver 1.1.1.1
nserver 8.8.8.8

config /conf/3proxy.cfg
monitor /conf/3proxy.cfg

log /logs/3proxy.log D
logformat "L%Y-%m-%d %H:%M:%S %N.%p %E %U %C:%c %R:%r %O %I %T"
rotate 30

counter /count/3proxy.3cf
users $/conf/passwd
include /conf/counters
include /conf/bandlimiters
auth strong
deny * * 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
allow *
proxy -p3128
socks -p1080

monitor reloads the config within a minute of the file changing. log with no file name writes to stdout; log @3proxy writes to syslog. D rotates daily (the file on disk is 3proxy.log.2026.10.01) and rotate 30 keeps 30 files. The counter and include lines come from the packaged config: they load the quotas and speed limits that add3proxyuser writes. Do not add daemon under systemd — the unit is Type=simple.

Step 3: Users and Authentication

sudo add3proxyuser alice "$ALICE_PROXY_PASSWORD"            # hashed entry in /etc/3proxy/conf/passwd
sudo add3proxyuser bob "$BOB_PROXY_PASSWORD" 2048 8388608   # + 2048 MB/day quota and an 8 Mbit/s cap
sudo systemctl restart 3proxy

A users line can also be written by hand. Password types: CL: cleartext, CR: crypt hash ($3$ BLAKE2b, or $1$ MD5-crypt when built with OpenSSL), NT: NT hash. 3proxy_crypt "$PROXY_SALT" "$ALICE_PROXY_PASSWORD" prints a ready CR:$3$… value. Quote any entry that contains $ — an unquoted $ starts a file include:

users "alice:CR:$3$k7Qm2x$G47yV9w…" ops:CL:Winter-Harbor-48

auth types: none (default — ACLs, limits and parents are not applied), iponly (ACLs by address, no password), strong (username and password), cache/cacheacl with authcache. auth iponly strong asks for a password only when the matching rule names a user.

Step 4: Access Control Lists (ACLs)

Fields, in order: users, source addresses, targets, target ports, operations, weekdays, time periods. Lists are comma-separated without spaces; * means any. Rules are checked top to bottom and the first match wins. An empty list means allow *; a non-empty list ends with an implicit deny *.

auth strong
# host names, with a wildcard at either end
deny * * *facebook.com,*instagram.com
# full access for one user
allow admin
# web ports only
allow alice,bob * * 80,443
# office LAN, Monday to Friday, working hours
allow * 192.168.1.0/24 * * * 1-5 08:00:00-18:00:00

Operations include CONNECT, BIND, UDPASSOC, HTTP, HTTPS, HTTP_GET, HTTP_POST and FTP. A host-name rule only matches when the client sends a host name, so pair it with address rules.

Step 5: Several Services with Different Rules

flush empties the access list; without it, rules keep accumulating for every later service.

# LAN clients, no password
auth iponly
allow * 10.8.0.0/24
proxy -p3128 -i10.8.0.1
flush

# Internet-facing SOCKS5, password required
auth strong
allow alice,bob * * 80,443
socks -p1080 -i203.0.113.50

-i sets the listening address for one service and -e the outgoing address; the internal and external commands set them for every service that follows. Port forwarding: tcppm -i127.0.0.1 2222 10.0.0.5 22 maps local port 2222 to SSH on 10.0.0.5.

Step 6: Parent Proxies (Chaining and Rotation)

parent extends the allow rule directly above it — a parent with no preceding allow is a startup error. The first argument is a weight from 1 to 1000. Parents whose weights add up to 1000 form one group, and one member is picked at random per new connection. Every further 1000 adds another hop.

auth strong

# Rotation: one hop, chosen at random among three upstreams
allow alice
parent 334 socks5 198.51.100.11 1080 rotate Upstream-Pass-71
parent 333 socks5 198.51.100.12 1080 rotate Upstream-Pass-71
parent 333 socks5 198.51.100.13 1080 rotate Upstream-Pass-71

# Two-hop chain: SOCKS5 first, then an HTTP CONNECT proxy
allow bob
parent 1000 socks5 198.51.100.11 1080
parent 1000 connect 198.51.100.40 3128

proxy -p3128

Types: socks4, socks5, connect (HTTP CONNECT), http, tcp, extip (only sets the outgoing address). A trailing + (socks5+, connect+) lets the parent resolve host names; combine it with fakeresolve. A trailing s (socks5s, https) connects to the parent over TLS and needs ssl_client_mode 3. parentretries 3 retries a failed parent.

Step 7: Bandwidth, Connection and Traffic Limits

# simultaneous connections per service started below (default 100)
maxconn 1000
# alice: 5 parallel connections (period 0); bob: 120 new connections per 60 seconds
connlim 5 0 alice
connlim 120 60 bob
# rates are bits per second: 8 Mbit/s incoming for alice, 2 Mbit/s outgoing shared by everyone
bandlimin 8388608 alice
bandlimout 2097152 *

counter /count/3proxy.3cf
# counter 1: 51200 MB per month in both directions; counter 2: 2048 MB incoming per day
countall 1 M 51200 alice
countin 2 D 2048 bob

connlim takes a rate and a period. countin/countout/countall take a counter number (sequential, and unique across the config — add3proxyuser numbers the ones it writes to /conf/counters from 0), a period (H, D, W, M) and a limit in megabytes. One rule that lists several users or a CIDR gives them a shared limit; write one rule per user for individual limits. maxconn affects the services started after it; bandwidth limits and counters apply to every service.

Step 8: Security Hardening

# bind explicitly instead of listening on every interface
internal 203.0.113.50
external 203.0.113.50
auth strong
deny * * 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,169.254.0.0/16
allow alice,bob * * 80,443
socks -p1080

Restrict the ports at the firewall as well:

sudo ufw allow from 198.51.100.0/24 to any port 1080 proto tcp
sudo ufw deny 1080/tcp

Examples