Overview UltraBalancer supports multiple configuration methods to fit different deployment scenarios. Choose the approach that works best for your infrastructure.
CLI Arguments Quick setup with command-line flags
YAML Config Human-readable configuration files
TOML Config Type-safe structured configuration
Environment Variables 12-factor app compliance
Configuration Methods 1. Command-Line Arguments Perfect for quick testing and simple deployments:
ultrabalancer \ --port 8080 \ --algorithm round-robin \ --backend server1:8080 \ --backend server2:8080 \ --health-check-interval 5000
CLI arguments take precedence over config files. Use them to override specific settings in production.
2. YAML Configuration File Recommended for production deployments:
listen_address : "0.0.0.0" listen_port : 8080 algorithm : "round-robin" backends : - host : "192.168.1.10" port : 8080 weight : 100 - host : "192.168.1.11" port : 8080 weight : 100 health_check : enabled : true interval_ms : 5000 max_failures : 3 timeout : connect_ms : 5000 request_ms : 30000
ultrabalancer -c config.yaml
3. TOML Configuration File Alternative structured format:
listen_address = "0.0.0.0" listen_port = 8080 algorithm = "round-robin" [[ backends ]] host = "192.168.1.10" port = 8080 weight = 100 [[ backends ]] host = "192.168.1.11" port = 8080 weight = 100 [ health_check ] enabled = true interval_ms = 5000 max_failures = 3 [ timeout ] connect_ms = 5000 request_ms = 30000
ultrabalancer -c config.toml
4. Environment Variables 12-factor app compliant configuration:
# Basic settings export ULTRA_LISTEN_ADDRESS = "0.0.0.0" export ULTRA_LISTEN_PORT = "8080" export ULTRA_ALGORITHM = "round-robin" # Backends (comma-separated) export ULTRA_BACKENDS = "server1:8080,server2:8080,server3:8080" # Health checks export ULTRA_HEALTH_CHECK_ENABLED = "true" export ULTRA_HEALTH_CHECK_INTERVAL_MS = "5000" export ULTRA_HEALTH_CHECK_MAX_FAILURES = "3" # Timeouts export ULTRA_TIMEOUT_CONNECT_MS = "5000" export ULTRA_TIMEOUT_REQUEST_MS = "30000" ultrabalancer
Configuration Hierarchy Configuration values are resolved in the following order (highest to lowest priority):
Command-Line Arguments
Highest priority - always override other sources ultrabalancer -c config.yaml --port 9090 # Port 9090 wins
Environment Variables
Second priority - useful for containerized deployments export ULTRA_PORT = 9090 ultrabalancer -c config.yaml # Env var wins over file
Configuration File
Third priority - main configuration source
Default Values
Lowest priority - sensible defaults const DEFAULT_PORT : u16 = 8080 ;
Configuration Structure Top-Level Options IP address to bind to. Use 0.0.0.0 for all interfaces, 127.0.0.1 for localhost only.
Port number to listen on (1-65535).
algorithm
string
default: "round-robin"
Load balancing algorithm: round-robin, least-connections, ip-hash, random, weighted.
Number of worker threads. Set to auto to match CPU cores.
Maximum concurrent connections.
Backend Configuration Array of backend servers.
Backend hostname or IP address.
Backend weight for weighted algorithms (1-1000).
backends[].max_connections
Maximum connections per backend.
Health Check Configuration Enable/disable health checking.
Health check interval in milliseconds.
Health check timeout in milliseconds.
health_check.max_failures
Number of failures before marking backend unhealthy.
HTTP path for health checks.
Timeout Configuration Connection timeout in milliseconds.
Request timeout in milliseconds.
Idle connection timeout in milliseconds.
Response Caching Enable response caching for GET/HEAD requests.
Maximum number of cached responses.
cache.default_ttl_seconds
Default TTL when no Cache-Control header present.
Compression Enable response compression.
Compression algorithm: gzip, brotli, zstd.
Minimum response size to compress (bytes).
Rate Limiting rate_limit.requests_per_second
Global rate limit (requests per second).
Per-IP rate limit (requests per second).
Burst allowance above rate limit.
IP Filtering Array of allowed IP addresses/CIDR ranges. If set, only these IPs are allowed.
Array of blocked IP addresses/CIDR ranges.
Sticky Sessions Enable cookie-based sticky sessions.
sticky_sessions.cookie_name
string
default: "ULTRABALANCER_SESSION"
Name of the session cookie.
sticky_sessions.ttl_seconds
Session TTL in seconds.
Retry Configuration Enable retry on backend failures.
Initial backoff delay in milliseconds.
Maximum backoff delay in milliseconds.
Access Logging Log format: combined, json.
TLS Configuration Path to TLS certificate file (PEM format).
Path to TLS private key file (PEM format).
Complete Configuration Example config.yaml
config.toml
Environment Variables
# UltraBalancer v3.0 Production Configuration # Listener configuration listen_address : "0.0.0.0" listen_port : 443 workers : auto max_connections : 50000 # Load balancing algorithm : "least-connections" # Backend servers backends : - host : "backend1.prod.internal" port : 8080 weight : 100 - host : "backend2.prod.internal" port : 8080 weight : 100 - host : "backend3.prod.internal" port : 8080 weight : 100 # Health checks health_check : enabled : true interval_ms : 3000 timeout_ms : 1500 max_failures : 3 path : "/health" # Response caching cache : enabled : true max_size : 10000 default_ttl_seconds : 300 # Compression compression : enabled : true algorithm : "gzip" # gzip, brotli, zstd min_size : 1024 # Rate limiting rate_limit : enabled : true requests_per_second : 10000 per_ip_rps : 100 burst : 50 # IP filtering ip_filter : blacklist : - "10.0.0.0/8" # Block internal probes # Sticky sessions sticky_sessions : enabled : true cookie_name : "ULTRABALANCER_SESSION" ttl_seconds : 3600 # Retry with backoff retry : enabled : true max_attempts : 3 backoff_ms : 100 max_backoff_ms : 5000 # Access logging access_log : enabled : true path : "/var/log/ultrabalancer/access.log" format : "json" # TLS termination tls : enabled : true cert_path : "/etc/ultrabalancer/cert.pem" key_path : "/etc/ultrabalancer/key.pem" # Graceful shutdown shutdown : timeout_seconds : 30 drain_connections : true
Validation Validate your configuration before deployment:
Validate Command
Output
Invalid Config
Error Output
ultrabalancer validate -c config.yaml
Configuration Templates Development Template listen_address : "127.0.0.1" listen_port : 8080 algorithm : "round-robin" backends : - host : "localhost" port : 3001 - host : "localhost" port : 3002 health_check : enabled : true interval_ms : 10000 # Less aggressive max_failures : 5 logging : level : "debug" format : "text"
Staging Template listen_address : "0.0.0.0" listen_port : 8080 algorithm : "least-connections" backends : - host : "backend1.staging.internal" port : 8080 - host : "backend2.staging.internal" port : 8080 health_check : enabled : true interval_ms : 5000 max_failures : 3 logging : level : "info" format : "json"
Production Template listen_address : "0.0.0.0" listen_port : 443 algorithm : "least-connections" workers : auto max_connections : 50000 backends : - host : "backend1.prod.internal" port : 8080 weight : 100 - host : "backend2.prod.internal" port : 8080 weight : 100 health_check : enabled : true interval_ms : 3000 max_failures : 3 cache : enabled : true max_size : 10000 compression : enabled : true algorithm : "gzip" rate_limit : enabled : true requests_per_second : 10000 per_ip_rps : 100 retry : enabled : true max_attempts : 3 access_log : enabled : true path : "/var/log/ultrabalancer/access.log" format : "json" tls : enabled : true cert_path : "/etc/ultrabalancer/cert.pem" key_path : "/etc/ultrabalancer/key.pem" shutdown : timeout_seconds : 30 drain_connections : true
Dynamic Configuration Reload UltraBalancer supports hot-reloading configuration without downtime:
# Send SIGHUP signal to reload config kill -HUP $( pidof ultrabalancer ) # Or use systemd systemctl reload ultrabalancer
Configuration reload will:
Update backend list (add/remove/modify backends)
Change algorithm settings
Adjust health check parameters
NOT reloaded:
Listen address/port (requires restart)
Worker count (requires restart)
TLS certificates (requires restart)
Best Practices Configuration Tips
Use config files in production - More maintainable than CLI argsVersion control your configs - Track changes over timeValidate before deployment - Use validate commandUse environment variables for secrets - Don’t commit credentialsStart with templates - Modify for your needsDocument custom settings - Add comments explaining why Security Considerations # DON'T: Hard-code secrets tls : key_password : "mysecretpassword" # Bad! # DO: Use environment variables tls : key_password : "${TLS_KEY_PASSWORD}" # Good!
# Set secrets via environment export TLS_KEY_PASSWORD = "mysecretpassword" ultrabalancer -c config.yaml
