Skip to main content

​
Synopsis

ultrabalancer [OPTIONS] [COMMAND]

​
Global Options

​
Listener Options

​
--host, -h
string
default:"0.0.0.0"
IP address to bind to
ultrabalancer --host 0.0.0.0 -b server1:8080
ultrabalancer --host 127.0.0.1 -b server1:8080  # Localhost only
​
--port, -p
integer
default:"8080"
Port number to listen on (1-65535)
ultrabalancer --port 80 -b server1:8080
ultrabalancer -p 443 -b server1:8080

​
Backend Options

​
--backend, -b
string
required
Backend server (format: host:port or host:port:weight)Can be specified multiple times for multiple backends.
# Simple format
ultrabalancer -b server1:8080 -b server2:8080

# With weights
ultrabalancer -b server1:8080:150 -b server2:8080:100

# Mixed
ultrabalancer -b 192.168.1.10:8080:200 -b 192.168.1.11:8080

​
Algorithm Options

​
--algorithm, -a
string
default:"round-robin"
Load balancing algorithmAvailable algorithms:
  • round-robin - Distribute evenly across backends
  • least-connections - Route to backend with fewest connections
  • ip-hash - Consistent hashing based on client IP
  • random - Random backend selection
  • weighted - Weighted round-robin distribution
ultrabalancer -a round-robin -b s1:8080 -b s2:8080
ultrabalancer -a least-connections -b s1:8080 -b s2:8080
ultrabalancer -a ip-hash -b s1:8080 -b s2:8080
​
--weight, -w
integer
default:"100"
Default weight for all backends (used with weighted algorithm)
ultrabalancer -a weighted -w 100 -b s1:8080 -b s2:8080

​
Health Check Options

​
--no-health-check
flag
Disable health checking
ultrabalancer --no-health-check -b server1:8080
​
--health-check-interval
integer
default:"5000"
Health check interval in milliseconds
ultrabalancer --health-check-interval 3000 -b server1:8080
​
--health-check-fails
integer
default:"3"
Number of failures before marking backend unhealthy
ultrabalancer --health-check-fails 5 -b server1:8080

​
Configuration File

​
--config, -c
string
Path to YAML or TOML configuration file
ultrabalancer --config config.yaml
ultrabalancer -c /etc/ultrabalancer/config.toml
Advanced Options: Additional configuration options like logging, timeouts, max connections, and worker threads are available via config file only. See File Configuration for details.

​
Miscellaneous

​
--version, -v
flag
Print version information
ultrabalancer --version
# Output: ultrabalancer 2.0.0
​
--help
flag
Print help information
ultrabalancer --help

​
Commands

​
start

Start the load balancer with specified configuration. Syntax: 
ultrabalancer start <ALGORITHM> <BACKENDS...> [OPTIONS]
Arguments:
  • <ALGORITHM> - Load balancing algorithm
  • <BACKENDS...> - Space-separated list of backend servers
Options:
  • --port, -p - Listen port (default: 8080)
  • --weight - Default backend weight (default: 100)
  • --no-health-check - Disable health checks
Examples: 
ultrabalancer start round-robin server1:8080 server2:8080 --port 80

​
validate

Validate a configuration file without starting the load balancer. Syntax: 
ultrabalancer validate --config <FILE>
Options:
  • --config, -c - Path to configuration file (required)
Examples: 
ultrabalancer validate --config config.yaml

​
example

Print an example configuration file. Syntax: 
ultrabalancer example [--format <FORMAT>]
Options:
  • --format - Output format: yaml or toml (default: yaml)
Examples: 
ultrabalancer example

​
info

Display information about available algorithms and features. Syntax: 
ultrabalancer info
Output: 
UltraBalancer v2.0.0
Production-grade load balancer written in Rust

Supported Algorithms:
  • round-robin       - Distribute requests evenly
  • least-connections - Route to server with fewest connections
  • ip-hash          - Consistent hashing based on client IP
  • random           - Random distribution
  • weighted         - Weight-based round robin

Features:
  • Automatic health checking
  • Real-time metrics (/metrics, /prometheus endpoints)
  • Zero-downtime failover
  • HTTP/1.1 proxying
  • Connection pooling
  • Circuit breaker pattern

​
Usage Examples

​
Basic Usage

# Start with two backends, round-robin algorithm
ultrabalancer -b server1:8080 -b server2:8080

​
Advanced Usage

ultrabalancer \
  --host 0.0.0.0 \
  --port 80 \
  --algorithm least-connections \
  --backend backend1.prod.internal:8080:150 \
  --backend backend2.prod.internal:8080:150 \
  --backend backend3.prod.internal:8080:100 \
  --health-check-interval 3000 \
  --health-check-timeout 1500 \
  --health-check-fails 3 \
  --health-check-path /health \
  --max-connections 50000 \
  --workers auto \
  --log-level info \
  --log-format json

​
Docker Usage

docker run -d \
  --name ultrabalancer \
  -p 80:8080 \
  ultrabalancer/ultrabalancer:latest \
  -b backend1:8080 \
  -b backend2:8080 \
  -a least-connections

​
Kubernetes Usage

# Run as a Kubernetes Job
kubectl run ultrabalancer \
  --image=ultrabalancer/ultrabalancer:latest \
  --port=8080 \
  -- \
  -b backend-service:8080 \
  -a least-connections \
  --log-format json

​
Exit Codes

CodeMeaning
0Success
1Configuration error
2Runtime error
3Invalid arguments
130Interrupted (SIGINT/Ctrl+C)

​
Signal Handling

SignalBehavior
SIGINT (Ctrl+C)Graceful shutdown
SIGTERMGraceful shutdown
Example: 
# Graceful shutdown
kill -TERM $(pidof ultrabalancer)

# Or use Ctrl+C

​
Tips & Tricks

Pro Tips
  1. Use config files in production - Easier to manage than long CLI commands
  2. Validate config before deployment - Use ultrabalancer validate -f config.yaml
  3. Start simple, then optimize - Begin with round-robin, monitor metrics, then adjust
  4. Use systemd for process management - See Systemd deployment guide
Common Mistakes
  1. Forgetting -b flag - At least one backend is required
  2. Invalid algorithm names - Use exact names from info command
  3. Port conflicts - Ensure port is not already in use
  4. Health check too aggressive - Can overload backends
  5. Missing config file - Check path with --config

​
Troubleshooting

Ensure UltraBalancer is installed and in your PATH:
# Check if installed
which ultrabalancer

# Add to PATH if needed
export PATH=$PATH:/usr/local/bin

# Or use full path
/usr/local/bin/ultrabalancer --help
Ports below 1024 require root privileges:
# Run with sudo
sudo ultrabalancer -p 80 -b server1:8080

# Or use setcap (Linux)
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/ultrabalancer
ultrabalancer -p 80 -b server1:8080
Ensure the config file exists and path is correct:
# Check if file exists
ls -la config.yaml

# Use absolute path
ultrabalancer -c /etc/ultrabalancer/config.yaml

# Or relative path from current directory
ultrabalancer -c ./config.yaml

Configuration Overview

Learn about all configuration methods

File Config

YAML/TOML configuration reference

Examples

Real-world configuration examples

Deployment

Deploy UltraBalancer in production