pveceph: fix spelling in section Trim/Discard

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

diff --git a/local-zfs.adoc b/local-zfs.adoc
index 2a5086e26c93c7b1914184c190d56fe702ff5ab2..b4fb7dbf1e8ffdb1a83ca595107130c001ba0e5a 100644 (file)
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -236,7 +236,7 @@ As `<device>` it is possible to use more devices, like it's shown in
 
 .Add cache and log to an existing pool
 
 
 .Add cache and log to an existing pool
 

-If you have an pool without cache and log. First partition the SSD in
+If you have a pool without cache and log. First partition the SSD in

 2 partition with `parted` or `gdisk`
 
 IMPORTANT: Always use GPT partition tables.
 2 partition with `parted` or `gdisk`
 
 IMPORTANT: Always use GPT partition tables.


@@ -269,7 +269,7 @@ 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. Newer ZFS packages ships the daemon in a separate package,
+pool errors. Newer ZFS packages ship the daemon in a separate package,

 and you can install it using `apt-get`:
 
 ----
 and you can install it using `apt-get`:
 
 ----


@@ -314,7 +314,8 @@ time this value changes:
 
 
 [[zfs_swap]]
 
 
 [[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
 
 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.
 |===========================================================
 | 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.