Skip to content

Latest commit

 

History

History
329 lines (239 loc) · 12.8 KB

SSH.md

File metadata and controls

329 lines (239 loc) · 12.8 KB

SSH Host Management

par-term provides comprehensive SSH host management with automatic discovery, quick connect, SSH profiles, and automatic profile switching on remote connections.

Table of Contents

Overview

The SSH system aggregates hosts from multiple sources and provides quick access via a searchable dialog:

graph TD
    Discovery[Host Discovery]
    Config[~/.ssh/config]
    Known[~/.ssh/known_hosts]
    History[Shell History]
    MDNS[mDNS/Bonjour]
    Aggregator[Discovery Aggregator]
    QuickConnect[Quick Connect Dialog]
    Profiles[SSH Profiles]
    ProfileDrawer[Profile Drawer]
    Terminal[Terminal]

    Discovery --> Config
    Discovery --> Known
    Discovery --> History
    Discovery --> MDNS

    Config --> Aggregator
    Known --> Aggregator
    History --> Aggregator
    MDNS --> Aggregator

    Aggregator --> QuickConnect
    QuickConnect --> Terminal
    Profiles --> ProfileDrawer
    ProfileDrawer --> Terminal

    style Discovery fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    style Config fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
    style Known fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
    style History fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
    style MDNS fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
    style Aggregator fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    style QuickConnect fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    style Profiles fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    style ProfileDrawer fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    style Terminal fill:#880e4f,stroke:#c2185b,stroke-width:2px,color:#ffffff
Loading

SSH Quick Connect

The Quick Connect dialog provides fast access to all discovered SSH hosts.

Opening Quick Connect:

Platform Shortcut
macOS Cmd + Shift + S
Linux/Windows Ctrl + Shift + S

Features:

  • Real-time search filtering by alias, hostname, or username
  • Hosts grouped by source (SSH Config, Known Hosts, History, mDNS)
  • Keyboard navigation with Up/Down arrows
  • Press Enter to connect, Escape to cancel

Connection Flow:

  1. Press Cmd+Shift+S to open the dialog
  2. Type to search and filter hosts
  3. Use arrow keys to select a host
  4. Press Enter to connect
  5. The SSH command is sent to the active terminal (e.g., ssh -p 2222 user@example.com)
  6. The SSH session begins in the current tab

Note: Before the command is written to the shell, par-term validates the hostname, user, identity file, and ProxyJump host. A host whose fields contain shell metacharacters or begin with - (for example, a hostile mDNS advertisement) is rejected, and safe values are shell-quoted.

Host Discovery

par-term automatically discovers SSH hosts from four sources. Hosts are deduplicated across sources with priority: SSH Config > Known Hosts > History.

SSH Config

Source: ~/.ssh/config

Parses your SSH configuration file for host entries.

Supported directives:

  • Host — Host alias (multi-host lines like Host foo bar create separate entries)
  • HostName — Target hostname or IP address
  • User — SSH username
  • Port — SSH port number
  • IdentityFile — Path to private key (tilde ~ expanded)
  • ProxyJump — Bastion/jump host for tunneling

Note: Wildcard-only entries (e.g., Host * or Host *.example.com) are skipped since they represent defaults, not connectable targets.

Known Hosts

Source: ~/.ssh/known_hosts

Extracts hostnames from previously-connected hosts.

Supported formats:

  • Plain hostnames: github.com ssh-ed25519 AAAA...
  • Bracketed ports: [myserver.example.com]:2222 ssh-rsa AAAA...
  • Comma-separated: host1.example.com,192.168.1.1 ssh-rsa AAAA...

Note: Hashed entries (lines starting with |1|) are skipped because the hostname cannot be extracted.

Shell History

Sources:

  • Bash: ~/.bash_history
  • Zsh: ~/.zsh_history
  • Fish: ~/.local/share/fish/fish_history

Scans shell history for previous ssh commands and extracts connection details including user, host, port, and identity file.

mDNS/Bonjour Discovery

Discovers SSH hosts on the local network by browsing the _ssh._tcp.local. service type.

This feature is opt-in. Enable it in Settings > Profiles > SSH > mDNS/Bonjour Discovery, or in config (top-level keys — ssh is a flattened sub-config):

enable_mdns_discovery: true
mdns_scan_timeout_secs: 3  # Range: 1-10 seconds

When enabled, the Quick Connect dialog shows a spinner while scanning and displays discovered hosts in real time.

SSH Profiles

Profiles can act as SSH bookmarks by setting SSH-specific fields.

Creating SSH Profiles

  1. Open Settings (F12; Cmd+, on macOS, Ctrl+Shift+, on Windows/Linux)
  2. Navigate to the Profiles tab
  3. Click + New Profile
  4. Expand the SSH Connection section
  5. Fill in the SSH fields:
Field Description Example
SSH Host Hostname or IP to connect to example.com
SSH User SSH username deploy
SSH Port Port number (blank = 22) 2222
SSH Identity File Path to private key ~/.ssh/id_work
SSH Extra Args Additional SSH flags -o ServerAliveInterval=60
  1. Click Done, then Save at the bottom of the Settings window

Note: When SSH Host is set, opening the profile connects via SSH instead of launching a local shell.

Launching SSH from Profiles

Profiles with ssh_host set can be launched in several ways:

  • Profile Drawer: Toggle via the Profiles menu or the on-screen drawer button (when show_profile_drawer_button: true), then select the profile
  • New Tab Button: Click the ▾ chevron on the tab bar and select the SSH profile

