s5p -- Usage

Basic Usage

# Direct proxy (no chain, just a SOCKS5 server)
s5p

# Through Tor
s5p -C socks5://127.0.0.1:9050

# Through Tor + another proxy
s5p -C socks5://127.0.0.1:9050,socks5://proxy:1080

# Custom listen address
s5p -l 0.0.0.0:9999 -C socks5://127.0.0.1:9050

# From config file
s5p -c config/s5p.yaml

# With proxy source API (rotate exit proxy per-connection)
s5p -C socks5://127.0.0.1:9050 -S http://10.200.1.250:8081/proxies

# Debug mode
s5p -v -C socks5://127.0.0.1:9050

Configuration

Copy the tracked example to create your live config:

cp config/example.yaml config/s5p.yaml

File	Tracked	Purpose
`config/example.yaml`	yes	Template with placeholder addresses
`config/s5p.yaml`	no (gitignored)	Live config with real proxy addresses

listen: 127.0.0.1:1080
timeout: 10
log_level: info

chain:
  - socks5://127.0.0.1:9050

proxy_source:
  url: http://10.200.1.250:8081/proxies
  proto: socks5       # optional: filter by protocol
  country: US         # optional: filter by country
  limit: 1000         # max proxies to fetch
  refresh: 300        # cache refresh interval (seconds)

Proxy URL Format

protocol://[username:password@]host[:port]

Protocol	Default Port	Auth Support
socks5	1080	username/password
socks4	1080	none
http	8080	Basic

Container

make build   # build image
make up      # start container (detached)
make logs    # follow logs
make down    # stop and remove container

Source (./src) and config (./config/s5p.yaml) are mounted read-only into the container. Edit locally, restart to pick up changes.

Proxy Source

Appends a random proxy from an HTTP API after the static chain on each connection. Proxies are cached and refreshed at a configurable interval.

proxy_source:
  url: http://10.200.1.250:8081/proxies
  proto: socks5       # optional: only fetch this protocol
  country: US         # optional: only fetch this country
  limit: 1000         # max proxies to fetch from API
  refresh: 300        # re-fetch every 300 seconds

CLI shorthand (uses defaults for limit/refresh):

s5p -C socks5://127.0.0.1:9050 -S http://10.200.1.250:8081/proxies

The API must return JSON: {"proxies": [{"proto": "socks5", "proxy": "host:port"}, ...]}. Entries with null proto are skipped.

Profiling

# Run with cProfile enabled
s5p --cprofile -c config/s5p.yaml

# Custom output file
s5p --cprofile output.prof -c config/s5p.yaml

# Analyze after stopping
python -m pstats s5p.prof

Testing the Proxy

# Check exit IP via Tor
curl --proxy socks5h://127.0.0.1:1080 https://check.torproject.org/api/ip

# Fetch a page
curl --proxy socks5h://127.0.0.1:1080 https://example.com

# Use with Firefox: set SOCKS5 proxy to 127.0.0.1:1080, enable remote DNS

Note: use socks5h:// (not socks5://) with curl to send DNS through the proxy.

Chain Order

Hops are traversed left-to-right:

-C hop1,hop2,hop3

Client -> s5p -> hop1 -> hop2 -> hop3 -> Destination

Each hop only sees its immediate neighbors.

3.2 KiB Raw Blame History