Configuring sozu via command line

The sozu executable can be used to start the proxy, and configure it: adding new backend servers, reading metrics, etc. It talks to the currently running proxy through a unix socket.

You can specify its path by adding to your config.toml:

command_socket = "path/to/your/command_folder/sock"

Add a cluster with an http and https frontends

First you need to create a new cluster with an id and a load balancing policy (roundrobin or random):

sozu --config /etc/sozu/config.toml cluster add --id <my_cluster_id> --load-balancing-policy roundrobin

To create a cluster with HTTP/2 backend connections enabled:

sozu --config /etc/sozu/config.toml cluster add --id <my_cluster_id> --load-balancing-policy roundrobin --http2

It won't show anything but you can verify that the cluster has been added successfully by querying sozu:

sozu --config /etc/sozu/config.toml query clusters

Then you need to add a backend:

sozu --config /etc/sozu/config.toml backend add --address 127.0.0.1:3000 --backend-id <my_backend_id> --id <my_cluster_id>

Add http frontend

And an http listener:

sozu --config /etc/sozu/config.toml listener http add --address 0.0.0.0:80 --tls-versions TLSv1.2 --tls-cipher-list ECDHE-ECDSA-AES256-GCM-SHA384 --tls-cipher-suites TLS_AES_256_GCM_SHA384 --tls-signature-algorithms ECDSA+SHA512 --tls-groups-list x25519 --expect-proxy

Finally you have to create a frontend to allow sozu to send traffic from the listener to your backend:

sozu --config /etc/sozu/config.toml frontend http add --address 0.0.0.0:80 --hostname <my_cluster_hostname> id <my_cluster_id>

To route only a sub-path of a hostname to this cluster, add --path-prefix (use --path-regex or --path-equals for the other matching modes — see "Path matching precedence within a frontend" in doc/configure.md):

sozu --config /etc/sozu/config.toml frontend http add --address 0.0.0.0:80 --hostname <my_cluster_hostname> --path-prefix /api id <my_cluster_id>

Add https frontend

And an https listener:

sozu --config /etc/sozu/config.toml listener https add --address 0.0.0.0:443

Finally you have to create a frontend to allow sozu to send traffic from the listener to your backend:

sozu --config /etc/sozu/config.toml frontend https add --address 0.0.0.0:443 --hostname <my_cluster_hostname> id <my_cluster_id>

Enable or disable HTTP/2 for backend connections

You can toggle HTTP/2 for backend connections on an existing cluster at runtime:

sozu --config /etc/sozu/config.toml cluster h2 enable --id <my_cluster_id>
sozu --config /etc/sozu/config.toml cluster h2 disable --id <my_cluster_id>

This queries the current cluster configuration, updates the http2 flag, and re-applies it to all workers without affecting other cluster settings.

Check the status of sozu

It shows a list of workers and show information about their statuses.

sozu --config /etc/sozu/config.toml status

Get metrics and statistics

It will show global statistics about sozu, workers and clusters metrics.

sozu --config /etc/sozu/config.toml query metrics

Dump and restore state

If sozu configurations (clusters, frontends & backends) are not written in the config file, you can save sozu state to restore it later.

sozu --config /etc/sozu/config.toml state save --file state.json

Then shutdown gracefully sozu:

sozu --config /etc/sozu/config.toml shutdown

Restart sozu and restore its state:

sozu --config /etc/sozu/config.toml state load --file state.json

You should be able to request your cluster like before the shutdown.

Monitor status of backends with events

This CLI command:

sozu --config /path/to/config.toml events

listens to events sent by Sōzu workers whenever a backend is down, up again, or when no backend is available.

Live operator TUI (sozu top)

The top subcommand is a btop/htop-style live dashboard. Build with the optional tui Cargo feature (cargo build -p sozu --features tui --release); sozu --version reports +tui when the subcommand is linked in. See doc/sozu-top.md for the full operator guide (panes, key bindings, skin format, threshold tuning).

sozu --config /path/to/config.toml top

Common flags:

Flag	Effect
--refresh-ms <N>	Data poll cadence in milliseconds (default 1000).
--detail <DETAIL>	Cardinality lease level (`process
--lease-ttl-seconds <N>	Lease TTL; auto-renewed at half-TTL (default 60, server clamps at 300).
--skin <NAME>	Resolve $XDG_CONFIG_HOME/sozu/skins/<NAME>.toml (SOZU_TOP_SKIN env wins).
--glyphs <MODE>	Force a glyph mode (`braille
--no-mouse	Disable SGR mouse capture (helps with multiplexers that mis-route mouse events).
--snapshot <N>, --tick-once	Render N frames / one tick and exit (test affordances).

Key bindings (operator quick reference; see doc/sozu-top.md for the full list):

• 1-7 jumps to OVERVIEW · CLUSTERS · BACKENDS · LISTENERS · CERTS · H2 · EVENTS.
• Tab / Shift-Tab cycles tabs forward / backward.
• s / S cycles / reverses the sort column on CLUSTERS and BACKENDS.
• q / Q / Ctrl-C / F10 quits, ? / F1 toggles help.