bro is a remote execution tool for Linux. It is built to execute commands outside of a sandbox. It does this by transporting all details of the command (argv, stdin, etc.) to a remote server, which executes and returns the results (stdout, stderr, and exit code).

Usage

Client

The client is for the most part configured only via environment variables. This is to make sure that any arguments and stdin contents can be passed to the remote server without any issues. The configuration variables are:

Variable	Description
`BRO_SOCKET_PATH` (required)	The path to the socket file of the bro server.
`BRO_FORWARD_ENV` (optional)	A comma-separated list of environment variables to forward to the remote server.
`BRO_FILE_FLAGS` (optional)	A comma-separated list of flags that might have a value that is a file path, and which should be forwarded to the remote server. Note that the values include dashes, e.g. `-f,--file`.
`BRO_FILE_ARGS` (optional)	If set to a non-empty value, all non-flag arguments that look like file paths, smell like file paths, or can somehow be opened as a file will be forwarded to the remote server.
`BRO_CAPTURE_TTY_STDIN` (optional)	By default, bro will only capture stdin if it detects that it is passed through a pipe or redirection of some sort. Setting this variable to a non-empty value will make bro capture stdin also when it is a TTY. Useful for interactive use.

The intended way to set these variables is by creating a wrapper script around the bro-client executable. That also lets you name this wrapper script the same as the executable you want to call remotely, so that you can transparently replace it.

Here is an example wrapper for the ls command:

#!/bin/bash

export BRO_SOCKET_PATH="/run/bro.sock"
export BRO_FORWARD_ENV="LS_COLORS,TIME_STYLE,QUOTING_STYLE"
export BRO_FILE_ARGS=1

exec bro-client "$@"

A note on debugging

You can set the RUST_LOG environment variable to debug to get debug logs from the client. The logs will be written to stderr.

Server

The server can be configured via command line flags (or corresponding environment variables, see --help).

Here are some of the more important flags:

Flag	Description
`--executable` (required)	The path to the executable that the server will run.
`--socket-path` (required*)	The path to the socket file that the server will listen on. This should be omitted if you are using socket activation.
`--systemd-socket` (required*)	If set, the server will look for a socket fd provided by systemd. This should be omitted if you are setting the socket path.
`--fd-passing` (optional)	If set, the server will use file descriptor passing mode instead of the default file content passing mode.
`--allowed-env` (optional)	A comma-separated whitelist of client-forwarded environment variables that the server may pass through to the spawned process.
`--inherit-env` (optional)	A comma-separated whitelist of serverside environment variables to inherit into the spawned process. By default, the spawned process inherits none of the server's environment variables.

Systemd socket activation

The server can be run as a systemd socket-activated service. This is the recommended way to run the server.

File descriptor passing mode

In the default mode, the client will take its stdin and any files that are passed via arguments and read them fully before sending them to the server. The server will then write these contents (apart from stdin) to temporary files and rewrite the arguments to point to these files before executing the command. This is relatively OS-agnostic, but for some applications it will introduce unnecessary overhead, especially if the executable being called is only going to read a small portion of the files or stdin.

In file descriptor passing mode, the client uses the SCM_RIGHTS mechanism to transfer the file descriptors of its stdin and any files passed via arguments to the server. The server can then use these file descriptors directly when executing the command, without needing to read and write the contents to temporary files. This mode might be more efficient for certain applications, but it is also heavily Linux-specific.

If you use this mode with systemd socket activation, remember to set the AcceptFileDescriptors= option in the socket unit file.