Run the Broker Locally

Goal

Start a local broker with an explicit trust boundary, the built-in auth Layer, and a file connection for development or integration testing.

Recipe

1. Read the current configuration skeleton in the broker operator guide.

2. Build binaries and storage plugins with make dist.

3. Create a local config with a UDS listener, explicit auth configuration, an [ovstorage] Layer graph, and a file [[connections]] entry. For a trusted-local smoke test, auth = "anonymous" is the smallest explicit choice; use kind = "builtin-auth" when testing policy behavior.

4. Create the file connection's root directory.

5. Start the daemon:

   OVSTORAGE_PLUGIN_DIR="$(pwd)/dist/plugins" \
     ./dist/bin/ovstorage-broker --config "$XDG_RUNTIME_DIR/broker.toml"
   

6. Exercise it through a broker-client connection or the broker integration tests under ovstorage-remote/ovstorage-broker/tests/.

7. Send SIGHUP on Unix after config edits. Send SIGTERM to exercise drain-first shutdown.

Common mistakes

• Omitting listener auth; current hosts fail startup instead of selecting an implicit mode.
• Setting TLS on UDS or peer credentials on TCP.
• Pointing OVSTORAGE_PLUGIN_DIR at an untrusted or incomplete directory.
• Using the retained policy plugin field as though it selected a cdylib.
• Editing the vendored ovstorage-services/ subtree for broker-only work.

References

• Broker operator guide
• Broker-client plugin
• Authorization policy
• Pre-merge verification