Module config 

Configuration management for vanguards-rs.

This module provides configuration parsing from TOML files, command-line arguments, and environment variables. Configuration is applied in order: defaults → config file → command-line arguments, with later sources overriding earlier ones.

Overview

The configuration system supports multiple sources with clear precedence rules, allowing flexible deployment scenarios from simple defaults to complex multi-source configurations.

Configuration Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                        Configuration Loading Flow                           │
└─────────────────────────────────────────────────────────────────────────────┘

    ┌─────────────────┐
    │ Config::default │ ◄── Start with sensible defaults
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ Config file     │ ◄───│ vanguards.conf  │  (TOML format)
    │ exists?         │     │ or --config     │
    └────────┬────────┘     └─────────────────┘
             │
        Yes  │  No
      ┌──────┴───────┐
      ▼              │
┌─────────────┐      │
│ Merge file  │      │
│ settings    │      │
└──────┬──────┘      │
       │             │
       └──────┬──────┘
              │
              ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ Apply CLI args  │ ◄───│ --control-port  │
    │ (override)      │     │ --state, etc.   │
    └────────┬────────┘     └─────────────────┘
             │
             ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ Apply env vars  │ ◄───│ VANGUARDS_STATE │
    │ (if not set)    │     │ VANGUARDS_CONFIG│
    └────────┬────────┘     └─────────────────┘
             │
             ▼
    ┌─────────────────┐
    │ Validate &      │
    │ resolve hosts   │
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │ Final Config    │ ◄── Ready to use
    └─────────────────┘

Configuration Sources

Source	Priority	Description
Defaults	Lowest	Built-in sensible defaults
Config File	Medium	TOML file (--config or VANGUARDS_CONFIG)
Environment	High	VANGUARDS_STATE, VANGUARDS_CONFIG
CLI Arguments	Highest	Command-line flags override all

Example Configuration File

# Connection settings
control_ip = "127.0.0.1"
control_port = 9051
# control_socket = "/run/tor/control"  # Alternative: Unix socket
# control_pass = "my_password"         # If using password auth

# File paths
state_file = "vanguards.state"

# Logging
loglevel = "notice"  # debug, info, notice, warn, error
# logfile = "/var/log/vanguards.log"  # Optional: log to file
# logfile = ":syslog:"                 # Optional: log to syslog

# Component toggles
enable_vanguards = true
enable_bandguards = true
enable_rendguard = true
enable_logguard = true
enable_cbtverify = false
enable_pathverify = false

# Operational settings
close_circuits = true
one_shot_vanguards = false
# retry_limit = 10  # Optional: limit reconnection attempts

[vanguards]
num_layer1_guards = 2   # 0 = use Tor default
num_layer2_guards = 4
num_layer3_guards = 8
min_layer2_lifetime_hours = 24
max_layer2_lifetime_hours = 1080  # 45 days
min_layer3_lifetime_hours = 1
max_layer3_lifetime_hours = 48

[bandguards]
circ_max_megabytes = 0           # 0 = disabled
circ_max_age_hours = 24
circ_max_hsdesc_kilobytes = 30
circ_max_serv_intro_kilobytes = 0
circ_max_disconnected_secs = 30
conn_max_disconnected_secs = 15

[rendguard]
use_global_start_count = 1000
use_scale_at_count = 20000
use_relay_start_count = 100
use_max_use_to_bw_ratio = 5.0
use_max_consensus_weight_churn = 1.0
close_circuits_on_overuse = true

[logguard]
protocol_warns = true
dump_limit = 25
dump_level = "notice"

What This Module Does NOT Do

• Runtime reconfiguration: Config is loaded once at startup
• Config file watching: Changes require restart
• Encrypted config files: Passwords are stored in plaintext

See Also

• LogLevel for logging configuration
• VanguardsConfig for vanguard-specific settings
• BandguardsConfig for bandwidth monitoring settings
• RendguardConfig for rendezvous point monitoring settings
• LogguardConfig for log monitoring settings
• CliArgs for command-line argument parsing

Structs

BandguardsConfig

Bandwidth monitoring configuration options.

CliArgs

Command-line arguments for vanguards-rs.

Config

Main configuration struct for vanguards-rs.

LogguardConfig

Log monitoring configuration options.

RendguardConfig

Rendezvous point monitoring configuration options.

VanguardsConfig

Vanguard-specific configuration options.

Enums

LogLevel

Log level for vanguards-rs output.

Functions

load_config

Load configuration from file and CLI arguments.