Skip to main content

​
Overview

UltraBalancer supports both YAML and TOML configuration formats. Choose the format that best fits your workflow and infrastructure.

YAML Format

Human-readable, widely adopted

TOML Format

Type-safe, explicit syntax

​
Complete Reference

​
Listener Configuration

listen_address: "0.0.0.0"  # Bind address (default: 0.0.0.0)
listen_port: 8080          # Port to listen on (default: 8080)
workers: auto              # Worker threads: auto or number (default: auto)
max_connections: 10000     # Max concurrent connections (default: 10000)
​
listen_address
string
default:"0.0.0.0"
IP address to bind to. Use 0.0.0.0 for all interfaces, 127.0.0.1 for localhost.
​
listen_port
integer
default:"8080"
TCP port to listen on (1-65535).
​
workers
string|integer
default:"auto"
Number of worker threads. Set to "auto" to match CPU cores, or specific number.
​
max_connections
integer
default:"10000"
Maximum number of concurrent connections.

​
Algorithm Configuration

algorithm: "round-robin"  # Load balancing algorithm

# Available algorithms:
# - round-robin: Distribute evenly
# - least-connections: Route to least busy
# - ip-hash: Consistent hashing by client IP
# - random: Random selection
# - weighted: Weight-based distribution
​
algorithm
string
default:"round-robin"
Load balancing algorithm. Options: round-robin, least-connections, ip-hash, random, weighted

​
Backend Configuration

backends:
  - host: "192.168.1.10"
    port: 8080
    weight: 100                # Optional (default: 100)
    max_connections: 1000      # Optional (default: 1000)

  - host: "192.168.1.11"
    port: 8080
    weight: 150
    max_connections: 1500
​
backends
array
required
Array of backend server configurations.
​
backends[].host
string
required
Backend hostname or IP address.
​
backends[].port
integer
required
Backend port number (1-65535).
​
backends[].weight
integer
default:"100"
Weight for weighted algorithms (1-1000).
​
backends[].max_connections
integer
default:"1000"
Maximum connections per backend.

​
Health Check Configuration

health_check:
  enabled: true              # Enable health checking
  interval_ms: 5000          # Check interval (milliseconds)
  timeout_ms: 2000           # Check timeout (milliseconds)
  max_failures: 3            # Failures before marking unhealthy
  path: "/health"            # HTTP path for health checks
  expected_status: 200       # Expected HTTP status code

  # Circuit breaker configuration
  circuit_breaker:
    enabled: true
    failure_threshold: 5     # Failures to open circuit
    success_threshold: 2     # Successes to close circuit
    timeout_seconds: 60      # Seconds before retry
    half_open_requests: 3    # Test requests in half-open state
​
health_check.enabled
boolean
default:"true"
Enable/disable active health checking.
​
health_check.interval_ms
integer
default:"5000"
Interval between health checks in milliseconds.
​
health_check.timeout_ms
integer
default:"2000"
Timeout for each health check in milliseconds.
​
health_check.max_failures
integer
default:"3"
Number of consecutive failures before marking unhealthy.
​
health_check.path
string
default:"/"
HTTP path to check on backends.
​
health_check.expected_status
integer
default:"200"
Expected HTTP status code for healthy response.

​
Timeout Configuration

timeout:
  connect_ms: 5000           # Connection timeout
  request_ms: 30000          # Request timeout
  idle_ms: 60000             # Idle connection timeout
  keepalive_ms: 75000        # TCP keepalive timeout
​
timeout.connect_ms
integer
default:"5000"
Maximum time to establish connection in milliseconds.
​
timeout.request_ms
integer
default:"30000"
Maximum request processing time in milliseconds.
​
timeout.idle_ms
integer
default:"60000"
Idle connection timeout in milliseconds.
​
timeout.keepalive_ms
integer
default:"75000"
TCP keepalive timeout in milliseconds.

​
Logging Configuration

logging:
  level: "info"              # Log level: trace, debug, info, warn, error
  format: "json"             # Format: json, text
  output: "/var/log/ultrabalancer/access.log"  # Log file path
  max_size_mb: 100           # Max log file size before rotation
  max_files: 10              # Number of rotated logs to keep
​
logging.level
string
default:"info"
Logging level: trace, debug, info, warn, error
​
logging.format
string
default:"text"
Log format: json or text
​
logging.output
string
default:"stdout"
Log output: stdout, stderr, or file path

​
Metrics Configuration

metrics:
  enabled: true              # Enable metrics collection
  endpoint: "/metrics"       # JSON metrics endpoint
  prometheus_endpoint: "/prometheus"  # Prometheus endpoint

​
TLS Configuration

tls:
  enabled: true
  cert_path: "/etc/ultrabalancer/cert.pem"
  key_path: "/etc/ultrabalancer/key.pem"
  key_password: "${TLS_KEY_PASSWORD}"  # Use env var
  client_auth: false         # Require client certificates
  min_version: "1.2"         # Minimum TLS version (1.2, 1.3)

​
Complete Example Configurations

​
Production Configuration

# UltraBalancer Production Configuration

# Listener
listen_address: "0.0.0.0"
listen_port: 80
workers: auto
max_connections: 50000

