Skip to main content

Quick Start

# Basic usage - 2 backends, round-robin
ultrabalancer -b server1:8080 -b server2:8080

# Custom port
ultrabalancer -p 80 -b backend1:8080 -b backend2:8080

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

Commands

start

Start the load balancer.
ultrabalancer start round-robin server1:8080 server2:8080

dashboard

Deploy Grafana/Prometheus monitoring.
ultrabalancer dashboard --start    # Interactive setup
ultrabalancer dashboard --status   # Check status
ultrabalancer dashboard --stop     # Stop dashboard

validate

Check config file syntax.
ultrabalancer validate -f config.yaml

example

Print example config.
ultrabalancer example

info

Show version and algorithms.
ultrabalancer info

Options

FlagDescriptionDefault
-p, --portListen port8080
-b, --backendBackend server (host:port)Required
-a, --algorithmLoad balancing algorithmround-robin
-w, --weightDefault backend weight100
-c, --configConfig file path-
--hostBind address0.0.0.0

Algorithms

AlgorithmDescription
round-robinEven distribution (default)
least-connectionsFewest active connections
ip-hashSame client → same server
randomRandom backend
weightedWeight-based distribution
power-of-twoPick 2, use least loaded
fastest-responseFastest recent response

Admin API

Secure API for managing backends (requires API key).
# List backends
curl -H "X-API-Key: YOUR_KEY" http://localhost:8080/admin/backends

# Add backend
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"10.0.0.5:8080","weight":100}' \
  http://localhost:8080/admin/backends

# Remove backend
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  -d '{"address":"10.0.0.5:8080"}' \
  http://localhost:8080/admin/backends

# Update weight
curl -X PUT -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"10.0.0.5:8080","weight":150}' \
  http://localhost:8080/admin/backends/weight

Admin Endpoints

MethodEndpointDescription
GET/admin/backendsList all backends
POST/admin/backendsAdd backend
DELETE/admin/backendsRemove backend
PUT/admin/backends/weightUpdate weight
POST/admin/backends/drainStart draining
POST/admin/backends/undrainStop draining
GET/admin/healthAPI health check

Exit Codes

CodeMeaning
0Success
1Error