boe debug

The debug command runs Envoy with local Go or Rust extensions built for debugging, and attaches a debug server to the Envoy process so you can set breakpoints in the extension code from your IDE.

Extensions run inside the Envoy process (they are loaded as shared libraries), so the debugger has to attach to Envoy, not to the boe CLI. This command builds the local extensions without optimizations and with full debug information, starts Envoy, and attaches a debug server to it, listening on 127.0.0.1:2345 by default. Debug builds are stored separately in the cache and are never used by boe run.

Only local extensions (--local) are supported: Go extensions, composer sub-extensions, or Rust extensions. Go and Rust extensions can’t be debugged in the same session. All other flags behave as in boe run.

Go extensions are debugged with Delve. boe debug builds its own patched Delve the first time it runs, so it does not need to be installed. Use --rebuild-dlv to force rebuilding it.
Rust extensions are debugged with the platform’s native debug server, which speaks the GDB remote protocol: gdbserver on Linux (it must be installed), and LLDB’s debugserver on macOS (from the Xcode Command Line Tools). The debug server is only attached to Envoy while a debugger is connected, so Envoy keeps running normally between debug sessions and you can reconnect at any time. Connect with GDB on Linux and with LLDB on macOS: LLDB can’t resolve breakpoints in extensions when connected to gdbserver.

warning

On Linux, the debug server attaches to the Envoy process started by boe, which is not its parent process. Many distributions, such as Ubuntu, only allow a process to attach to its own descendants (kernel.yama.ptrace_scope=1), and attaching then fails with “operation not permitted”. Allow it by setting ptrace_scope to 0 (until the next reboot):

sudo sysctl -w kernel.yama.ptrace_scope=0

To make it permanent, add kernel.yama.ptrace_scope = 0 to a file in /etc/sysctl.d/. Alternatively, run boe debug as root, or, for Go extensions, use boe debug --docker to run Envoy and Delve in a container.

While the debugger is stopped at a breakpoint all Envoy workers are paused, so in-flight requests may time out.

Breakpoints are resolved using the exact source paths recorded when building the extension, which are the paths given in --local. If those paths go through a symlink (for example, /tmp is a symlink to /private/tmp on macOS) and your IDE sets breakpoints using the resolved path, they will not be hit. boe debug warns about this and prints the path mapping to add to the IDE configuration.

Examples

Debug the opa extension from the composer bundle:

boe debug --local ~/src/built-on-envoy/extensions/composer/opa \
    --config '{"policies":[{"inline":"package envoy.authz\ndefault allow := true"}]}'

Debug a Rust extension:

boe debug --local ~/src/built-on-envoy/extensions/ip-restriction \
    --config '{"deny_addresses":["192.168.1.50"]}'

Debug a Go extension using a custom port for the debug server:

boe debug --local ./my-go-extension --debug-port 40000

Once the debug server is listening, attach your IDE to 127.0.0.1:2345: as a remote Delve session for Go extensions, or as a GDB remote (gdb-remote) session for Rust extensions. From the command line, use dlv connect 127.0.0.1:2345 for Go, or, for Rust, gdb -ex 'target remote 127.0.0.1:2345' on Linux and lldb -o 'gdb-remote 127.0.0.1:2345' on macOS. Run detach before quitting the debugger: quitting without detaching kills Envoy. See the Debugging guide for IDE configurations and caveats.

Usage details

boe debug [flags]
boe debug --help

Flags

