mirror of
https://github.com/quintusl/rust-socksd.git
synced 2026-11-13 16:17:46 +00:00
110 lines
3.3 KiB
Markdown
110 lines
3.3 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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](authentication.md) for details.
|
|
|
|
```bash
|
|
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)
|
|
```bash
|
|
curl --socks5-hostname localhost:1080 https://httpbin.org/ip
|
|
```
|
|
|
|
#### curl Example (With Credentials)
|
|
```bash
|
|
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)
|
|
```bash
|
|
curl --proxy localhost:8080 https://httpbin.org/ip
|
|
```
|
|
|
|
#### curl Example (With Credentials)
|
|
```bash
|
|
curl --proxy localhost:8080 --proxy-user "username:password" https://httpbin.org/ip
|
|
```
|