Btrfs

btrfs is a modern copy on write (CoW) filesystem for Linux aimed at implementing advanced features while also focusing on fault tolerance, repair and easy administration.

Note: Use disko to manage your NixOS storage layout declaratively. The following shows a manual approach as seen in traditional Linux distributions.

Installation

Note: The following example is for EFI enabled systems. Adjust commands accordingly for a BIOS installation.

Partition the disk

# printf "label: gpt\n,550M,U\n,,L\n" | sfdisk /dev/sdX

Format partitions and create subvolumes

# mkfs.fat -F 32 /dev/sdX1

# mkfs.btrfs /dev/sdX2
# mkdir -p /mnt
# mount /dev/sdX2 /mnt
# btrfs subvolume create /mnt/root
# btrfs subvolume create /mnt/home
# btrfs subvolume create /mnt/nix
# umount /mnt

Mount the partitions and subvolumes

# mount -o compress=zstd,subvol=root /dev/sdX2 /mnt
# mkdir /mnt/{home,nix}
# mount -o compress=zstd,subvol=home /dev/sdX2 /mnt/home
# mount -o compress=zstd,noatime,subvol=nix /dev/sdX2 /mnt/nix

# mkdir /mnt/boot
# mount /dev/sdX1 /mnt/boot

Install NixOS

# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix # manually add mount options
# nixos-install

Configuration

Compression

nixos-generate-config --show-hardware-config doesn't detect mount options automatically, so to enable compression, you must specify it and other mount options in a persistent configuration:

fileSystems = {
  "/".options = [ "compress=zstd" ];
  "/home".options = [ "compress=zstd" ];
  "/nix".options = [ "compress=zstd" "noatime" ];
  "/swap".options = [ "noatime" ];
};

Swap file

Optionally, create a separate subvolume for the swap file. Be sure to regenerate your hardware-configuration.nix if you choose to do this.

# mkdir -p /mnt
# mount /dev/sdXY /mnt
# btrfs subvolume create /mnt/swap
# umount /mnt
# mkdir /swap
# mount -o subvol=swap /dev/sdXY /swap

Then, create the swap file and adjust its size as desired:

# btrfs filesystem mkswapfile --size 8g --uuid clear /swap/swapfile

Finally, add the swap file to your configuration and nixos-rebuild switch:

swapDevices = [ { device = "/swap/swapfile"; } ];

Scrubbing

Btrfs filesystem by default keeps checksums for all files, and this allows to check if contents of the file has not changed due to hardware malfunctions and other external effects.

Scrubbing - is the process of checking file consistency (for this it may use checksums and/or duplicated copies of data, from raid for example). Scrubbing may be done "online", meaning you don't need to unmount a subvolume to scrub it.

You can enable automatic scrubbing with

services.btrfs.autoScrub.enable = true;

Automatic scrubbing by default is performed once a month, but you can change that with

services.btrfs.autoScrub.interval = "weekly";

interval syntax is defined by systemd.timer's Calendar Events

By default autoscrub will scrub all detected btrfs mount points, howeven in case of mounted nested subvolumes (like in example above /nix and /home are nested subvolumes under /) you only need to scrub the top-most one. So an example configuration may look like this:

services.btrfs.autoScrub = {
  enable = true;
  interval = "monthly";
  fileSystems = [ "/" ];
};

The result of periodic auto scrub will be save to system journal, however you can also always check the status of the last scrub with

btrfs scrub status /

You can also start a scrubbing in background manually

btrfs scrub start /

You can check the status of the ongoing scrubbing process with the same status command from above

Usage

Subvolume

Create a subvolume

btrfs subvolume create /mnt/nixos

Removing a subvolume

btrfs subvolume delete /mnt/nixos

Snapshots

A snapshot in btrfs is simply a subvolume that shares its data (and metadata) with some other subvolume, using btrfs's COW capabilities.

Because of that, there is no special location for snapshots - you need to decide where you want to store them for yourself. It can be a simple directory inside root subvolume, or a directory inside a dedicated "snapshots" subvolume.

For this example we are going to store snapshots in a simple directory /snapshots, that has to be created beforehand with sudo mkdir /snapshots

Taking a read-only (-r) snapshot called home_snapshot_202302 of the subvolume mounted at /home

btrfs subvolume snapshot -r /home /snapshots/home_snapshot_202302

You can also snapshot the root subvolume. But keep in mind, that nested subvolumes are not part of a snapshot. So if you have subvolumes /nix /home, taking snapshot of / will not include them.

btrfs subvolume snapshot -r / /snapshots/nixos_snapshot_202302

Make snapshot read-write again

btrfs property set -ts /snapshots/home_snapshot_202302 ro false

However, changing read-only property of a snapshot in-place may causes issues with any future incremental send/receive.

Instead, a read-only snapshot itself (being a simple subvolume) can be snapshoted again as a read-write snapshot like this:

btrfs subvolume snapshot /snapshots/home_snapshot_202302 /snapshots/home_snapshot_202302_rw

Or it can be restored directly to /home straight away like this:

Warning: this will delete current /home and restore the snapshot! /home must be unmounted for this operation

btrfs subvolume delete /home
btrfs subvolume snapshot /snapshots/home_snapshot_202302 /home

After this you can mount /home again.

Transfer snapshot

Sending the snapshot /snapshots/nixos_snapshot_202302 compressed to a remote host via ssh at root@192.168.178.110 and saving it to a subvolume mounted or directory at /mnt/nixos

sudo btrfs send /snapshots/nixos_snapshot_202302 | zstd | ssh root@192.168.178.110 'zstd -d | btrfs receive /mnt/nixos'