From d2df32fdab908f9569c09da60739cd42fca9d326 Mon Sep 17 00:00:00 2001 From: user Date: Mon, 16 Feb 2026 20:09:51 +0100 Subject: [PATCH] docs: document Tor control port integration 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 --- README.md | 7 +++++- ROADMAP.md | 2 +- TASKS.md | 3 ++- docs/CHEATSHEET.md | 14 +++++++++++ docs/USAGE.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 86 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d5ecbe0..58c0193 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ through configurable chains of SOCKS4, SOCKS5, and HTTP CONNECT proxies. - Supported hop protocols: SOCKS5, SOCKS4/4a, HTTP CONNECT - Per-hop authentication (username/password) - DNS leak prevention (domain names forwarded to proxies, never resolved locally) -- Tor integration (Tor is just another SOCKS5 hop) +- Tor integration (SOCKS5 hop + control port NEWNYM for circuit rotation) - Managed proxy pool: multiple sources (API + file), health-tested, weighted selection - Per-proxy failure backoff (60s cooldown), stale proxy expiry, chain pre-flight - Fast warm start (seconds on restart vs minutes on cold start) @@ -76,6 +76,11 @@ api_listen: 127.0.0.1:1081 # control API (disabled by default) chain: - socks5://127.0.0.1:9050 # Tor +tor: + control_port: 9051 # Tor control port (NEWNYM) + password: "" # or cookie_file for auth + newnym_interval: 0 # periodic circuit rotation (0 = manual) + proxy_pool: sources: - url: http://10.200.1.250:8081/proxies diff --git a/ROADMAP.md b/ROADMAP.md index ac5f329..6ec6df6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -24,7 +24,7 @@ - [x] Built-in control API (runtime metrics, pool state, config reload) - [ ] SOCKS5 server authentication (username/password) -- [ ] Tor control port integration (circuit renewal via NEWNYM) +- [x] Tor control port integration (circuit renewal via NEWNYM) - [ ] Metrics (connections/sec, bytes relayed, hop latency) ## v0.3.0 diff --git a/TASKS.md b/TASKS.md index 3bb79c2..a45ec1f 100644 --- a/TASKS.md +++ b/TASKS.md @@ -44,7 +44,8 @@ - [x] Use k8s-file logging driver with rotation - [x] Built-in control API (`api.py`, `--api`, `api_listen`) +- [x] Tor control port integration (NEWNYM signaling, periodic rotation) + ## Next - [ ] Integration tests with mock proxy server - [ ] SOCKS5 server-side authentication -- [ ] Tor control port integration diff --git a/docs/CHEATSHEET.md b/docs/CHEATSHEET.md index bff5a6d..c338fcc 100644 --- a/docs/CHEATSHEET.md +++ b/docs/CHEATSHEET.md @@ -59,6 +59,20 @@ proxy_pool: 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 diff --git a/docs/USAGE.md b/docs/USAGE.md index 3a05155..eea824e 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -281,6 +281,69 @@ curl -s -X POST http://127.0.0.1:1081/pool/refresh | jq . Settings that require a restart: `listen`, `chain`, `pool_size`, `pool_max_idle`, `api_listen`. +## Tor Control Port + +Optional integration with Tor's control protocol for circuit management. +When enabled, s5p connects to Tor's control port and can send NEWNYM signals +to request new circuits (new exit node) on demand or on a timer. + +### Configuration + +```yaml +tor: + control_host: 127.0.0.1 # Tor control address + control_port: 9051 # Tor control port + password: "" # HashedControlPassword (torrc) + cookie_file: "" # CookieAuthentication file path + newnym_interval: 0 # periodic NEWNYM in seconds (0 = manual only) +``` + +Requires Tor's `ControlPort` enabled in `torrc`: + +``` +ControlPort 9051 +HashedControlPassword 16:... # or CookieAuthentication 1 +``` + +### Authentication modes + +| Mode | Config | torrc | +|------|--------|-------| +| Password | `password: "secret"` | `HashedControlPassword 16:...` | +| Cookie | `cookie_file: /var/run/tor/control.authcookie` | `CookieAuthentication 1` | +| None | (leave both empty) | No auth configured | + +### Rate limiting + +Tor enforces a minimum 10-second interval between NEWNYM signals. s5p +applies the same client-side rate limit to avoid unnecessary rejections. + +### API endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/tor` | Controller status (enabled, connected, last NEWNYM) | +| `POST` | `/tor/newnym` | Trigger NEWNYM signal (new circuit) | + +```bash +# Check tor controller status +curl -s http://127.0.0.1:1081/tor | jq . + +# Request new circuit +curl -s -X POST http://127.0.0.1:1081/tor/newnym | jq . +``` + +### Periodic NEWNYM + +Set `newnym_interval` to automatically rotate circuits: + +```yaml +tor: + newnym_interval: 60 # new circuit every 60 seconds +``` + +Values below 10 are clamped to Tor's minimum interval. + ## Connection Retry When a proxy pool is active, s5p retries failed connections with a different