~>insrt_

Projects
Posts
Homelab
« Read other posts

ZFS Quickstart Reference Guide for Linux

5 min read ·

This is intended as a quick start-to-finish reference on setting up ZFS while also explaining exactly what everything does.

1. Install ZFS

Begin by configuring ZFS on your system, this depends on the distribution:

  • Arch Linux: See Arch Wiki, you may need to switch kernel or otherwise use DKMS.
  • Ubuntu: From the official guide: sudo apt install zfsutils-linux.

For other distros, refer to the OpenZFS documentation.

2. Create Pool

There are two main types of pools you can create:

  • Striped Pool without Parity ("RAID0"): data is striped across all disks.
    If one disk dies, then you will lose all of your data.
  • Striped Pool with Parity ("RAID5" or “RAID6”): like RAID0 except some disks are used for parity.
  • Mirrored Pool ("RAID1"): data is copied to all disks.

To create the pool you need to construct a command which looks like this:

zpool create -f -o <option> -m <mount> <pool> [raidz(2|3)|mirror] <disk-ids>
SwitchDescriptionValues
-fForce create the pool.
This avoids a a common error on creation.		 
-o <option>Specify additional options for this pool.It is recommended that you specify ashift=(12|13) (disk sector size), it is typically recommended to specify 12 for hard drives and 13 for solid state drives. This entirely depends on your use-case, you may be sacrificing some amount of space depending on your configuration by using a custom value over the default, but you will get better write performance.
-O <filesystem_option>Specify additional options for the file system.

It is recommended that you specify some or all of the following options:

  • dedup=on: enable deduplication to remove redundant data, this is only required if you store a lot of the same data.
  • compression=lz4: enable lz4 compression, this typically has almost no impact on your pool performance.
  • atime=off: disable access time for files, if you do not need this information, add this option to improve performance.
-m <mount>Optionally specify a mount point, by default ZFS will mount to /<pool>. 
<pool>The name of your ZFS pool. 
[raidz(2|3)|mirror]Optionally specify the type of pool to create.
  • default: if you omit this option, ZFS will create a striped pool without any parity.
  • raidz: single disk of parity (requires at least 2 disks)
  • raidz2: two disks of parity (requires at least 3 disks)
  • raidz3: three disks of parity (requires at least 4 disks)
  • mirror: copy data to all disks
<disk-ids>IDs of your disks that you will be using for your pool.Use ls /dev/disk/by-id to find relevant paths.

 

You can read more about performance tuning on the OpenZFS wiki.

For example, if I want to create a ZFS pool on my single disk I run:

zpool create -f -o ashift=12 -O compression=lz4 -O atime=off tank /dev/disk/by-id/ata-ST4000VN008-2DR166_ZDHBJ3DG

Re-configuring File System Options

If at any point you want to change filesystem properties, you can use the following command:

zfs set <option> <pool>

# For example, enable deduplication after the fact:
zfs set dedup=on tank

3. Create Data Set (optional but recommended)

Within your ZFS pool, you can create data sets which are like folders or partitions with different properties.

You can create a new data set by constructing a command like so:

zfs create -o <option> <pool>/<path>
SwitchDescriptionValues
compression=<method>Enable compression.Read more about available different compression options here.
quota=<size>Maximum storage quota.For example, 1tb.
recordsize=<size>Configure a recordsize / basic unit of data for files.
  • The default is recordsize=128K, which is great for general purpose use.
  • Set recordsize=1M if you are dealing with sequential workloads, such as game libraries or movies and media.
  • Set recordsize=16K if you are downloading data using a torrent client, read more here.
    Though, I would recommend just downloading outside the pool, such as your boot SSD (if you have one) and then copying the data over to the pool when it's complete. This should be supported by most clients.
mountpoint=/<path>Configure a custom mount point for this data set. 

 

Encryption

Encryption is super simple to setup, simply create a new data set with the following flags:

zfs create -o encryption=on -o keyformat=passphrase <pool>/<path>

If you would like to use a key, refer to the Arch Wiki's section on ZFS encryption.

On creation, ZFS will mount this new data set, but on restart you will need to re-mount it manually:

# Load the key required for this data set.
zfs load-key <pool>/<path>

# Hence, mount the data set.
zfs mount <pool>/<path>

If you want to unmount and unload the passphrase, run the following:

# Unmount the data set.
zfs unmount <pool>/<path>

# Unload the key, running this on its own is sufficient to unmount.
zfs unload-key <pool>/<path>

Example Data Sets

Here are some example data sets as-per the instructions above:

# Create a general purpose data set
zfs create -o compression=gzip-4 tank/data

# Create a set to store movies and media
zfs create -o recordsize=1M tank/media

# Create a set for torrent downloads
zfs create -o recordsize=16K -o quota=1tb -o mountpoint=/home/paul/downloads tank/downloads

# Create an encrypted data set
zfs create -o encryption=on -o keyformat=passphrase -o compression=gzip-9 tank/documents

4. ZFS Upkeep

To list and look at your pool status, use:

# List all pools
zpool list

# Display status
zpool status

Or list all data sets:

zfs list

You should occasionally scrub your zpool to validate checksums:

zpool scrub <pool>

5. Migrating and Destroying

When it comes time to destroy a data set or pool, you can run the following:

# Destroy a data set
zfs destroy <pool>/<path>

# Destroy a pool
zpool destroy <pool>

If you want to move a ZFS pool between systems:

# Export the pool from current system
zfs export <pool>

# List pools for import on new system
zfs import
zfs import <pool>

References