zfs: add encryption docs

[pve-docs.git] / local-zfs.adoc

diff --git a/local-zfs.adoc b/local-zfs.adoc
index 6aae81e4a275c729a86514fd2b2d1b5321dcb59b..e3c65de7c51faa3751ef6f300db5b92376560896 100644 (file)
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -1,6 +1,6 @@
+[[chapter_zfs]]

 ZFS on Linux
 ------------
 ZFS on Linux
 ------------

-include::attributes.txt[]

 ifdef::wiki[]
 :pve-toplevel:
 endif::wiki[]
 ifdef::wiki[]
 :pve-toplevel:
 endif::wiki[]


@@ -60,7 +60,7 @@ ZFS depends heavily on memory, so you need at least 8GB to start. In
 practice, use as much you can get for your hardware/budget. To prevent
 data corruption, we recommend the use of high quality ECC RAM.
 
 practice, use as much you can get for your hardware/budget. To prevent
 data corruption, we recommend the use of high quality ECC RAM.
 

-If you use a dedicated cache and/or log disk, you should use a
+If you use a dedicated cache and/or log disk, you should use an

 enterprise class SSD (e.g. Intel SSD DC S3700 Series). This can
 increase the overall performance significantly.
 
 enterprise class SSD (e.g. Intel SSD DC S3700 Series). This can
 increase the overall performance significantly.
 


@@ -154,15 +154,9 @@ rpool/swap        4.25G  7.69T    64K  -
 Bootloader
 ~~~~~~~~~~
 
 Bootloader
 ~~~~~~~~~~
 

-The default ZFS disk partitioning scheme does not use the first 2048
-sectors. This gives enough room to install a GRUB boot partition. The
-{pve} installer automatically allocates that space, and installs the
-GRUB boot loader there. If you use a redundant RAID setup, it installs
-the boot loader on all disk required for booting. So you can boot
-even if some disks fail.
-
-NOTE: It is not possible to use ZFS as root file system with UEFI
-boot.
+Depending on whether the system is booted in EFI or legacy BIOS mode the
+{pve} installer sets up either `grub` or `systemd-boot` as main bootloader.
+See the chapter on xref:sysboot[{pve} host bootladers] for details.

 
 
 ZFS Administration
 
 
 ZFS Administration


@@ -255,7 +249,19 @@ can be used as cache.
 
 .Changing a failed device
 
 
 .Changing a failed device
 

- zpool replace -f <pool> <old device> <new-device>
+ zpool replace -f <pool> <old device> <new device>
+
+.Changing a failed bootable device when using systemd-boot
+
+ sgdisk <healthy bootable device> -R <new device>
+ sgdisk -G <new device>
+ zpool replace -f <pool> <old zfs partition> <new zfs partition>
+ pve-efiboot-tool format <new disk's ESP>
+ pve-efiboot-tool init <new disk's ESP>
+
+NOTE: `ESP` stands for EFI System Partition, which is setup as partition #2 on
+bootable disks setup by the {pve} installer since version 5.4. For details, see
+xref:sysboot_systemd_boot_setup[Setting up a new partition for use as synced ESP].

 
 
 Activate E-Mail Notification
 
 
 Activate E-Mail Notification


@@ -263,7 +269,12 @@ Activate E-Mail Notification
 
 ZFS comes with an event daemon, which monitors events generated by the
 ZFS kernel module. The daemon can also send emails on ZFS events like
 
 ZFS comes with an event daemon, which monitors events generated by the
 ZFS kernel module. The daemon can also send emails on ZFS events like

-pool errors.
+pool errors. Newer ZFS packages ships the daemon in a separate package,
+and you can install it using `apt-get`:
+
+----
+# apt-get install zfs-zed
+----

 
 To activate the daemon it is necessary to edit `/etc/zfs/zed.d/zed.rc` with your
 favourite editor, and uncomment the `ZED_EMAIL_ADDR` setting:
 
 To activate the daemon it is necessary to edit `/etc/zfs/zed.d/zed.rc` with your
 favourite editor, and uncomment the `ZED_EMAIL_ADDR` setting:


@@ -302,14 +313,18 @@ time this value changes:
 ====
 
 
 ====
 
 

+[[zfs_swap]]

 .SWAP on ZFS
 
 .SWAP on ZFS
 

