rust-socksd/doc/admin_api.md

Admin API Reference Guide

The administrative server allows monitoring the proxy server status, validating and reloading configurations at runtime, and inspecting execution metrics.

Configuration

To enable the admin server, append an admin section to your main config.yml configuration file:

admin:
  # Enable/disable the admin API listener (default: false)
  enabled: true
  
  # Address to bind the listener to (default: 127.0.0.1)
  bind_address: "127.0.0.1"
  
  # Port to listen on (default: 8081)
  port: 8081
  
  # Static pre-shared token (Optional)
  # If configured, clients can bypass login and authenticate directly
  token: "my-secure-static-bypass-token"
  
  # List of usernames permitted to log in and receive transient tokens
  admin_users:
    - "admin"
    
  # Lifespan of transient dynamic tokens in seconds (default: 3600)
  token_ttl: 3600

---

Authentication Schemes

The Admin API supports two primary authentication modes for all administrative endpoints (except /health):

1. Static Token Authentication

Use the token configured via admin.token as a direct Bearer header:

Authorization: Bearer my-secure-static-bypass-token

2. Dynamic Token Authentication

If a static token is not preferred, exchange credentials for a temporary session token using Basic Authentication:

1. Call /login using the credentials of a user defined in your active authenticator backend (e.g. users.yml, LDAP, Database) who is listed in the config's admin.admin_users.
2. Extract the returned token from the response.
3. Attach it to administrative calls:

   Authorization: Bearer <returned-token>
   

---

Endpoints

1. Liveness & Health Check

Checks if the admin server is up. This endpoint is public and does not require authentication headers.

• Path: GET /health
• Response Status: 200 OK
• Response Body:

  {
    "status": "ok"
  }
  

• Example Request:

  curl http://127.0.0.1:8081/health
  

---

2. User Authentication / Login

Exchanges user credentials for a dynamic bearer token.

• Path: POST /login
• Authentication: HTTP Basic Auth (username/password)
• Response Status: 200 OK on success, 401 Unauthorized on bad credentials, 403 Forbidden if the user is authenticated but not configured under admin_users.
• Response Body:

  {
    "token": "QWVyV1p2T2x3NmRl...",
    "expires_in": 3600
  }
  

• Example Request:

  curl -X POST -u "admin:secretpassword" http://127.0.0.1:8081/login
  

---

3. Metrics Export

Provides execution counters and gauges in Prometheus-compatible exposition format.

• Path: GET /metrics
• Authentication: Bearer token
• Response Status: 200 OK
• Response Body:

  # HELP rust_socksd_active_connections Number of active connections
  # TYPE rust_socksd_active_connections gauge
  rust_socksd_active_connections 2
  # HELP rust_socksd_total_connections Total connections accepted
  # TYPE rust_socksd_total_connections counter
  rust_socksd_total_connections 14
  # HELP rust_socksd_bytes_tx Total bytes transmitted (client to target)
  # TYPE rust_socksd_bytes_tx counter
  rust_socksd_bytes_tx 819240
  # HELP rust_socksd_bytes_rx Total bytes received (target to client)
  # TYPE rust_socksd_bytes_rx counter
  rust_socksd_bytes_rx 1902488
  # HELP rust_socksd_auth_failures Total authentication failures
  # TYPE rust_socksd_auth_failures counter
  rust_socksd_auth_failures 1
  

• Example Request:

  curl -H "Authorization: Bearer QWVyV1p2T2x3NmRl..." http://127.0.0.1:8081/metrics
  

---

4. Configuration Inspect

Returns the active configuration schema. Sensitive values (like passwords, keys, and URL credentials) are automatically masked to ******.

• Path: GET /config
• Authentication: Bearer token
• Response Status: 200 OK
• Response Body:

  {
    "server": {
      "bind_address": "127.0.0.1",
      "socks5_port": 1080,
      "http_port": 8080,
      "max_connections": 1000,
      "connection_timeout": 300,
      "buffer_size": 65536
    },
    "auth": {
      "enabled": true,
      "backend": {
        "type": "simple",
        "user_config_file": "config/users.yml"
      }
    },
    ...
  }
  

• Example Request:

  curl -H "Authorization: Bearer QWVyV1p2T2x3NmRl..." http://127.0.0.1:8081/config
  

---

5. Configuration Validation

Validates a potential configuration without applying it.

• Path: POST /config/validate
• Authentication: Bearer token
• Request Body: Configuration YAML string
• Response Status: 200 OK (if valid), 400 Bad Request (if validation rules or parsing failed)
• Response Body (Valid):

  {
    "valid": true
  }
  

• Response Body (Invalid):

  {
    "valid": false,
    "error": "SOCKS5 and HTTP ports cannot be the same"
  }
  

• Example Request:

  curl -H "Authorization: Bearer QWVyV1p2T2x3NmRl..." \
       -H "Content-Type: application/yaml" \
       --data-binary @config.yml \
       http://127.0.0.1:8081/config/validate
  

---

6. Live Configuration Reload

Triggers the server to re-read its main configuration file from disk. Swaps out the routing, rules, and authenticators seamlessly.

• Path: POST /config/reload
• Authentication: Bearer token
• Response Status: 200 OK on success, 400 Bad Request or 500 Internal Error on failure (e.g. invalid syntax, file missing, or unsupported port updates).
• Response Body (Success):

  {
    "status": "reloaded"
  }
  

• Example Request:

  curl -X POST -H "Authorization: Bearer QWVyV1p2T2x3NmRl..." http://127.0.0.1:8081/config/reload
  

Important

To ensure continuous operation, you cannot update bind addresses or ports (for SOCKS5, HTTP, or Admin listeners) at runtime via a reload command. Attempting to change bind targets will abort the reload operation with a validation error, requesting a service restart instead.