== Encrypted Dataset Format Change ==

The introduction of native encryption on ZFS was highly anticipated. However since it was introduced, there have been various issues discovered. Due to this, a rather large patch containing many fixes was merged into master, see https://github.com/zfsonlinux/zfs/pull/6864 for more information.

However this leads to a format change of the encrypted datasets. As a result of this format change, encrypted datasets that were created by older zfs versions can only be mounted as read-only. Encrypted datasets created with the new format cannot be opened at all on older versions. Unencrypted datasets were not altered and work as before.

If you've followed this wiki entry and didn't create an encrypted top-level dataset but a child-dataset, e.g. <code>zroot/root/nixos</code> where <code>zroot</code> is the name of the pool and the top-level dataset and <code>root</code> is the encrypted child-dataset, then you can easily use zfs send/recv to migrate it to the new format.

# Create a custom NixOS iso with crypto stability patch applied
# Boot into that live environment
# Import the pool and load the key
# Create a new encrypted dataset, e.g.<br/><code>zfs create -o encryption=aes-256-gcm -o keyformat=passphrase -o mountpoint=none zroot/rootNEW</code>
# Use zfs send and receive to copy the data to new format:<br/><code>zfs send zpool/root/nixos | zfs receive zpool/rootNew/nixos</code>
# Set correct mountpoint for the newly created dataset:<br/><code>zfs set moutpoint=legacy zpool/root/New/nixos</code>
# Rename the old and new datasets:<br/><code>zfs rename zpool/root zpool/rootOLD</code><br/><code>zfs rename zpool/rootNEW zpool/root</code>
# That should allow to boot Nixos already with new format. If you have other encrypted mounts, you will probably need to convert them to new format as well first.

It's also recommended to have two usb sticks available. One custom iso with the old zfs format and one with the new one. So you can easily switch between them.

If you don't have enough free space to move a dataset completely, you can just use both usb sticks to boot either version and transfer files partially by rsync like this:

# Boot usb with stability patches applied
# Import the pool and load the key
# Create a new encrypted dataset, e.g.<br/><code>zfs create -o encryption=aes-256-gcm -o keyformat=passphrase -o mountpoint=legacy zroot/mediaNEW</code>
# Mount the format one and the new format one, e.g. <br/><code>mkdir -p /mtn/media{OLD,NEW}</code><br/><code>mount -o ro -t zfs zroot/media /mnt/mediaOLD</code><br/><code>mount -t zfs zroot/mediaNEW /mnt/mediaNEW</code>
# Once mounted, you can use rsync to transfer (part) of the data:<br/><code>rsync -avp /mnt/mediaOLD/Music /mnt/mediaNew/</code><br/>Notice: In the source folder there's no trailing "/" so that in the destination location provided that whole folder will be created. Of course you can also just start with a sub folder if one is too big.
# Rsync (or copy) over as much data as you can. Since the old format dataset can only be mounted as read-only, you'll have to boot into the other usb stick with the old format, mount the old media folder and delete files in there. You may also need to delete snapshots first.
# Afterwards boot again into the new format usb stick and repeat.

Of course if there's no sensitive data that needs encryption, you can just boot up into the old format, create a new, non-encrypted dataset and start moving files over. Once done, boot into new format, create an encrypted pool and move files over again.