username/s5p
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document Tor control port integration

Browse Source 
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>
This commit is contained in:
user
2026-02-16 20:09:51 +01:00
parent f0281c4069
commit d2df32fdab
5 changed files with 86 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/USAGE.md
View File

@@ -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