Install ZFS on Debian 12 (Hetzner Cloud VPS)

This guide is part of a series on setting up an Incus host server on Hetzner Cloud. It follows the initial article where we covered repartitioning the existing disk to create a dedicated 30GB partition for ZFS. This tutorial will walk you through the process of installing and configuring ZFS on Debian 12, with specific optimizations for Hetzner Cloud VPS environments.

1. Configure Debian Backports

ZFS packages are available through the Debian backports repository. We’ll add this to our system and configure package pinning:

# Create the backports source list file
cat > /etc/apt/sources.list.d/bookworm-backports.list << EOF
deb http://deb.debian.org/debian bookworm-backports main contrib
deb-src http://deb.debian.org/debian bookworm-backports main contrib
EOF

# Configure package preferences for ZFS
cat > /etc/apt/preferences.d/90_zfs << EOF
Package: src:zfs-linux
Pin: release n=bookworm-backports
Pin-Priority: 990
EOF

Understanding ZFS Package Pinning:

• We pin src:zfs-linux specifically because it’s the source package for the ZFS kernel modules and userspace utilities
• The src: prefix ensures that all binary packages built from this source package are pinned
• This pinning is crucial for maintaining version consistency between:
• The ZFS kernel modules
• The userspace utilities
• Related dependencies
• The priority of 990 ensures packages are installed from backports while being below 1000 (which would force installation of packages not explicitly requested)
• This approach follows the official ZFS on Linux recommendations for Debian systems

2. Install Required Packages

Update the package list and install the necessary packages:

apt update
apt install dpkg-dev linux-headers-generic linux-image-generic -y
apt install zfs-dkms zfsutils-linux -y

3. Load ZFS Module

Ensure the ZFS module is loaded and configured to load at boot:

modprobe zfs
echo zfs >> /etc/modules

4. Configure ZFS ARC Size

For a system with 4GB RAM, we’ll set a conservative ARC size to ensure enough memory for other processes:

# Set ARC to 1.5GB maximum
echo "options zfs zfs_arc_max=$((1536*1024*1024))" >> /etc/modprobe.d/zfs.conf

Note on ARC Sizing: The general rule is 2 GiB base + 1 GiB/TiB of storage. However, for systems with limited RAM, we use a more conservative value to ensure system stability.

5. Create ZFS Pool

First, identify your disk:

ls -al /dev/disk/by-id/

Create the ZFS pool with optimized settings:

zpool create -o ashift=12 -O atime=off -O compression=lz4 \
incus-zfs /dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_XXXXX-partX

Important Settings Explained:

• ashift=12: Optimized for 4K sectors, which is appropriate for most modern storage systems including Hetzner’s underlying SSD infrastructure
• atime=off: Reduces write operations by not updating access times
• compression=lz4: Provides efficient compression with minimal CPU overhead, ideal for VPS environments
• Using /dev/disk/by-id/ ensures consistent device naming across reboots

6. Enable ZFS Services

Enable necessary ZFS services to ensure proper operation:

systemctl enable zfs-import-cache
systemctl enable zfs-import.target
systemctl enable zfs-mount
systemctl enable zfs.target

7. Verify Installation

Check the status of your ZFS pool and configuration:

# Check pool status
zpool status
zpool list

# Check ZFS properties
zfs list
zfs get all incus-zfs

Compression Considerations

The default configuration uses LZ4 compression, which provides a good balance of compression ratio and performance. While ZSTD-9 offers better compression ratios, it’s generally not recommended for VPS environments with limited CPU resources. If you want to experiment with ZSTD:

# Change compression for new writes
zfs set compression=zstd-9 incus-zfs

Note: Compression changes only affect new writes. Existing data retains its original compression.

Monitoring and Maintenance

Regular monitoring helps ensure optimal performance:

# Check compression ratio
zfs get compressratio incus-zfs

# Monitor IO statistics
zpool iostat -v

# Check pool health
zpool scrub incus-zfs
zpool status

Troubleshooting

If you encounter issues, check these common points:

1. Verify ZFS module is loaded:

lsmod | grep zfs

2. Check system logs:

journalctl -u zfs-import-cache
journalctl -u zfs-mount

3. Verify memory usage:

arc_summary

Next Steps

With ZFS now properly configured, your system is ready for Incus installation. The next article in this series will cover the installation and configuration of Incus using this ZFS storage pool.