linbit-tunl: architecture-brief

linbit-tunl: Overview

A short, customer-and-support-facing summary of what linbit-tunl is and how a session looks from each side. See the landing page for the download and the relay's published CA keys; see the full architecture document for the design detail behind everything below.

What it is

A reverse-SSH tunnel tool that lets a LINBIT support engineer reach into a customer Linux system that is not directly reachable from the internet. No VPN, no inbound firewall holes, no persistent install -- the customer runs one Python script when they want a session and closes it when they're done.

The connection is opened by the customer, outbound to the LINBIT relay (tunl.linbit.com, port 443), encrypted end-to-end with SSH, and recorded on both ends.

Session modes

Support tells the customer which mode to start. In order of increasing access:

Mode	Command	What support can do
Restricted	`linbit-tunl --restricted <session-id>`	Watch the shared shell and chat. Cannot type, cannot request a tunnel. One-way: the customer cannot promote out of this within the running session.
Share (default)	`linbit-tunl <session-id>`	Watch the shared shell, type into it, and chat. Can request a reverse tunnel; each request raises a Grant/Deny popup on the customer side.
Tunnel	`linbit-tunl --tunnel <session-id>`	Same as Share, plus a reverse SSH tunnel is pre-opened at session start (no popup). This mode also works without `tmux` installed on the customer system.

In Share mode the customer has three runtime controls over tunnel requests, via the tmux prefix Ctrl-b:

Ctrl-b u -- pre-grant. Subsequent tunnel requests skip the popup.
Ctrl-b U -- revoke. Closes any active tunnel and removes the support keys that were installed. Returns to popup-on-each-request.
Ctrl-b X -- auto-reject. Subsequent tunnel requests are denied without prompting until Ctrl-b u unblocks again.

Ctrl-b Q ends the session in any mode.

Session ID

A four-word phrase generated by the relay when support runs tunl create-session, e.g. swift-fox-jumps-barrel. It is human-speakable on a support call: support reads it to the customer over the phone or pastes it into a ticket. The four-word format is drawn from curated word lists, chosen for phonetic distinctness so the ID can be dictated without confusion.

Support engineers join with an SSH key registered on the relay's support account; the session ID by itself does not let anyone join from the support side.

What the customer sees

In share mode (default), the script lays out a tmux session with two visible panes:

+----------------------------------------------------------------+
|                                                                |
| user@customer-srv:~#                       <- main shell pane  |
|                                                                |
+----------------------------------------------------------------+
| [LINBIT SHARE] swift-fox-jumps-barrel   relay connected  1v    |
|----------------------------------------------------------------|
| support: can you run `dmesg | tail`?       <- chat scrollback  |
| > _                                        <- chat input       |
+----------------------------------------------------------------+

The pinned status row at the top of the chat pane shows the connection state, viewer count, mode, and case number. Brief network blips don't end the session: the script keeps the tmux session alive across reconnects so the customer's shell, history, and working directory survive.

What gets recorded

Every session is recorded server-side on the relay (terminal cast, chat transcript, audit log of open/close/tunnel events) and a copy of the terminal recording is also written on the customer side -- the path is printed at session end so the customer can keep their own record. Password prompts and other no-echo input are not in the recordings (the OS suppresses them at the terminal layer).

What support sees

tunl join <session-id> opens a local two-window tmux that mirrors the customer's shared shell. Window 0 is the shared shell; window 1 is the chat side with a pinned status header (case number, viewers, mode, connection state). Multiple support engineers can join the same session at once -- they all see the same shell and the same chat.

Ending the session

The customer ends the session with Ctrl-b Q in the tmux window, or by closing the terminal. Anything the support side has gained -- keystroke ability, an installed support key for the reverse tunnel, a reverse port forward -- ends with it. Restarting the script with the same session ID resumes the same session.

For more depth -- the full trust model, the support-side commands (tunl ssh, tunl browser), reconnect and idle-timeout behaviour, the exact relay access controls -- see architecture.html and security.html.