rust-socksd/doc/usage.md

CLI & Usage Guide

This guide details the command-line options available for rust-socksd and instructions on configuring proxy client applications.

---

Command Line Interface (CLI)

Main Server Entry

Run rust-socksd using standard flags to start the daemon.

rust-socksd [OPTIONS] [SUBCOMMAND]

Global Options

• -c, --config <FILE>: Path to the YAML configuration file (default: config.yml).
• -g, --generate-config <FILE>: Generates a default YAML configuration file and exits (conflicts with --config).
• -v, --verbose: Enables verbose logging (can be specified multiple times for deeper trace levels).
• -q, --quiet: Suppresses all standard output logs except errors.
• -b, --bind <ADDRESS>: Binds the proxy listeners to the specified IP address.
• -p, --http-port <PORT>: Port for the HTTP proxy.
• -s, --socks5-port <PORT>: Port for the SOCKS5 proxy.
• -l, --loglevel <LEVEL>: Logging filter level: trace, debug, info, warn, error.
• --admin-port <PORT>: Port for the administrative API listener.
• --admin-enabled: Enables the admin server listener at boot time.
• -h, --help: Prints CLI help and usage details.
• -V, --version: Prints application version information.

Subcommands

• validate: Validates the syntax of configuration files.
• user: Manages credentials database for Simple authentication backend.

---

Configuration Validation Subcommand

Validate your main configuration or user configuration syntax before launching the server:

rust-socksd validate [OPTIONS]

Subcommand Options

• -c, --config <FILE>: Main config file to validate (default: config.yml).
• --user-config <FILE>: Simple backend user file to validate (optional).

Examples

# Validate default config.yml
rust-socksd validate

# Validate specific configurations
rust-socksd validate --config /etc/socksd/config.yml --user-config /etc/socksd/users.yml

---

User Management Subcommand

Manages user credentials for the simple authenticator backend file. See Authentication Backends Guide for details.

rust-socksd user [OPTIONS] <SUBCOMMAND> [SUBCOMMAND_ARGS]

---

Client Proxy Usage

Once rust-socksd is running, configure client applications to route traffic through it.

SOCKS5 Client Setup

The SOCKS5 proxy implements the standard SOCKS5 protocol (RFC 1928), supporting username/password auth (RFC 1929).

• Protocol: SOCKS5 (or SOCKS5h to resolve DNS names remotely on the proxy side)
• Default Port: 1080

curl Example (Unauthenticated)

curl --socks5-hostname localhost:1080 https://httpbin.org/ip

curl Example (With Credentials)

curl --socks5-hostname localhost:1080 --user "username:password" https://httpbin.org/ip

---

HTTP Client Setup

The HTTP proxy supports HTTP/HTTPS tunnel connections via the CONNECT method and regular proxy requests, optionally requiring Basic Authentication.

• Protocol: HTTP / HTTPS
• Default Port: 8080

curl Example (Unauthenticated)

curl --proxy localhost:8080 https://httpbin.org/ip

curl Example (With Credentials)

curl --proxy localhost:8080 --proxy-user "username:password" https://httpbin.org/ip