# 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:

```text
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:

```sh
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:

```sh
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:

```sh
/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.