Protocols

What “supported” means

sortOfRemoteNG distinguishes four kinds of protocol surface. This matters because a backend crate, an importer mapping, or a settings form does not by itself make a usable connection tab.

The executable contract is src/utils/session/protocolAvailability.ts. The session manager consults it before creating a direct session, and the regression test tests/session/protocolAvailability.test.ts checks every persisted protocol and every protocol advertised by the primary editor.

Saved connection protocols

SSH-family host keys and known_hosts

SSH, SFTP, and SCP resolve host keys through the Trust Center rather than through OpenSSH’s known_hosts file. Records are keyed by host:port with a SHA-256 fingerprint, so one accepted key covers the terminal, the file browser, and SCP for the same endpoint, and they are stored per database in databases/<id>.trust.json — encrypted whenever the database is. A key already trusted for that database is accepted with no prompt; a changed key always takes the mismatch path, even when known_hosts still matches the old one; a revoked record is refused outright.

known_hosts remains an import source. An unknown key that matches the configured or default known_hosts file is adopted into the Trust Center and accepted instead of re-prompting, and Settings → Trust Center can import the whole file on demand. Hashed (|1|…) entries, wildcard and negation patterns, and undecodable keys are reported as skipped rather than guessed at, and an endpoint already recorded is never overwritten — an import cannot re-trust a key you rejected or revoked.

Accepting a new key still appends it to known_hosts by default so other tools sharing that file keep working. also_write_known_hosts — a per-connection option on SSH, SFTP, and SCP connections, defaulting to true, so connections saved before this behavior existed are unchanged — turns the dual write off and keeps the decision inside the database. The shared file is written before the Trust Center record, so a failure to write it aborts the connection with nothing memorized in either place.

With no database open there is nothing to consult: host-key verification fails closed with an error naming the fix rather than falling back to known_hosts. See Security for the storage, encryption, and migration details.

VoIP Phone (Yealink T2x)

The voip-phone protocol manages Yealink desk phones through their web-admin interface. It is modelled with a vendor field (yealink today) so other vendors can be added as drivers later without touching the protocol registry. Verified targets are the SIP-T20P and SIP-T21P, including the T21P E2. Other Yealink models that share the T2x web admin may work but are not verified.

Firmware generations

Yealink changed the web admin between firmware lines. The driver probes the phone on connect and picks the matching path; the detected generation is shown as a badge in the session panel and can be forced through Login mode in the editor if detection fails.

Both generations report the same normalised status shape (model, firmware, hardware, MAC, IP, uptime, per-account registration); unknown fields are kept in rawFields for diagnostics.

Enable Action URI for reboot

