layered-soul/skills/bootable-usb-images/references/freebsd-live-usb-xorg-xfce.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

3.3 KiB

FreeBSD live USB Xorg/XFCE troubleshooting notes

Use when validating a custom FreeBSD graphical live USB/operator image after flashing.

Boot/root mount checks

A healthy writable operator USB should show / mounted from the UFS image without ro, and should not hide /tmp or /var behind tiny stock installer tmpfs overlays unless that is intentional:

mount | egrep ' on / | on /tmp | on /var '
df -h / /tmp /var

If tmpfs on /tmp and/or tmpfs on /var appears on a FreeBSD installer-derived image, it can hide image content under /var and starve desktop runtime space. In rc.conf, explicitly disable overlays for a writable live USB:

root_rw_mount="YES"
tmpmfs="NO"
varmfs="NO"

Static build-time checks should confirm those rc.conf entries and that /etc/fstab mounts /dev/ufs/FreeBSD_Install read-write.

XKB failure pattern

Symptoms:

Couldn't change directory to "/usr/local/share/X11/xkb"
Can't find file "xfree86" for keycodes include
XKB: Failed to compile keymap
Fatal server error: Failed to activate virtual core keyboard

First verify the files and traversal permissions:

ls -ld /usr /usr/local /usr/local/share /usr/local/share/X11 /usr/local/share/X11/xkb
ls -l /usr/local/share/X11/xkb/keycodes/xfree86
ls -ld /var/lib/xkb

If xfree86 exists but X still cannot find it, check whether /var was overmounted by tmpfs or the X server/session is running with an unexpected root/XKB base path.

Smoke-test compilation when possible:

setxkbmap -print | xkbcomp -w 10 -xkm - /tmp/clawdie-xkb-test.xkm

startxfce4 / xinit failure patterns

If X starts and then exits with:

xinit: Unable to run program "/usr/local/etc/xdg/xfce4/xinitrc": Permission denied

check every parent directory plus the script:

ls -ld /usr /usr/local /usr/local/etc /usr/local/etc/xdg /usr/local/etc/xdg/xfce4
ls -l /usr/local/etc/xdg/xfce4/xinitrc
chmod 755 /usr/local/etc/xdg /usr/local/etc/xdg/xfce4 /usr/local/etc/xdg/xfce4/xinitrc

If X starts and terminates successfully but xinit reports:

xinit: Unable to run program "xterm": No such file or directory

then Xorg is not the failing layer; the default client is missing. Point ~/.xinitrc at XFCE:

cat > ~/.xinitrc <<'EOF'
#!/bin/sh
exec /usr/local/bin/startxfce4
EOF
chmod 755 ~/.xinitrc
startx

Interpreting Xorg logs

Server terminated successfully (0). Closing log file. means the X server shut down cleanly after the client/session exited. Look for the client-side xinit, startxfce4, LightDM, or .xsession-errors message above it rather than treating graphics init as the root cause.

Useful bundle for screenshots/OCR:

{
  echo "===== /var/log/Xorg.0.log ====="
  tail -200 /var/log/Xorg.0.log
  echo "===== /var/log/lightdm/lightdm.log ====="
  tail -200 /var/log/lightdm/lightdm.log 2>/dev/null || true
  echo "===== /var/log/lightdm/x-0.log ====="
  tail -200 /var/log/lightdm/x-0.log 2>/dev/null || true
  echo "===== /home/clawdie/.xsession-errors ====="
  tail -200 /home/clawdie/.xsession-errors 2>/dev/null || true
  echo "===== xinitrc permissions ====="
  ls -ld /usr /usr/local /usr/local/etc /usr/local/etc/xdg /usr/local/etc/xdg/xfce4
  ls -l /usr/local/etc/xdg/xfce4/xinitrc
  ls -l /home/clawdie/.xinitrc 2>/dev/null || true
} | less