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]
  -L [local_port:]host:port[/udp]  Forward a local port to a remote address (repeatable)
  -v, -vv, -vvv                    Verbosity level (see below)
  --server-path PATH               Path to etrs on the remote host [default: etrs or config server_path]
  --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]
# 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"

Port forwarding

# Forward local port 5432 to db-host:5432 via jumphost (TCP, default)
etr -L 5432:db-host:5432 user@jumphost

# Use the same port number on both ends
etr -L db-host:5432 user@jumphost

# UDP forwarding
etr -L 5353:8.8.8.8:53/udp user@jumphost

# Multiple forwards in one session
etr -L 5432:db:5432 -L 6379:cache:6379 user@host

Port forwards run alongside the PTY session and survive the same reconnect cycle. Each TCP connection gets its own QUIC stream. UDP uses a dedicated QUIC stream per -L spec.

etrs (server) options

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

etrs [OPTIONS]

Options:
  -p, --port PORT       QUIC 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	QUIC details, TLS cipher suite, session ID, port
-vvv	Stream trace: every chunk type, sequence number, size

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).

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