---
title: ETRS
section: 1
header: User Commands
date: June 2026
---

# NAME

etrs - Eternal Terminal server (per-session)

# SYNOPSIS

**etrs** \[*OPTIONS*\]

# DESCRIPTION

**etrs** is the per-session server component of **etr**(1). It is not
normally invoked directly; **etr** starts it automatically via SSH during
session bootstrap.

When started, **etrs** reads a single line from stdin in the form:

    SESSION_ID_HEX/PASSKEY/TERM

It then generates an ephemeral self-signed TLS certificate, binds a QUIC
port, prints **PORT** *n* **CERT** *cert_hex* to stdout, and forks. The
parent process exits immediately (allowing the SSH connection to close
cleanly). The child detaches from stdio, redirects stderr to its log file,
and enters the session loop.

The session loop keeps the PTY and shell alive across reconnects for up to
30 minutes. If the client reconnects, it presents the same session ID and
passkey to resume. When the client cleanly disconnects (or the reconnect
window expires), the child exits.

# OPTIONS

**-p**, **\-\-port** *PORT*
:   QUIC port to bind. Defaults to **0** (OS-assigned random port).

**-b**, **\-\-bind** *ADDR*
:   IP address to bind. Defaults to **[::]** (dual-stack, all interfaces).

**-v**
:   Increase verbosity. May be repeated up to three times:

    **-v** — session lifecycle events (connect, disconnect, timeout)

    **-vv** — QUIC details and session ID

    **-vvv** — per-stream trace

    Output is written to **\$XDG_STATE_HOME/etr/etrs.log** (default:
    **~/.local/state/etr/etrs.log**) after the child forks and detaches.

**\-\-log-path** *PATH*
:   Path to the server log file. Defaults to **\$XDG_STATE_HOME/etr/etrs.log**.

**-h**, **\-\-help**
:   Print help and exit.

**-V**, **\-\-version**
:   Print version and exit.

# FILES

**~/.local/state/etr/etrs.log**
:   Server log file (XDG_STATE_HOME honoured). Written after the child
    forks. Follow with **tail -f** to monitor a running session.

# ENVIRONMENT

**SHELL**
:   Shell to launch for the PTY session. Defaults to **/bin/bash** if unset.

**XDG_STATE_HOME**
:   Base directory for the log file. Defaults to **~/.local/state**.

# SECURITY

**etrs** uses a self-signed TLS certificate generated fresh for each
session. The certificate DER (hex-encoded) is transmitted to the client
over the authenticated SSH channel and pinned — no CA is required. The
QUIC transport uses TLS 1.3 (X25519 key exchange, AES-256-GCM-SHA384 or
ChaCha20-Poly1305).

Incoming QUIC connections must present the correct session ID and passkey
(32-character random alphanumeric string) generated by **etr**(1) at
session start. Connections that fail this check are rejected.

**etrs** also receives reverse port forwarding specifications from the client
via the **SessionOpen** message and binds TCP/UDP listeners for each spec.
By default these listeners bind to **127.0.0.1** and **[::1]** (loopback only).
When the client specifies **-g** / **\-\-gateway-ports**, the listeners bind to
a dual-stack **[::]** socket instead, making them reachable from external
hosts.  Ensure appropriate firewall rules are in place before enabling
gateway-mode reverse forwarding.


# SEE ALSO

**etr**(1), **ssh**(1)

# BUGS

- The reconnect window (30 minutes) is not configurable.

# AUTHORS

The etr project contributors. See the source repository for details.

# LICENSE

GNU General Public License v3.0 or later.
