Features of ZFS include: pooled storage (integrated volume management – zpool), Copy-on-write, snapshots, data integrity verification and automatic repair (scrubbing), RAID-Z, a maximum 16 Exabyte file size, and a maximum 256 Quadrillion Zettabytes storage with no limit on number of filesystems (datasets) or files. ZFS is licensed under the Common Development and Distribution License (CDDL).
Described as "The last word in filesystems" ZFS is stable, fast, secure, and future-proof. Being licensed under the CDDL, and thus incompatible with GPL, it is not possible for ZFS to be distributed along with the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with zfsonlinux.org (ZOL).
ZOL is a project funded by the Lawrence Livermore National Laboratory to develop a native Linux kernel module for its massive storage requirements and super computers.
As a result:
- ZFSonLinux project must keep up with Linux kernel versions. After making stable ZFSonLinux release - Arch ZFS maintainers release them.
- This situation sometimes locks down the normal rolling update process by unsatisfied dependencies because the new kernel version, proposed by update, is unsupported by ZFSonLinux.
- 1 Installation
- 2 Experimenting with ZFS
- 3 Configuration
- 4 Creating a storage pool
- 5 Tuning
- 5.1 General
- 5.2 Scrubbing
- 5.3 Destroy a storage pool
- 5.4 Exporting a storage pool
- 5.5 Extending an existing zpool
- 5.6 Renaming a zpool
- 5.7 Setting a different mount point
- 5.8 SSD Caching
- 5.9 ZVOLs
- 5.10 I/O Scheduler
- 6 Creating datasets
- 7 Troubleshooting
- 7.1 Creating a zpool fails
- 7.2 ZFS is using too much RAM
- 7.3 Does not contain an EFI label
- 7.4 No hostid found
- 7.5 Pool cannot be found while booting from SAS/SCSI devices
- 7.6 On boot the zfs pool does not mount stating: "pool may be in use from other system"
- 7.7 Devices have different sector alignment
- 7.8 Pool resilvering stuck/restarting/slow?
- 7.9 Fix slow boot caused by failed import of unavailable pools in the initramfs zpool.cache
- 8 Tips and tricks
- 8.1 Embed the archzfs packages into an archiso
- 8.2 Automatic snapshots
- 8.3 Creating a share
- 8.4 Encryption in ZFS using dm-crypt
- 8.5 Emergency chroot repair with archzfs
- 8.6 Bind mount
- 8.7 Monitoring / Mailing on Events
- 8.8 Wrap shell commands in pre & post snapshots
- 8.9 Remote unlocking of ZFS encrypted root
- 9 See also
- stable releases. AUR for
- development releases (with support of newer kernel versions). AUR for
- AUR for stable releases for LTS kernels.
- development releases for LTS kernels. AUR for
- AUR for stable releases for hardened kernels.
- development releases for hardened kernels. AUR for
- AUR for stable releases for zen kernels.
- development releases for zen kernels. AUR for
- AUR for versions with dynamic kernel module support.
- development releases for versions with dynamic kernel module support. AUR for
These branches have (according to them) dependencies on the
spl-utils packages. SPL (Solaris Porting Layer) is a Linux Kernel module implementing Solaris APIs for ZFS compatibility.
Test the installation by issuing
zpool status on the command line. If an "insmod" error is produced, try
Root on ZFS
When performing an Arch install on ZFS,AUR or AUR and its dependencies can be installed in the archiso environment as outlined in the previous section.
Users can make use of DKMS Dynamic Kernel Module Support to rebuild the ZFS modules automatically with every kernel upgrade.
InstallAUR or AUR and apply the post-install instructions given by these packages.
IgnorePkgentry to pacman.conf to prevent these packages from upgrading when doing a regular update.
Experimenting with ZFS
Users wishing to experiment with ZFS on virtual block devices (known in ZFS terms as VDEVs) which can be simple files like
~/zfs2.img etc. with no possibility of real data loss are encouraged to see the Experimenting with ZFS article. Common tasks like building a RAIDZ array, purposefully corrupting data and recovering it, snapshotting datasets, etc. are covered.
ZFS is considered a "zero administration" filesystem by its creators; therefore, configuring ZFS is very straight forward. Configuration is done primarily with two commands:
Currently, by default, the kernel module is not loaded at boot (see more details in https://github.com/zfsonlinux/zfs/issues/6083). To automatically load
zfs module on boot, see Kernel module#Automatic module loading with systemd.
For ZFS to live by its "zero administration" namesake,
zfs-import-cache.service must be enabled to import the pools and
zfs-mount.service must be enabled to mount the filesystems available in the pools. A benefit to this is that it is not necessary to mount ZFS filesystems in
zfs-import-cache.service imports the zfs pools reading the file
For each imported pool you want automatically imported by
# zpool set cachefile=/etc/zfs/zpool.cache <pool>
Enable the relevant service and target so the pools are automatically imported at boot time:
# systemctl enable zfs-import-cache # systemctl enable zfs-import.target
To mount the ZFS filesystems, you have 2 choices:
In order to mount ZFS filesystems automatically on boot you need to enable the following services and targets:
# systemctl enable zfs-mount # systemctl enable zfs.target
You can also use the zfs-mount-generator to create systemd mount units for your ZFS filesystems at boot. systemd will automatically mount the filesystems based on the mount units without having to use the
zfs-mount.service. To do that, you need to:
- Create the
- Enable the ZFS Event Daemon(ZED) script (called a ZEDLET) required to create a list of mountable ZFS filesystems.
# ln -s /usr/lib/zfs/zfs/zed.d/history_event-zfs-list-cacher.sh /etc/zfs/zed.d
- Enable and start the ZFS Event Daemon. This service is responsible for running the script in the previous step.
# systemctl enable zfs-zed.service
# systemctl enable zfs.target
# systemctl start zfs-zed.service
- You need to create an empty file named after your pool in
/etc/zfs/zfs-list.cache. The ZEDLET will only update the list of filesystems if the file for the pool already exists.
# touch /etc/zfs/zfs-list.cache/<pool-name>
- Check the contents of
/etc/zfs/zfs-list.cache/<pool-name>. If it is empty, make sure that the
zfs-zed.serviceis running and just change the canmount property of any of your ZFS filesystem by running:
zfs set canmount=off zroot/fs1This change causes ZFS to raise an event which is captured by ZED, which in turn runs the ZEDLET to update the file in
/etc/zfs/zfs-list.cache. If the file in
/etc/zfs/zfs-list.cacheis updated, you can set the
canmountproperty of the filesystem back by running:
zfs set canmount=on zroot/fs1
You need to add a file in
/etc/zfs/zfs-list.cache for each ZFS pool in your system. Make sure the pools are imported by enabling
zfs-import.target as explained above.
Creating a storage pool
It is not necessary to partition the drives before creating the ZFS filesystem. It is recommended to point ZFS at an entire disk (ie. `/dev/sdx` rather than `/dev/sdx1`), which will automatically create a GPT partition table and add an 8 MB reserved partition at the end of the disk for legacy bootloaders. However, you can specify a partition or a file within an existing filesystem, if you wish to create multiple volumes with different redundancy properties.
ZFS on Linux recommends using device IDs when creating ZFS storage pools of less than 10 devices. Use Persistent block device naming#by-id and by-path to identify the list of drives to be used for ZFS pool.
The disk IDs should look similar to the following:
# ls -lh /dev/disk/by-id/
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JKRR -> ../../sdc lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JTM1 -> ../../sde lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KBP8 -> ../../sdd lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KDGY -> ../../sdb
/dev/sdb,...) ZFS might not be able to detect zpools intermittently on boot.
Using GPT labels
Disk labels and UUID can also be used for ZFS mounts by using GPT partitions. ZFS drives have labels but Linux is unable to read them at boot. Unlike MBR partitions, GPT partitions directly support both UUID and labels independent of the format inside the partition. Partitioning rather than using the whole disk for ZFS offers two additional advantages. The OS does not generate bogus partition numbers from whatever unpredictable data ZFS has written to the partition sector, and if desired, you can easily over provision SSD drives, and slightly over provision spindle drives to ensure that different models with slightly different sector counts can zpool replace into your mirrors. This is a lot of organization and control over ZFS using readily available tools and techniques at almost zero cost.
Use gdisk to partition the all or part of the drive as a single partition. gdisk does not automatically name partitions so if partition labels are desired use gdisk command "c" to label the partitions. Some reasons you might prefer labels over UUID are: labels are easy to control, labels can be titled to make the purpose of each disk in your arrangement readily apparent, and labels are shorter and easier to type. These are all advantages when the server is down and the heat is on. GPT partition labels have plenty of space and can store most international characters wikipedia:GUID_Partition_Table#Partition_entries allowing large data pools to be labeled in an organized fashion.
Drives partitioned with GPT have labels and UUID that look like this.
# ls -l /dev/disk/by-partlabel # lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata1 -> ../../sdd1 # lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata2 -> ../../sdc1 # lrwxrwxrwx 1 root root 10 Apr 30 01:59 zfsl2arc -> ../../sda1
# ls -l /dev/disk/by-partuuid # lrwxrwxrwx 1 root root 10 Apr 30 01:44 148c462c-7819-431a-9aba-5bf42bb5a34e -> ../../sdd1 # lrwxrwxrwx 1 root root 10 Apr 30 01:59 4f95da30-b2fb-412b-9090-fc349993df56 -> ../../sda1 # lrwxrwxrwx 1 root root 10 Apr 30 01:44 e5ccef58-5adf-4094-81a7-3bac846a885f -> ../../sdc1
$ UUID=$( lsblk --noheadings --output PARTUUID /dev/sdXY )
Creating ZFS pools
To create a ZFS pool:
# zpool create -f -m <mount> <pool> [raidz(2|3)|mirror] <ids>
ashifton pool creation.
- create: subcommand to create the pool.
- -f: Force creating the pool. This is to overcome the "EFI label error". See #Does not contain an EFI label.
- -m: The mount point of the pool. If this is not specified, then the pool will be mounted to
- pool: This is the name of the pool.
- raidz(2|3)|mirror: This is the type of virtual device that will be created from the pool of devices, raidz is a single disk of parity, raidz2 for 2 disks of parity and raidz3 for 3 disks of parity, similar to raid5 and raid6. Also available is mirror, which is similar to raid1 or raid10, but is not constrained to just 2 device. If not specified, each device will be added as a vdev which is similar to raid0. After creation, a device can be added to each single drive vdev to turn it into a mirror, which can be useful for migrating data.
- ids: The ID's of the drives or partitions that to include into the pool.
Create pool with single raidz vdev:
# zpool create -f -m /mnt/data bigdata \ raidz \ ata-ST3000DM001-9YN166_S1F0KDGY \ ata-ST3000DM001-9YN166_S1F0JKRR \ ata-ST3000DM001-9YN166_S1F0KBP8 \ ata-ST3000DM001-9YN166_S1F0JTM1
Create pool with two mirror vdevs:
# zpool create -f -m /mnt/data bigdata \ mirror \ ata-ST3000DM001-9YN166_S1F0KDGY \ ata-ST3000DM001-9YN166_S1F0JKRR \ mirror \ ata-ST3000DM001-9YN166_S1F0KBP8 \ ata-ST3000DM001-9YN166_S1F0JTM1
Advanced Format disks
At pool creation, ashift=12 should always be used, except with SSDs that have 8k sectors where ashift=13 is correct. A vdev of 512 byte disks using 4k sectors will not experience performance issues, but a 4k disk using 512 byte sectors will. Since ashift cannot be changed after pool creation, even a pool with only 512 byte disks should use 4k because those disks may need to be replaced with 4k disks or the pool may be expanded by adding a vdev composed of 4k disks. Because correct detection of 4k disks is not reliable,
-o ashift=12 should always be specified during pool creation. See the ZFS on Linux FAQ for more details.
# blockdev --getpbsz /dev/sdXY.
Create pool with ashift=12 and single raidz vdev:
# zpool create -f -o ashift=12 -m /mnt/data bigdata \ raidz \ ata-ST3000DM001-9YN166_S1F0KDGY \ ata-ST3000DM001-9YN166_S1F0JKRR \ ata-ST3000DM001-9YN166_S1F0KBP8 \ ata-ST3000DM001-9YN166_S1F0JTM1
GRUB-compatible pool creation
By default, zpool create enables all features on a pool. If
/boot resides on ZFS when using GRUB you must only enable features supported by GRUB otherwise GRUB will not be able to read the pool. GRUB 2.02 supports the read-write features
large_blocks; this is not suitable for all the features of ZFSonLinux 0.8.0, and must have unsupported features disabled. We can explicitly name features to enable with the
-d argument to
zpool create, which disables all features by default.
You can create a pool with only the compatible features enabled:
# zpool create -d -o feature@allocation_classes=enabled \ -o feature@async_destroy=enabled \ -o feature@bookmarks=enabled \ -o feature@embedded_data=enabled \ -o feature@empty_bpobj=enabled \ -o feature@enabled_txg=enabled \ -o feature@extensible_dataset=enabled \ -o feature@filesystem_limits=enabled \ -o feature@hole_birth=enabled \ -o feature@large_blocks=enabled \ -o feature@lz4_compress=enabled \ -o feature@project_quota=enabled \ -o feature@resilver_defer=enabled \ -o feature@spacemap_histogram=enabled \ -o feature@spacemap_v2=enabled \ -o feature@userobj_accounting=enabled \ -o feature@zpool_checkpoint=enabled \ $POOL_NAME $VDEVS
Verifying pool status
If the command is successful, there will be no output. Using the mount command will show that the pool is mounted. Using
zpool status will show that the pool has been created:
# zpool status -v
pool: bigdata state: ONLINE scan: none requested config: NAME STATE READ WRITE CKSUM bigdata ONLINE 0 0 0 -0 ONLINE 0 0 0 ata-ST3000DM001-9YN166_S1F0KDGY-part1 ONLINE 0 0 0 ata-ST3000DM001-9YN166_S1F0JKRR-part1 ONLINE 0 0 0 ata-ST3000DM001-9YN166_S1F0KBP8-part1 ONLINE 0 0 0 ata-ST3000DM001-9YN166_S1F0JTM1-part1 ONLINE 0 0 0 errors: No known data errors
At this point it would be good to reboot the machine to ensure that the ZFS pool is mounted at boot. It is best to deal with all errors before transferring data.
Importing a pool created by id
Eventually a pool may fail to auto mount and you need to import to bring your pool back. Take care to avoid the most obvious solution.
zpool import pool! This will import your pools using
/dev/sd?which will lead to problems the next time you rearrange your drives. This may be as simple as rebooting with a USB drive left in the machine, which harkens back to a time when PCs would not boot when a floppy disk was left in a machine.
Adapt one of the following commands to import your pool so that pool imports retain the persistence they were created with:
# zpool import -d /dev/disk/by-id bigdata # zpool import -d /dev/disk/by-partlabel bigdata # zpool import -d /dev/disk/by-partuuid bigdata
-lflag when importing a pool that contains encrypted datasets keys:
# zpool import -l -d /dev/disk/by-id bigdata
Finally check the state of the pool:
# zpool status -v bigdata
ZFS pools can be further adjusted using parameters, most commonly
To retrieve the current pool parameter status:
# zfs get all <pool>
To disable access time (atime), which is enabled by default:
# zfs set atime=off <pool>
As an alternative to turning off atime completely,
relatime is available. This brings the default ext4/XFS atime semantics to ZFS, where access time is only updated if the modified time or changed time changes, or if the existing access time has not been updated within the past 24 hours. It is a compromise between
atime=on. This property only takes effect if
# zfs set atime=on <pool> # zfs set relatime=on <pool>
Compression is just that, transparent compression of data. ZFS supports a few different algorithms, presently lz4 is the default, gzip is also available for seldom-written yet highly-compressible data; consult the OpenZFS Wiki for more details.
To enable compression:
# zfs set compression=on <pool>
# zfs inherit -rS atime <pool> # zfs inherit -rS atime <pool>/<dataset>
Whenever data is read and ZFS encounters an error, it is silently repaired when possible, rewritten back to disk and logged so you can obtain an overview of errors on your pools. There is no fsck or equivalent tool for ZFS. Instead, ZFS supports a feature known as scrubbing. This traverses through all the data in a pool and verifies that all blocks can be read.
To scrub a pool:
# zpool scrub <pool>
To cancel a running scrub:
# zpool scrub -s <pool>
How often should I do this?
From the Oracle blog post Disk Scrub - Why and When?:
- This question is challenging for Support to answer, because as always the true answer is "It Depends". So before I offer a general guideline, here are a few tips to help you create an answer more tailored to your use pattern.
- What is the expiration of your oldest backup? You should probably scrub your data at least as often as your oldest tapes expire so that you have a known-good restore point.
- How often are you experiencing disk failures? While the recruitment of a hot-spare disk invokes a "resilver" -- a targeted scrub of just the VDEV which lost a disk -- you should probably scrub at least as often as you experience disk failures on average in your specific environment.
- How often is the oldest piece of data on your disk read? You should scrub occasionally to prevent very old, very stale data from experiencing bit-rot and dying without you knowing it.
- If any of your answers to the above are "I do not know", the general guideline is: you should probably be scrubbing your zpool at least once per month. It is a schedule that works well for most use cases, provides enough time for scrubs to complete before starting up again on all but the busiest & most heavily-loaded systems, and even on very large zpools (192+ disks) should complete fairly often between disk failures.
In the ZFS Administration Guide by Aaron Toponce, he advises to scrub consumer disks once a week.
Start with a service or timer
Using a systemd timer/service it is possible to automatically scrub pools monthly:
[Unit] Description=Monthly zpool scrub on %i [Timer] OnCalendar=monthly AccuracySec=1h Persistent=true [Install] WantedBy=multi-user.target
[Unit] Description=zpool scrub on %i [Service] Nice=19 IOSchedulingClass=idle KillSignal=SIGINT ExecStart=/usr/bin/zpool scrub %i
Destroy a storage pool
ZFS makes it easy to destroy a mounted storage pool, removing all metadata about the ZFS device.
To destroy the pool:
# zpool destroy <pool>
To destroy a dataset:
# zpool destroy <pool>/<dataset>
And now when checking the status:
# zpool status
no pools available
Exporting a storage pool
If a storage pool is to be used on another system, it will first need to be exported. It is also necessary to export a pool if it has been imported from the archiso as the hostid is different in the archiso as it is in the booted system. The zpool command will refuse to import any storage pools that have not been exported. It is possible to force the import with the
-f argument, but this is considered bad form.
Any attempts made to import an un-exported storage pool will result in an error stating the storage pool is in use by another system. This error can be produced at boot time abruptly abandoning the system in the busybox console and requiring an archiso to do an emergency repair by either exporting the pool, or adding the
zfs_force=1 to the kernel boot parameters (which is not ideal). See #On boot the zfs pool does not mount stating: "pool may be in use from other system"
To export a pool:
# zpool export <pool>
Extending an existing zpool
A device (a partition or a disk) can be added to an existing zpool:
# zpool add <pool> <device-id>
To import a pool which consists of multiple devices:
# zpool import -d <device-id-1> -d <device-id-2> <pool>
# zpool import -d /dev/disk-by-id/ <pool>
Renaming a zpool
Renaming a zpool that is already created is accomplished in 2 steps:
# zpool export oldname # zpool import oldname newname
Setting a different mount point
The mount point for a given zpool can be moved at will with one command:
# zfs set mountpoint=/foo/bar poolname
You can add SSD devices as a write intent log (external ZIL or SLOG) and also as a layer 2 adaptive replacement cache (L2ARC). The process to add them is very similar to adding a new VDEV.
All of the below references to device-id are the IDs from
To add a mirrored SLOG:
# zpool add <pool> log mirror <device-id-1> <device-id-2>
Or to add a single device SLOG (unsafe):
# zpool add <pool> log <device-id>
Because the SLOG device stores data that has not been written to the pool, it is important to use devices that can finish writes when power is lost. It is also important to use redundancy, since a device failure can cause data loss. In addition, the SLOG is only used for sync writes, so may not provide any performance improvement.
To add L2ARC:
# zpool add <pool> cache <device-id>
Because every block cached in L2ARC uses a small amount of memory, it is generally only useful in workloads where the amount of hot data is *bigger* than the maximum amount of memory that can fit in the computer, but small enough to fit into L2ARC. It is also cleared at reboot and is only a read cache, so redundancy is unnecessary. Un-intuitively, L2ARC can actually harm performance since it takes memory away from ARC.
ZFS volumes (ZVOLs) can suffer from the same block size-related issues as RDBMSes, but it is worth noting that the default recordsize for ZVOLs is 8 KiB already. If possible, it is best to align any partitions contained in a ZVOL to your recordsize (current versions of fdisk and gdisk by default automatically align at 1MiB segments, which works), and file system block sizes to the same size. Other than this, you might tweak the recordsize to accommodate the data inside the ZVOL as necessary (though 8 KiB tends to be a good value for most file systems, even when using 4 KiB blocks on that level).
RAIDZ and Advanced Format physical disks
Each block of a ZVOL gets its own parity disks, and if you have physical media with logical block sizes of 4096B, 8192B, or so on, the parity needs to be stored in whole physical blocks, and this can drastically increase the space requirements of a ZVOL, requiring 2× or more physical storage capacity than the ZVOL's logical capacity. Setting the recordsize to 16k or 32k can help reduce this footprint drastically.
When the pool is imported, for whole disk vdevs, the block device I/O scheduler is set to
zfs_vdev_scheduler . The most common schedulers are: noop, cfq, bfq, and deadline.
In some cases, the scheduler is not changeable using this method. Known schedulers that cannot be changed are: scsi_mq and none. In these cases, the scheduler is unchanged and an error message can be reported to logs. Manually setting one of the common schedulers used by
zfs_vdev_scheduler can result in more consistent performance.
Users can optionally create a dataset under the zpool as opposed to manually creating directories under the zpool. Datasets allow for an increased level of control (quotas for example) in addition to snapshots. To be able to create and mount a dataset, a directory of the same name must not pre-exist in the zpool. To create a dataset, use:
# zfs create <nameofzpool>/<nameofdataset>
It is then possible to apply ZFS specific attributes to the dataset. For example, one could assign a quota limit to a specific directory within a dataset:
# zfs set quota=20G <nameofzpool>/<nameofdataset>/<directory>
To see all the commands available in ZFS, seeor .
ZFS offers the following supported encryption options:
aes-256-gcm. When encryption is set to
aes-256-ccm will be used.
The following keyformats are supported:
One can also specify/increase the default iterations of PBKDF2 when using
-o pbkdf2iters <n>, although it may increase the decryption time.
- Native ZFS encryption has been made available in the stable 0.8.0 release or newer. Previously it was only available in development versions provided by packages like AUR, AUR or other development builds. Users who were only using the development versions for the native encryption, may now switch to the stable releases if they wish.
- To import a pool with keys, one needs to specify the
-lflag, without this flag encrypted datasets will be left unavailable until the keys are loaded. See #Importing a pool created by id.
To create a dataset including native encryption with a passphrase, use:
# zfs create -o encryption=on -o keyformat=passphrase <nameofzpool>/<nameofdataset>
To use a key instead of using a passphrase:
# dd if=/dev/random of=/path/to/key bs=1 count=32 # zfs create -o encryption=on -o keyformat=raw -o keylocation=file:///path/to/key <nameofzpool>/<nameofdataset>
To verify the key location:
# zfs get keylocation <nameofzpool>/<nameofdataset>
To change the key location:
# zfs set keylocation=file:///path/to/key <nameofzpool>/<nameofdataset>
You can also manually load the keys by using one of the following commands:
# zfs load-key <nameofzpool>/<nameofdataset> # load key for a specific dataset # zfs load-key -a # load all keys # zfs load-key -r zpool/dataset # load all keys in a dataset
To mount the created encrypted dataset:
# zfs mount <nameofzpool>/<nameofdataset>
Unlock at boot time
It is possible to automatically unlock a pool dataset on boot time by using a systemd unit. For example create the following service to unlock any dataset of the pool named tank:
[Unit] Description=Load %I encryption keys Before=systemd-user-sessions.service After=zfs-import.target [Service] Type=oneshot RemainAfterExit=yes ExecStart=/usr/bin/bash -c 'until (systemd-ask-password "Encrypted ZFS password for %I" --no-tty | zfs load-key %I); do echo "Try again!"; done' [Install] WantedBy=zfs-mount.service
Before=systemd-user-sessions.serviceensures that systemd-ask-password is invoked before the local IO devices are handed over to the desktop environment.
An alternative is to load all possible keys:
[Unit] Description=Load encryption keys DefaultDependencies=no After=zfs-import.target [Service] Type=oneshot RemainAfterExit=yes ExecStart=/usr/bin/bash -c '/usr/bin/zfs load-key -a' [Install] WantedBy=zfs-mount.service
ZFS does not allow to use swapfiles, but users can use a ZFS volume (ZVOL) as swap. It is important to set the ZVOL block size to match the system page size, which can be obtained by the
getconf PAGESIZE command (default on x86_64 is 4KiB). Another option useful for keeping the system running well in low-memory situations is not caching the ZVOL data.
Create a 8 GiB zfs volume:
# zfs create -V 8G -b $(getconf PAGESIZE) \ -o logbias=throughput -o sync=always\ -o primarycache=metadata \ -o com.sun:auto-snapshot=false <pool>/swap
Prepare it as swap partition:
# mkswap -f /dev/zvol/<pool>/swap # swapon /dev/zvol/<pool>/swap
To make it permanent, edit
/etc/fstab. ZVOLs support discard, which can potentially help ZFS's block allocator and reduce fragmentation for all other datasets when/if swap is not full.
Add a line to
/dev/zvol/<pool>/swap none swap discard 0 0
Access Control Lists
To use ACL on a ZFS pool:
# zfs set acltype=posixacl <nameofzpool>/<nameofdataset> # zfs set xattr=sa <nameofzpool>/<nameofdataset>
xattr is recommended for performance reasons .
It may be preferable to enable ACL on the zpool instead. Setting
aclinherit=passthrough may be wanted as the default mode is
# zfs set aclinherit=passthrough <nameofzpool> # zfs set acltype=posixacl <nameofzpool> # zfs set xattr=sa <nameofzpool>
ZFS, unlike most other file systems, has a variable record size, or what is commonly referred to as a block size. By default, the recordsize on ZFS is 128KiB, which means it will dynamically allocate blocks of any size from 512B to 128KiB depending on the size of file being written. This can often help fragmentation and file access, at the cost that ZFS would have to allocate new 128KiB blocks each time only a few bytes are written to.
Most RDBMSes work in 8KiB-sized blocks by default. Although the block size is tunable for MySQL/MariaDB, PostgreSQL, and Oracle, all three of them use an 8KiB block size by default. For both performance concerns and keeping snapshot differences to a minimum (for backup purposes, this is helpful), it is usually desirable to tune ZFS instead to accommodate the databases, using a command such as:
# zfs set recordsize=8K <pool>/postgres
These RDBMSes also tend to implement their own caching algorithm, often similar to ZFS's own ARC. In the interest of saving memory, it is best to simply disable ZFS's caching of the database's file data and let the database do its own job:
# zfs set primarycache=metadata <pool>/postgres
If your pool has no configured log devices, ZFS reserves space on the pool's data disks for its intent log (the ZIL). ZFS uses this for crash recovery, but databases are often syncing their data files to the file system on their own transaction commits anyway. The end result of this is that ZFS will be committing data twice to the data disks, and it can severely impact performance. You can tell ZFS to prefer to not use the ZIL, and in which case, data is only committed to the file system once. Setting this for non-database file systems, or for pools with configured log devices, can actually negatively impact the performance, so beware:
# zfs set logbias=throughput <pool>/postgres
These can also be done at file system creation time, for example:
# zfs create -o recordsize=8K \ -o primarycache=metadata \ -o mountpoint=/var/lib/postgres \ -o logbias=throughput \ <pool>/postgres
Please note: these kinds of tuning parameters are ideal for specialized applications like RDBMSes. You can easily hurt ZFS's performance by setting these on a general-purpose file system such as your /home directory.
If you would like to use ZFS to store your /tmp directory, which may be useful for storing arbitrarily-large sets of files or simply keeping your RAM free of idle data, you can generally improve performance of certain applications writing to /tmp by disabling file system sync. This causes ZFS to ignore an application's sync requests (eg, with
O_SYNC) and return immediately. While this has severe application-side data consistency consequences (never disable sync for a database!), files in /tmp are less likely to be important and affected. Please note this does not affect the integrity of ZFS itself, only the possibility that data an application expects on-disk may not have actually been written out following a crash.
# zfs set sync=disabled <pool>/tmp
Additionally, for security purposes, you may want to disable setuid and devices on the /tmp file system, which prevents some kinds of privilege-escalation attacks or the use of device nodes:
# zfs set setuid=off <pool>/tmp # zfs set devices=off <pool>/tmp
Combining all of these for a create command would be as follows:
# zfs create -o setuid=off -o devices=off -o sync=disabled -o mountpoint=/tmp <pool>/tmp
Please note, also, that if you want /tmp on ZFS, you will need to mask (disable) systemd's automatic tmpfs-backed /tmp, else ZFS will be unable to mount your dataset at boot-time or import-time:
# systemctl mask tmp.mount
Creating a zpool fails
If the following error occurs then it can be fixed.
# the kernel failed to rescan the partition table: 16 # cannot label 'sdc': try using parted(8) and then provide a specific slice: -1
One reason this can occur is because ZFS expects pool creation to take less than 1 second. This is a reasonable assumption under ordinary conditions, but in many situations it may take longer. Each drive will need to be cleared again before another attempt can be made.
# parted /dev/sda rm 1 # parted /dev/sda rm 1 # dd if=/dev/zero of=/dev/sdb bs=512 count=1 # zpool labelclear /dev/sda
A brute force creation can be attempted over and over again, and with some luck the ZPool creation will take less than 1 second. Once cause for creation slowdown can be slow burst read writes on a drive. By reading from the disk in parallell to ZPool creation, it may be possible to increase burst speeds.
# dd if=/dev/sda of=/dev/null
This can be done with multiple drives by saving the above command for each drive to a file on separate lines and running
# cat $FILE | parallel
Then run ZPool creation at the same time.
ZFS is using too much RAM
zfs.zfs_arc_max=536870912 # (for 512MB)
For a more detailed description, as well as other configuration options, see gentoo-wiki:zfs#arc.
Does not contain an EFI label
The following error will occur when attempting to create a zfs filesystem,
/dev/disk/by-id/<id> does not contain an EFI label but it may contain partition
The way to overcome this is to use
-f with the zfs create command.
No hostid found
An error that occurs at boot with the following lines appearing before initscript output:
ZFS: No hostid found on kernel command line or /etc/hostid.
This warning occurs because the ZFS module does not have access to the spl hosted. There are two solutions, for this. Either place the spl hostid in the kernel parameters in the boot loader. For example, adding
The other solution is to make sure that there is a hostid in
/etc/hostid, and then regenerate the initramfs image. Which will copy the hostid into the initramfs image.
Pool cannot be found while booting from SAS/SCSI devices
In case you are booting a SAS/SCSI based, you might occassionally get boot problems where the pool you are trying to boot from cannot be found. A likely reason for this is that your devices are initialized too late into the process. That means that zfs cannot find any devices at the time when it tries to assemble your pool.
In this case you should force the scsi driver to wait for devices to come online before continuing. You can do this by putting this into
options scsi_mod scan=sync
Afterwards, regenerate the initramfs.
This works because the zfs hook will copy the file at
/etc/modprobe.d/zfs.conf into the initcpio which will then be used at build time.
On boot the zfs pool does not mount stating: "pool may be in use from other system"
If the new installation does not boot because the zpool cannot be imported, chroot into the installation and properly export the zpool. See #Emergency chroot repair with archzfs.
Once inside the chroot environment, load the ZFS module and force import the zpool,
# zpool import -a -f
now export the pool:
# zpool export <pool>
To see the available pools, use,
# zpool status
It is necessary to export a pool because of the way ZFS uses the hostid to track the system the zpool was created on. The hostid is generated partly based on the network setup. During the installation in the archiso the network configuration could be different generating a different hostid than the one contained in the new installation. Once the zfs filesystem is exported and then re-imported in the new installation, the hostid is reset. See Re: Howto zpool import/export automatically? - msg#00227.
If ZFS complains about "pool may be in use" after every reboot, properly export pool as described above, and then regenerate the initramfs in normally booted system.
Double check that the pool is properly exported. Exporting the zpool clears the hostid marking the ownership. So during the first boot the zpool should mount correctly. If it does not there is some other problem.
Reboot again, if the zfs pool refuses to mount it means the hostid is not yet correctly set in the early boot phase and it confuses zfs. Manually tell zfs the correct number, once the hostid is coherent across the reboots the zpool will mount correctly.
Boot using zfs_force and write down the hostid. This one is just an example.
Users can always ignore the check adding
zfs_force=1 in the kernel parameters, but it is not advisable as a permanent solution.
Devices have different sector alignment
Once a drive has become faulted it should be replaced A.S.A.P. with an identical drive.
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -f
but in this instance, the following error is produced:
cannot replace ata-ST3000DM001-9YN166_S1F0KDGY with ata-ST3000DM001-1CH166_W1F478BD: devices have different sector alignment
ZFS uses the ashift option to adjust for physical block size. When replacing the faulted disk, ZFS is attempting to use
ashift=12, but the faulted disk is using a different ashift (probably
ashift=9) and this causes the resulting error.
Use zdb to find the ashift of the zpool:
zdb , then use the
-o argument to set the ashift of the replacement drive:
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -o ashift=9 -f
Check the zpool status for confirmation:
# zpool status -v
pool: bigdata state: DEGRADED status: One or more devices is currently being resilvered. The pool will continue to function, possibly in a degraded state. action: Wait for the resilver to complete. scan: resilver in progress since Mon Jun 16 11:16:28 2014 10.3G scanned out of 5.90T at 81.7M/s, 20h59m to go 2.57G resilvered, 0.17% done config: NAME STATE READ WRITE CKSUM bigdata DEGRADED 0 0 0 raidz1-0 DEGRADED 0 0 0 replacing-0 OFFLINE 0 0 0 ata-ST3000DM001-9YN166_S1F0KDGY OFFLINE 0 0 0 ata-ST3000DM001-1CH166_W1F478BD ONLINE 0 0 0 (resilvering) ata-ST3000DM001-9YN166_S1F0JKRR ONLINE 0 0 0 ata-ST3000DM001-9YN166_S1F0KBP8 ONLINE 0 0 0 ata-ST3000DM001-9YN166_S1F0JTM1 ONLINE 0 0 0 errors: No known data errors
Pool resilvering stuck/restarting/slow?
According to the ZFSonLinux github it is a known issue since 2012 with ZFS-ZED which causes the resilvering process to constantly restart, sometimes get stuck and be generally slow for some hardware. The simplest mitigation is to stop zfs-zed.service until the resilver completes
Your boot time can be significantly impacted if you update your intitramfs (eg when doing a kernel update) when you have additional but non-permanently attached pools imported because these pools will get added to your initramfs zpool.cache and ZFS will attempt to import these extra pools on every boot, regardless of whether you have exported it and removed it from your regular zpool.cache.
If you notice ZFS trying to import unavailable pools at boot, first run:
$ zdb -C
To check your zpool.cache for pools you do not want imported at boot. If this command is showing (a) additional, currently unavailable pool(s), run:
# zpool set cachefile=/etc/zfs/zpool.cache zroot
To clear the zpool.cache of any pools other than the pool named zroot. Sometimes there is no need to refresh your zpool.cache, but instead all you need to do is regenerate the initramfs.
Tips and tricks
Embed the archzfs packages into an archiso
Follow the Archiso steps for creating a fully functional Arch Linux live CD/DVD/USB image.
Enable the archzfs repository:
... [archzfs] Server = http://archzfs.com/$repo/x86_64 SigLevel = Optional TrustAll
archzfs-linux group to the list of packages to be installed (the
archzfs repository provides packages for the x86_64 architecture only).
Complete Build the ISO to finally build the iso.
ZFS Automatic Snapshot Service for Linux
The AUR provides a shell script to automate the management of snapshots, with each named by date and label (hourly, daily, etc), giving quick and convenient snapshotting of all ZFS datasets. The package also installs cron tasks for quarter-hourly, hourly, daily, weekly, and monthly snapshots. Optionally adjust the
--keep parameter from the defaults depending on how far back the snapshots are to go (the monthly script by default keeps data for up to a year).
To prevent a dataset from being snapshotted at all, set
com.sun:auto-snapshot=false on it. Likewise, set more fine-grained control as well by label, if, for example, no monthlies are to be kept on a snapshot, for example, set
ZFS Snapshot Manager
The AUR provides a python service that takes daily snapshots from a configurable set of ZFS datasets and cleans them out in a "Grandfather-father-son" scheme. It can be configured to e.g. keep 7 daily, 5 weekly, 3 monthly and 2 yearly snapshots.AUR package from
The package also supports configurable replication to other machines running ZFS by means of
zfs send and
zfs receive. If the destination machine runs this package as well, it could be configured to keep these replicated snapshots for a longer time. This allows a setup where a source machine has only a few daily snapshots locally stored, while on a remote storage server a much longer retention is available.
ZFS has support for creating shares by SMB or NFS.
To make a pool available on the network:
# zfs set sharenfs=on <nameofzpool>
To make a dataset available on the network:
# zfs set sharenfs=on <nameofzpool>/<nameofdataset>
To enable read/write access for a specific ip-range(s):
# zfs set sharenfs="firstname.lastname@example.org/24,email@example.com/24" <nameofzpool>/<nameofdataset>
To check if the dataset is exported successful:
# showmount -e `hostname`
Export list for hostname: /path/of/dataset 192.168.1.100/24
To view the current loaded exports state in more detail, use:
# exportfs -v
When sharing smb shares configuring usershares in your smb.conf will allow ZFS to setup and create the shares.
# [global] # usershare path = /var/lib/samba/usershares # usershare max shares = 100 # usershare allow guests = yes # usershare owner only = no
Create and set permissions on the user directory as root
# mkdir /var/lib/samba/usershares # chmod +t /var/lib/samba/usershares
Encryption in ZFS using dm-crypt
The stable release version of ZFS on Linux used to not support encryption directly (now it's available, see #Native encryption), but zpools can be created on dm-crypt block devices. Since the zpool is created on the plain-text abstraction, it is possible to have the data encrypted while having all the advantages of ZFS like deduplication, compression, and data robustness.
dm-crypt, possibly via LUKS, creates devices in
/dev/mapper and their name is fixed. So you just need to change
zpool create commands to point to that names. The idea is configuring the system to create the
/dev/mapper block devices and import the zpools from there. Since zpools can be created in multiple devices (raid, mirroring, striping, ...), it is important all the devices are encrypted otherwise the protection might be partially lost.
For example, an encrypted zpool can be created using plain dm-crypt (without LUKS) with:
# cryptsetup --hash=sha512 --cipher=twofish-xts-plain64 --offset=0 \ --key-file=/dev/sdZ --key-size=512 open --type=plain /dev/sdX enc # zpool create zroot /dev/mapper/enc
In the case of a root filesystem pool, the
mkinitcpio.conf HOOKS line will enable the keyboard for the password, create the devices, and load the pools. It will contain something like:
HOOKS="... keyboard encrypt zfs ..."
/dev/mapper/enc name is fixed no import errors will occur.
Creating encrypted zpools works fine. But if you need encrypted directories, for example to protect your users' homes, ZFS loses some functionality.
ZFS will see the encrypted data, not the plain-text abstraction, so compression and deduplication will not work. The reason is that encrypted data has always high entropy making compression ineffective and even from the same input you get different output (thanks to salting) making deduplication impossible. To reduce the unnecessary overhead it is possible to create a sub-filesystem for each encrypted directory and use eCryptfs on it.
For example to have an encrypted home: (the two passwords, encryption and login, must be the same)
# zfs create -o compression=off -o dedup=off -o mountpoint=/home/<username> <zpool>/<username> # useradd -m <username> # passwd <username> # ecryptfs-migrate-home -u <username> <log in user and complete the procedure with ecryptfs-unwrap-passphrase>
Emergency chroot repair with archzfs
To get into the ZFS filesystem from live system for maintenance, there are two options:
- Build custom archiso with ZFS as described in #Embed the archzfs packages into an archiso.
- Boot the latest official archiso and bring up the network. Then enable archzfs repository inside the live system as usual, sync the pacman package database and install the archzfs-archiso-linux package.
To start the recovery, load the ZFS kernel modules:
# modprobe zfs
Import the pool:
# zpool import -a -R /mnt
Mount the boot partitions (if any):
# mount /dev/sda2 /mnt/boot # mount /dev/sda1 /mnt/boot/efi
Chroot into the ZFS filesystem:
# arch-chroot /mnt /bin/bash
Check the kernel version:
# pacman -Qi linux # uname -r
uname will show the kernel version of the archiso. If they are different, run depmod (in the chroot) with the correct kernel version of the chroot installation:
# depmod -a 3.6.9-1-ARCH (version gathered from pacman -Qi linux but using the matching kernel modules directory name under the chroot's /lib/modules)
This will load the correct kernel modules for the kernel version installed in the chroot installation.
Regenerate the initramfs. There should be no errors.
Here a bind mount from /mnt/zfspool to /srv/nfs4/music is created. The configuration ensures that the zfs pool is ready before the bind mount is created.
/mnt/zfspool /srv/nfs4/music none bind,defaults,nofail,x-systemd.requires=zfs-mount.service 0 0
Monitoring / Mailing on Events
See ZED: The ZFS Event Daemon for more information.
An email forwarder, such as S-nail (installed as part of ), is required to accomplish this. Test it to be sure it is working correctly.
Uncomment the following in the configuration file:
ZED_EMAIL_ADDR="root" ZED_EMAIL_PROG="mailx" ZED_NOTIFY_VERBOSE=0 ZED_EMAIL_OPTS="-s '@SUBJECT@' @ADDRESS@"
Update 'root' in
ZED_EMAIL_ADDR="root" to the email address you want to receive notifications at.
If you are keeping your mailrc in your home directory, you can tell mail to get it from there by setting
This works because ZED sources this file, so
mailx sees this environment variable.
If you want to receive an email no matter the state of your pool, you will want to set
ZED_NOTIFY_VERBOSE=1. You will need to do this temporary to test.
ZED_NOTIFY_VERBOSE=1, you can test by running a scrub as root:
zpool scrub <pool-name>.
Wrap shell commands in pre & post snapshots
Since it is so cheap to make a snapshot, we can use this as a measure of security for sensitive commands such as system and package upgrades. If we make a snapshot before, and one after, we can later diff these snapshots to find out what changed on the filesystem after the command executed. Furthermore we can also rollback in case the outcome was not desired.
# zfs snapshot -r zroot@pre # pacman -Syu # zfs snapshot -r zroot@post # zfs diff zroot@pre zroot@post # zfs rollback zroot@pre
A utility that automates the creation of pre and post snapshots around a shell command is znp.
# znp pacman -Syu # znp find / -name "something*" -delete
and you would get snapshots created before and after the supplied command, and also output of the commands logged to file for future reference so we know what command created the diff seen in a pair of pre/post snapshots.
Remote unlocking of ZFS encrypted root
As of PR #261,
archzfs supports SSH unlocking of natively-encrypted ZFS datasets. This section describes how to use this feature, and is largely based on dm-crypt/Specialties#Remote unlocking (hooks: netconf, dropbear, tinyssh, ppp).
- Install to provide hooks for setting up early user space networking.
- Choose an SSH server to use in early user space. The options are
or , and are mutually exclusive.
- If using , it is also recommended to install or AUR. This tool converts an existing OpenSSH hostkey to the TinySSH key format, preserving the key fingerprint and avoiding connection warnings. The TinySSH and Dropbear mkinitcpio install scripts will automatically convert existing hostkeys when generating a new initcpio image.
- Decide whether to use an existing OpenSSH key or generate a new one (recommended) for the host that will be connecting to and unlocking the encrypted ZFS machine. Copy the public key into
/etc/dropbear/root_key. When generating the initcpio image, this file will be added to
authorized_keysfor the root user and is only valid in the initrd environment.
- Add the
ip=kernel parameter to your boot loader configuration. The
ipstring is highly configurable. A simple DHCP example is shown below.
/etc/mkinitcpio.confto include the
zfsencryptsshhooks before the
HOOKS=(... netconf <tinyssh>|<dropbear> zfsencryptssh zfs ...)
- Regenerate the initramfs.
- Reboot and try it out!
Changing the SSH server port
22. You may wish to change this.
For TinySSH, copy
/etc/initcpio/hooks/tinyssh, and find/modify the following line in the
/usr/bin/tcpserver -HRDl0 0.0.0.0 <new_port> /usr/sbin/tinysshd -v /etc/tinyssh/sshkeydir &
For Dropbear, copy
/etc/initcpio/hooks/dropbear, and find/modify the following line in the
/usr/sbin/dropbear -E -s -j -k -p <new_port>
First, we need to use
puttygen.exe to import and convert the OpenSSH key generated earlier into PuTTY's .ppk private key format. Let us call it
zfs_unlock.ppk for this example.
The mkinitcpio-netconf process above does not setup a shell (nor do we need need one). However, because there is no shell, PuTTY will immediately close after a successful connection. This can be disabled in the PuTTY SSH configuration (Connection -> SSH -> [X] Do not start a shell or command at all), but it still does not allow us to see stdout or enter the encryption passphrase. Instead, we use
plink.exe with the following parameters:
plink.exe -ssh -l root -i c:\path\to\zfs_unlock.ppk <hostname>
The plink command can be put into a batch script for ease of use.
- Aaron Toponce's 17-part blog on ZFS
- ZFS on Linux
- ZFS on Linux FAQ
- FreeBSD Handbook -- The Z File System
- Oracle Solaris ZFS Administration Guide
- Solaris Internals -- ZFS Troubleshooting Guide[dead link 2017-05-30]
- How Pingdom uses ZFS to back up 5TB of MySQL data every day
- Tutorial on adding the modules to a custom kernel
- How to create cross platform ZFS disks under Linux
- How-To: Using ZFS Encryption at Rest in OpenZFS (ZFS on Linux, ZFS on FreeBSD, …)