Reboot tries the phone’s Action URI first (http://<phone>/servlet?key=Reboot or the legacy cgi-bin/ConfigManApp.com?key=Reboot). Yealink phones reject Action URI calls (HTTP 403) unless remote control is enabled and the caller’s IP is allowed. On the phone’s web admin:

1. Open Features → Remote Control.
2. Set Action URI Allow IP List to this computer’s IP address (or any on a trusted network).
3. Save and, on older firmware, reboot once for the setting to take effect.
4. Tick Action URI enabled on the phone in the connection’s Advanced tab so the panel reports the expected method.

If the Action URI is refused or disabled, the reboot falls back to the authenticated web-admin reboot form, so the button still works; the completion toast names the method that was accepted (action-uri or web-form).

Transport and credentials

• Default port is 80 over plain HTTP. Enable Use HTTPS (and usually change the port to 443) for phones with TLS turned on. Phones ship self-signed certificates, so the first HTTPS connection is pinned (trust on first use) and later certificate changes are rejected unless Verify server certificate is disabled for that connection.
• Username and password live on the saved connection (Basics). Opening the web UI creates an http/https session through a runtime-registered connection with auto-login selectors; the password is never copied onto the session object, logs, or serialized status types.

Serial device selection

A Serial connection stores a device selection mode in serialSettings.portSelection alongside the line settings. fixed (the default, and what every connection saved before this field existed reopens as) uses the saved device path exactly as typed. The three automatic modes exist because USB serial adapters get a different COMn / ttyUSBn name on every machine and USB socket:

Resolution happens in the native backend on every connect and reconnect, from a fresh port enumeration, so hot-plugging and re-seating an adapter needs no edit to the connection. Candidates are ordered by natural name (COM3 before COM10, /dev/ttyUSB0 before /dev/ttyUSB1) so “first” is stable regardless of the OS enumeration order; ports already held by another session in this app are skipped, so two automatic connections never silently share one device. The resolver never opens candidate ports while choosing (probing would toggle DTR and reset devices such as Arduinos); a port held by another program fails at open time as before. When nothing matches, the session fails with No serial device is attached that matches "<mode>" plus a summary of the devices that were seen, so “nothing plugged in” is distinguishable from “wrong filter”; Reconnect re-resolves. The chosen port replaces the placeholder in the session header (Serial · COM7 with an auto · first USB badge whose tooltip is the full device description) and in the session status line (SERIAL to COM7); the saved connection keeps its auto:first-usb / auto:first-device / auto:match placeholder. The editor’s Preview button runs the same resolution without opening the port.

ARD and Apple Account authentication

ARD presents three distinct authentication paths, not three interchangeable password formats. A portable profile can keep the macOS-only handoff and one embedded fallback together while preserving that separation:

1. An embedded session can authenticate with an account authorized by the remote Mac, including an eligible local or directory-backed account.
2. An embedded VNC-compatible session can use the dedicated password configured for VNC viewers on the remote Mac. That password must be unique and must not reuse an Apple Account password, a local-user password, or a Remote Desktop administrator password.
3. An Apple Account connection is a macOS-only external handoff. sortOfRemoteNG saves the non-secret Apple Account identifier, opens Screen Sharing.app, and leaves password entry, two-factor authentication, connection approval, and the remote session inside Apple’s process. On Windows, Linux, or a Mac where the native handoff is unavailable, a portable profile resolves to its explicitly selected embedded fallback; without a valid fallback it fails closed.

Sign in with Apple identity tokens are scoped to the application or web service requesting them; they are not ARD/RFB credentials. Apple app-specific passwords likewise do not authenticate ARD/RFB. Apple documents entering an Apple Account in Screen Sharing.app, but does not document a public URL scheme or API for pre-filling an Apple Account connection, so the handoff does not attempt to automate Apple’s authentication UI.

Credential-bearing, full-fidelity JSON exports preserve the saved identifier, fallback selection, and embedded credentials according to the selected storage/export policy. Credential-free JSON exports retain the non-secret fallback selection but omit the Apple Account identifier and generic username/password, so setup may be required after import. Neither JSON export path can contain an Apple Account password or two-factor authentication code because sortOfRemoteNG never receives those values.

Embedded ARD connects directly to the saved host and port. A system VPN can supply reachability, but the protocol does not manage that VPN and rejects app proxy, SSH-hop, and tunnel-chain routing rather than silently bypassing it.

See Apple Screen Sharing and portable ARD access for setup, security boundaries, and the supporting Apple documentation.

Import mappings versus runtime support

The native and vendor importers normalize recognized names into saved connection protocols. For example, RAW variants map to raw, RLogin maps to rlogin, and PowerShell-like entries map to winrm. The shared persistence boundary also maps the legacy postgres alias to canonical postgresql. Those destinations now have interactive clients, but conversion can preserve only fields represented by the source format. Review transport, authentication, trust, and protocol-specific settings after import.

Recognizing a protocol during import still does not widen its runtime capabilities: imported FTP remains passive/EPSV and direct-route only, imported SCP retains its explicit host-key policy and direct-route boundary, and imported VNC settings still require review of the target, credentials, and any legacy-security exceptions before use. Imported AnyDesk and RustDesk entries still require their installed native clients. See Import, Export & Clone for the review workflow.

Cloud and Lights-Out management panels

The active picker now offers twelve saved management connections in the Cloud Platforms and Lights-Out & BMC groups. Each has a dedicated SessionViewer panel, native command registration, validation, and teardown. They are interactive management panels, not interchangeable terminal or desktop transports.

Required fields, protected credential boundaries, legacy migration, lease behavior, rollback, and recovery are documented in Cloud & Lights-Out Connections.

Service integrations use the separate integration:* descriptor contract and route through src/components/integrations/IntegrationPanelHost.tsx. Their support level belongs to each integration panel and is not inferred from this direct-session matrix.

Audited implementations not exposed as saved direct sessions

These implementations are included in the audit because their hooks, backend crates, or templates can otherwise look like finished protocols.

Verification boundaries

The protocol matrix is checked at three layers:

1. BuiltInConnectionProtocol is exhaustively mapped at compile time. Adding a persisted protocol without declaring its runtime truth fails TypeScript compilation.
2. tests/session/protocolAvailability.test.ts verifies that every primary editor option is client-owned, every built-in direct protocol appears exactly once, and all management-only identities remain absent from the picker.
3. tests/session/SessionViewer.test.tsx verifies that dedicated clients mount during connecting and reconnecting states, before any runtime can honestly report success.

Focused protocol tests cover the transport-specific behavior. FTP verifies native DTOs, redacted credential logging, lifecycle, direct file operations, and fail-closed routing/modes. SCP verifies host-key policy mapping, known_hosts handling, lifecycle, direct file/directory operations, and fail-closed routing. PostgreSQL verifies DTO construction, SSL validation, secret redaction, direct-route rejection, lifecycle/reconnect, typed native values, and command registration. SPICE, XDMCP, X2Go, and NoMachine verify exact native-process launch contracts, secret handling, fail-closed options/routes, reattach, polling, and final close without claiming remote readiness. Raw Socket and RLogin have native Rust end-to-end tests; Telnet verifies native connect/events/exact input; Serial verifies configuration, byte streaming, echo, controls, and cleanup; ARD verifies framebuffer/input and command parity; and PowerShell verifies PSRP over SSH and WSMan. Live WinRM, SSH, FTP/SCP, PostgreSQL, VNC, native-client, and hardware-backed Serial checks remain environment-dependent because they require reachable targets, credentials, local applications, devices, or drivers—an ignored live fixture is not counted as a passing connection.

Choosing a path

• Prefer SSH, RDP, ARD, or PowerShell Remoting for their intended interactive workloads.
• Prefer SFTP for the broadest in-app file-management surface; use FTP/FTPS or SCP when the target specifically requires them and the direct-route limits fit.
• Use PostgreSQL for an isolated native database workbench when a direct target and the configured SSL policy fit.
• Use VNC for native TCP/RFB endpoints, keeping legacy transport and authentication exceptions disabled unless a trusted isolated environment requires them. VeNCrypt/TLS and Tight security negotiation are not yet supported.
• Treat AnyDesk and RustDesk as native application handoffs and install their clients first.
• Install virt-viewer, X2Go Client, or NoMachine Client before using SPICE, X2Go, or NX; use their native authentication prompts and treat app status as local-process status only.
• Use XDMCP only on a trusted isolated network after accepting its unauthenticated, unencrypted transport boundary and installing a supported local X server.
• Use Telnet and RLogin only when a legacy system requires them; both expose credentials and traffic unless the surrounding network supplies protection.
• Use Raw Socket only when you understand the target framing and security model.

For routing compatibility, continue to Network Paths. For source boundaries and backend layering, see Architecture.