Arch Linux BTRFS + LUKS2 Recovery Guide with Timeshift Snapshots

This guide covers how to recover a broken Arch Linux system using BTRFS snapshots (Timeshift) when your system won't boot or is corrupted. Based on a real recovery scenario with an encrypted NVME drive setup.

System Configuration Example

Drive: /dev/nvme0n1 (931.5GB)
Partitions:
- /dev/nvme0n1p1 - 512MB EFI boot partition (FAT32)
- /dev/nvme0n1p2 - 931GB encrypted partition (LUKS2)
Encryption: LUKS2 mapped to /dev/mapper/cryptroot
Filesystem: BTRFS with subvolumes
Subvolumes:
- @ - Root filesystem
- @home - User home directories
- @log - System logs (/var/log)
- @tmp - Temporary files (/var/tmp)
- @libvirt - Virtual machine data (/var/lib/libvirt)

Prerequisites

Arch Linux live USB/DVD
Access to your LUKS passphrase
Basic knowledge of terminal commands

Step 1: Boot from Live Environment

Boot from Arch Linux installation media
Connect to internet (if needed for updates)
Load necessary kernel modules:
```
modprobe dm-crypt
modprobe dm-mod
```

Step 2: Unlock the Encrypted Drive

Identify your encrypted partition:
```
lsblk
fdisk -l
```
Unlock the LUKS2 partition:
```
cryptsetup luksOpen /dev/nvme0n1p2 cryptroot
```
Enter your encryption passphrase when prompted.

Verify the mapping:

ls -la /dev/mapper/
# Should show: cryptroot -> ../dm-0

Step 3: Mount and Explore the Filesystem

Mount the BTRFS root:
```
mount /dev/mapper/cryptroot /mnt
```
List available snapshots:
```
ls -la /mnt/
btrfs subvolume list /mnt
```

Check available Timeshift snapshots:

ls -la /mnt/timeshift-btrfs/snapshots/

Example output:

2024-01-17_07-42-29/
2024-04-09_05-26-44/
2025-08-08_08-03-16/
2025-08-08_15-09-17/
2025-08-09_00-46-30/

Step 4: Identify a Working Snapshot

Test snapshots to find one with a complete system:

echo "=== Checking snapshot completeness ==="
for snapshot in /mnt/timeshift-btrfs/snapshots/*/; do
    snapshot_name=$(basename "$snapshot")
    echo "Checking $snapshot_name..."
    
    if [[ -f "$snapshot/@/etc/pacman.conf" && -f "$snapshot/@/usr/bin/pacman" ]]; then
        echo "✓ $snapshot_name - Complete system"
    else
        echo "✗ $snapshot_name - Incomplete/corrupted"
    fi
done

Step 5: Restore from Working Snapshot

Delete the current broken @ subvolume:
```
btrfs subvolume delete /mnt/@
```

Create new @ subvolume from working snapshot:

# Replace YYYY-MM-DD_HH-MM-SS with your chosen snapshot
btrfs subvolume snapshot /mnt/timeshift-btrfs/snapshots/YYYY-MM-DD_HH-MM-SS/@ /mnt/@

Example:

btrfs subvolume snapshot /mnt/timeshift-btrfs/snapshots/2025-08-08_15-09-17/@ /mnt/@

Verify the restoration:

ls -la /mnt/@/etc/pacman.conf
ls -la /mnt/@/usr/bin/pacman
ls -la /mnt/@/bin/bash

Step 6: Mount All Subvolumes and Filesystems

Unmount and remount with proper subvolume:

umount /mnt
mount -o noatime,compress=zstd,subvol=@ /dev/mapper/cryptroot /mnt

Create mount points:

mkdir -p /mnt/{boot,home,var/log,var/tmp,var/lib/libvirt,proc,sys,dev,dev/pts,run,tmp}

Mount other BTRFS subvolumes:

mount -o noatime,compress=zstd,subvol=@home /dev/mapper/cryptroot /mnt/home
mount -o noatime,compress=zstd,subvol=@log /dev/mapper/cryptroot /mnt/var/log
mount -o noatime,compress=zstd,subvol=@tmp /dev/mapper/cryptroot /mnt/var/tmp
mount -o noatime,compress=zstd,subvol=@libvirt /dev/mapper/cryptroot /mnt/var/lib/libvirt

Mount the boot partition:
```
mount /dev/nvme0n1p1 /mnt/boot
```

Mount system filesystems for chroot:

mount -t proc proc /mnt/proc
mount -t sysfs sysfs /mnt/sys
mount -t devtmpfs devtmpfs /mnt/dev
mount -t devpts devpts /mnt/dev/pts

Step 7: Enter the Chroot Environment

arch-chroot /mnt

You should now be in your restored system with a working shell prompt like:

[root@EndeavourOS /]#

Step 8: System Maintenance and Updates

Remove stale package manager locks:
```
rm -f /var/lib/pacman/db.lck
```

Update the system (handle conflicts if necessary):

# Standard update
pacman -Syyu

# If you get file conflicts, force overwrite:
pacman -Syyu --overwrite '*'

Update bootloader:

# For GRUB:
grub-mkconfig -o /boot/grub/grub.cfg

# For systemd-boot:
bootctl update

Regenerate initramfs:
```
mkinitcpio -P
```

Step 9: Exit and Reboot

Exit chroot:
```
exit
```
Unmount all filesystems:
```
umount -R /mnt
```
Close the encrypted container:
```
cryptsetup luksClose cryptroot
```
Reboot:
```
reboot
```

Troubleshooting Common Issues

Database Lock Errors

# Remove lock file
rm -f /var/lib/pacman/db.lck

# Check for running pacman processes
ps aux | grep pacman

File Conflicts During Updates

# Force overwrite all conflicting files
pacman -Syyu --overwrite '*'

# Or be selective with specific paths
pacman -Syyu --overwrite '/usr/share/wayland-sessions/*,/usr/lib/firmware/nvidia/*'

Missing System Directories in Chroot

# Ensure all mount points exist
mkdir -p /mnt/{proc,sys,dev,dev/pts,run,tmp}

# Remount system filesystems
mount -t proc proc /mnt/proc
mount -t sysfs sysfs /mnt/sys
mount -t devtmpfs devtmpfs /mnt/dev
mount -t devpts devpts /mnt/dev/pts

Empty or Corrupted Snapshots

Try different snapshots from your list
Older snapshots might be more stable
Check snapshot completeness before restoring

Prevention Tips

Regular snapshots: Configure Timeshift for automatic snapshots
Test snapshots: Periodically verify snapshot integrity
Multiple restore points: Keep several working snapshots
System updates: Test system updates in a snapshot before applying permanently

Snapshot Management Commands

# List all snapshots
btrfs subvolume list /

# Create manual snapshot
btrfs subvolume snapshot / /timeshift-btrfs/snapshots/manual-$(date +%Y-%m-%d_%H-%M-%S)

# Delete old snapshot
btrfs subvolume delete /timeshift-btrfs/snapshots/old-snapshot-name

# Check snapshot space usage
btrfs filesystem usage /

This guide should help you recover from most system failures when using BTRFS with LUKS2 encryption and Timeshift snapshots on Arch Linux.

al-swaiti/gist:2f571ffd506090d92bcb3cf9afb33066