My commonly used zfs commands. I find the Arch Wiki ZFS article to be a great resource, and is more complete and meaningful reference than my commonly used commands listed here.

Export a pool from a machine

This should be done before unplugging drives and plugging them into a new machine.

zpool export mypool

List pools

zpool list

List pools with datasets

zfs list

Change encrypted dataset key location

zfs set keylocation=file:///keys/my.key mypool/mydataset

View/get encrypted dataset key location

zfs get keylocation mypool/mydataset

Load the key for a dataset

zfs load-key -r mypool/mydataset

Mount a dataset

zfs mount mypool/mydataset

Change the mountpoint of a pool

zfs set mountpoint=/mnt/mymount mypool

Change the mountpoint of a dataset

zfs set mountpoint=/mnt/mymount mypool/mydataset

Create an encrypted pool (no dataset)

sudo zpool create \
  -o feature@encryption=enabled \
  -O encryption=on \
  -O keylocation=file:///keys/my.key \
  -O keyformat=raw \
  -O mountpoint=/mnt/mymount \
  mypool /dev/my/device/123

Rename a pool

zpool export mypool
zpool import mypool mypool-with-new-name

Rename a dataset

zfs rename mypool/mydataset-old-name mypool/mydataset-new-name

Rename/change the udev symlink of a pool

If disks were added with references like /dev/sdX the entire pool can be exported and re-imported with the -d search path to use predictable dev node names.

zpool export mypool
zpool import -d /dev/disk/by-id mypool

Create a zpool dataset with encryption

zfs create \
  -o encryption=on \
  -o keyformat=raw \
  -o keylocation=file:///keys/my.key \
  -o mountpoint=/mnt/mymount \
  mypool/mydataset

Destroy a zpool

zpool destroy mypool

Create a pool with a single disk

zpool create mypool /dev/my/device/abc

Create a simple spanned/JBOD pool

This will not create a mirror. This will create a single pool with the capacity of both disks. The disks do not have to be the same size.

zpool create mypool /dev/my/device/123 /dev/my/device/456

Add capacity to an existing pool

This is not adding a mirror. This adds a disk, and so additional capacity, to an existing pool.

zpool add mypool /dev/my/device/789

Upgrade or exchange the only drive in a single-disk pool

zpool attach mypool /dev/my/device/already/in/the/pool /dev/my/new/device

Then, wait for the device to finish resilvering data to the new disk. Once done, the old pre-existing disk can be removed like so.

zpool detach mypool /dev/my/device/already/in/the/pool

Tell the pool to use all available size if the new disk is larger than the old disk.

zpool online -e mypool /dev/my/new/device

Replace a disk in a pool

zpool replace mypool /dev/my/device/already/in/the/pool /dev/my/new/device

Add mirror set vdev to an existing pool

Add a pair of disks, as a mirro, to a pool.

Assume mypool already had ~4GB of space. Assume each of these disks is only ~1GB large. By adding this mirrored set of disks to mypool the capacity of mypool will only increase by ~1GB. These disks exist in a mirror for fault tolerance and redundancy.

zpool add mypool mirror /dev/my/device/123 /dev/my/device/456

The disks do not have to be the same size, but (because it is a mirror set) the size of mypool would only increase by the size of the smallest disk if they were of different sizes.

Attach a new disk to an existing non-mirrored disk to make it into a mirror

zpool attach mypool /dev/my/device/already/in/the/pool /dev/my/new/device

This can be repeated with more disks to add additional disks into a mirrored set. A mirror is not restricted to only two disks.

Remove a disk from a mirror

This can be done until all redundant disks are removed from a mirror.

zpool remove mypool /dev/my/device

Detach a disk from a mirror

This can be done until all redundant disks are removed from a mirror.

zpool detach mypool /dev/my/device

Remove a single disk from a pool

zpool remove mypool /dev/my/device