Appendix: Issues Encountered

Issues Encountered

Problems hit during deployment and their resolutions:

Phase Issue Resolution

0

cp to USB: permission denied

sudo mount without uid/gid flags — remount with -o uid=$(id -u),gid=$(id -g)

0

NFS mount hung on nas-02

Wrong hostname — nas-01.inside.domusdigitalis.dev is correct

1

DataConnect SQL ORA-00904: invalid identifier

Wrong column names (CALLING_STATION_ID etc.) — validated from codex: mac_address, timestamp, passed

2

mkdir -p /mnt/\{boot/efi,…​} then mount ext4 on /mnt/boot — efi dir disappears

ext4 mount overlays btrfs. Create efi/ AFTER mounting /boot: mkdir -p /mnt/boot/efi

4

ext4 /boot — systemd-boot "reboot to firmware" loop

Boot Loader Spec requires VFAT for XBOOTLDR. Entries + kernels must be on same partition. Fix: everything on ESP.

4

efibootmgr needed to register boot entry

ThinkPad didn’t auto-detect systemd-boot binary

4

Fallback preset not generating images

Arch ships with fallback commented out. Uncomment PRESETS, fallback_image, fallback_options in presets.

4

Boot entries at wrong path (/boot/loader/entries/)

bootctl --boot-path=/boot creates entries on ext4. Remove --boot-path, entries go on ESP.

4

512M ESP ran out of space copying all 4 initramfs

Only copy default images (no fallback). Fallback stays on ext4 /boot only.

6

nvidia-smi fails after install

Kernel module not loaded — must reboot. Also must sync new initramfs to ESP.

6

nvidia package not found

RTX 5090 requires nvidia-open (open kernel module), not proprietary nvidia.

7

iPSK VLAN blocks outbound port 22

Use ssh.github.com:443 with -l git. Goes away after EAP-TLS on DOMUS-Secure.

7

stow conflicts with default shell configs

rm -f ~/.bashrc ~/.bash_profile ~/.zshrc before stowing

7

GPG database locked after rsync

Stale lock files from source. find ~/.gnupg -name "*.lock" -delete && gpgconf --kill all

7

gopass "not initialized" after rsync

Config references ~/.password-store (legacy). Fix: sed -i to point at ~/.local/share/gopass/stores/root

7

gopass -c (clipboard) fails over SSH

No clipboard daemon. Use gopass show -f to print to console.

7

rsync from Razer fails — password denied

Razer SSH config Host * forces pubkey-only. Use -e "ssh -F /dev/null". Also enable KbdInteractiveAuthentication and PasswordAuthentication on target.

7

sshd_config sed didn’t match — password auth still yes

Line was PasswordAuthentication yes (commented). Use s/^\?PasswordAuthentication.*/PasswordAuthentication no/

7

nvim opens blank despite correct ~/.config/nvim symlink

.zshrc exports NVIM_APPNAME="nvim-domus". nvim looks at ~/.config/nvim-domus/, not ~/.config/nvim/.

7

dots-quantum missing gpg/, hosts/, secrets/ packages

Gitignored private packages. Must scp/rsync separately from source machine.

7

SSH to Razer from P16g fails — pubkey denied

P16g’s key not in Razer’s authorized_keys. Added pub key manually. Proper fix: Vault SSH certs.

7

git clone remote URL set to port 443 format

Cloned with ssh://ssh.github.com:443/ on iPSK. After moving to DOMUS-Secure: git remote set-url origin git@github.com:user/repo.git

8b

Vault cert issued with wrong hostname (modestus-razer)

$(cat /etc/hostname) on Razer returns Razer’s name. Must HOSTNAME="modestus-p16g" explicitly.

8b

Hostname set as modestus-t16g (wrong model)

Machine is P16g Gen 3, not T16g. hostnamectl set-hostname modestus-p16g + sed /etc/hosts.

7

GPG "No pinentry" — pinentry-qt missing libKF6GuiAddons.so.6

kguiaddons package not installed. Use ldd /usr/bin/pinentry-qt | grep "not found" to find ALL missing deps at once, then pacman -Qo on a working machine to find package names.

7

GPG pinentry-qt prompts on desktop instead of SSH terminal

gpg-agent inherits WAYLAND_DISPLAY from desktop. pinentry-auto script checks SSH_CONNECTION first. Also need gpg-connect-agent updatestartuptty /bye on SSH login (added to .zshrc).

7

env-gpu.conf symlink in repo points to hosts/razer/ — breaks on P16g

Per-host config committed as symlink to Razer. Fix: gitignore hyprland/.config/hypr/env-gpu.conf, each machine symlinks to its own hosts/<hostname>/env-gpu.conf manually.

4

ACPI interrupt storm — gpe6E firing 4.7M times, CPU at 84C idle

acpi_mask_gpe=0x6E kernel parameter masks the rogue GPE. Added to all boot entries. CPU dropped to 41C after reboot.

8b

