index

setup hibernate with a BTRFS drive

Usage & Limitations

There are specific limitations for Btrfs and Linux swap subsystems:

  • Swap files on multi-device filesystems are not supported.
  • Data profile must be single.
  • Snapshots cannot be created for subvolumes containing active swap files.
  • Swap files must be pre-allocated and have the NOCOW attribute.

Create Swap Subvolume & File

To avoid snapshot issues, create a dedicated subvolume:

# Create the subvolume
sudo btrfs subvolume create /swap

# Create a 8 GiB swap file (handles NOCOW and pre-allocation automatically)
sudo btrfs filesystem mkswapfile --size 8g --uuid clear /swap/swapfile

# Activate the swap
sudo swapon /swap/swapfile

Permanent Configuration (fstab)

Add the following to /etc/fstab:

/swap/swapfile none swap defaults 0 0

Configure Hibernation (Kernel Parameters)

To hibernate, the kernel needs to know where the swap resides.

  1. Find the Resume Offset:

    sudo btrfs inspect-internal map-swapfile -r /swap/swapfile

    Example Output: 6841523

  2. Find the UUID:

    findmnt -no UUID -T /swap/swapfile

  3. Update Bootloader: In your boot entry (e.g., /boot/loader/entries/arch.conf), append the parameters:

    options ... resume=UUID=<YOUR_UUID> resume_offset=<YOUR_OFFSET>

Final Checklist

  • ☐ mkinitcpio.conf: Ensure resume is in the HOOKS=(...) list (after udev).
  • ☐ Regenerate: Run sudo mkinitcpio -P.
  • ☐ Priority: Check with swapon --show. Ensure the file has lower priority than zram/zswap.
  • ☐ Safe Entry: Keep a fallback boot entry without resume parameters.

Issues

Black/Blank Screen

If you hang on wake, try removing the kms (ps: no its not that kms) module from mkinitcpio.conf and regenerate:

sudo mkinitcpio -P