tailrescue-headscale-iso/skills/devops/tailrescue-headscale-live-iso/SKILL.md

name, description, version, author, license, metadata

name	description	version	author	license	metadata
tailrescue-headscale-live-iso	Use when building, testing, or operating a Ventoy/iVentoy Debian Live rescue ISO that auto-enrolls into PharmQ Headscale/Tailscale for remote SSH and Windows/NTFS backup.	1.0.0	Hermes Agent	MIT	hermes tags related_skills devops live-iso headscale tailscale ventoy rescue ntfs gitea-pat-askpass-push nested-pve-auto-install-lab

TailRescue Headscale Live ISO

Overview

This project builds a Debian Live rescue ISO for field PCs. It should boot from Ventoy/iVentoy/Proxmox, get DHCP on common Ethernet NICs, enroll into https://head.pharmq.kr, start OpenSSH, and expose disk/NTFS read-only backup helpers.

Current Verified Baseline

• Build host: pve7
• Test VM: pve7 VMID 990
• Verified SSH over Tailnet: rescue@100.64.0.80
• Verified commands: rescue-status, list-disks
• Verified packages: tailscale, openssh-server, ntfs-3g, firmware packages
• Verified ISO hash: 3d7995cfdf58c62f6ee167458079a7eaa1d2a79ac56e5f019cab1ec856943ddd

Repository Policy

Commit scripts, docs, templates, and this skill. Do not commit ISO files, rescue.env, preauth keys, passwords, private keys, live-build chroot/, binary/, cache/, or other build artifacts.

Build Flow

1. Create a short-lived Headscale preauth key:

./scripts/headscale-create-preauth.sh

2. Create local secrets:

cp templates/rescue.env.example rescue.env
cp templates/authorized_keys.example templates/authorized_keys

3. Fill rescue.env and templates/authorized_keys without committing them.
4. Build:

./scripts/build-live-iso.sh

Proxmox Test Flow

cp /root/tailrescue-dist/$(cat /root/tailrescue-dist/latest.txt) /var/lib/vz/template/iso/tailrescue-headscale-test.iso
./scripts/test-proxmox-vm.sh
ssh rescue@100.64.x.y 'echo SSH_OK; sudo -n true; rescue-status; list-disks'

Field Flow

1. Copy ISO to Ventoy USB or iVentoy ISO folder.
2. Boot target PC and select the ISO.
3. Press Enter at Debian Live menu if needed.
4. Wait 1-2 minutes.
5. Find tailrescue-* in Headscale.
6. SSH to rescue@100.64.x.y.
7. Run list-disks.
8. Mount Windows partition read-only:

sudo mount-ntfs-ro /dev/sdXN /mnt/windows

Ethernet Coverage

The ISO includes Debian 12 kernel and broad firmware: firmware-linux, firmware-linux-nonfree, firmware-misc-nonfree, firmware-realtek, firmware-atheros, firmware-brcm80211, firmware-bnx2, firmware-bnx2x, firmware-iwlwifi, firmware-libertas. Carry USB Ethernet dongles such as Realtek RTL8153/RTL8156 or ASIX AX88179 for field fallback.

Common Pitfalls

1. SSH may connect but auth can fail if the rescue user is only created in firstboot. Keep the chroot hook that creates rescue, sudoers, sshd config, and authorized keys at build time.
2. Headscale duplicate ephemeral nodes can appear because live ISOs reuse machine IDs. Use the newest online Tailnet IP.
3. Never write to real rescue disks by default. Mount NTFS read-only.
4. Separate Ventoy/iVentoy boot problems from Linux NIC/firmware problems.
5. Rotate preauth keys and fallback passwords per field build.

Verification Checklist

• ISO boots in Proxmox VM.
• Headscale node appears as tailrescue-*.
• ssh rescue@100.64.x.y works with public key.
• sudo -n true works.
• rescue-status shows LAN and tailscale0 IPs.
• list-disks shows internal disks.
• ntfs-3g, ntfs-3g.probe, and ntfsfix are present.
• No secrets or ISO files are staged in Git.