nmcli connection down over SSH kills the WiFi link — SSH session dies, connection up never runs

NEVER bounce WiFi from an SSH session over that same WiFi. Run locally from the P16g desktop, or write to /tmp/bounce-wifi.sh over SSH and execute it from the local terminal. nohup with sleep also works but risky.

7

SSH config had wrong IPs for hosts

modestus-razer had 10.50.10.111 but actual IP is 10.50.1.106. Verify IPs before encrypting: ip -4 -o addr show | awk '$2!="lo" \{print $2, $4}'. Fix with sed -i '/Host modestus-razer$/,/^$/s/HostName OLD/HostName NEW/'. Re-encrypt + push + pull + decrypt on all machines.

7

age -d …​ > file fails with zsh: file exists

zsh noclobber prevents overwriting. Use >| (force overwrite): age -d -i key config.age >| config

7

~/.ssh/sockets/ directory missing on P16g

SSH config uses ControlPath ~/.ssh/sockets/…​ but directory wasn’t created. mkdir -p ~/.ssh/sockets before first SSH.

7

stow audit script misses share package — shows X when stowed

share stows to ~/.local/share/awk/, sed/, etc. at depth 4. Audit find uses maxdepth 2 — change to maxdepth 4 for accurate results.

7

hosts, gpg, secrets are NOT stow packages

stow -t ~ hosts creates wrong-level symlinks (~/razer/, ~/x1/, ~/aw/). These are per-host config containers — use manual symlinks only. secrets is a separate git repo at ~/.secrets/.

7

gcvault (gocryptfs vault manager) not deployed

Entire ~/atelier/_vaults/ directory needs rsync from Razer. Contains 4 vaults: credentials, work-sensitive, network-configs, personal. Symlinks from ~/.config/gh and ~/.claude/credentials.json point into mounted vault.

7

SSH between P16g (VLAN 10) and Razer (VLAN 1) — connection hangs

Different subnets with no inter-VLAN routing by design (anti-pivot security). Administrators with EAP-TLS certs connect to VLAN 100 (management VLAN) which has routing to infrastructure VLANs. Need to verify Razer’s cert + ISE authorization profile assigns the correct VLAN for cross-VLAN SSH access.

9

make fails — Cannot find module '@antora/lunr-extension'

Fresh clone has no node_modules/ (gitignored). npx antora auto-installs antora itself but not extensions from package.json. Fix: npm install in each domus-* repo after cloning. Not documented in any phase.

9

AsciiDoc validation not running on terminal commits

Claude Code hooks (PostToolUse in ~/.claude/settings.json) only fire inside Claude Code sessions. Terminal gach/git commit bypasses validation entirely. No git-level pre-commit hook exists — .git/hooks/ only contains .sample files. core.hooksPath not configured. dots-quantum git stow package has no hooks directory.

11

No Mandatory Access Control — AppArmor not installed or enabled

Discovered Apr 4 during domus-digitalis setup audit. Arch kernel has CONFIG_SECURITY_APPARMOR=y but it’s not enabled at boot. All user processes have unrestricted access to ~/.secrets/, ~/.gnupg/, ~/.age/, gopass stores. Fix applied Apr 5: pacman -S apparmor, boot params updated on all 3 entries with lsm=…​apparmor,bpf apparmor=1 security=apparmor, also restored missing acpi_mask_gpe=0x6E on fallback + LTS. apparmor.service enabled. Pending reboot. Now tracked as Phase 12. INC-2026-04-04-002. CR: AppArmor.

9

make serve fails — docker: command not found

Kroki diagram server requires Docker or Podman. Neither installed on P16g. make serve proceeds past the error but diagrams won’t render.

9

make serve fails — UI bundle not found

domus-antora-ui repo was cloned but build/ui-bundle.zip never built. Fix: cd ~/atelier/_bibliotheca/domus-antora-ui && npm install && npx gulp bundle. Note: npx --prefix does NOT change cwd for gulp — must cd into the repo first.

9

lsof: command not found during make serve

Makefile uses lsof -ti:8000 | xargs -r kill -9 to kill stale servers. lsof not installed on fresh Arch. Non-fatal but noisy. Fix: sudo pacman -S lsof.

12

AppArmor boot params not active after reboot — aa-enabled returns No

CR-2026-04-04 sed commands targeted /boot/loader/entries/ (ext4 shadow) instead of /boot/efi/loader/entries/ (ESP — what systemd-boot actually reads). Boot entries on ext4 had correct params but kernel never received them. This is the same Phase 4 deviation (entries must live on ESP VFAT) manifesting again. Fix: variable-driven idempotent patch targeting ESP_ENTRIES="/boot/efi/loader/entries" with GUARD="apparmor=1" check. See Phase 12 for the corrected commands.

8b

vault CLI not installed — cannot issue certs locally

