Skip to content
Panix

SSH

Connect to machines you are provisioning by specifying separate regular and bootstrap SSH credentials.

Fragment: nest under fleet.flakes.<flake>.installables.<type>.<name>.machines.

machines:
  server:
    ssh:                          # Regular SSH (after bootstrap)
      hostname: 192.168.1.100
      port: 9999
      identity_file: ./keys/prod.key
    bootstrap:
      ssh:                        # Bootstrap SSH (during bootstrap)
        hostname: 192.168.1.100
        identity_file: ./keys/temp.key

Requirements

Section titled “Requirements”
  • Unbootstrapped machines: must have bootstrap SSH configured (unless force_bootstrap: true)
  • Bootstrapped machines: must not have bootstrap SSH configured (unless force_bootstrap: true)
  • The Inspect phase errors if the SSH configuration does not match the machine state (bootstrap SSH on a bootstrapped machine, or regular SSH on an unbootstrapped one)
  • SSH keys: see SSH Setup for creating and installing a key
  • Non-root SSH users: bootstrap as a non-root user is not end-to-end supported. Bootstrap commands that need root (kexec staging reset, disko, nixos-install, reboot, secret transfers) run via the configured sudo_program and need passwordless sudo (Panix cannot answer password prompts). Additionally, the closure copy into the installer’s /mnt runs as the SSH user, so the full bootstrap flow assumes a root SSH user; SSH as root for the bootstrap phase.

Workflow

Section titled “Workflow”
  1. During Inspect: Panix validates that SSH configuration matches machine state
  2. While bootstrapping: bootstrap SSH is used for all bootstrap operations; after reboot, Panix switches to regular SSH as part of running the post_bootstrap_provisioned_hooks (with no provisioned hooks, the run ends right after the reboot)
  3. On already bootstrapped machines: regular SSH is used

SSH Key Checking Options

Section titled “SSH Key Checking Options”

Defaults:

ssh:
  # Disable strict host key checking (default: false for both regular and bootstrap SSH)
  disable_strict_key_checking: false
  # Disable auto-adding host keys (default: false for both regular and bootstrap SSH)
  disable_auto_add_host_key: false
  # Path to known_hosts file (default: user's ~/.ssh/known_hosts; bootstrap SSH uses a temporary file)
  known_hosts_file: ""

Behavior

Section titled “Behavior”
  • Regular SSH: uses the user’s ~/.ssh/known_hosts with StrictHostKeyChecking=accept-new (trusts new machines, verifies against existing entries)
  • Bootstrap SSH: Panix creates a temporary known_hosts file for the session. The first connection records the installer’s host key (trust on first use); all subsequent commands verify against it, preventing man-in-the-middle attacks mid-session. If known_hosts_file is set, that file is used instead. The temporary file (but not the user set one) is removed when the machine’s entire workflow finishes, not when bootstrapping completes.
  • After kexec: the kexec installer preserves SSH host keys from the original system, so the recorded key remains valid. If the kexec SSH port differs from the bootstrap SSH port, a new [host]:port entry is recorded for the new port (same key, different entry).
  • disable_strict_key_checking: true disables all host key checking (UserKnownHostsFile=/dev/null, StrictHostKeyChecking=no)