OpenZFS

You can automate snapshotting and rolling back of the root dataset during the boot process using these kernel command line flags:

Snapshotting (bootfs.snapshot)

Enables zfs-snapshot-bootfs.service. This creates a snapshot of the root dataset after the pool is imported but before the rootfs is mounted.

• Usage: bootfs.snapshot or bootfs.snapshot=snapshot-name.
• Snapshot Name: If no name is provided, it uses $root_dataset@$(uname -r).
• Behavior: If snapshot creation fails, the error is noted, but the system continues to boot.

Rolling back (bootfs.rollback)

Enables zfs-rollback-bootfs.service. This performs a zfs rollback -Rf on the root dataset after pool import but before the rootfs is mounted.

• Usage: bootfs.rollback or bootfs.rollback=snapshot-name.
• Snapshot Name: If no name is provided, it uses $root_dataset@$(uname -r).
• Behavior: If the rollback fails, the system drops to a rescue shell.
• Warning: This can cause data loss. Ensure persistent data is not located below the rootfs and that you do not require intermediate snapshots.

Ordering: If both flags are provided, bootfs.rollback is executed after bootfs.snapshot.

You can provide custom logic to load encryption keys during the initramfs stage by using drop-in scripts.

Mechanism:

• The initramfs will copy a shell program located at /etc/zfs/initramfs-tools-load-key and any files matching /etc/zfs/initramfs-tools-load-key.d/* into the initramfs.
• These scripts are sourced during the boot process.
• The following variables are available within your script:
  • $ENCRYPTIONROOT: The dataset requiring the key.
  • $KEYLOCATION: The location of the key (e.g., a file path).
• You can use unquoted $ZPOOL and $ZFS to execute zpool and zfs commands directly.

Return Codes:

• A successful return (exit code 0) indicates the key was loaded and stops the search for other key-loading methods.
• A failure return is non-fatal; the script will proceed to the next available hook.

# Example: A drop-in script that uses the BLAKE2 checksum of a file as the key
key="$(b2sum "${KEYLOCATION#file://}")" || return
printf '%s\n' "${key%% *}" | $ZFS load-key -L prompt "$ENCRYPTIONROOT"

Because the compressed byte stream may change between Zstd versions, OpenZFS follows a strict update policy to manage compatibility:

• Release Timing: Zstd may be updated after a new .0 release is tagged. Critical patches can be applied up until the next release freeze, potentially using a newer upstream version.
• Version Stability: The Zstd version will not be upgraded within a major release, and multiple Zstd versions are not supported concurrently within a single release.
• Import Integrity: The library import commit must be a clean, unmodified upstream import. Any OpenZFS-specific integration or local adjustments must be placed in separate, follow-up commits.
• Documentation: Release notes must highlight Zstd updates and any expected impacts, such as changes in compression ratio/performance or differences in compressed byte streams that might affect deduplication or NOP writes.
• Backwards Compatibility: If Zstd introduces breaking changes, OpenZFS must maintain backwards compatibility. The Zstd version number is saved within the block header to facilitate future compatibility checks or fixes.

You can specify a snapshot as the <dataset> in your kernel command line arguments.

Behavior when a snapshot is specified:

• The script will clone the snapshot and use the resulting clone as the root filesystem.
• If the clone dataset already exists, it is destroyed before the new one is created.
• The clone is created with mountpoint=none and canmount=noauto; the initramfs script handles the manual mounting.
• Fallback: If the specified snapshot does not exist, the script falls back to using the base dataset (the part before the @ symbol) as the boot filesystem.

Interactive Mode:

• If you specify a dataset containing an @ (indicating a snapshot) but do not specify a specific snapshot name on the root= command line, the script will prompt the user to choose a snapshot to use during boot.

# Example: Booting from a specific snapshot via cloning
root=zfs:rpool/ROOT/default@backup_snapshot

The initramfs-tools scripts for ZFS allow you to specify the root pool and dataset using various kernel command line arguments. The script evaluates these arguments in a specific order, and the first match wins.

Supported argument combinations:

• rpool=<pool>
• bootfs=<pool>/<dataset>
• rpool=<pool> bootfs=<pool>/<dataset>
• -B zfs-bootfs=<pool>/<fs>
• root=<pool>/<dataset>
• root=ZFS=<pool>/<dataset>
• root=zfs:AUTO
• root=zfs:<pool>/<dataset>
• rpool=rpool

Pool Discovery Behavior:

• If a pool is explicitly specified, it is used.
• If root=zfs:AUTO is used, the script searches all available pools. You can exclude specific pools from this search by adding them to the ZFS_POOL_EXCEPTIONS variable in /etc/default/zfs.
• The import search order is: /dev/disk/by-vdev (if /etc/zfs/vdev_id.conf exists) $\rightarrow$ /dev/disk/by-id and other /dev/disk/by-* directories $\rightarrow$ /dev $\rightarrow$ ZFS cache file.
• You can modify the import path by setting ZPOOL_IMPORT_PATH in /etc/default/zfs.

Filesystem Mounting:

• If a dataset is specified, it is used as the root. If not, the script attempts to find one automatically.
• Sub-filesystems below the root (e.g., rpool/ROOT/rootfs/var) are automatically mounted if they exist.

# Example kernel command line arguments:
rpool=rpool bootfs=rpool/ROOT/default
root=zfs:rpool/ROOT/default
root=zfs:AUTO