I'm not making any argument for or against encryption in this post. Discussion of the merits of encryption in general or FreeNAS's specific use/implementation is beyond the scope of this guide.
To by knowledge the commands below are good on all versions of 11.2 and possibly even 11.3. I have not tested them on older versions and have only limited testing on 11.3. Despite this, the commands blow are non-destructive and reversible.
Encryption problems typically fall into 3 categories: incorrect key/passphrase, unable to locate disks, or a bug in the FreeNAS middleware. These issues can be experienced in a variety of situations though typically are seen when importing a pool and after reinstalling the OS to the boot drive.
Note
Throughout this resource I will refer to commands sometimes with portions that you need to fill in in brackets. Replace the entire text in brackets (including the brackets) with the values specific to your system. For example
Identifying Disks
Though not the most common issue, it is a good place to start because if your system cannot find the disks to unlock it does not matter whether you have the correct keys or not. The command above lists every provider your system expects to find in
Identifying the Correct Key(s)
Note: The above command only works with already-imported pools. For issues during pool import look to the manual geli command below.
This command tells you where FreeNAS looks to find the key for a given pool. From that command you'll then look in
Do note that you could copy either key however it is ill advised to copy the recovery key. The recovery key is treated differently by FreeNAS and FreeNAS expects the key found in
If, after copying the key to the location above your system still does not properly unlock your pool, or if you are having issues with importing a drive, you can verify your keys manually as follows.
The above code is the geli command used to unlock a disk. This is the command used by FreeNAS to unlock a disk prior to importing the pool. Note that the
Note about the recovery key
The recovery key, as configured in FreeNAS, never uses a passphrase, even a pool with a passphrase set does not use a passphrase for the recovery key. This means that when using the geli command above you MUST provide the
Note about manually importing your pool
I do not recommend that you manually import your pool and leave it that way. Manually importing your pool is a great way to get access to data for backup/recovery purposes etc but if used long-term can cause unexpected behavior. FreeNAS manages pools in large part by reference to its database. Manual management of your pool circumvents this database and can have unexpected behavior.
In Closing
I consider this a rough draft and a work in progress. If you have suggestions of things to add or questions just let me know and I'll update this document accordingly.
To by knowledge the commands below are good on all versions of 11.2 and possibly even 11.3. I have not tested them on older versions and have only limited testing on 11.3. Despite this, the commands blow are non-destructive and reversible.
Encryption problems typically fall into 3 categories: incorrect key/passphrase, unable to locate disks, or a bug in the FreeNAS middleware. These issues can be experienced in a variety of situations though typically are seen when importing a pool and after reinstalling the OS to the boot drive.
Note
Throughout this resource I will refer to commands sometimes with portions that you need to fill in in brackets. Replace the entire text in brackets (including the brackets) with the values specific to your system. For example
zpool status {pool_name} would become zpool status tank if your system had a pool named "tank".Identifying Disks
Code:
freenas# sqlite3 /data/freenas-v1.db 'select sed.encrypted_provider from storage_encrypteddisk as sed join storage_volume sv on sv.id = sed.encrypted_volume_id where sv.vol_name = "{pool_name}";'
Though not the most common issue, it is a good place to start because if your system cannot find the disks to unlock it does not matter whether you have the correct keys or not. The command above lists every provider your system expects to find in
/dev/gptid to unlock the pool. If you do not see the providers in that directory you're going to want to double-check your cabling, etc. It may able be worth ensuring your disks did not get formatted accidentally. Using gpart show can give you some insight into your disk partitions. For encrypted disks you expect to see something like the following.Code:
=> 40 5860533088 da7 GPT (2.7T)
40 88 - free - (44K)
128 4194304 1 freebsd-swap (2.0G)
4194432 5856338696 2 freebsd-zfs (2.7T)
Identifying the Correct Key(s)
Code:
dorothy# sqlite3 /data/freenas-v1.db 'select vol_encryptkey from storage_volume where vol_name = "{pool}";'
Note: The above command only works with already-imported pools. For issues during pool import look to the manual geli command below.
This command tells you where FreeNAS looks to find the key for a given pool. From that command you'll then look in
/data/geli for a key with a matching name. The most common reason for this file to be missing is that folks reinstall FreeNAS on their boot media and then upload their configs and expect everything to be as it was. However, the User Guide clearly states the importance of downloading and backing up your keys. When you reinstall your OS you must restore your keys manually; this can be done easily by copying your backed up key to the correct location and with the correct file name above.Do note that you could copy either key however it is ill advised to copy the recovery key. The recovery key is treated differently by FreeNAS and FreeNAS expects the key found in
/data/geli to be the primary key and not the recovery key. If the only key you have is the recovery key once you successfully unlock and import your pool I recommend you rekey your pool and recreate/download the recovery key. This will give you a backup of the two new keys and your FreeNAS system will be configured as it expects.If, after copying the key to the location above your system still does not properly unlock your pool, or if you are having issues with importing a drive, you can verify your keys manually as follows.
Code:
freenas# geli attach -k /data/geli/{key}.key [-p] /dev/gptid/{uuid}
The above code is the geli command used to unlock a disk. This is the command used by FreeNAS to unlock a disk prior to importing the pool. Note that the
-p flag is optional and should be used when you're using a key that does not make use of a passphrase. Attempt this command on every disk which should be a part of the pool. If every disk can be unlocked you know you have the correct key. Be sure you have no file name errors from above. You can also check the integrity of your pool at this point with zpool import.Note about the recovery key
The recovery key, as configured in FreeNAS, never uses a passphrase, even a pool with a passphrase set does not use a passphrase for the recovery key. This means that when using the geli command above you MUST provide the
-p flag when using the recovery key. Additionally, when importing a pool or unlocking a pool via the GUI if you are using the recovery key you MUST leave the passphrase field empty.Note about manually importing your pool
I do not recommend that you manually import your pool and leave it that way. Manually importing your pool is a great way to get access to data for backup/recovery purposes etc but if used long-term can cause unexpected behavior. FreeNAS manages pools in large part by reference to its database. Manual management of your pool circumvents this database and can have unexpected behavior.
In Closing
I consider this a rough draft and a work in progress. If you have suggestions of things to add or questions just let me know and I'll update this document accordingly.
