I’m a FreeBSD guy that has had a long, serious, and very much monogamous relationship with ZFS. I experimented with Solaris 9 to learn about ZFS, adopted OpenSolaris (2008?) back in the “aughts” for my first ZFS server, transitioned my installations over to OpenIndiana after Oracle bought Sun Microsystems out, and then at some point switched to FreeBSD, which I found to be a better designed OS once I had moved everything headless and was ready to completely bid the need for a desktop environment goodbye. But every once in a while I have to stand up a ZFS installation on Ubuntu, and then I spend a little too much time trying to remember how to do ZFS things that FreeBSD makes easy out-of-the-box. After doing that one time too many, I decided to put down my Linux-specific notes in a post for others (and myself) to reference in the future.<\/p>\n
This guide will focus mainly on the Linux sysadmin side of things; note that basic knowledge and understanding of ZFS concepts and principles is assumed, but I’ll do my best to provide a succinct summary of what we’re doing and why we’re doing it at each point.<\/p>\n
<\/p>\n
Unlike on FreeBSD, on Linux you need to manually install the ZFS kernel modules and userland tooling to bring in ZFS filesystem support and install the venerable This will download, build, and install the ZFS kernel modules to match the version of the Linux kernel you’re currently running. Unlike most kernel modules,1<\/a><\/sup> ZFS support isn’t built or distributed as part of the base kernel that Canonical maintains for its distributions, instead you have to manually build and load the kernel module that provides ZFS support (but this is automated by the This part of the process is largely going to be the same regardless of which operating system you are using and is standard ZFS fare. You’ll need to identify the drives you wish to use in your zpool (the ZFS abstraction over the physical disks, arranged in the hierarchy\/topography you desire) and use And you can verify that the operation has succeeded by using `zpool list` to see the list of zpools live on the system.<\/p>\n Most ZFS properties and features are configurable, can be set at any time,4<\/a><\/sup> and are inherited from parent datasets. Let’s set some default properties that are good starting values (we can always change them or override them for specific child datasets at any time):<\/p>\n The “zpool” is, as mentioned, the abstraction over the physical disks in your PC. It’s closest analogue is a “smart disk” comprised of multiple physical disks arranged in some specific topography with certain striping\/redundancy\/parity managed by the lower-level While ZFS automatically creates a dataset for the root zpool (in this case we now have and we can see all our datasets with `zfs list`, which shows them in their hierarchy\/tree as configured.<\/p>\n One of the coolest and most important ZFS features is undoubtedly its instant, zero-cost snapshotting (enabled by its copy-on-write design). This lets you freeze an image of any dataset (or all of them) as it exists at any point of time, then restore back to it (or selectively copy files\/data back, as needed) at any point in the future, regardless of any changes you’ve made. (You only pay the storage cost of data added or deleted thereafter.) ZFS snapshots can be made manually with On Linux, the best way to automate these snapshots is with After installing Let’s enable a daily snapshot of the root volume (and all child datasets):<\/p>\n You can repeat this but replace You can check if this is working (after waiting the prescribed amount of time) by checking to see what snapshots you have listed:<\/p>\n One thing that makes ZFS stand out compared to other operating systems like On FreeBSD, this would be accomplished with the help of a simple monthly periodic script, but on Linux (Ubuntu particularly) it’s not as simple. The idiomatic way of setting up monthly work on Ubuntu is via the use of systemd units (aka services) and timers, unfortunately this requires setting up two separate files, but the good news is that you can just copy and paste what I’ve provided below, only modifying the zpool name from The first file we need to create is the actual systemd service, which is what is tasked with running running the And copy this timer file (which specifies when Then execute the following to get systemd to see and activate the monthly scrub service:<\/p>\n and verify that the timer has been started with the following:<\/p>\n which should show you output along the lines of the following:<\/p>\n You can see if this is working by checking when the last scrub took place with And with that, you’re all set!<\/p>\n Largely due to licensing restriction workarounds ↩<\/a><\/p><\/li> This too is *normally* taken care of by the package manager, provided all the packages have been correctly built and uploaded to the repository by the time you try to install a newer kernel version. There’s very little you have to do manually. ↩<\/a><\/p><\/li> You could<\/em> use The most notable exception to this is the Or assuming you are using I’m a FreeBSD guy that has had a long, serious, and very much monogamous relationship with ZFS. I experimented with Solaris 9 to learn about ZFS, adopted OpenSolaris (2008?) back in the “aughts” for my first ZFS server, transitioned my … Continue reading zfs<\/code> and zpool<\/code> utils used to manage a ZFS installation. Canonical’s Ubuntu was, to my knowledge, the first to offer a pre-packaged ZFS option for Linux users (after gambling Oracle wouldn’t sue them for violating the CDDL license if they included ZFS support in their repos), and I believe it’s still the most popular Linux distribution for ZFS users, so the specific command line incantations below are for Ubuntu:<\/p>\nsudo apt install zfs-dkms\r\n<\/code><\/pre>\n.deb<\/code> installed with apt<\/code>) – and this needs to be done each time you upgrade the kernel.2<\/a><\/sup> All this really means is that installing zfs-dkms<\/code> will take longer than installing most packages – expect the installation process to look like it’s stuck and be extra patient. Installing zfs-dkms<\/code> will also pull in an automatic dependency on the userspace tools, zfsutils-linux<\/code>, as well as other ZFS-related libraries and dependencies.<\/p>\nStep 2: Setting up your zpool<\/h3>\n
sudo zpool create<\/code> to create your first zpool (traditionally named tank<\/code>). The only thing of note here is that you should use a stable path available to identify your disks, so instead of doing something like sudo zpool create tank mirror \/dev\/sda \/dev\/sdb<\/code> to create a two-disk mirror zpool comprised of the two disks \/dev\/sda<\/code> and \/dev\/sdb<\/code>, you should instead use a different path to the same device, such as via \/dev\/disk\/by-id\/<\/code> or \/dev\/disk\/by-uuid\/<\/code> (going with by-id\/<\/code>\u00a0might make it easier to figure out which disk to use, as the contents of by-uuid\/<\/code> are all GUIDs).3<\/a><\/sup> On Linux, lsblk<\/code> is your friend here to list disks attached to the system.<\/p>\n# to create a mirror of the two volumes:\r\nsudo zpool create -o ashift=12 tank mirror \/dev\/disk\/by-id\/scsi-0VOLUME_NAME_01 \/dev\/disk\/by-id\/scsi-0VOLUME_NAME_02\r\n<\/code><\/pre>\nsudo zfs set compression=lz4 tank # or =zstd if you're on the very newest versions\r\nsudo zfs set recordsize=1m tank # i\/o optimization for storing content that rarely changes\r\n<\/code><\/pre>\nStep 3: Creating your ZFS datasets<\/h3>\n
zpool<\/code> command. Just as a zpool is a virtual disk, a dataset is a “smart partition” used to break up your “disk” into multiple logical storage units. Unlike real partitions, zfs datasets aren’t fixed in size, they rather straddle the line between a partition and a folder. They can be nested (like a folder), but you can’t rename a file across datasets (like a separate filesystem\/partition). You can snapshot them individually (or altogether, atomically) for backup and cloning purposes (see below), and its the finest-grained level of control you have for turning on\/off or re-configuring ZFS features and properties like the record size (only available to the time of creation), automatic block-level compression, etc.<\/p>\n\/tank\/<\/code> mounted and ready) but it’s generally<\/em> not a good practice to write directly to this dataset. Instead, you should create one or more child datasets where most content will go. We’ll just create one dataset for now:<\/p>\nsudo zfs create tank\/data\r\n<\/code><\/pre>\nStep 4: Configuring automatic snapshots<\/h3>\n
sudo zfs snap -r tank@snapshot_name_or_date<\/code> (which snapshots tank<\/code> and all its child datasets, instantly) or sudo zfs snap tank\/data@snapshot_name<\/code> (which snapshots only the one tank\/data<\/code> dataset). But since they’re virtually free, why not go a step further and automatically take snapshots of the data on a schedule? That way you’re protected in case of inadvertent data loss, not just when you take a snapshot before manually performing a known potentially destructive action.<\/p>\nzfs-auto-snapshot<\/code>, which we’ll install with sudo apt install zfs-auto-snapshot<\/code>. It’ll automatically create new snapshots every month\/week\/day\/hour of designated zfs datasets, and delete the oldest ones too so you’re not paying the storage price forever.<\/p>\nzfs-auto-snapshot<\/code>, it’s time to choose which datasets we want to protect and how often we want to take the snapshots. Instead of using a configuration file, zfs-auto-snapshot<\/code> uses zfs properties to determine which zfs datasets to include in each snapshot interval, and since zfs properties are inherited by default, if we set up snapshots for the root dataset, it’ll automatically do the same for all child datasets.<\/p>\nsudo zfs set com.sun:auto-snapshot:daily=true tank\r\n<\/code><\/pre>\ndaily<\/code> with one of daily<\/code>, monthly<\/code>, weekly<\/code>, or hourly<\/code> to (additionally) opt-into that frequency of snapshots. To exclude<\/em> a dataset (and its children) from being included in a particular schedule, you can e.g. use sudo zfs set com.sun:auto-snapshot:daily=false tank\/no_backups<\/code> to turn off daily snapshots for the tank\/no_backups<\/code> dataset (assuming it exists).<\/p>\nzfs list -t snap<\/pre>\n
Step 5: Automatic monthly ZFS scrubs on Linux with systemd<\/h3>\n
ext4<\/code> or even xfs<\/code> is that it calculates the hash of each block of data you store on it. In the event of bitrot<\/a> (the silent corruption of data already stored to disk), zfs can a) flag that a file has been silently corrupted, b) automatically restore a good copy from another disk or parity (assuming your zpool topography provides redunancy).5<\/a><\/sup> It does this automatically every time you read a file, but what about if you have terabytes of data just sitting there, silently rotting away? How do you catch that corruption in time to fix it from a second copy on the zpool? The zpool scrub tank<\/code> operation runs a low-priority scan in the background to detect and (hopefully) repair just that, but it needs to be scheduled (or run manually).<\/p>\ntank<\/code> to whatever you are using, as needed.<\/p>\nzfs scrub<\/code> operation. Copy the following to \/etc\/systemd\/system\/zfs-scrub.service<\/code>:<\/p>\n[Unit]\r\nDescription=ZFS scrub of all pools\r\n\r\n[Service]\r\nType=oneshot\r\nExecStart=\/usr\/sbin\/zpool scrub tank\r\n<\/code><\/pre>\nzfs-scrub.service<\/code> is automatically run) to \/etc\/systemd\/system\/zfs-scrub.timer<\/code>:<\/p>\n[Unit]\r\nDescription=Run ZFS scrub service monthly\r\n\r\n[Timer]\r\nOnCalendar=monthly\r\n# Run if missed while machine was off\r\nPersistent=true\r\n# Add some randomization to start time to prevent thundering herd\r\nRandomizedDelaySec=30m\r\nAccuracySec=1h\r\n\r\n[Install]\r\nWantedBy=timers.target\r\n<\/code><\/pre>\nsystemctl daemon-reload\r\nsystemctl enable --now zfs-scrub.timer\r\n<\/code><\/pre>\nsystemctl list-timers zfs-scrub.timer\r\n<\/code><\/pre>\n$ systemctl list-timers zfs-scrub.timer\r\nNEXT LEFT LAST PASSED UNIT ACTIVATES\r\nWed 2025-10-01 00:23:31 UTC 2 weeks 6 days - - zfs-scrub.timer zfs-scrub.service\r\n\r\n1 timers listed.\r\n<\/code><\/pre>\nzpool status<\/code>:<\/p>\n$ zpool status\r\npool: tank\r\nstate: ONLINE\r\nscan: scrub repaired 0B in 00:00:00 with 0 errors on Wed Sep 10 18:43:22 2025\r\n<\/code><\/pre>\n\/dev\/disk\/by-path\/<\/code> but that means if you physically swap disks around in their cages the references would become switched around, so it’s best not to. ↩<\/a><\/p><\/li>ashift<\/code> property set above with -o ashift=12<\/code>, which is a decent value for any ssd or 4k\/512e hdd. ↩<\/a><\/p><\/li>zfs set copies=2 tank<\/code> (or greater). ↩<\/a><\/p><\/li><\/ol>","protected":false},"excerpt":{"rendered":"