Usage

CLI

./haribon start --config haribon-config.yml

Commands

start

Start the load balancer

check

Read a config file and report problems. Exits 0 when it is fine, 1 when it is not

validate

The same, plus a check against the JSON schema, which catches misspelled keys

version

Print the version and exit

Flags for `start`

--config

Path to the YAML configuration file. Defaults to $HARIBON_CONFIG, then ./haribon-config.yml

--watch_config

Check the config file for changes every N seconds and apply them without a restart

Reloading without restarting

On Linux and macOS you can send SIGHUP to the process and it will re-read its config file:

kill -HUP $(pgrep haribon)

Windows never delivers SIGHUP, so on Windows use --watch_config instead. It polls the file every N seconds and applies a change when it sees one.

./haribon start --config haribon-config.yml --watch_config 30

Either way, a reload rebuilds the routing state in place: request counters and breaker history for backends that are still there are kept, so a reload does not reset a breaker that is midway through its cooldown.

Example

With the default configuration, Haribon listens on port 4444 and distributes requests across three local backends.

        # Check the config first

        ./haribon check --config haribon-config.yml

        # Start the load balancer

        ./haribon start --config haribon-config.yml

Send a request:

curl http://localhost:4444

Haribon proxies it to one of the healthy backends. If the first one it picks refuses the connection, it tries another — but only for methods that are safe to repeat, and the response you get back says how many attempts it took in X-Haribon-Retries.

Log Output

        {

            "time": "2026-05-04T01:31:55.3551454Z",

            "method": "GET",

            "path": "/",

            "backend": "http://localhost:4442",

            "status": 200,

            "duration_ms": 5,

            "level": "info"

        }

retries appears only when a request was actually retried. Set log_format: text for a plain line instead of JSON.

Metrics

/metrics returns Prometheus text format — request counts, retries, last response time, backend health, breaker state, and active connections, each labelled with the backend it refers to.

curl -s http://localhost:4444/metrics | grep haribon_requests_total

Query Logs in Grafana

The observability Compose stack runs Promtail, which tails the log file and ships it to Loki, and provisions Loki as a Grafana data source. Open Grafana (admin / admin), go to Explore, and pick the Loki source:

{job="haribon"}

Filter to failures:

{job="haribon"} |= "error"

There are no dashboards pre-built; Grafana starts with the data source wired up and nothing on the boards.

Tips

Logs go to stdout always. Add file to exporters to also write them to log_path, and loki, elasticsearch, or fluentbit to ship them somewhere.
Use HARIBON_HOST, HARIBON_PORT, and HARIBON_CONFIG to override the config in a container.
Put a check in your CI pipeline. It is the cheapest way to catch a config that would not have started.
For high availability, run several Haribon replicas rather than one. With cluster.enabled they share what they find about each backend, so a server one of them cannot reach is skipped by all of them — see docs/clustering.md.

CLI