Add section 'Compression in ZFS'

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

diff --git a/local-zfs.adoc b/local-zfs.adoc
index f4db54b046a11f1a6c7255153f1ea3d4fd5f76ef..7043a245f97b21ec197781a52ff53702ea0b6cd6 100644 (file)
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -180,7 +180,7 @@ underlying disk.
 
  zpool create -f -o ashift=12 <pool> <device>
 
-To activate compression
+To activate compression (see section <<zfs_compression,Compression in ZFS>>):
 
  zfs set compression=lz4 <pool>
 
@@ -433,6 +433,35 @@ change-key` commands and the `Encryption` section from `man zfs` for more
 details and advanced usage.
 
 
+[[zfs_compression]]
+Compression in ZFS
+~~~~~~~~~~~~~~~~~~
+
+When compression is enabled on a dataset, ZFS tries to compress all *new*
+blocks before writing them and decompresses them on reading. Already
+existing data will not be compressed retroactively.
+
+You can enable compression with:
+
+----
+# zfs set compression=<algorithm> <dataset>
+----
+
+We recommend using the `lz4` algorithm, because it adds very little CPU
+overhead. Other algorithms like `lzjb` and `gzip-N`, where `N` is an
+integer from `1` (fastest) to `9` (best compression ratio), are also
+available. Depending on the algorithm and how compressible the data is,
+having compression enabled can even increase I/O performance.
+
+You can disable compression at any time with:
+
+----
+# zfs set compression=off <dataset>
+----
+
+Again, only new blocks will be affected by this change.
+
+
 ZFS Special Device
 ~~~~~~~~~~~~~~~~~~
 
@@ -441,11 +470,11 @@ pool is used to store metadata, deduplication tables, and optionally small
 file blocks.
 
 A `special` device can improve the speed of a pool consisting of slow spinning
-hard disks with a lot of changing metadata. For example workloads that involve
-creating or deleting a large number of files will benefit from the presence of
-a `special` device. ZFS datasets can be configured to store whole small files
-on the `special` device which can further improve the performance. Use SSDs for
-the `special` device.
+hard disks with a lot of metadata changes. For example workloads that involve
+creating, updating or deleting a large number of files will benefit from the
+presence of a `special` device. ZFS datasets can also be configured to store
+whole small files on the `special` device which can further improve the
+performance. Use fast SSDs for the `special` device.
 
 IMPORTANT: The redundancy of the `special` device should match the one of the
 pool, since the `special` device is a point of failure for the whole pool.
@@ -466,14 +495,14 @@ two in the range between `512B` to `128K`. After setting the property new file
 blocks smaller than `size` will be allocated on the `special` device.
 
 IMPORTANT: If the value for `special_small_blocks` is greater than or equal to
-the `recordsize` of the dataset, *all* data will be written to the `special`
-device, so be careful!
+the `recordsize` (default `128K`) of the dataset, *all* data will be written to
+the `special` device, so be careful!
 
 Setting the `special_small_blocks` property on a pool will change the default
 value of that property for all child ZFS datasets (for example all containers
 in the pool will opt in for small file blocks).
 
-.Opt in for small file blocks pool-wide:
+.Opt in for all file smaller than 4K-blocks pool-wide:
 
  zfs set special_small_blocks=4K <pool>