Phase 8b cert issuance was performed from the Razer via SSH, so the missing vault binary on the P16g was never caught. Discovered Apr 14 when attempting to check the Vault PKI role (vault read pki_int/roles/domus-client) for the wired 802.1X admin cert. Fix: sudo pacman -S vault. Should be added to Phase 9 package list or Phase 8 prerequisites.

8b

P16g cert issued without OU=Domus-Admins — ISE cannot assign VLAN 100

Cert shows only CN=modestus-p16g.inside.domusdigitalis.dev — missing O=Domus-Infrastructure and OU=Domus-Admins. ISE authorization policy matches Certificate.Subject-OU == "Domus-Admins" for MGMT VLAN 100 + DACL_ADMIN_FULL. Without OU, wired 802.1X would land on wrong VLAN or be rejected. Root cause: Vault domus-client role had empty organization[] and ou[]. Fix applied Apr 14: vault write pki_int/roles/domus-client organization="Domus-Infrastructure" ou="Domus-Admins" (with full field set — vault write replaces entire role). Cert re-issued with correct subject: O=Domus-Infrastructure, OU=Domus-Admins, CN=modestus-p16g.inside.domusdigitalis.dev.

8b

ISE rejected endpoint blocked all wired 802.1X authentication

DOT1X-5-FAIL on switch for every attempt. NM reported "Secrets were required, but not provided" (misleading — actual cause was ISE rejecting the MAC). Discovery: netapi ise get-rejected-endpoints showed A8:2B:DD:8F:23:E6 in rejected list. Endpoint likely rejected during early failed auth attempts before cert/config was correct. Fix: netapi ise release-rejected A8:2B:DD:8F:23:E6. After release, 802.1X authenticated immediately — dot1x: Authc Success, User-Name: modestus-p16g.inside.domusdigitalis.dev.

8b

Wired 802.1X authenticated but assigned VLAN 10 (DATA) instead of VLAN 100 (MGMT)

Switch shows Vlan Group: Vlan: 10, Domain: DATA despite cert having OU=Domus-Admins. ISE wired authorization policy (Wired Dot1X Closed) not matching on certificate OU for admin VLAN assignment. Static IP 10.50.1.203/24 (MGMT subnet) becomes unreachable when assigned to VLAN 10 (DATA subnet 10.50.10.0/24). ISE policy investigation pending.

8b

802-1x.password-flags 4 required in addition to private-key-password-flags 4

NM fails with "Secrets were required, but not provided" even with private-key-password-flags 4 set. Must also set 802-1x.password-flags 4 for the EAP password field. Both flags must be 4 (not required) for passwordless EAP-TLS. Fix: sudo nmcli connection modify "<name>" 802-1x.password-flags 4. This burned multiple connection attempts across wired and WiFi profiles.

8b

802-1x.identity-flags not supported on NetworkManager 1.48+

Phase 8b documented identity-flags 0 for wired connections. NM rejects it: invalid property 'identity-flags'. Identity is stored in the connection file by default on newer versions. Fix: remove identity-flags from nmcli connection add.

8b

Vault HA cluster — each node must be unsealed independently

vault read pki_int/roles/domus-client returned 503 after unsealing vault-01 because active node was vault-02 (still sealed). Each Raft cluster node maintains its own seal state. Required: export VAULT_ADDR="https://vault-02.inside.domusdigitalis.dev:8200" then vault operator unseal ×2. netapi vault unseal --auto also failed due to quoted unseal keys in dsec (separate issue).

8b

dsec vault unseal keys wrapped in literal double quotes

netapi vault unseal --auto failed: 'key' must be a valid hex or base64 string. echo -n "$VAULT_UNSEAL_KEY_1" | wc -c returned 46 (expected 44). cat -A showed leading " — literal double quotes baked into the stored value in d000/dev/vault.env.age. VAULT_TOKEN also had unresolved template placeholder \{{VAULT_ROOT_TOKEN}}. Fix: dsec edit d000 dev/vault — strip quotes, replace placeholder.

8b

Wired 802.1X supplicant not sending EAPOL-Start — switch sees no session (OPEN)

NM passes correct supplicant config (key_mgmt=IEEE8021X, eap=TLS, ca_cert, identity, client_cert, private_key) and reports supplicant interface state: disconnected → associated. But the switch shows No sessions match supplied criteria — no EAPOL frames received. After 25 seconds NM times out: association took too longno-secretsfailed. WiFi 802.1X works fine on same machine with identical cert. Ruled out: cert/key issues (WiFi works), ISE rejection (no auth attempt logged), password-flags (both set to 4 in .nmconnection), wpa_supplicant not running (it is active). Observations: /etc/NetworkManager/conf.d/ is empty, no /etc/wpa_supplicant/wpa_supplicant.conf exists, journalctl -u wpa_supplicant shows zero entries for wired. Workaround: Domus-WiFi-Mgmt-VLAN100 provides VLAN 100 access over WiFi. Next steps: investigate whether wired 802.1X requires explicit wpa_supplicant configuration on Arch, check NM version-specific behavior, test with wpa_supplicant -D wired -i enp134s0 directly.