Commands

Run rustle <command> --help for the exact usage of your version. With no command, rustle is rustle run; rustle /path/to/config.toml is rustle run /path/to/config.toml.

When a command takes a config file and you do not give one, rustle uses the first that exists among ./config.toml, ~/.config/rustle/config.toml ($XDG_CONFIG_HOME/rustle/config.toml when that variable is set) and /etc/rustle/config.toml. A config.toml in the current directory therefore wins over your user config.

run

Runs the proxy in the foreground. It stops on SIGTERM or SIGINT (Ctrl+C), after giving open connections a few seconds to finish. A missing config, an unknown key or a port already in use stops it with exit code 1 and a message on standard error. Diagnostics go to standard error, at the level of the RUST_LOG variable (info by default).

init

Writes a config with a freshly generated API key.

• --path <PATH> writes elsewhere than the default location.
• --force overwrites an existing file; without it, init refuses.

The file is created readable by its owner only. The key is 48 hexadecimal characters, printed once.

check

Validates a config without starting the proxy: syntax, unknown keys, the addresses in allow_clients and deny, and the certificate and key when tls.listen is set. It prints what the proxy would listen on and warns when api_keys is empty. It does not open any port, so it cannot tell you that a port is already taken.

status

Asks the running proxy for its health: GET /health on server.admin_listen, which only answers on the machine that can reach that address (loopback by default). It also reports the state of the service, if one is installed. Exit code 0 when healthy, 1 when the proxy does not answer. When the admin listener is disabled it says so and exits 0, which proves nothing about the proxy.

reload

Makes the running proxy re-read its config without restarting it. See which settings a reload applies in Configuration.

• On success it prints reloaded. If you changed settings that need a restart, it prints reloaded; restart required for: … and exits 0: the running proxy keeps their old value.
• If the new config is invalid (a bad CIDR, a certificate that does not match its key), nothing is applied: the proxy keeps running with the previous config and reload exits 1 with the reason.
• It talks to the proxy through a Unix socket (server.control_socket). When that socket is disabled, send the signal yourself: kill -HUP <pid>.

SIGHUP does the same as rustle reload and also reopens the access log file, which is how you rotate it. Under systemd, systemctl reload rustle sends SIGHUP.

service

rustle service <action> manages a systemd unit (Linux) or a launchd agent (macOS).

Action	What it does
install	Writes the service definition only.
enable	Installs it, starts it now and at boot (Linux) or login (macOS).
disable	Stops it and disables it.
uninstall	Stops, disables and removes it.
start, stop, restart, status	What they say.
logs	Follows the logs (journalctl on Linux, the log file on macOS).

Options:

• --config <PATH> is the config file the service runs with. It is stored as an absolute path.
• --system (Linux, needs root) installs a system-wide unit that runs as a dedicated rustle user, with the config in /etc/rustle/config.toml by default, instead of a user unit. The config must already exist.
• --dry-run prints what would be written and run, and changes nothing.

The system unit can only write to /var/log/rustle, /run/rustle and a private /tmp, and it cannot see /home. Put log.file under /var/log/rustle/ and keep the certificate and key somewhere the rustle user can read.

update

Replaces the binary with the latest release, after checking its SHA-256, and restarts the installed service if there is one. A rustle run started by hand is not restarted.

• --check only reports whether a newer version exists.
• --version <VERSION> installs that version (for example v1.0.0) instead of the latest, newer or older.

When the binary sits in a folder you cannot write to, it tells you to re-run with the right privileges.

uninstall

Removes the service and the binary. --purge also removes your user config folder, including the API key. It does not touch /etc/rustle, a log file or the rustle system user created by service enable --system.

Environment variables

Variable	Used by	Effect
XDG_CONFIG_HOME	all	Where the user config folder is, and the systemd user unit.
RUST_LOG	run	Level of the diagnostics on standard error.
RUSTLE_VERSION	install.sh	Version to install, set on the sh side of the pipe.
RUSTLE_INSTALL_DIR	install.sh	Folder to install into.

Logs

Diagnostics (startup, reloads, warnings) go to standard error: the journal under systemd, ~/Library/Logs/rustle.log under launchd. The access log is separate and is configured in the [log] table. By default it is set to a file with no path, which means no access log at all: set log.file, or log.output = "stdout", to get one. To rotate the file, rename it and send SIGHUP.

Exit codes

Every command exits 0 on success and 1 on failure, with rustle: <reason> on standard error. status also exits 1 when the proxy does not answer. service status returns the exit code of the underlying tool (systemctl status; on macOS 0 when running, 3 otherwise).