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>
158 lines
4.3 KiB
Markdown
158 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cp config/example.yaml config/s5p.yaml # create live config (gitignored)
|
|
```
|
|
|
|
## Performance Tuning (config)
|
|
|
|
```yaml
|
|
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)
|
|
|
|
```yaml
|
|
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)
|
|
|
|
```yaml
|
|
tor:
|
|
control_port: 9051
|
|
password: "" # or cookie_file: /path/to/cookie
|
|
newnym_interval: 60 # auto-rotate every 60s (0 = manual)
|
|
```
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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 |
|