kevinveenbirkenbach/hetzner-arch-luks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Use $SERVER env var in README instead of YOUR_SERVER_IP placeholder

Browse Source 
`$SERVER` is set once at the top of the setup flow, then reused across
all five setup sections and the debugging chapter. Avoids 24× repetition
of the placeholder and lets the reader paste the blocks directly after
`export SERVER=...`.

`$SERVER` (not `$HOST`) because zsh sets `$HOST` to the local hostname
as a built-in parameter, and many tools use `$HOST` conventionally — name
collision would be confusing.

While here: drop the "(recommended)" hedge on `hal fix static-ip` in
section 3 of the install flow — given Hetzner's DHCP fragility (the bug
that caused this whole debugging session), the static cmdline IP belongs
in the standard install path, not as an optional extra.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-Birkenbach
2026-05-12 18:21:24 +02:00
parent 3cf66640b5
commit 88e9127f9b
1 changed files with 30 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
README.md
View File

@@ -71,12 +71,18 @@ The LUKS passphrase is prompted (hidden) on first use and cached in the libsecre
Each section is a small handful of `hal` commands. Click into the corresponding Each section is a small handful of `hal` commands. Click into the corresponding
table row above for what each one actually does. table row above for what each one actually does.
Set the server IP/hostname once per shell — every block below uses `$SERVER`:
```bash
export SERVER=your_server_ip # e.g. 46.4.224.77 or boot.echoserver
```
### 1. Install Arch via installimage ### 1. Install Arch via installimage
```bash ```bash
hal connect rescue YOUR_SERVER_IP # verify rescue is up hal connect rescue "$SERVER" # verify rescue is up
hal setup image YOUR_SERVER_IP --autosetup autosetup # see autosetup.example hal setup image "$SERVER" --autosetup autosetup # see autosetup.example
hal connect rescue YOUR_SERVER_IP reboot hal connect rescue "$SERVER" reboot
``` ```
Tip: copy `autosetup.example` to `autosetup`, edit `DRIVE1`/`DRIVE2`/`HOSTNAME`, Tip: copy `autosetup.example` to `autosetup`, edit `DRIVE1`/`DRIVE2`/`HOSTNAME`,
@@ -85,9 +91,9 @@ then run `setup image`.
### 2. Boot Arch, install the dropbear stack ### 2. Boot Arch, install the dropbear stack
```bash ```bash
hal connect server YOUR_SERVER_IP # verify SSH works hal connect server "$SERVER" # verify SSH works
hal connect server YOUR_SERVER_IP pacman -Syyu # bring system current hal connect server "$SERVER" pacman -Syyu # bring system current
hal setup dropbear YOUR_SERVER_IP # dropbear + mkinitcpio plugins + HOOKS hal setup dropbear "$SERVER" # dropbear + mkinitcpio plugins + HOOKS
``` ```
### 3. Convert root to LUKS ### 3. Convert root to LUKS
@@ -95,17 +101,17 @@ hal setup dropbear YOUR_SERVER_IP # dropbear + mkinitcpio
Activate Rescue in the Hetzner Robot UI, then: Activate Rescue in the Hetzner Robot UI, then:
```bash ```bash
hal connect server YOUR_SERVER_IP reboot # boots back into rescue hal connect server "$SERVER" reboot # boots back into rescue
hal connect rescue YOUR_SERVER_IP # verify rescue is up hal connect rescue "$SERVER" # verify rescue is up
hal setup encrypt-root YOUR_SERVER_IP # LUKS conversion — DESTRUCTIVE hal setup encrypt-root "$SERVER" # LUKS conversion — DESTRUCTIVE
hal setup grub YOUR_SERVER_IP # initial GRUB for LUKS boot hal setup grub "$SERVER" # initial GRUB for LUKS boot
hal fix static-ip YOUR_SERVER_IP # (recommended) harden initramfs network hal fix static-ip "$SERVER" # static initramfs IP — Hetzner DHCP is fragile
``` ```
Deactivate Rescue in the Hetzner Robot UI, then: Deactivate Rescue in the Hetzner Robot UI, then:
```bash ```bash
hal connect rescue YOUR_SERVER_IP reboot # final reboot into encrypted system hal connect rescue "$SERVER" reboot # final reboot into encrypted system
``` ```
### 4. Day-to-day use ### 4. Day-to-day use
@@ -114,9 +120,9 @@ After every reboot the system blocks at dropbear in initramfs waiting for the
LUKS passphrase. From your client: LUKS passphrase. From your client:
```bash ```bash
hal status YOUR_SERVER_IP # wait for dropbear / sshd hal status "$SERVER" # wait for dropbear / sshd
hal unlock YOUR_SERVER_IP # send passphrase to dropbear hal unlock "$SERVER" # send passphrase to dropbear
hal connect server YOUR_SERVER_IP # normal SSH after unlock hal connect server "$SERVER" # normal SSH after unlock
``` ```
### 5. Expand the root filesystem later ### 5. Expand the root filesystem later
@@ -124,7 +130,7 @@ hal connect server YOUR_SERVER_IP # normal SSH after unloc
If the autosetup gave you a small root LV and the rest is free LVM space: If the autosetup gave you a small root LV and the rest is free LVM space:
```bash ```bash
hal fix expand-fs YOUR_SERVER_IP hal fix expand-fs "$SERVER"
``` ```
## Debugging an unresponsive server ## Debugging an unresponsive server
@@ -133,20 +139,20 @@ The server isn't booting / SSH never comes up:
```bash ```bash
# 1. Reach the server's chroot # 1. Reach the server's chroot
hal connect rescue YOUR_SERVER_IP # via Hetzner Robot → Rescue first hal connect rescue "$SERVER" # via Hetzner Robot → Rescue first
hal diagnose YOUR_SERVER_IP | tee "diag-$(date +%F-%H%M).log" hal diagnose "$SERVER" | tee "diag-$(date +%F-%H%M).log"
# 2. Apply best-guess fixes in roughly this order # 2. Apply best-guess fixes in roughly this order
hal fix boot YOUR_SERVER_IP # sshd config + journald hal fix boot "$SERVER" # sshd config + journald
hal fix network YOUR_SERVER_IP # interface naming drift hal fix network "$SERVER" # interface naming drift
hal fix grub YOUR_SERVER_IP # stale MBR after grub upgrades hal fix grub "$SERVER" # stale MBR after grub upgrades
hal fix static-ip YOUR_SERVER_IP # DHCP-in-initramfs fragility hal fix static-ip "$SERVER" # DHCP-in-initramfs fragility
# 3. Last-resort kernel rollback (if a kernel bump is the suspect) # 3. Last-resort kernel rollback (if a kernel bump is the suspect)
hal fix kernel YOUR_SERVER_IP hal fix kernel "$SERVER"
# 4. Or, after fixing whatever was broken, upgrade everything cleanly # 4. Or, after fixing whatever was broken, upgrade everything cleanly
hal fix upgrade YOUR_SERVER_IP hal fix upgrade "$SERVER"
``` ```
Every `hal` chroot command makes its own backups (`<file>.hal-backup`) Every `hal` chroot command makes its own backups (`<file>.hal-backup`)