Operating an Executor

An executor runs debuglet measurements. It has no public control listener: it dials the dispatcher over two authenticated control paths. Operators normally need only the executor package, a configuration file, its persistent SQLite state, and its transport credentials.

Published v0.2.0 includes this daemon in the full bundle. Newer source builds provide a separate executor package; see component installation and use the package version selected by your deployment.

Before you start

• Use the same Debuglet release as the dispatcher.
• Keep a stable UUID in identity.executor_id across restarts.
• Give its SQLite state directory to this executor alone.
• For a networked deployment, use a dispatcher certificate trusted by the executor and an executor client certificate.
• Use packet_counter = "fallback" when eBPF counters are not configured; use auto only with the required interface and privileges.

Validate readiness

After starting the systemd service, wait for the executor to announce resources. Verify it from an authenticated client:

dbl --dispatcher research nodes

The executor must be listed and ready before it can receive work. Check the service log first if it repeatedly reconnects; a common cause is confusing the direct gRPC address with the reverse control address.

Operational rules

• Upgrade the package and database by the explicit deployment procedure; daemons do not migrate state on startup.
• Drain or stop an executor before maintenance. Interrupted measurements are not resumed after restart.
• Limit outbound network access according to the destinations you authorize for measurements.
• Treat executor credentials and its database as host-local secrets.

The complete configuration reference, recovery procedure, and systemd deployment details are in the deployment documentation and executor recovery guide.

For port, executor connection, OAuth, readiness or state-version failures, start with the troubleshooting guide for the package you installed.