Skip to content

CONFIG.md

Latest commit

 

History

History
310 lines (233 loc) · 9.41 KB

CONFIG.md

File metadata and controls

310 lines (233 loc) · 9.41 KB
Raw

socks2proxy configuration reference

This document describes all supported configuration keys for socks2proxy. It reflects current runtime and --check validation behavior.

Full example

listen: ":41080"

allowed_client_addresses:
  - "172.31.11.0/24"
  - "127.0.0.1/32"

tls:
  insecure_skip_verify: false
  min_version: "1.2"

routing:
  default:
    method: "reject"
    source_ip: "127.0.0.1"

  rules:
    - dst_ports: [80]
      dst_addresses: ["0.0.0.0/0", "::/0"]
      method: "http"
      upstream: "http://proxy.example.com:3128"
      source_ip: "127.0.0.1"

    - dst_ports: [443]
      dst_addresses: ["0.0.0.0/0", "::/0"]
      method: "connect"
      upstream: "http://proxy.example.com:3128"
      source_ip: "127.0.0.1"

    - dst_ports: [22]
      dst_addresses: ["0.0.0.0/0", "::/0"]
      method: "direct"
      source_ip: "127.0.0.1"

    - dst_ports: [25]
      dst_addresses: ["0.0.0.0/0", "::/0"]
      method: "reject"

timeouts:
  connect: "10s"
  idle: "300s"

http:
  max_header_bytes: 65536

logging:
  level: "info"

Top-level keys

Key Type Required Description
listen string yes TCP listen address for SOCKS5 server.
allowed_client_addresses list[string] yes Client source address allowlist (single IP, CIDR, or IP range).
tls object no Global TLS defaults for HTTPS upstream proxy connections.
routing object yes Routing rules by destination ports/addresses plus optional default rule.
timeouts object yes Connect and idle timeout values.
http object yes HTTP parser/server limits.
logging object yes Logging settings.

listen

  • Format: Go TCP address format, for example:
    • ":41080" (all interfaces, port 41080)
    • "127.0.0.1:41080"
    • "[::1]:41080"
  • Validation:
    • must resolve as TCP listen address
    • port must be in range 1..65535

allowed_client_addresses

List of source client address selectors allowed to connect to the SOCKS5 listener.

Accepted forms (scalar or list, CSV supported):

  • single IP (for example 10.0.0.10)
  • CIDR (for example 10.0.0.0/24)
  • IP range (for example 10.0.0.10-10.0.0.50)

Notes:

  • Each entry must be a valid address selector.
  • If a client IP does not match any selector, connection is denied.

routing

Routing has two parts:

  • routing.rules: first-match rules by destination selectors (dst_port(s), dst_address(es), or both)
  • routing.default: fallback when no rule matches

routing.default

routing.default is optional.

If routing.default is not specified, an implicit fallback is used:

routing:
  default:
    method: "reject"

That means unmatched ports are rejected unless you set another default.

routing.rules[] fields

Field Type Required Description
dst_ports / dst_port list/scalar conditional Destination TCP port selector(s); accepts list or comma-separated/range scalar. If omitted, any destination port matches.
dst_addresses / dst_address list/scalar conditional Destination address selector(s); accepts list or comma-separated scalar. If omitted, any destination address matches.
method string yes One of http, connect, direct, reject.
upstream string conditional Required for http and connect; forbidden for direct and reject.
source_ip string optional Local source IP used to bind outbound sockets for this rule before dialing target/upstream.
tls object optional Optional HTTPS upstream TLS settings.

routing.default fields

Field Type Required Description
method string yes One of http, connect, direct, reject.
upstream string conditional Required for http and connect; forbidden for direct and reject.
source_ip string optional Local source IP used to bind outbound sockets when the default rule dials target/upstream.
tls object optional Optional HTTPS upstream TLS settings.

Methods

  • http

    • Reads HTTP/1.x request from client.
    • Sends absolute-form request to upstream proxy.

  • connect

    • Sends upstream CONNECT host:port.
    • On success, tunnels bytes bidirectionally.

  • direct

    • Opens direct TCP connection to target host:port.
    • Does not use upstream proxy.

  • reject

    • Rejects request immediately.

upstream format

  • Preferred format: URL with scheme:
    • http://proxy.example.com:3128
    • https://proxy.example.com:8443
  • Validation:
    • URL scheme must be http or https
    • host must be non-empty
    • port must be numeric and in 1..65535

