Remote SSH Overview
Remote SSH gives operators a browser-based terminal to any registered embedded Linux device from the OTA-Pulse console. Sessions run through an outbound frp reverse-tunnel so the device never needs an inbound port or a public IP — NAT, CGNAT, cellular, and firewalled deployments all work the same way.
What it is
- Per-device shell access. Navigate to a device in the console, click Open Terminal, choose a tier and (for elevated tiers) provide a justification, then get a PTY in your browser.
- Three-tier model. Standard (non-root diagnostic user), Elevated (root, approval optional), and Break-Glass (root, mandatory audit trail, immediate alerting). The tier controls the OS user, recording policy, and approval requirements.
- Mandatory recording for privileged tiers. All Elevated and Break-Glass sessions are recorded at the gateway in asciinema v2 format regardless of what the operator does. The device cannot disable it.
- AND-gated authorisation. Opening a session requires both a
device.shell.<tier>role grant AND active membership in the fleet’s Shell Access Group. Holding an OTA admin or org-owner role is not sufficient on its own. - Hash-chained audit log. Every role grant, group change, policy change, session open, approval decision, and recording view is appended to a tamper-evident chain scoped to the organisation.
What it is not
- Not a mass-fleet operation tool. You open one session to one device at a time. Parallel multi-device scripting is out of scope.
- Not a file transfer UI. SCP/SFTP file transfer from the browser is deferred to a future sprint.
- Not a port-forwarding proxy. Arbitrary TCP tunnels are not supported.
- Not mobile-first. The terminal UI targets desktop browsers. Mobile is best-effort.
Three pillars
| Pillar | What it means |
|---|---|
| Per-device frp tunnel | Each device runs the frp client agent, which maintains a persistent outbound connection to the gateway. No inbound connectivity required. |
| Per-session recording | The gateway’s AsciinemaRecorder captures every PTY byte flowing through the bridge (gateway/app/recorder.py). The device never sees the capture path. |
| AND-gated authorisation | enforce_shell_access_for_tier in app/core/deps.py checks role + group on every session-open request before any side effects occur. |
Next steps
- Security Model — the full reference for roles, tiers, recording, audit chain, approvals, and token lifetimes.
- Operator How-To — step-by-step guide for opening sessions, handling network blips, and viewing recordings.
- Admin Guide — setting fleet policy, managing group membership, approving sessions, and reading the audit log.