Name	Description	Type	Default	Env Var	Required
`--envoy-version`	Envoy version to use (e.g., 1.31.0, dev, dev-latest)	`string`	-	`ENVOY_VERSION`	No
`--envoy-path`	Path to a custom Envoy binary. Skips Envoy download and version selection.	`string`	-	`ENVOY_PATH`	No
`--log-level`	Envoy component log level.	`string`	`all:error`	`ENVOY_LOG_LEVEL`	No
`--log-format`	Envoy log format.	`string`	-	`ENVOY_LOG_FORMAT`	No
`--run-id`	Run identifier for this invocation. Overrides the default timestamp-based ID.	`string`	-	`BOE_RUN_ID`	No
`--listen-port`	Port for Envoy listener to accept incoming traffic.	`uint32`	`10000`	-	No
`--admin-port`	Port for Envoy admin interface.	`uint32`	`9901`	`BOE_ADMIN_PORT`	No
`--extension`	Extensions to enable (in the format: “name” or “name:version”).	`[]string`	-	-	No
`--local`	Path to a directory containing a local Extension to enable.	`[]string`	-	-	No
`--dev`	Whether to allow downloading dev versions of extensions (with -dev suffix). By default, only stable versions are allowed.	`bool`	`false`	-	No
`--config`	Optional JSON config string for extensions. Applied in order to combined —extension and —local flags.	`[]string`	-	-	No
`--filter-type`	Set the filter type for an extension. Applied positionally to the combined —extension and —local flags. Accepted values: http, network, listener, udp_listener.	`[]string`	-	-	No
`--native-http-filter-before`	Optional YAML/JSON native HTTP filter list (or @filepath) per extension position. Overrides manifest nativeHttpFilters.before.	`[]string`	-	-	No
`--native-http-filter-after`	Optional YAML/JSON native HTTP filter list (or @filepath) per extension position. Overrides manifest nativeHttpFilters.after.	`[]string`	-	-	No
`--cluster`	Optional additional Envoy cluster provided in the host:tlsPort pattern.	`[]string`	-	-	No
`--cluster-insecure`	Optional additional Envoy cluster (with TLS transport disabled) provided in the host:port pattern.	`[]string`	-	-	No
`--cluster-json`	Optional additional Envoy cluster providing the complete cluster config in JSON format.	`[]string`	-	-	No
`--test-upstream-host`	Hostname for the test upstream cluster. Mutually exclusive with —test-upstream-cluster. Defaults to “httpbin.org”.	`string`	-	-	No
`--test-upstream-cluster`	Name of an existing configured cluster to use as the test upstream. The cluster must be configured via —cluster, —cluster-insecure, or —cluster-json. Mutually exclusive with —test-upstream-host.	`string`	-	-	No
`--listener-cert`	Path to a PEM-encoded certificate chain used to terminate TLS on the Envoy listener. Requires —listener-key.	`string`	-	-	No
`--listener-key`	Path to the PEM-encoded private key for the listener certificate. Requires —listener-cert.	`string`	-	-	No
`--docker`	Run Envoy as a Docker container instead of using func-e.	`bool`	`false`	`BOE_RUN_DOCKER`	No
`--pull`	Pull policy for the BOE Docker image (missing, always, never). Only applicable when running with —docker.	`string`	`missing`	-	No
`--docker-image-version`	Override the BOE Docker image tag to use when running with —docker. By default, the image version matches the BOE version.	`string`	-	-	No
`--registry`	OCI registry URL for the extensions.	`string`	`ghcr.io/tetratelabs/built-on-envoy`	`BOE_REGISTRY`	No
`--insecure`	Allow connecting to an insecure (HTTP) registry.	`bool`	`false`	`BOE_REGISTRY_INSECURE`	No
`--username`	Username for the OCI registry.	`string`	-	`BOE_REGISTRY_USERNAME`	No
`--password`	Password for the OCI registry.	`string`	-	`BOE_REGISTRY_PASSWORD`	No
`--debug-port`	Port for the debug server attached to Envoy.	`uint32`	`2345`	`BOE_DEBUG_PORT`	No
`--debug-server-path`	Path to the debug server binary: dlv for Go extensions (instead of the patched Delve that boe builds; unpatched versions may not be able to list goroutines), or gdbserver (Linux) or debugserver (macOS) for Rust extensions.	`string`	-	`BOE_DEBUG_SERVER_PATH`	No
`--rebuild-dlv`	Rebuild the patched Delve used for Go extensions even if it is already in the cache.	`bool`	-	`BOE_REBUILD_DLV`	No