X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=local-zfs.adoc;h=af330e157b67d15c1d13a5e5d3e7ecffffc18fc9;hb=0aebb0d9fc9c47015423f5c6b3dff98c110c3596;hp=2a5086e26c93c7b1914184c190d56fe702ff5ab2;hpb=0daaddbdc0bce7af1dddeea637d0ea69c73aa088;p=pve-docs.git

diff --git a/local-zfs.adoc b/local-zfs.adoc
index 2a5086e..af330e1 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -314,7 +314,8 @@ time this value changes:
 
 
 [[zfs_swap]]
-.SWAP on ZFS
+SWAP on ZFS
+~~~~~~~~~~~
 
 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
@@ -349,3 +350,84 @@ improve performance when sufficient memory exists in a system.
 | 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 can 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` on existing datasets:
+
+----
+# 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.