Table of Content

• useful links
• Pool handling
• Dataset handling
• Encrypted Datasets
  • Auto unlock of encrypted datasets
• Snapshots
• Send and Receive
  • Send and Receive with mbuffer
• Troubleshooting and Fixes

useful links

https://wiki.archlinux.org/index.php/ZFS

Pool handling

Dataset handling

Encrypted Datasets

Auto unlock of encrypted datasets

If you want to get your encrypted datasets auto unlocked while booting you could create a systemd service which performs the action for you.

You just need ot make sure that the passphrase is somehow accessable in this state.

Lets assume that you have created your dataset with keyformat=raw and lets assume you have only one zpool.

First create a generic systemd serivce file which you can use for this, something like this (if you don’t get it by installing zfs already):

$ cat /etc/systemd/system/zfs-load-key@.service
[Unit]
Description=Load ZFS keys
DefaultDependencies=no
Before=zfs-mount.service
After=zfs-import.target
Requires=zfs-import.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/sbin/zfs load-key <zpool_name>/%I

[Install]
WantedBy=zfs-mount.service

Next could be that you just create a soft link like:

$ ln -s zfs-load-key@.service zfs-load-key@<zfs_dataset_name>.service

This will require to reload systemd and of course enable the service so that it runs while your system is booting.

$ systemctl daemon-reload
$ systemctl enable zfs-load-key@<zfs_dataset_name>.service

But what happens if you have more then one zpool and you want to auto unlock them.

systemd can deal make use of parameters only via the attribute EnvironmentFile.

This means that you would need to prepare for each zfs dataset such an config file.

cat /etc/zfs/service_config/<zpool_name>_<zfs_dataset_name>
zpool_name=<zpool_name>
zfs_dataset_name=<zfs_dataset_name>

Sample:

$ cat /etc/zfs/service_config/data_pool-picture_dataset
zpool_name=data_pool
zfs_dataset_name=picture_dataset

This brings us the benefit, that we can use %I in the service name as the file name:

$ cat /etc/systemd/system/zfs-load-key@data_pool-picture_dataset.service
[Unit]
Description=Load ZFS keys
DefaultDependencies=no
Before=zfs-mount.service
After=zfs-import.target
Requires=zfs-import.target

[Service]
Type=oneshot
EnvironmentFile=/etc/zfs/service_config/%I
RemainAfterExit=yes
ExecStart=/usr/sbin/zfs load-key $zpool_name/$zfs_dataset_name

[Install]
WantedBy=zfs-mount.service

And from now on it is very easy to auto unlock multible zfs datasets located in multible zpools.

Side note, of course you could also use service config file to specify different comands to execute, e.g. if you require a yubikey or need to get the pwd from your pass/gpg.

$ cat /etc/zfs/service_config/data_pool-picture_dataset
zpool_name=data_pool
zfs_dataset_name=picture_dataset
decrypt_cmd="gpg --batch --decrypt --pinentry-mode loopback /root/.zfs/${zpool_name}/${zfs_dataset_name}.gpg | /usr/sbin/zfs load-key ${zpool_name}/${zfs_dataset_name}"

$ cat /etc/systemd/system/zfs-load-key@data_pool-picture_dataset.service
[Unit]
Description=Load ZFS keys
DefaultDependencies=no
Before=zfs-mount.service
After=zfs-import.target
Requires=zfs-import.target

[Service]
Type=oneshot
EnvironmentFile=/etc/zfs/service_config/%I
RemainAfterExit=yes
ExecStart=$decrypt_cmd

[Install]
WantedBy=zfs-mount.service

Btw this is not the best sample ;) but it shows what the idea behind it is

Snapshots

Send and Receive

Send and Receive with mbuffer

ssh is the more secure but a bit slower approach since it does not buffer and needs to encrypt data. In case of a trustworthy network path mbuffer can be used.
Open up a port restricted to the source IP on the destination node
mbuffer -I ${sourceIP}:${destPort} | zfs receive ${pool}/${ds}
Start transfer on source node
zfs send ${pool}/${ds}@${snapshot} | mbuffer -O ${destIP}:${destPort}
If ram allowes it, you can increase the mbuffer cache by using for example -m 4G.

Troubleshooting and Fixes

used /dev/sd instead of /dev/disk/by-id on creation

# no data loss, first export the pool
$ sudo zpool export [pool name]
# import the pool again using the right IDs
$ sudo zpool import -d /dev/disk/by-id [pool name]

replace disk of raidz1/2/3

# get status of pool
$ zpool status ${pool}
# find out which disk is the new disk in case you did not note down the serial
$ lsblk
$ ls -la /dev/disk/by-id/
# replace disk
$ zpool replace ${pool} ${old_disk_id} ${new_disk_id}