# Load balancing
algorithm: "least-connections"

# Backend servers
backends:
  - host: "backend1.prod.internal"
    port: 8080
    weight: 150
    max_connections: 2000

  - host: "backend2.prod.internal"
    port: 8080
    weight: 150
    max_connections: 2000

  - host: "backend3.prod.internal"
    port: 8080
    weight: 100
    max_connections: 1500

# Health checks
health_check:
  enabled: true
  interval_ms: 3000
  timeout_ms: 1500
  max_failures: 3
  path: "/health"
  expected_status: 200

  circuit_breaker:
    enabled: true
    failure_threshold: 5
    success_threshold: 2
    timeout_seconds: 60
    half_open_requests: 3

# Timeouts
timeout:
  connect_ms: 5000
  request_ms: 30000
  idle_ms: 60000

# Logging
logging:
  level: "info"
  format: "json"
  output: "/var/log/ultrabalancer/access.log"
  max_size_mb: 100
  max_files: 10

# Metrics
metrics:
  enabled: true
  endpoint: "/metrics"
  prometheus_endpoint: "/prometheus"

​
Development Configuration

# Development Configuration

listen_address: "127.0.0.1"
listen_port: 8080
algorithm: "round-robin"

backends:
  - host: "localhost"
    port: 3001
  - host: "localhost"
    port: 3002
  - host: "localhost"
    port: 3003

health_check:
  enabled: true
  interval_ms: 10000
  max_failures: 5

logging:
  level: "debug"
  format: "text"
  output: "stdout"

metrics:
  enabled: true

​
High-Traffic Configuration

config-hightraffic.yaml
# High-Traffic Configuration (100k+ req/s)

listen_address: "0.0.0.0"
listen_port: 80
workers: 16                    # More workers
max_connections: 100000        # High connection limit

algorithm: "least-connections"

backends:
  - host: "backend1.prod.internal"
    port: 8080
    weight: 100
    max_connections: 5000      # High per-backend limit

  - host: "backend2.prod.internal"
    port: 8080
    weight: 100
    max_connections: 5000

health_check:
  enabled: true
  interval_ms: 2000            # Faster checks
  timeout_ms: 1000
  max_failures: 2              # Faster failover

timeout:
  connect_ms: 3000             # Aggressive timeouts
  request_ms: 15000
  idle_ms: 30000

logging:
  level: "warn"                # Less verbose
  format: "json"
  output: "/var/log/ultrabalancer/access.log"

​
Environment Variable Substitution

Use environment variables in config files:
config.yaml
listen_address: "${LISTEN_ADDRESS}"
listen_port: ${LISTEN_PORT}

backends:
  - host: "${BACKEND_1_HOST}"
    port: ${BACKEND_1_PORT}
  - host: "${BACKEND_2_HOST}"
    port: ${BACKEND_2_PORT}

tls:
  cert_path: "${TLS_CERT_PATH}"
  key_path: "${TLS_KEY_PATH}"
  key_password: "${TLS_KEY_PASSWORD}"

export LISTEN_ADDRESS="0.0.0.0"
export LISTEN_PORT="80"
export BACKEND_1_HOST="backend1.internal"
export BACKEND_1_PORT="8080"
export TLS_KEY_PASSWORD="secret"

ultrabalancer -c config.yaml

​
Configuration Validation

Validate configuration before deployment: 
ultrabalancer validate -c config.yaml

​
Validation Rules

  • listen_port must be between 1 and 65535
  • listen_address must be valid IP or hostname
  • workers must be positive integer or “auto”
  • max_connections must be positive integer
  • At least one backend required
  • host must not be empty
  • port must be between 1 and 65535
  • weight must be between 1 and 1000
  • No duplicate backends (same host:port)
  • interval_ms must be ≥ 1000
  • timeout_ms must be < interval_ms
  • max_failures must be ≥ 1
  • path must start with /
  • All timeout values must be positive
  • connect_ms should be < request_ms
  • idle_ms should be > request_ms

​
Migration Guide

​
From Nginx

nginx.conf
upstream backend {
    least_conn;
    server backend1:8080 weight=2;
    server backend2:8080 weight=1;
    server backend3:8080 backup;
}

server {
    listen 80;
    location / {
        proxy_pass http://backend;
    }
}
UltraBalancer equivalent:
config.yaml
algorithm: "least-connections"

backends:
  - host: "backend1"
    port: 8080
    weight: 200
  - host: "backend2"
    port: 8080
    weight: 100
  - host: "backend3"
    port: 8080
    weight: 50

​
From HAProxy

haproxy.cfg
backend app
    balance leastconn
    option httpchk GET /health
    server app1 backend1:8080 check weight 100
    server app2 backend2:8080 check weight 100
UltraBalancer equivalent:
config.yaml
algorithm: "least-connections"

backends:
  - host: "backend1"
    port: 8080
    weight: 100
  - host: "backend2"
    port: 8080
    weight: 100

health_check:
  enabled: true
  path: "/health"

Configuration Overview

Learn about all configuration methods

CLI Reference

Command-line interface documentation

Examples

Real-world configuration examples

Deployment

Deploy with your configuration