layered-soul/skills/bootable-usb-images/references/freebsd-live-usb-desktop-triage.md

FreeBSD Live USB Desktop / Xorg Triage Notes

Use this when a FreeBSD-based live/operator USB boots but the graphical desktop fails. These notes came from a Clawdie XFCE live USB debugging session, but the failure classes are general.

Fast state classification

Capture these first from the live system:

mount
mount | egrep ' on / | on /tmp | on /var '
df -h / /tmp /var
egrep 'root_rw_mount|tmpmfs|varmfs' /etc/rc.conf /etc/rc.conf.local 2>/dev/null || true
ls -ld /var/lib/xkb /usr/local/share/X11/xkb /usr/local/share/X11/xkb/keycodes 2>/dev/null
ls -l /usr/local/etc/xdg/xfce4/xinitrc 2>/dev/null
which startx startxfce4 xterm 2>/dev/null || true
cat ~/.xinitrc 2>/dev/null || true

Root cause patterns and meanings

Root mounted read-only

Symptom examples:

Trying to mount root from ufs:/dev/ufs/FreeBSD_Install [ro,noatime]
mkdir: ... Read-only file system
touch: /etc/zfs/exports: Read-only file system

Image-side fix: make /etc/fstab mount /dev/ufs/FreeBSD_Install at / with rw,noatime, and set:

root_rw_mount="YES"

/tmp or /var hidden by installer tmpfs overlays

Symptom examples:

tmpfs on /tmp (tmpfs, local)
tmpfs on /var (tmpfs, local)

This can hide image content such as /var/lib/xkb and leaves too little runtime space for a desktop session. On a writable operator USB, disable the stock memstick overlays in /etc/rc.conf:

tmpmfs="NO"
varmfs="NO"

Expected after rebuild:

/dev/ufs/FreeBSD_Install on / (ufs, local, noatime, soft-updates)

and no separate tmpfs on /tmp / tmpfs on /var lines, except unrelated Linux compat tmpfs such as /compat/linux/dev/shm.

XKB keycodes missing

Symptom examples:

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

Check both the tree and whether /var is overmounted:

ls -l /usr/local/share/X11/xkb/keycodes/xfree86
ls -ld /usr/local/share/X11/xkb /usr/local/share/X11/xkb/keycodes /var/lib/xkb
mount | grep ' /var '

If the file exists in the image but X cannot see it at runtime, suspect mount overlays or bad XKB base path rather than a missing package.

Xorg starts, then xinit/session exits

Once logs show GPU/DRM and Xorg initialization succeeded and then terminate with status 0, move to session/client startup. Common messages:

xinit: Unable to run program "/usr/local/etc/xdg/xfce4/xinitrc": Permission denied
xinit: Unable to run program "xterm": No such file or directory
xfwm4 and xfce4-panel are both gone; ending session

Checks/fixes for the image:

chmod 755 /usr/local/etc/xdg /usr/local/etc/xdg/xfce4 /usr/local/etc/xdg/xfce4/xinitrc
pkg install xterm   # or include xterm as the rescue X client in the image
cat > /home/clawdie/.xinitrc <<'EOF'
#!/bin/sh
exec /usr/local/bin/startxfce4
EOF
chmod 755 /home/clawdie/.xinitrc

Do not keep treating these as GPU/XKB failures once Xorg starts and the log ends with:

Server terminated successfully (0). Closing log file.

Xauthority/serverauth noise

Symptoms can include:

xauth: bad display name ":0" in "add" command
(EE) Failed to open authorization file "/home/clawdie/.serverauth.NNNN": No such file or directory

This can be secondary to session startup failure. For diagnosis only, try:

rm -f ~/.serverauth.* ~/.Xauthority
touch ~/.Xauthority
chmod 600 ~/.Xauthority
startx /usr/local/bin/clawdie-xfce-session

If needed to distinguish auth from session failures, a temporary diagnostic bypass is:

startx /usr/local/bin/clawdie-xfce-session -- -ac

What to report from screenshots

When OCRing user photos of this flow, preserve exact log text and classify the current layer:

1. Boot/storage/mount issue
2. XKB/keymap issue
3. Xorg GPU/server startup issue
4. xinit/session/client startup issue
5. XFCE component/runtime issue

Avoid re-debugging earlier layers once logs prove they passed.