The profile builds the SSH command from its fields:

ssh -p 2222 -i ~/.ssh/id_work deploy@example.com

Extra-argument filtering: ssh_extra_args is tokenized with shell-style quoting, and tokens that enable command execution, forwarding, or tunnels (-A, -D, -R, -L, -W, -w, and denied -o options such as ProxyCommand) are dropped with a logged warning. If the string cannot be parsed, all extra arguments are dropped.

Field Priority: The ssh_host field takes precedence over command. If both are set, par-term launches the SSH connection and ignores command.

Automatic Profile Switching

par-term can automatically switch profiles when connecting to SSH hosts, providing visual context for remote sessions.

Hostname-Based Switching

When an SSH session is detected, par-term monitors terminal output for the remote hostname (via OSC 7 shell-integration sequences, emitted as file://hostname/path) and searches for a profile with matching hostname_patterns.

When a match is found:

  • Profile icon appears in the tab bar
  • Tab title updates to the profile's tab name
  • Badge text and styling apply
  • Profile command runs after confirmation (if configured)

Command-Based Switching

par-term also detects when an ssh process is running in the terminal. This marks the session as remote so it can revert on disconnect; the profile match itself still comes from the OSC 7 hostname (see Hostname-Based Switching).

Auto-Revert on Disconnect

When an SSH session ends, par-term automatically reverts to the previous profile:

  • Tab icon, title, and badge restore to pre-SSH state
  • The revert happens when the SSH process exits

Reversion happens automatically when the SSH process exits or the reported hostname returns to the local machine.

Remote Tab Title Format

When shell integration detects a remote host (via OSC 7 sequences), par-term can automatically update the tab title to reflect the remote connection. The format is controlled by remote_tab_title_format:

Value Format Example
user_at_host (default) user@hostname deploy@prod.example.com
host hostname only prod.example.com
host_and_cwd hostname:~/cwd prod.example.com:~/app
remote_tab_title_format: user_at_host  # default

# When true (default), explicit OSC title sequences take precedence over
# remote_tab_title_format. Set to false to always use the format above.
remote_tab_title_osc_priority: true

Settings UI: Settings > Windows & Tabs > Tab Bar > "Remote Tab Title Format"

Note: remote_tab_title_format requires shell integration to be installed on the remote host so that OSC 7 sequences are emitted. See Integrations for installation instructions.

Remote Clipboard (OSC 52)

When a remote program copies text — for example, a selection inside a remote tmux session — it typically uses the OSC 52 escape sequence to push that text to your local clipboard. par-term bridges OSC 52 clipboard-set sequences to the system clipboard, so a copy initiated on the remote host lands in your local clipboard and is ready to paste locally (Cmd+V / Ctrl+Shift+V). No shell integration is required; it works over any SSH session.

osc52_clipboard: true  # default — set to false to stop programs overwriting your clipboard

See Mouse Features for the full OSC 52 clipboard behavior, including per-pane polling and the focused-pane caveat.

Configuration

# SSH settings — top-level keys (the `ssh` sub-config is `#[serde(flatten)]`'d
# into Config, so these write to the top of config.yaml, not under a `ssh:` block).
enable_mdns_discovery: false              # default: false
mdns_scan_timeout_secs: 3                 # range: 1-10, default: 3
ssh_auto_profile_switch: true             # default: true
ssh_revert_profile_on_disconnect: true    # default: true

# Remote tab title format (also top-level; requires shell integration on the remote host)
remote_tab_title_format: user_at_host     # user_at_host | host | host_and_cwd
remote_tab_title_osc_priority: true       # OSC titles take priority over format

Profile SSH fields (in profiles.yaml):

- id: 550e8400-e29b-41d4-a716-446655440000
  name: Production Server
  icon: "🌐"
  ssh_host: prod.example.com
  ssh_user: deploy
  ssh_port: 22
  ssh_identity_file: ~/.ssh/id_prod
  ssh_extra_args: "-o ServerAliveInterval=60"
  badge_text: "🔴 PROD"
  badge_color: [255, 0, 0]

Keybinding:

keybindings:
  - key: "CmdOrCtrl+Shift+S"
    action: "ssh_quick_connect"

Settings UI

The SSH page of the Profiles tab in Settings (F12) has a section with three sub-sections:

Profile Auto-Switching:

  • Toggle auto-switch on SSH connection
  • Toggle revert on SSH disconnect

mDNS/Bonjour Discovery:

  • Enable/disable mDNS host discovery
  • Scan timeout slider (1-10 seconds)

Quick Connect:

  • Shows the currently bound chord for ssh_quick_connect, or a hint to bind the action under Keys > Key Bindings if none is bound
  • Info about host sources

Troubleshooting

Hosts not appearing in Quick Connect:

  • Verify ~/.ssh/config exists and has valid Host entries (not just wildcards)
  • Check that ~/.ssh/known_hosts is readable
  • For mDNS hosts, ensure enable_mdns_discovery: true is set and devices are on the same network

Profile not auto-switching on SSH:

  • Ensure ssh_auto_profile_switch: true in config
  • Verify the profile has hostname_patterns that match the remote hostname
  • Shell integration must be installed on the remote host for OSC 7 hostname reporting

mDNS hosts not appearing:

  • Enable mDNS in Settings > Profiles > SSH > mDNS/Bonjour Discovery
  • Increase mdns_scan_timeout_secs for slower networks
  • Ensure the remote hosts advertise _ssh._tcp via Bonjour/Avahi

Related Documentation