Configuration

Complete configuration reference for ProxLB

  2 minute read  

Configuration File

ProxLB uses a configuration file located at /etc/proxlb/proxlb.conf. The file uses INI format with multiple sections.

Proxmox Connection

Configure your Proxmox VE API connection:

[proxmox]
# Proxmox API host (required)
api_host = pve.example.com

# API port (default: 8006)
api_port = 8006

# Authentication - Username/Password
api_user = root@pam
api_pass = your-password

# OR Authentication - API Token (recommended)
api_token_id = proxlb@pve!token
api_token_secret = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# SSL verification (default: true)
verify_ssl = true

API Token Authentication

For better security, use API tokens instead of passwords:

  1. Create a token in Proxmox: Datacenter > Permissions > API Tokens
  2. Assign necessary privileges (VM.Audit, VM.Migrate)
  3. Use the token in your configuration

Balancing Options

[balancing]
# Balancing mode: cpu, memory, combined (default: memory)
mode = memory

# Enable dry-run mode (default: false)
# When true, shows what would happen without making changes
dry_run = false

# Balancing threshold percentage (default: 10)
# Minimum difference required to trigger migration
threshold = 10

# Include stopped VMs in calculations (default: false)
include_stopped = false

# Exclude specific nodes (comma-separated)
exclude_nodes = node3,node4

# Exclude specific VMIDs (comma-separated)
exclude_vmids = 100,101,102

VM Groups (Affinity Rules)

Define groups to keep VMs together or apart:

[groups]
# Affinity: Keep VMs on the same node
web_servers = 100,101,102
database_cluster = 200,201,202

[affinity]
# Group affinity settings
web_servers = together
database_cluster = together

# Anti-affinity: Spread VMs across different nodes
[anti-affinity]
ha_group = 300,301,302

Scheduling

[schedule]
# Run interval in seconds (default: 3600)
interval = 3600

# Quiet hours - don't migrate during these times
# Format: HH:MM-HH:MM
quiet_hours = 02:00-06:00

Logging

[logging]
# Log level: DEBUG, INFO, WARNING, ERROR (default: INFO)
level = INFO

# Log file location
file = /var/log/proxlb/proxlb.log

# Log to syslog (default: false)
syslog = false

Complete Example

[proxmox]
api_host = pve.example.com
api_token_id = proxlb@pve!token
api_token_secret = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
verify_ssl = true

[balancing]
mode = combined
dry_run = false
threshold = 15
exclude_nodes = maintenance-node

[groups]
webservers = 100,101,102
databases = 200,201

[affinity]
databases = together

[anti-affinity]
webservers = 100,101,102

[schedule]
interval = 1800

[logging]
level = INFO
file = /var/log/proxlb/proxlb.log

Command Line Options

Override configuration file settings via command line:

# Run with dry-run mode
proxlb --dry-run

# Use a different config file
proxlb --config /path/to/config.conf

# Set log level
proxlb --log-level DEBUG

# Run once and exit (don't daemonize)
proxlb --once

Environment Variables

You can also use environment variables (useful for containers):

export PROXLB_API_HOST=pve.example.com
export PROXLB_API_TOKEN_ID=proxlb@pve!token
export PROXLB_API_TOKEN_SECRET=your-secret
export PROXLB_MODE=memory
export PROXLB_DRY_RUN=true