Join the tailnet from a cidata tailscale_authkey (#97)

* Join the tailnet from a cidata tailscale_authkey

A tailscale_authkey file on the autoinstall drive gets the installed
machine onto the tailnet on its own: the tailscale package is bundled in
the offline mirror and installed only when the key is present, the key is
staged root-only at /etc/tailscale/authkey, and a oneshot first-boot unit
runs tailscale up once the network is really there. On success the key is
deleted and the unit disables itself; on failure both survive to retry on
the next boot, so an offline install joins whenever it first gets
connectivity. ufw allows traffic in on tailscale0 via the same
write-the-rule-then-ignore-the-chroot-exit-code dance as the SSH phase.

Bundling rather than fetching at first boot is deliberate: pacman -Sy
tailscale on a fresh machine is a partial upgrade, and pacman -Syu means
an unattended full system upgrade racing the user's first login. The
offline mirror is a coherent snapshot; installing from it keeps the
target consistent and the install offline-capable. See plans/tailscale.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xc74h4WSYpuYPGuYbFAR1q

* Do not hold boot hostage for the tailnet join

Review caught that the join unit was Type=oneshot wanted by
multi-user.target: target units implicitly gain After= for their Wants=,
so an offline machine's boot -- SDDM included -- stalled for the full
10-minute timeout, and once timed out the join never retried within that
boot. Type=simple counts as started the moment it forks, so boot proceeds
while the join retries in the background for as long as the boot lasts.
Cleanup moves inside the script, sequenced after tailscale up succeeds,
which preserves the retry-across-boots behavior: key and unit survive a
boot with no connectivity, and the key never outlives a successful join.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xc74h4WSYpuYPGuYbFAR1q

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
David Heinemeier HanssonandClaude Fable 5 authored and GitHub committed 2026-08-07 15:10:30 +02:00
1 parent 4d10233371
commit 0339b13d12
11 files changed
+419 -3

No files matched your search

@@ -38,7 +38,7 @@ mount -o ro "$device" "$mnt" || exit 1
loaded=1
if [[ -f $mnt/user_configuration.json && -f $mnt/user_credentials.json ]]; then
files=("$mnt"/user_configuration.json "$mnt"/user_credentials.json)
for file in user_full_name.txt user_email_address.txt user_encrypt_installation.txt authorized_keys; do
for file in user_full_name.txt user_email_address.txt user_encrypt_installation.txt authorized_keys tailscale_authkey; do
[[ -f $mnt/$file ]] && files+=("$mnt/$file")
done
if cp "${files[@]}" "$dest"/; then
@@ -17,6 +17,7 @@ while [[ $# -gt 0 ]]; do
--email-file) export OMARCHY_INSTALL_EMAIL_FILE="$2"; shift 2 ;;
--encrypt-file) export OMARCHY_INSTALL_ENCRYPT_FILE="$2"; shift 2 ;;
--authorized-keys-file) export OMARCHY_INSTALL_AUTHORIZED_KEYS_FILE="$2"; shift 2 ;;
--tailscale-authkey-file) export OMARCHY_INSTALL_TAILSCALE_AUTHKEY_FILE="$2"; shift 2 ;;
*) echo "omarchy-iso-install: unknown arg $1" >&2; exit 2 ;;
esac
done
@@ -19,6 +19,7 @@ class InstallContext:
email: str
encrypt: bool
authorized_keys_path: Path | None
tailscale_authkey_path: Path | None
user_configuration: dict
user_credentials: dict
@@ -61,6 +62,7 @@ class InstallContext:
email=_read_text(os.environ.get("OMARCHY_INSTALL_EMAIL_FILE")),
encrypt=_read_text(os.environ.get("OMARCHY_INSTALL_ENCRYPT_FILE")).lower() in ("true", "yes", "1"),
authorized_keys_path=_optional_path(os.environ.get("OMARCHY_INSTALL_AUTHORIZED_KEYS_FILE")),
tailscale_authkey_path=_optional_path(os.environ.get("OMARCHY_INSTALL_TAILSCALE_AUTHKEY_FILE")),
user_configuration=user_configuration,
user_credentials=json.loads(creds_path.read_text()),
arch_config_path=arch_config_path,
@@ -39,6 +39,7 @@ def build_phases(ctx: InstallContext):
configure_dns_resolver,
configure_login,
configure_ssh_access,
configure_tailscale,
validate_boot,
)
@@ -52,6 +53,7 @@ def build_phases(ctx: InstallContext):
("Finalizing user", run_chroot_finalizer),
("Configuring login", configure_login),
("Configuring SSH access", configure_ssh_access),
("Configuring Tailscale", configure_tailscale),
("Configuring DNS resolver", configure_dns_resolver),
("Validating boot setup", validate_boot),
]
@@ -16,6 +16,7 @@ Phase ordering (full-disk and protected/pre-mounted):
run_chroot_finalizer → arch-chroot -u user omarchy-finalize-user
configure_login → sddm state + encrypted-install autologin
configure_ssh_access → authorized_keys for autoinstall; no-op otherwise
configure_tailscale → tailnet join staged for first boot; no-op otherwise
validate_boot → assert UKI / limine.conf / kernel cmdline are sane
"""
@@ -290,6 +291,14 @@ def arch_install_system(ctx: InstallContext) -> None:
info("› installing Omarchy runtime + omarchy-base.packages")
installer.add_additional_packages(_runtime_package_list(ctx))
# Tailscale is bundled in the offline mirror but only installed
# when an autoinstall drive staged an auth key; must happen here,
# while the mirror is still bind-mounted, not in the phase that
# configures the join.
if ctx.tailscale_authkey_path is not None:
info("› installing tailscale (auth key staged for first boot)")
installer.add_additional_packages(["tailscale"])
finally:
_unmask_mkinitcpio_pacman_hooks(ctx)
_unmount_offline_package_cache(ctx)
@@ -1381,6 +1390,113 @@ def _authorized_keys(path: Path) -> list[str]:
return keys
# ─────────────────────────────────────────────────────────────────────────────
# configure_tailscale: stage the tailnet join an autoinstall drive asked for.
# `tailscale up` needs a running tailscaled and there is no systemd in the
# chroot, so the install only stages: the key, the enabled services, and a
# oneshot first-boot unit that performs the join once the network is really
# there. The package itself was installed from the offline mirror during
# arch_install_system -- nothing is fetched at boot.
# ─────────────────────────────────────────────────────────────────────────────
TAILSCALE_AUTHKEY_TARGET = "/etc/tailscale/authkey"
# systemd expands $VAR in ExecStart, so the retry loop avoids `$` entirely.
# network-online.target can be reached before there is real connectivity, so
# retry inside the boot -- but NOT as a oneshot: target units implicitly gain
# After= for their Wants=, so a oneshot in multi-user.target holds the whole
# boot (SDDM included) hostage until it finishes. Type=simple counts as
# started the moment it forks, letting boot proceed while the join retries in
# the background for as long as the boot lasts. Cleanup lives inside the
# script because it must only run after a successful join: the key is removed
# and the unit disabled on success, while on a boot with no connectivity both
# survive -- so a machine installed offline joins on the first boot that can.
TAILSCALE_JOIN_UNIT = f"""\
[Unit]
Description=Join the tailnet with the auth key staged by autoinstall
Wants=network-online.target
After=network-online.target tailscaled.service
Requires=tailscaled.service
ConditionPathExists={TAILSCALE_AUTHKEY_TARGET}
[Service]
Type=simple
ExecStart=/usr/bin/sh -c 'until tailscale up --auth-key file:{TAILSCALE_AUTHKEY_TARGET}; do sleep 15; done; rm -f {TAILSCALE_AUTHKEY_TARGET}; systemctl disable omarchy-tailscale-join.service'
[Install]
WantedBy=multi-user.target
"""
def configure_tailscale(ctx: InstallContext) -> None:
if ctx.tailscale_authkey_path is None:
return
key = _tailscale_authkey(ctx.tailscale_authkey_path)
# An ISO built before tailscale was bundled installs nothing, and a staged
# key with no binary would fail silently forever on first boot.
if not (ctx.target / "usr" / "bin" / "tailscale").exists():
raise RuntimeError("tailscale is not installed on the target; this ISO does not bundle it")
info("› staging Tailscale auth key")
ts_dir = ctx.target / "etc" / "tailscale"
ts_dir.mkdir(parents=True, exist_ok=True)
ts_dir.chmod(0o700)
authkey = ts_dir / "authkey"
authkey.write_text(f"{key}\n")
authkey.chmod(0o600)
info("› enabling tailscaled and the first-boot join")
unit = ctx.target / "etc" / "systemd" / "system" / "omarchy-tailscale-join.service"
unit.parent.mkdir(parents=True, exist_ok=True)
unit.write_text(TAILSCALE_JOIN_UNIT)
subprocess.run(
["arch-chroot", str(ctx.target), "systemctl", "enable",
"tailscaled.service", "omarchy-tailscale-join.service"],
check=True,
)
# Same dance as configure_ssh_access: ufw cannot reach netfilter from the
# chroot and exits non-zero, but it records the rule in user.rules first,
# and that file is what ufw.service loads on first boot. Without the rule
# the node joins the tailnet and is then unreachable over it.
info("› allowing tailnet traffic through ufw")
subprocess.run(
["arch-chroot", str(ctx.target), "ufw", "allow", "in", "on", "tailscale0"],
check=False,
)
rules = ctx.target / "etc" / "ufw" / "user.rules"
text = rules.read_text() if rules.exists() else ""
if "-i tailscale0 -j ACCEPT" not in text:
raise RuntimeError(f"ufw did not record an allow rule for tailscale0 in {rules}")
def _tailscale_authkey(path: Path) -> str:
"""Read the autoinstall tailscale_authkey: exactly one key, with blank
lines and # comments dropped. No format validation beyond that -- key
formats are Tailscale's to change.
Raise rather than skip on anything unusable, same reasoning as
_authorized_keys: a machine that "succeeds" into never joining the
tailnet is worse than one that stops with the reason on screen.
"""
try:
lines = path.read_text().splitlines()
except OSError as exc:
raise RuntimeError(f"{path} is not readable: {exc}") from exc
keys = [line.strip() for line in lines]
keys = [key for key in keys if key and not key.startswith("#")]
if not keys:
raise RuntimeError(f"{path} contains no auth key")
if len(keys) > 1:
raise RuntimeError(f"{path} contains {len(keys)} keys; expected exactly one")
return keys[0]
# ─────────────────────────────────────────────────────────────────────────────
# validate_boot: hard checks before reboot. If the install ran but produced a
# boot config or UKI that can't actually boot, halt here rather than surprise