feat(homelab): enable Wake-on-LAN on the mini PCs (#509)

2026-11-13 12:13:36 +01:00 · 2026-11-02 15:36:29 +08:00
1 parent 7ea9fd3197
commit be3e27c49b
@@ -0,0 +1,5 @@
+# Documentation
+
+- [BIOS settings](./bios.md)
+- [Wake-on-LAN](./wake-on-lan.md)
+- [NixOS modernization options](./nixos-modernization-options.md)
@@ -0,0 +1,58 @@
+# BIOS Settings
+
+Manual firmware settings are not managed by Nix. Record values that affect power use, remote wake,
+and boot behavior here so they survive BIOS updates and hardware swaps. The related Wake-on-LAN
+workflow and verification commands are in [Wake-on-LAN](./wake-on-lan.md).
+
+Enter firmware setup with `Del` unless a host section says otherwise.
+
+Last reviewed: 2026-11-02.
+
+## `12kingdoms` mini PCs
+
+Hosts: `shoryu` (MoreFine S500+), `shushou` (MinisForum UM560), `youko` (Beelink GTR5).
+
+### Common settings
+
+- `Advanced > CPU Configuration > PPC Adjustment (P-State)` = `PState 2` (full-range adjustment
+  mode).
+- `Advanced > AMD CBS > FCH Common Options > AC Power Loss Options`:
+  - `AC Power Loss` = `Always On`
+  - `SATA Controller` = `Disabled`
+- Disable unused onboard devices where the firmware exposes them (for example `HDD` and WLAN
+  options); none are in use on these hosts. `youko`'s two 4TB HDDs are behind a USB JMicron JMS567
+  enclosure, so disabling the motherboard SATA controller does not affect them.
+
+### Wake-on-LAN
+
+The firmware path differs by model:
+
+| Host      | Model            | Setting                                |
+| --------- | ---------------- | -------------------------------------- |
+| `shoryu`  | MoreFine S500+   | `Advanced > Network Stack` = `Enabled` |
+| `shushou` | MinisForum UM560 | `Advanced > Resume on LAN` = `Enabled` |
+| `youko`   | Beelink GTR5     | `Advanced > Network Stack` = `Enabled` |
+
+The firmware side only exposes the wake path. NixOS arming and verification are documented in
+[Wake-on-LAN](./wake-on-lan.md#nixos-configuration).
+
+## `aquamarine`
+
+Board: Colorful CVN Z890 ARK FROZEN V20 (BIOS 1013). Settings changed on 2026-11-01.
+
+| Page             | Setting                  | Value                                          |
+| ---------------- | ------------------------ | ---------------------------------------------- |
+| Home             | Performance mode         | Power-saving mode                              |
+| Home             | Cooler                   | Intel default settings (lowers PL1/PL2 limits) |
+| Home             | HD audio                 | Disabled                                       |
+| Advanced > Power | RGB lighting             | Disabled                                       |
+| Advanced > Power | Restore on AC power loss | Power on                                       |
+| OC > Frequency   | Intel 200S Boost         | Disabled                                       |
+| OC > Frequency   | Intel Default Settings   | Enabled                                        |
+
+Wake-on-LAN is also required for the idle-suspend path:
+
+- `Advanced > Power Setting > Wake By Lan` = `Enabled`.
+- EUP must not cut standby power to the NIC.
+- NixOS arms the RTL8125BG through `systemd.network.links`; see
+  [Wake-on-LAN](./wake-on-lan.md#verify).
@@ -0,0 +1,61 @@
+# Wake-on-LAN
+
+Wake-on-LAN is available on `aquamarine` and the three `12kingdoms` mini PCs (`shoryu`, `shushou`,
+and `youko`). Firmware prerequisites are recorded in [BIOS settings](./bios.md).
+
+## NixOS configuration
+
+The three mini PCs share [`lib/genVmHostModule.nix`](../lib/genVmHostModule.nix), which adds a
+`systemd.network.links` entry that arms `WakeOnLan = "magic"` on their physical `eno1` NIC after
+every boot. `aquamarine` has the equivalent entry for its `en*` NIC in
+[`hosts/idols-aquamarine/default.nix`](../hosts/idols-aquamarine/default.nix).
+
+The MAC addresses used by the wake command live in [`scripts/wake.py`](../scripts/wake.py).
+
+## Verify
+
+After a boot, confirm the physical NIC reports `Wake-on: g`:
+
+| Host         | Command                                                   |
+| ------------ | --------------------------------------------------------- |
+| `12kingdoms` | `ethtool eno1 \| grep -E 'Supports Wake-on\|Wake-on'`     |
+| `aquamarine` | `ethtool enp133s0 \| grep -E 'Supports Wake-on\|Wake-on'` |
+
+## Wake hosts
+
+Wake every Wake-on-LAN-capable homelab host from another L2 host:
+
+```sh
+just wake
+```
+
+Pass one or more host names to wake only those machines; `aqua` is an alias for `aquamarine`:
+
+```sh
+just wake youko
+just wake aqua shoryu
+```
+
+The command retries the magic packet every few seconds and exits when every selected host answers
+ICMP **and** accepts an SSH connection. The SSH check prevents a host that is still shutting down or
+partway through boot from being mistaken for online. It prints a progress line every five seconds
+while waiting. Run `just wake --help` for all options:
+
+```text
+--timeout SECONDS           Stop waiting after SECONDS; 0 waits forever (default: 180)
+--retry-interval SECONDS    Time between magic-packet bursts (default: 5)
+--probe-interval SECONDS    Time between reachability checks (default: 1)
+--progress-interval SECONDS How often to print progress (default: 5)
+--packets N                 Magic packets per broadcast address and burst (default: 3)
+```
+
+Examples:
+
+```sh
+just wake aqua --timeout 0
+just wake youko --timeout 60
+just wake --retry-interval 2 --progress-interval 2
+```
+
+Add a host to the MAC list only after its firmware setting and NixOS link config are in place. Test
+wake-up from a powered-off state, not from a reboot.