-SWAP on ZFS on Linux may generate some troubles, like blocking the
+Swap-space created on a zvol may generate some troubles, like blocking the

 server or generating a high IO load, often seen when starting a Backup
 to an external Storage.
 
 We strongly recommend to use enough memory, so that you normally do not
 server or generating a high IO load, often seen when starting a Backup
 to an external Storage.
 
 We strongly recommend to use enough memory, so that you normally do not

-run into low memory situations. Additionally, you can lower the
+run into low memory situations. Should you need or want to add swap, it is
+preferred to create a partition on a physical disk and use it as swapdevice.
+You can leave some space free for this purpose in the advanced options of the
+installer. Additionally, you can lower the

 ``swappiness'' value. A good value for servers is 10:
 
  sysctl -w vm.swappiness=10
 ``swappiness'' value. A good value for servers is 10:
 
  sysctl -w vm.swappiness=10


@@ -334,3 +349,83 @@ improve performance when sufficient memory exists in a system.
 | vm.swappiness = 60  | The default value.
 | vm.swappiness = 100 | The kernel will swap aggressively.
 |===========================================================
 | vm.swappiness = 60  | The default value.
 | vm.swappiness = 100 | The kernel will swap aggressively.
 |===========================================================

+
+[[zfs_encryption]]
+.Encrypted ZFS Datasets
+
+ZFS on Linux version 0.8.0 introduced support for native encryption of
+datasets. After an upgrade from previous ZFS on Linux versions, the encryption
+feature needs to be enabled per pool:
+
+----
+# zpool get feature@encryption tank
+NAME  PROPERTY            VALUE            SOURCE
+tank  feature@encryption  disabled         local
+
+# zpool set feature@encryption=enabled
+
+# zpool get feature@encryption tank
+NAME  PROPERTY            VALUE            SOURCE
+tank  feature@encryption  enabled         local
+----
+
+WARNING: There is currently no support for booting from pools with encrypted
+datasets using Grub, and only limited support for automatically unlocking
+encrypted datasets on boot. Older versions of ZFS without encryption support
+will not be able to decrypt stored data.
+
+NOTE: It is recommended to either unlock storage datasets manually after
+booting, or to write a custom unit to pass the key material needed for
+unlocking on boot to `zfs load-key`.
+
+WARNING: Establish and test a backup procedure before enabling encryption of
+production data.If the associated key material/passphrase/keyfile has been
+lost, accessing the encrypted data is no longer possible.
+
+Encryption needs to be setup when creating datasets/zvols, and is inherited by
+default to child datasets. For example, to create an encrypted dataset
+`tank/encrypted_data` and configure it as storage in {pve}, run the following
+commands:
+
+----
+# zfs create -o encryption=on -o keyformat=passphrase tank/encrypted_data
+Enter passphrase:
+Re-enter passphrase:
+
+# pvesm add zfspool encrypted_zfs -pool tank/encrypted_data
+----
+
+All guest volumes/disks create on this storage will be encrypted with the
+shared key material of the parent dataset.
+
+To actually use the storage, the associated key material needs to be loaded
+with `zfs load-key`:
+
+----
+# zfs load-key tank/encrypted_data
+Enter passphrase for 'tank/encrypted_data':
+----
+
+It is also possible to use a (random) keyfile instead of prompting for a
+passphrase by setting the `keylocation` and `keyformat` properties, either at
+creation time or with `zfs change-key`:
+
+----
+# dd if=/dev/urandom of=/path/to/keyfile bs=32 count=1
+
+# zfs change-key -o keyformat=raw -o keylocation=file:///path/to/keyfile tank/encrypted_data
+----
+
+WARNING: When using a keyfile, special care needs to be taken to secure the
+keyfile against unauthorized access or accidental loss. Without the keyfile, it
+is not possible to access the plaintext data!
+
+A guest volume created underneath an encrypted dataset will have its
+`encryptionroot` property set accordingly. The key material only needs to be
+loaded once per encryptionroot to be available to all encrypted datasets
+underneath it.
+
+See the `encryptionroot`, `encryption`, `keylocation`, `keyformat` and
+`keystatus` properties, the `zfs load-key`, `zfs unload-key` and `zfs
+change-key` commands and the `Encryption` section from `man zfs` for more
+details and advanced usage.