nixos-configs/machines/nix-book/nixbook-btrfs-migration.md

NixBook ext4 to btrfs Migration Guide

Overview

This guide converts your nixbook machine from ext4 to btrfs with zstd compression and beesd deduplication while preserving your LUKS encryption and all data.

Current System Info

• Hostname: nix-book
• Root filesystem: ext4 on /dev/disk/by-uuid/bd396529-e2c4-47cb-b844-8d6ed841f81a
• Encryption: LUKS with two devices configured
• Current usage: 138GB used / 225GB total (65% full)
• Free space: 76GB available (sufficient for conversion)

Pre-Migration Checklist

1. Create Full System Backup (CRITICAL)

# Boot from NixOS live USB
# Mount encrypted filesystem
cryptsetup luksOpen /dev/disk/by-uuid/4126fbd4-bd09-4ece-af0d-6fff414c21b3 luks-nixbook
mount /dev/mapper/luks-nixbook /mnt

# Create backup to external drive (adjust target as needed)
rsync -avxHAX --progress /mnt/ /path/to/backup/nixbook-backup/

2. Verify Configuration Changes

The following files have been updated for btrfs:

• machines/nix-book/configuration.nix - Added beesd service
• machines/nix-book/hardware-configuration.nix - Changed fsType to btrfs with compression

Migration Process

Phase 1: Boot to Live Environment

1. Create NixOS live USB:

   # Download latest NixOS ISO
   # Flash to USB drive
   dd if=nixos-minimal-xx.xx-x86_64-linux.iso of=/dev/sdX bs=4M status=progress
   

2. Boot from live USB and ensure you can access the encrypted drives

Phase 2: Filesystem Conversion

3. Unlock LUKS volumes:

   cryptsetup luksOpen /dev/disk/by-uuid/4126fbd4-bd09-4ece-af0d-6fff414c21b3 luks-nixbook
   cryptsetup luksOpen /dev/disk/by-uuid/b614167b-9045-4234-a441-ac6f60a96d81 luks-nixbook2
   

4. Check filesystem before conversion:

   fsck.ext4 -f /dev/mapper/luks-nixbook
   

5. Convert ext4 to btrfs (this preserves all data):

   # Install btrfs-progs if not available
   nix-shell -p btrfs-progs
   
   # Convert the filesystem (takes 15-45 minutes depending on data)
   btrfs-convert /dev/mapper/luks-nixbook
   
   # Verify conversion succeeded
   mount /dev/mapper/luks-nixbook /mnt
   ls -la /mnt  # Should show your normal filesystem
   btrfs filesystem show /mnt
   

6. Get new filesystem UUID (may have changed):

   blkid /dev/mapper/luks-nixbook
   # Note the new UUID if it changed
   

Phase 3: Configuration Update

7. Mount and chroot into system:

   mount -o compress=zstd,noatime /dev/mapper/luks-nixbook /mnt
   mount /dev/disk/by-uuid/7A0B-CF88 /mnt/boot
   nixos-enter --root /mnt
   

8. Update hardware-configuration.nix if UUID changed:

   # Edit /etc/nixos/hardware-configuration.nix if needed
   # Update the UUID in fileSystems."/" section
   

9. Rebuild system with btrfs configuration:

   cd /home/johno/nixos-configs
   nixos-rebuild switch --flake .#nix-book
   

Phase 4: Enable Compression and Deduplication

10. Reboot into new btrfs system:

    exit  # Exit chroot
    umount -R /mnt
    reboot
    

11. Verify btrfs is working:

    mount | grep btrfs
    btrfs filesystem usage /
    

12. Enable and start beesd:

    systemctl status beesd-root
    systemctl start beesd-root
    systemctl enable beesd-root
    

13. Force compression on existing files (optional but recommended):

    # This will compress existing files with zstd
    btrfs filesystem defragment -r -czstd /
    

Post-Migration Verification

Check System Health

# Verify btrfs health
btrfs scrub start /
btrfs scrub status /

# Check compression effectiveness
compsize /

# Monitor beesd deduplication
journalctl -u beesd-root -f

# Check filesystem usage
btrfs filesystem usage /
df -h /

Performance Monitoring

# Monitor beesd hash table
ls -lh /.beeshash

# Check compression ratio over time
compsize /home /nix /var

Expected Benefits

Space Savings

• Compression: 20-30% reduction in disk usage from zstd
• Deduplication: Additional 10-20% savings on duplicate files
• Combined: Potentially 30-40% total space savings

Performance Impact

• Compression: Minimal CPU overhead, often improves I/O performance
• Deduplication: Background process, minimal impact during normal use
• Overall: Should be neutral to positive performance impact

Rollback Plan (Emergency)

If something goes wrong:

1. Boot from live USB
2. Restore from backup:

   cryptsetup luksOpen /dev/disk/by-uuid/4126fbd4-bd09-4ece-af0d-6fff414c21b3 luks-nixbook
   mkfs.ext4 /dev/mapper/luks-nixbook
   mount /dev/mapper/luks-nixbook /mnt
   rsync -avxHAX --progress /path/to/backup/nixbook-backup/ /mnt/
   

3. Restore original hardware-configuration.nix with ext4 settings
4. Rebuild and reboot

Troubleshooting

Common Issues

"Device busy" during conversion:

• Ensure no processes are accessing the filesystem
• Check with lsof and fuser

UUID changed after conversion:

• Update hardware-configuration.nix with new UUID
• Regenerate initrd: nixos-rebuild switch

Beesd service fails to start:

• Check disk space for hash table
• Verify filesystem is btrfs: mount | grep btrfs
• Check logs: journalctl -u beesd-root

Boot issues after conversion:

• Boot from live USB
• Check /boot partition is mounted correctly
• Verify LUKS UUIDs match in configuration
• Rebuild bootloader: nixos-rebuild switch --install-bootloader

Maintenance

Regular Tasks

# Monthly scrub (checks for corruption)
btrfs scrub start /

# Monitor compression effectiveness
compsize /

# Check beesd deduplication status
systemctl status beesd-root

Space Management

# Balance filesystem (defragments and optimizes)
btrfs balance start -dusage=50 /

# Check for space issues
btrfs filesystem usage /

This migration preserves all your data while gaining the benefits of modern btrfs features including transparent compression and automatic deduplication.