le-app/docs/le-app-database-migration/phase2a-host-maintenance/grub-btrfs-readiness.md

GRUB and grub-btrfs readiness

Verified baseline:

• GRUB has normal, fallback, and recovery entries for both linux-zen and standard linux.
• Snapper snapshots 1, 2, and 3 exist.
• /boot/grub/grub-btrfs.cfg is absent, so there are currently no generated snapshot entries.
• grub-btrfs-snapper.path is active and watching /.snapshots.

The installed unit definitions are:

# /usr/lib/systemd/system/grub-btrfs-snapper.path
[Unit]
Description=Monitors for new snapshots

[Path]
PathModified=/.snapshots

[Install]
WantedBy=multi-user.target

# /usr/lib/systemd/system/grub-btrfs-snapper.service
[Unit]
Description=Regenerate grub-btrfs.cfg

[Service]
Type=oneshot
Environment="PATH=/sbin:/bin:/usr/sbin:/usr/bin"
EnvironmentFile=/etc/default/grub-btrfs/config
ExecStart=bash -c 'if [[ -z $(/usr/bin/findmnt -n / | /usr/bin/grep "\.snapshots") ]]; then if [ -s "${GRUB_BTRFS_GRUB_DIRNAME:-/boot/grub}/grub-btrfs.cfg" ]; then /etc/grub.d/41_snapshots-btrfs; else ${GRUB_BTRFS_MKCONFIG:-grub-mkconfig} -o ${GRUB_BTRFS_GRUB_DIRNAME:-/boot/grub}/grub.cfg; fi; fi'

The bounded July 12 journal contains only these two parser warnings and no recorded service activation that generated snapshot entries:

Jul 12 17:16:42 TITANSERVER systemd[1]: /usr/lib/systemd/system/grub-btrfs-snapper.service:11: Ignoring unknown escape sequences in the ExecStart expression containing "\.snapshots".
Jul 12 17:18:23 TITANSERVER systemd[1]: /usr/lib/systemd/system/grub-btrfs-snapper.service:11: Ignoring unknown escape sequences in the ExecStart expression containing "\.snapshots".

The most supportable inference is that the watcher was enabled after snapshots 1–3 or received no qualifying modification afterward; absence of grub-btrfs.cfg confirms that the generator has not completed successfully for those snapshots.

The separately approved standalone generation and verification procedure is:

/etc/grub.d/41_snapshots-btrfs
generate_rc=$?
printf 'grub_btrfs_generate_rc=%s\n' "$generate_rc"

test -s /boot/grub/grub-btrfs.cfg
present_rc=$?
printf 'grub_btrfs_cfg_present_rc=%s\n' "$present_rc"

grub-script-check /boot/grub/grub-btrfs.cfg
syntax_rc=$?
printf 'grub_btrfs_cfg_syntax_rc=%s\n' "$syntax_rc"

grep -E 'snapshot|Snapshot|snapper|\.snapshots' /boot/grub/grub-btrfs.cfg
entries_rc=$?
printf 'grub_btrfs_entries_rc=%s\n' "$entries_rc"

grep -q 'snapshots-btrfs' /boot/grub/grub.cfg
main_menu_link_rc=$?
printf 'grub_main_menu_snapshot_link_rc=%s\n' "$main_menu_link_rc"

This procedure is not approved or executed by the maintenance scripts. If the last check fails, stop: making the submenu reachable would require a separately approved grub-mkconfig -o /boot/grub/grub.cfg. Do not regenerate full GRUB as an incidental readiness repair.