Skip to content

Latest commit

 

History

History
392 lines (309 loc) · 16.8 KB

SNAP.md

File metadata and controls

392 lines (309 loc) · 16.8 KB

RustConn Snap Package

RustConn is available as a Snap package with strict confinement for enhanced security. Both rustconn (GUI) and rustconn-cli are included.

Build platform: the snap is built on core26 (Ubuntu 26.04 base) via the snapcraft gnome extension, which provides the gnome-core26 platform (GTK 4.24, libadwaita 1.10) and takes GPU drivers from mesa-2604. The snap is built with adw-1-8, so it gets the same libadwaita 1.8 widget tier the Flatpak ships. Building needs Snapcraft 9.2 or newer, the first release whose gnome extension accepts core26 (an earlier 0.23.2 attempt was reverted for exactly that reason; issue #174). On first update, snapd downloads the gnome-core26 and mesa-2604 platform snaps. The embedded web browser (WebKitGTK 6.0) is built in and comes from the same platform; see Embedded web browser for its sandbox caveat.

Installation

sudo snap install rustconn

Apps

App Command Description
GUI rustconn GTK4 connection manager
CLI rustconn.rustconn-cli Command-line interface
# GUI
rustconn

# CLI
rustconn.rustconn-cli --help
rustconn.rustconn-cli list
rustconn.rustconn-cli add --name myserver --protocol ssh --host 192.168.1.10

Strict Confinement

This snap uses strict confinement with embedded Rust protocol implementations. External CLIs (Zero Trust, password managers, kubectl) can be downloaded on demand via the Components dialog (Menu → Components) inside the sandbox — no host access required.

Automatic Interfaces

These interfaces are connected automatically:

Interface Purpose
network Network access for connections
network-bind Listening on network ports
audio-playback RDP audio playback
desktop, wayland, x11 GUI access
gsettings GNOME settings
home Access to home directory
opengl GPU rendering

Manual Interface Connections

These interfaces require manual connection after installation:

# System keyring (GNOME Keyring / KDE Wallet — required for password storage)
sudo snap connect rustconn:password-manager-service

# SSH keys (required for SSH connections)
sudo snap connect rustconn:ssh-keys

# Serial port access (for serial console connections)
sudo snap connect rustconn:serial-port

# Cloud provider credentials
sudo snap connect rustconn:aws-credentials       # ~/.aws (read-write for SSO token cache)
sudo snap connect rustconn:gcloud-credentials     # ~/.config/gcloud (read-only)
sudo snap connect rustconn:azure-credentials      # ~/.azure (read-only)
sudo snap connect rustconn:oci-credentials        # ~/.oci (read-only)

# Kubernetes config
sudo snap connect rustconn:kube-credentials       # ~/.kube (read-only)

Screen lock and suspend

When a jump-host (-J) connect, SFTP or Midnight Commander needs a key the SSH agent does not hold, RustConn adds it with a 12-hour lifetime and later removes exactly those keys again. In the snap:

  • Exit: the keys are removed when you quit RustConn.
  • Screen lock: the keys are removed. The desktop interface, connected automatically, lets RustConn receive the screensaver's ActiveChanged signal.
  • Suspend: not detected. The snap declares no interface that delivers login1's PrepareForSleep, and a snap user can only connect interfaces the snap declares, so there is no step that turns it on. The keys stay in the agent while the machine sleeps.
  • 12-hour lifetime: applies in every case, also after a crash.

Bundled Components

The snap includes all core protocol clients — no separate installation needed:

Component Purpose
openssh-client SSH client
IronRDP Embedded RDP client
vnc-rs Embedded VNC client
inetutils-telnet Telnet client
picocom Serial console (RS-232/USB)
Midnight Commander SFTP file browser
waypipe Wayland application forwarding over SSH

Embedded Protocol Clients

Protocol Implementation Notes
SSH VTE terminal Always embedded
RDP IronRDP + bundled FreeRDP (xfreerdp3) Embedded by default; the bundled X11 FreeRDP client is the external client and the fallback (see below)
VNC vnc-rs Embedded only — no external TigerVNC fallback in the snap
SPICE — Not available in the snap: no viewer is bundled, and strict confinement cannot start the host's remote-viewer
Telnet Bundled inetutils VTE terminal session
Serial Bundled picocom VTE terminal session; requires serial-port interface
Kubernetes Components kubectl Requires kube-credentials
SFTP Bundled mc Midnight Commander FISH VFS
Waypipe Bundled waypipe Wayland forwarding over SSH
Web WebKitGTK 6.0 from the gnome-core26 platform Embedded tab, system browser or custom command; the embedded content is not WebKit-sandboxed in the snap (see below)

Embedded web browser (WebKitGTK)

New in 0.24.0 (issue #244). Web connections can open in an embedded WebKitGTK tab, as in the Flatpak and the native packages. The snap does not carry WebKit itself: libwebkitgtk-6.0 and libjavascriptcoregtk-6.0 (WebKitGTK 2.52) come from the gnome-core26 platform snap and are updated together with it. WebKit finds its helper processes through the /usr/lib/<arch>/webkitgtk-6.0 layout that the snapcraft gnome extension adds for core26.

Security caveat — no WebKit sandbox inside a snap. WebKit isolates web content with bubblewrap and seccomp, but it switches that off by itself whenever it runs inside a snap, and WebKitGTK 6.0 offers no way to turn it back on. The web and network processes therefore run as ordinary child processes of RustConn, confined only by the snap's strict confinement. They have the same access as RustConn itself: your home directory, SSH keys (ssh-keys), the cloud credential folders you connected, the system keyring (password-manager-service), the network (network, network-bind) and the X11 socket (x11, which lets a compromised process watch keystrokes of other XWayland/X11 applications). That includes RustConn's own data in ~/snap/rustconn/ (the connection list, settings, session logs that may contain terminal output, the cookies of your other Web connections) and the temporary credential files RustConn creates for SSH tunnels. The list is an example, not a complete one. A browser-engine exploit in a page you open could therefore reach those. The Flatpak (flatpak-spawn --sandbox) and the native packages (bubblewrap) keep the web content in a sandbox of its own.

RustConn sets no WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS for the snap: inside a snap WebKit already runs without its sandbox, so the variable would change nothing.

Despite that caveat, the embedded browser is the default in the snap, the same as in the Flatpak and the native packages:

  • New Web connections, mRemoteNG and CSV imports, and the connection dialog's Mode list default to Embedded. Open Browser via Tunnel defaults to the in-app browser too.
  • For a connection where the missing sandbox matters, choose System or Custom in the connection dialog's Mode list. For the tunnelled browser, turn off Settings → Interface → Connections → Open tunnelled browser in the embedded browser to use an external Chromium-based browser instead.
  • Open Browser via Tunnel with no usable external Chromium-based browser opens the embedded browser instead, with a toast explaining the fallback — it never silently falls back to the system browser, which cannot take the SOCKS proxy. A Web connection that tunnels through SSH needs Embedded or a Chromium Custom command: System opens it without the tunnel.
  • Or use the Flatpak or a native package, which keep web content in a sandbox.

Embedded browser cookies and cache live under the snap's user data (see Data Locations).

If an embedded tab stays blank, look for AppArmor denials:

journalctl -f | grep -i 'apparmor.*DENIED.*rustconn'

Serial Console

Serial connections use the bundled picocom client. Connect the serial-port interface:

sudo snap connect rustconn:serial-port

Your user must also be in the dialout group for serial device access:

sudo usermod -aG dialout $USER
# Log out and back in for the change to take effect

External CLIs (On-Demand Download)

External CLIs (Zero Trust providers, password managers, kubectl) are downloaded on demand via the Components dialog (Menu → Components) inside the sandbox. CLIs install into $SNAP_USER_DATA/cli/ and are available for connections automatically — no host access is required.

Protocol viewers do not appear here. FreeRDP publishes no pre-built Linux binaries and the TigerVNC download is marked as not working in a sandbox, so neither is a downloadable component. RDP instead has FreeRDP's X11 client bundled in the snap (below); VNC uses the embedded vnc-rs client only.

External RDP client (bundled FreeRDP)

New in 0.22.7. The snap ships xfreerdp3 from Ubuntu's freerdp3-x11 package. RustConn finds it inside the snap, so it is used for everything the embedded IronRDP client cannot do:

  • the legacy RDP security layer and TLS-only servers (e.g. Windows 2008 R2)
  • RemoteApp
  • audio left playing on the remote computer
  • an RD Gateway whose target listens on a port other than 3389 (the embedded client tunnels the usual case through the gateway itself)
  • connections set to the External client mode, including Smart sizing and Dynamic resolution

It is the X11 client — it runs through XWayland on a Wayland session, and it is the client RemoteApp needs. The Wayland client (wlfreerdp3) is deprecated upstream and is not bundled. Before 0.22.7 the snap had no external RDP client at all, and those connections could not be made.

The snap is on base: core26 (Ubuntu 26.04), whose archive also packages the SDL3 client as freerdp3-sdl — the upstream-preferred client that the Flatpak already bundles. The snap deliberately stays on freerdp3-x11 for now; switching to the SDL client is a possible follow-up that needs its own RemoteApp and strict-confinement test.

Available CLIs

CLI Purpose
aws AWS SSM connections
gcloud GCP IAP connections
az Azure Bastion connections
oci OCI Bastion connections
cloudflared Cloudflare Tunnel
tsh Teleport
tailscale Tailscale
boundary HashiCorp Boundary
kubectl Kubernetes
pywinrm Run Local Script .ps1 files on WinRM hosts
bw Bitwarden CLI
op 1Password CLI
passbolt Passbolt CLI
keepassxc-proxy KeePassXC proxy

Zero Trust CLIs

Download the CLIs you need from the Components dialog, then connect the credentials interfaces:

# AWS SSM
sudo snap connect rustconn:aws-credentials

# GCP IAP
sudo snap connect rustconn:gcloud-credentials

# Azure Bastion
sudo snap connect rustconn:azure-credentials

# OCI Bastion
sudo snap connect rustconn:oci-credentials

# Kubernetes
sudo snap connect rustconn:kube-credentials

For CLI installation instructions, see INSTALL.md — Zero Trust CLI Tools.

Password Manager CLIs

Download the CLI from the Components dialog. No additional interface connections are needed for password manager CLIs (they run inside the sandbox).

Manager Host package Notes
Bitwarden bw npm install -g @bitwarden/cli or snap: sudo snap install bw
1Password op 1password.com/downloads/command-line
Passbolt go-passbolt-cli passbolt.com
KeePassXC keepassxc-proxy keepassxc package

Quick Setup

Connect all commonly used interfaces at once:

# Essential
sudo snap connect rustconn:ssh-keys

# Serial console
sudo snap connect rustconn:serial-port

# Cloud credentials (connect only what you use)
sudo snap connect rustconn:aws-credentials
sudo snap connect rustconn:gcloud-credentials
sudo snap connect rustconn:azure-credentials
sudo snap connect rustconn:oci-credentials
sudo snap connect rustconn:kube-credentials

Data Locations

Due to snap confinement, RustConn stores data in snap-specific locations:

Data Path
Connections ~/snap/rustconn/current/.local/share/rustconn/
Config ~/snap/rustconn/current/.config/rustconn/
Session logs ~/snap/rustconn/current/.local/share/rustconn/logs/
Embedded browser data ~/snap/rustconn/current/.local/share/rustconn/webkit/ (cache: ~/snap/rustconn/common/.cache/rustconn/webkit/)

Troubleshooting

SSH connections fail

  • Ensure ssh-keys interface is connected: sudo snap connect rustconn:ssh-keys
  • Check that SSH keys are in ~/.ssh/

SSH agent does not work (known limitation)

The host SSH agent ($SSH_AUTH_SOCK) is not reachable from the strictly confined snap. snapd has no interface that exposes the agent socket (unlike Flatpak's --socket=ssh-auth), so agent-based authentication and agent forwarding (ForwardAgent) cannot work in the snap package.

Workarounds:

  • Use key files directly (the ssh-keys interface grants read access to ~/.ssh/); passphrases are prompted in the terminal
  • If your workflow relies on the SSH agent, prefer the Flatpak or native package

Zero Trust / kubectl CLI not found

  • Open the Components dialog (Menu → Components) and download the CLI
  • Connect credentials: e.g. sudo snap connect rustconn:aws-credentials

Serial port permission denied

  • Connect interface: sudo snap connect rustconn:serial-port
  • Add user to dialout group: sudo usermod -aG dialout $USER
  • Log out and back in

Check connected interfaces

snap connections rustconn

Comparison with Other Packages

Feature Snap (strict) Flatpak Native (.deb/.rpm)
Security High (strict) High (sandbox) Medium
Setup Manual interfaces Automatic None needed
SSH/RDP/VNC Embedded Embedded Embedded
External RDP client Bundled xfreerdp3 Bundled sdl-freerdp Host FreeRDP
SPICE Not available External (host remote-viewer) External (remote-viewer)
SSH agent Not available (no snapd interface) Host agent via ssh-auth socket Host agent
Telnet Bundled Bundled Host CLI
Serial Bundled Bundled Host CLI
Waypipe Bundled Bundled Host CLI
Embedded web browser Yes, but no WebKit sandbox (snap confinement only) Yes, WebKit sandbox (flatpak-spawn --sandbox) Yes, WebKit sandbox (bubblewrap)
Kubernetes Components kubectl Components kubectl (flatpak-spawn) Host kubectl
WinRM Not available, use SSH; Components pywinrm for Run Local Script Host evil-winrm (flatpak-spawn); Components pywinrm Host evil-winrm and python3-winrm
Zero Trust Components CLIs Components CLIs (flatpak-spawn) Host CLIs
Password CLIs Components CLIs Components CLIs (flatpak-spawn) Host CLIs
CLI downloads Components dialog Components dialog —

Flatpak Components — Flatpak users can download additional CLI tools (Zero Trust, password managers, kubectl) directly within the sandbox via Menu → Components. Both sandboxed builds bundle a FreeRDP client for the external RDP path: the Flatpak the SDL3 client, the snap the X11 client (xfreerdp3). See User Guide — Flatpak Components for details.

Why the Components dialog shows three sections, not four — the dialog hides any category with no sandbox-compatible, downloadable component. The Protocol Clients category currently holds only the external TigerVNC vncviewer, which needs host display access that strict confinement does not grant (works_in_sandbox: false), so that section is omitted inside a sandbox and only Zero Trust CLIs, Password Manager CLIs and Container Orchestration remain. This is expected: the embedded RDP (IronRDP) and VNC (vnc-rs) clients are the preferred path, and the external protocol-client downloads are only a fallback for non-sandboxed installs (issue #342). On ARM64 the Bitwarden CLI is additionally not offered (it has no ARM64 build), so the Password Manager section lists 1Password only — the section count is still three.

Recommendation:

  • Flatpak: Recommended for most users. Full functionality with on-demand CLI downloads.
  • Snap: Good for users who prefer strict confinement; on-demand CLI downloads and manual interface connections.
  • Native: Full functionality with all host CLIs, no sandboxing overhead.