| authors | state |
|---|---|
Alexey Kontsevoy ([email protected]) |
implemented |
Teleport Terminal is a desktop application that provides quick access to remote resources via Teleport. This RFD defines the high-level architecture of Teleport Terminal.
There are two main components to Teleport Terminal:
- teleterm
- tsh (daemon mode)
teleterm is an Electron application that uses Chromium engine
for its tabbed UI and nodejs for OS-level operations.
Electron has been chosen because of cross-platform support and an ability to reuse most of existing Teleport Web UI components and design system.
teleterm UI will have the following features:
- Built-in fully featured terminal based on xterm and node-pty to fork processes.
- Tabbed layout where a tab can be an ssh session, rdp connection, or any other document.
- Ability to add and access multiple Teleport clusters at the same time.
- Connection Tracker for quick access and navigation.
- Command Bar for quick command execution.
tsh daemon is a tsh tool that runs as a service. A hidden command launches tsh in a background process that exposes gRPC API over unix-socket (similarly to docker daemon).
This API is used by teleterm to call tsh internal methods to access Teleport clusters.
This makes tsh a backend service for teleterm that stores information about clusters and retrieved certificates.
tsh gRPC API allows programmatic access to tsh functionality. This includes logging into a cluster, k8s, and creating a local proxy (alpn).
It uses unix-sockets as the primary communication channel. Unix Sockets are now broadly supported as Microsoft added Unix Sockets support to Windows (Windows 10 Version 1803).
On systems where Unix Sockets are not supported, tsh can establish a localhost TLS/TCP connection where TLS certificates are re-generated at start-time by teleterm.
Only unix-sockets are supported at this time.
teleterm runs under OS local user's privileges and does not require root access. It stores its state under user’s "app data" folder.
This includes UI state, settings, and temporary files such as unix-sockets.
Currently tsh profiles are also stored there as well.
teleterm minimizes the attack surface by delegating as much as possible to tsh. For example,
SSH to a server happens via executing a local TELEPORT_CLUSTER=leafCluster tsh --proxy=rootCluster ssh login@server command and piping it to the pty.
Database access happens via creating a local alpn proxy connection over tsh API. If MFA is required, teleterm receives a notification (over gRPC stream) before alpn proxy accepts a new connection request.
UI process (Electron renderer) runs in the context isolation mode with nodejs integration turned off. UI talks to tsh API and node-pty over contextBridge.
Even though UI does have access to local shells (via contextBridge -> node-pty), using contextBridge by default helps clear access boundaries between processes.
UI will ensure that general security recommendations are implemented.
teleterm uses Electron-Builder that handles creation of packages for multiple platforms. tsh is packaged together with the
rest of the application and installed into the "app data" folder.
Electron supports automatic updates. The updates happens via a publicly exposed service that Electron trusts. This service can be hosted by the cloud team. This functionality currently is not implemented.
+------------+
| |
+-------+---------+ |
| | |
| teleport +--+
| clusters |
| |
+------+-+--------+
^ ^ External Network
+------------------------------------------------|-|---------------------+
| | Host OS
Clients (psql) | |
| | |
v | |
+--------+---------------+ | |
| | SNI/ALPN | |
+--+----------------------+ | routing | |
| | | | |
| proxy connections +-+ | |
| | | |
+-------------------+-----+ | |
^ | |
| | |
+---------------+ | tls/tcp on localhost | |
| tsh profiles | | | |
| (files) | | v v
| | | +------+-+-------------------+
+-------^-------+ | | |
| +-------------------+ tsh |
+<------------------------------+ (daemon) |
| |
+-------------+--------------+
+--------+-----------------+ ^
| Terminal | |
| Electron Main Process | | gRPC API
+-----------+--------------+ | (domain socket)
^ |
| |
IPC | |
named pipes | |
v Terminal UI (Electron Renderer Process) |
+-----------+------------+---------------------------------------------+
| -recently used | root@node1 × | k8s_c × | rdp_win2 × |
| root@node1 +---------------------------------------------+
| root@node2 | |
+------------------------+ ./ |
| -clusters | ../ |
| -cluster1 | assets/ |
| servers (20) | babel.config.js |
| databases (12) | |
| +cluster2 | |
| +cluster3 | |
+------------------------+---------------------------------------------+