d2df32fdab
Adds Tor control port section to USAGE.md covering config, auth modes, rate limiting, and API endpoints. Updates README feature line and config example, CHEATSHEET with tor snippets, and marks the feature complete in TASKS.md and ROADMAP.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
4.3 KiB
4.3 KiB
s5p -- Cheatsheet
CLI
s5p # direct, listen :1080
s5p -C socks5://127.0.0.1:9050 # through Tor
s5p -C socks5://tor:9050,http://px:8080 # Tor + HTTP proxy
s5p -c config/s5p.yaml # from config file
s5p -l 0.0.0.0:9999 # custom listen address
s5p -t 30 # 30s per-hop timeout
s5p -v # debug logging
s5p -q # errors only
s5p -S http://api:8081/proxies # proxy source API
s5p -r 5 # retry up to 5 proxies
s5p -m 512 # max concurrent connections
s5p --api 127.0.0.1:1081 # enable control API
s5p --cprofile # profile to s5p.prof
s5p --cprofile out.prof # profile to custom file
Container
make build # podman-compose build
make up # podman-compose up -d
make logs # podman-compose logs -f
make down # podman-compose down
Volumes: ./src (ro), ./config/s5p.yaml (ro), ~/.cache/s5p → /data (pool state + profiles)
Config
cp config/example.yaml config/s5p.yaml # create live config (gitignored)
Performance Tuning (config)
max_connections: 256 # concurrent connection cap
pool_size: 8 # pre-warmed TCP conns to first hop (0 = off)
pool_max_idle: 30 # evict idle pooled conns (seconds)
Proxy Pool (config)
proxy_pool:
sources:
- url: http://10.200.1.250:8081/proxies
proto: socks5
limit: 1000
- file: /etc/s5p/proxies.txt
refresh: 300 # re-fetch interval
test_interval: 120 # health test cycle
max_fails: 3 # evict after N fails
report_url: "" # POST dead proxies (optional)
Tor Control Port (config)
tor:
control_port: 9051
password: "" # or cookie_file: /path/to/cookie
newnym_interval: 60 # auto-rotate every 60s (0 = manual)
curl -s http://127.0.0.1:1081/tor | jq . # status
curl -s -X POST http://127.0.0.1:1081/tor/newnym | jq . # new circuit
Hot Reload
kill -HUP $(pidof s5p) # reload config
podman kill --signal HUP s5p # container reload
Proxy File Format
# one proxy URL per line
socks5://1.2.3.4:1080
socks5://user:pass@5.6.7.8:1080
http://proxy.example.com:8080
Proxy URLs
socks5://host:port
socks5://user:pass@host:port
socks4://host:port
http://host:port
http://user:pass@host:port
Control API
s5p --api 127.0.0.1:1081 -c config/s5p.yaml # enable API
curl -s http://127.0.0.1:1081/status | jq . # runtime status
curl -s http://127.0.0.1:1081/metrics | jq . # full metrics
curl -s http://127.0.0.1:1081/pool | jq . # all proxies
curl -s http://127.0.0.1:1081/pool/alive | jq . # alive only
curl -s http://127.0.0.1:1081/config | jq . # current config
curl -s -X POST http://127.0.0.1:1081/reload # reload config
curl -s -X POST http://127.0.0.1:1081/pool/test # health test now
Testing
# Check exit IP
curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip
# Tor check
curl -x socks5h://127.0.0.1:1080 https://check.torproject.org/api/ip
# Verbose curl
curl -v -x socks5h://127.0.0.1:1080 https://example.com
# With timeout
curl --max-time 30 -x socks5h://127.0.0.1:1080 https://example.com
Profiling
# Enable in compose.yaml: uncomment the command line
python -m pstats s5p.prof # interactive stats viewer
python -m pstats ~/.cache/s5p/s5p.prof # container profile output
Metrics Log
metrics: conn=142 ok=98 fail=44 retries=88 active=3 in=1.2M out=4.5M up=0h05m12s pool=42/65
Troubleshooting
| Symptom | Check |
|---|---|
| Connection refused | Is Tor running? ss -tlnp | grep 9050 |
| Timeout | Increase -t, check proxy reachability |
| DNS leak | Use socks5h:// (not socks5://) in client |
| Auth failed | Verify credentials in proxy URL |
| Port in use | fuser -k 1080/tcp to free the port |
| Proxy keeps failing | Backoff penalizes for 60s; check pool= in metrics |
| "static chain unreachable" | Tor/upstream hop is down; pool tests skipped |
| Slow startup | Normal on cold start; warm restarts serve instantly from state |