clawdie/layered-soul
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
layered-soul/skills/bootable-usb-images/references/freebsd-live-usb-xkb-overlays.md
Hermes & Sam 5c5df32101 Populate layered-soul: identity, memories, skills, plan (Hermes & Sam) 
- SOUL.md: full agent identity, operating principles, voice
- IDENTITY.md: runtime identity, hosts, boundaries
- USER.md: operator context imported from hermes-soul
- AGENTS.md: actual operating rules, infrastructure, quick reference
- memories/curated/: 5 topics (tailscale, forgejo, agents, projects, vaultwarden)
- skills/: 9 cross-harness skills imported from hermes-soul after review
- docs/PLAN-CONFIGURE-PRIVATE-REPO.md: configuration plan
- Validate: passes clean
2026-06-14 00:21:26 +02:00

2.3 KiB
Raw Permalink Blame History

FreeBSD installer-derived live USB: XKB, /var, and tmpfs overlays

Use this note when a custom FreeBSD live/operator USB boots but the graphical desktop fails with Xorg/XKB errors or a black screen.

Symptom pattern

Common visible errors:

Couldn't change directory to "/usr/local/share/X11/xkb"
Can't find file "xfree86" for keycodes include
XKB: Failed to compile keymap
Keyboard initialization failed. This could be a missing or incorrect setup of xkeyboard-config.
Fatal server error: Failed to activate virtual core keyboard: 2

The file may still exist when checked manually:

ls -l /usr/local/share/X11/xkb/keycodes/xfree86

If it exists, do not stop at “missing xkeyboard-config”. Check the live filesystem layout.

Why it happens

Stock FreeBSD installer memsticks are installer-oriented and can mount small tmpfs-style overlays on /tmp and /var. In a desktop/operator USB that has a writable UFS root, those overlays can be harmful:

  • /var/lib/xkb may be hidden or missing at runtime.
  • Xorg/rootless XKB cache generation may fail.
  • /var may be too small for desktop services.
  • The resulting errors can misleadingly point at /usr/local/share/X11/xkb.

Runtime proof commands

Run these on the failing USB:

mount | egrep ' on / | on /tmp | on /var '
cat /etc/fstab
egrep 'root_rw_mount|tmpmfs|varmfs' /etc/rc.conf /etc/rc.conf.local 2>/dev/null
touch /root/probe 2>&1
touch /tmp/probe 2>&1
touch /var/tmp/probe 2>&1
ls -ld /var/lib/xkb /usr/local/share/X11/xkb /usr/local/share/X11/xkb/keycodes

Interpretation:

  • Desired desktop/operator USB: / is writable UFS, and /tmp + /var are not separate tiny tmpfs mounts.
  • Suspicious: tmpfs on /var or tiny /var, especially with XKB cache/runtime failures.

Build-time fix pattern

For writable live/operator USBs, build scripts should write or validate:

/dev/ufs/FreeBSD_Install / ufs rw,noatime 1 1
root_rw_mount="YES"
tmpmfs="NO"
varmfs="NO"

Also add static checks to fail the build if these entries are absent.

Avoid false leads

A user shell profile such as ~/.profile/~/.xprofile that only sets PATH, best-effort loads mac_do, or launches a bootstrap page is unlikely to explain:

  • read-only root
  • hidden /var/lib/xkb
  • missing XKB runtime/cache paths
  • black screen before desktop startup

Check mounts and rc.conf first.