tls options (optional)

tls may be defined only when upstream uses https://.

Key Type Default Description
insecure_skip_verify bool false Disables certificate chain and hostname verification (not recommended).
ca_cert_file string unset Path to PEM certificate bundle used as root CA store for this upstream.
min_version string 1.2 Minimum TLS version for HTTPS upstream handshake (1.2 or 1.3).

Behavior:

  • Default (no tls block): verify certificate and hostname using system CA trust store.
  • With ca_cert_file: use provided PEM bundle as root CAs for this upstream.
  • min_version controls minimum TLS version for HTTPS upstream (1.2 or 1.3).
  • tls options with http:// upstream are invalid.

Top-level tls defaults

You can define a top-level tls block to set defaults for HTTPS upstream proxy connections:

tls:
  insecure_skip_verify: false
  min_version: "1.2"

Resolution order:

  1. Per-rule/default tls block, if present.
  2. Top-level tls block, if present.
  3. Built-in defaults (insecure_skip_verify: false, system trust store, min_version: "1.2").

Important:

  • Per-rule/default tls fully overrides top-level tls (it is not field-wise merged).
  • Top-level tls is ignored for non-HTTPS upstream URLs.

Rule matching order

  1. First routing.rules match in list order (port + address match)
  2. routing.default fallback
  3. If no routing.default configured, implicit reject

Selector semantics:

  • If a rule defines both port and address selectors, both must match.
  • If a rule omits dst_port(s), port matching is wildcard (any).
  • If a rule omits dst_address(es), address matching is wildcard (any).
  • A rule must define at least one selector type (port and/or address).

source_ip semantics:

  • If set, socks2proxy binds the outbound socket to this local IP before dialing.
  • Applies to direct, http, and connect methods.
  • Works for both routing.rules[] and routing.default.

Rule validation

  • each expanded port value from dst_port(s) must be in 1..65535.
  • each dst_addresses entry must be one of:
    • single IP (for example 10.0.0.10)
    • CIDR (for example 10.0.0.0/24)
    • IP range (for example 10.0.0.10-10.0.0.50)
  • method must be one of http, connect, direct, reject.
  • source_ip, when set, must be a valid literal IPv4 or IPv6 address.

timeouts

Duration values use Go duration syntax (10s, 300ms, 2m, etc.).

Key Type Required Description
connect duration string yes Dial timeout for upstream/direct target connection.
idle duration string yes Connection idle timeout for client/upstream/target sockets.

Validation:

  • all timeout values must be greater than 0.

http

Key Type Required Description
max_header_bytes int yes Max header read buffer size for client HTTP request parsing.

Validation:

  • must be greater than 0.

logging

Key Type Required Allowed values Description
level string yes debug, info, warn, error Log verbosity threshold.

Validation:

  • unknown values cause startup/check failure.

Effective behavior and failure mode

  • Validation runs when loading config for normal runtime.
  • Validation also runs for --check mode.
  • If CLI overrides are used (for example --log-level), config is re-validated.
  • Any invalid value causes immediate exit with an error.

Minimal examples

Default reject (implicit)

routing:
  rules:
    - dst_ports: [443]
      dst_addresses: ["0.0.0.0/0", "::/0"]
      method: "connect"
      upstream: "http://proxy.example.com:3128"

Unmatched ports are rejected because routing.default is omitted.

Default direct

routing:
  default:
    method: "direct"
  rules:
    - dst_ports: [443]
      dst_addresses: ["0.0.0.0/0", "::/0"]
      method: "connect"
      upstream: "http://proxy.example.com:3128"

Default connect via upstream

routing:
  default:
    method: "connect"
    upstream: "https://proxy.example.com:8443"
  rules:
    - dst_ports: [80]
      dst_addresses: ["0.0.0.0/0", "::/0"]
      method: "http"
      upstream: "https://proxy.example.com:8443"

Common mistakes (and why they fail)

  • method: "direct" with upstream set -> invalid (upstream forbidden).
  • method: "reject" with upstream set -> invalid (upstream forbidden).
  • method: "http" or "connect" without upstream -> invalid (upstream required).
  • missing both destination selector types in a rule -> invalid (at least one of port/address is required).
  • invalid source_ip value (not a literal IP) -> invalid.
  • logging.level: "verbose" -> invalid (not in allowed set).
  • listen: ":0" -> invalid (port out of allowed range).