Configuration

Configuration

etr (client) options

etr [OPTIONS] [TARGET]

Arguments:
  [TARGET]              Remote host — user@host or host

Options:
  -s, --ssh-port PORT   SSH port for bootstrap [default: 22 or config ssh_port]
  -v, -vv, -vvv         Verbosity level (see below)
  --server-path PATH    Path to etrs on the remote host [default: etrs or config server_path]
  --cipher NAME         Cipher suite, in preference order (repeatable; see below)
  --completions SHELL   Print shell completions and exit
  -h, --help
  -V, --version

Config file

etr reads $XDG_CONFIG_HOME/etr/config.toml (usually ~/.config/etr/config.toml) on startup. All fields are optional. CLI flags take precedence over config file values.

[client]
# Cipher suites in preference order.
# Available: ml-kem-1024, ml-kem-768, x25519-aes, x25519-chacha
# Default: all supported suites, strongest first.
ciphers = ["ml-kem-1024", "x25519-aes"]

# SSH port for bootstrap (default: 22)
ssh_port = 22

# Path to etrs on remote hosts (default: etrs, relies on PATH)
server_path = "/usr/local/bin/etrs"

Cipher suite selection

Use --cipher (repeatable) to restrict or reorder cipher suites:

# Use only ML-KEM-1024 (fail if server doesn't support PQC)
etr --cipher ml-kem-1024 user@host

# Prefer classical crypto, fall back to ChaCha20 if needed
etr --cipher x25519-aes --cipher x25519-chacha user@host

Available cipher suite names:

Name	KEM	AEAD	Requires
ml-kem-1024	ML-KEM-1024	AES-256-GCM	pqc feature (default)
ml-kem-768	ML-KEM-768	AES-256-GCM	pqc feature (default)
x25519-aes	X25519	AES-256-GCM	always available
x25519-chacha	X25519	ChaCha20-Poly1305	always available

Preference order is: CLI --cipher flags > config ciphers list > compiled-in defaults (strongest first).

etrs (server) options

etrs is normally started by etr automatically. You can run it manually for testing:

etrs [OPTIONS]

Options:
  -p, --port PORT       UDP port to bind [default: 0 = OS-assigned]
  -b, --bind ADDR       IP address to bind [default: [::] = dual-stack]
  -v, -vv, -vvv         Verbosity level (see below)
  -h, --help
  -V, --version

Verbosity levels

Both binaries use SSH-style -v counting:

Flag	What you see
(none)	Silent
-v	Connection events: connect, reconnect, disconnect, timeout
-vv	Cipher suite negotiated, session ID, port
-vvv	Every packet: type, sequence number, size, peer address

Client verbose logs are written to ~/.local/state/etr/etr.log during a live session (to avoid corrupting the raw-mode terminal display). A single line on stderr tells you the path. Watch it with:

tail -f ~/.local/state/etr/etr.log

Server logs go to ~/.local/state/etr/etrs.log on the remote host.

Server not in PATH

If etrs is installed somewhere not on the SSH session PATH:

etr --server-path /home/user/.cargo/bin/etrs user@host

SSH non-interactive sessions often have a minimal PATH. The safest fix is to add ~/.cargo/bin to PATH unconditionally in ~/.bashrc or ~/.zshrc (not just in the interactive section).

Disabling post-quantum crypto

PQC (ML-KEM-1024) is on by default. To build without it:

cargo install etr --no-default-features

Both client and server must agree — if the server has PQC disabled, the client will fall back to X25519 automatically during negotiation.

Shell completions

# Zsh
etr --completions zsh > ~/.zfunc/_etr
# then add `fpath=(~/.zfunc $fpath)` and `autoload -Uz compinit && compinit` to ~/.zshrc

# Bash
etr --completions bash > /etc/bash_completion.d/etr

# Fish
etr --completions fish > ~/.config/fish/completions/etr.fish

# Nushell
etr --completions nushell | save completions-etr.nu