From 4c8e88e4b6c1412a1d4f7364b82b81f49c954c99 Mon Sep 17 00:00:00 2001 From: Calvin Walton Date: Mon, 10 Aug 2026 13:51:26 -0400 Subject: [PATCH 1/6] btrfs-progs: docs: Draft update for setting compression level via btrfs-property Based on change described as option 2 in https://lore.kernel.org/linux-btrfs/DKJZQAFIRW7H.3KE8DKWO5E3TV@gmail.com/ Signed-off-by: Calvin Walton --- Documentation/btrfs-property.rst | 32 +++++++++++++++++++----------- Documentation/ch-mount-options.rst | 6 +++--- 2 files changed, 23 insertions(+), 15 deletions(-) diff --git a/Documentation/btrfs-property.rst b/Documentation/btrfs-property.rst index 399adec7c..e072ebccb 100644 --- a/Documentation/btrfs-property.rst +++ b/Documentation/btrfs-property.rst @@ -36,18 +36,26 @@ Inode properties ^^^^^^^^^^^^^^^^ compression - compression algorithm set for an inode (it's not possible to set the - compression level this way), possible values: - - - *lzo* - - *zlib* - - *zstd* - - *no* or *none* - disable compression (equivalent to ``chattr +m``) - - *""* (empty string) - set the default value - - .. note:: - This has changed in version 5.18 of btrfs-progs and - requires kernel 5.14 or newer to work. + file data compression of an inode. The type and level are specified as *[=]* + using the same format as the *compress* mount option, described in + :ref:`MOUNT OPTIONS` (level support since: 7.X). + + For more information on btrfs compression, see :doc:`Compression`. + + *""* (empty string) sets the default value (use compression specified by mount options). + + .. note:: + This has changed in version 5.18 of btrfs-progs and + requires kernel 5.14 or newer to work. + + TYPE can be one of *zlib*, *lzo*, or *zstd* to select a specific algorithm, or *no* or *none* + to disable compression. LEVEL can be in the range [1, 9] for *zlib* or [-15, 15] for *zstd*. + If level is omitted or set to 0, the level specified via mount options will be used if + the type matches. Otherwise, the type's default compression level will be used. + + .. note:: + When the filesystem is mounted using a kernel older than 7.X, the level set in the + property will be ignored. Subvolume properties ^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/ch-mount-options.rst b/Documentation/ch-mount-options.rst index 7ce56c706..7a1431c55 100644 --- a/Documentation/ch-mount-options.rst +++ b/Documentation/ch-mount-options.rst @@ -112,9 +112,9 @@ compress, compress=, compress-force, compress-force= Both *zlib* and *zstd* (since version 5.1) expose the compression level as a tunable knob with higher levels trading speed and memory (*zstd*) for higher compression ratios. This can be set by appending a colon and the desired level. - ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. If no level is set, - both currently use a default level of 3. The value 0 is an alias for the - default level. + ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15] and [-15,-1] (since 6.15). + If no level is set, both currently use a default level of 3. The value 0 is an + alias for the default level. Otherwise some simple heuristics are applied to detect an incompressible file. If the first blocks written to a file are not compressible, the whole file is From ac10bce5e7886ab08f928e0c942ecfe399180c27 Mon Sep 17 00:00:00 2001 From: koraynilay Date: Mon, 10 Aug 2026 23:55:38 +0200 Subject: [PATCH 2/6] btrfs-progs: docs: finish btrfs-property compression level draft Based on commit 4c8e88e4b6c1412a1d4f7364b82b81f49c954c99 ("btrfs-progs: docs: Draft update for setting compression level via btrfs-property") Signed-off-by: koraynilay --- Documentation/btrfs-property.rst | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/Documentation/btrfs-property.rst b/Documentation/btrfs-property.rst index e072ebccb..50f5a2899 100644 --- a/Documentation/btrfs-property.rst +++ b/Documentation/btrfs-property.rst @@ -36,27 +36,33 @@ Inode properties ^^^^^^^^^^^^^^^^ compression - file data compression of an inode. The type and level are specified as *[=]* + file data compression of an inode. The type and level are specified as *type[:level]* using the same format as the *compress* mount option, described in - :ref:`MOUNT OPTIONS` (level support since: 7.X). + :ref:`MOUNT OPTIONS` (level support since: 7.X). When applied to a + folder, it will be inherited by (copied to) new files created in it, leaving the already + existing ones unaffected. For more information on btrfs compression, see :doc:`Compression`. - *""* (empty string) sets the default value (use compression specified by mount options). + *""* (empty string) unsets this property (uses compression specified by mount options, if any). - .. note:: - This has changed in version 5.18 of btrfs-progs and - requires kernel 5.14 or newer to work. + .. note:: + This has changed in version 5.18 of btrfs-progs and + requires kernel 5.14 or newer to work. + + *type* can be one of *zlib*, *lzo*, or *zstd* to select a specific algorithm, or *no* or *none* + to disable compression (equivalent to :command:`chattr +m`). - TYPE can be one of *zlib*, *lzo*, or *zstd* to select a specific algorithm, or *no* or *none* - to disable compression. LEVEL can be in the range [1, 9] for *zlib* or [-15, 15] for *zstd*. - If level is omitted or set to 0, the level specified via mount options will be used if - the type matches. Otherwise, the type's default compression level will be used. + *level* can be in the range [1, 9] for *zlib*, [-15, 15] for *zstd* and is ignored for *lzo*. + + If *level* is omitted or set to 0 and *type* is the same as the one specified via mount options, + the latter will be used. Otherwise, the type's default compression level will be used. .. note:: When the filesystem is mounted using a kernel older than 7.X, the level set in the property will be ignored. + Subvolume properties ^^^^^^^^^^^^^^^^^^^^ From 93d9baebeab7d603a109b816c8b0e272aa5f5327 Mon Sep 17 00:00:00 2001 From: koraynilay Date: Tue, 11 Aug 2026 01:18:37 +0200 Subject: [PATCH 3/6] btrfs-progs: docs: clarify btrfs-property compression inheritance Signed-off-by: koraynilay --- Documentation/btrfs-property.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/btrfs-property.rst b/Documentation/btrfs-property.rst index 50f5a2899..5d97e6ece 100644 --- a/Documentation/btrfs-property.rst +++ b/Documentation/btrfs-property.rst @@ -39,8 +39,8 @@ compression file data compression of an inode. The type and level are specified as *type[:level]* using the same format as the *compress* mount option, described in :ref:`MOUNT OPTIONS` (level support since: 7.X). When applied to a - folder, it will be inherited by (copied to) new files created in it, leaving the already - existing ones unaffected. + folder, it will be inherited by (copied to) new files/folders (but not subvolumes) created in + it, leaving the already existing ones unaffected. For more information on btrfs compression, see :doc:`Compression`. From 04ef13878b2949c9daa83a1ff36b4d0fd8a20ff2 Mon Sep 17 00:00:00 2001 From: koraynilay Date: Tue, 11 Aug 2026 03:57:29 +0200 Subject: [PATCH 4/6] btrfs-progs: docs: clarify btrfs-property compression type check and version support Signed-off-by: koraynilay --- Documentation/btrfs-property.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/btrfs-property.rst b/Documentation/btrfs-property.rst index 5d97e6ece..d87caa5fb 100644 --- a/Documentation/btrfs-property.rst +++ b/Documentation/btrfs-property.rst @@ -38,7 +38,7 @@ Inode properties compression file data compression of an inode. The type and level are specified as *type[:level]* using the same format as the *compress* mount option, described in - :ref:`MOUNT OPTIONS` (level support since: 7.X). When applied to a + :ref:`MOUNT OPTIONS`. When applied to a folder, it will be inherited by (copied to) new files/folders (but not subvolumes) created in it, leaving the already existing ones unaffected. @@ -56,11 +56,11 @@ compression *level* can be in the range [1, 9] for *zlib*, [-15, 15] for *zstd* and is ignored for *lzo*. If *level* is omitted or set to 0 and *type* is the same as the one specified via mount options, - the latter will be used. Otherwise, the type's default compression level will be used. + the latter's level will be used. Otherwise, the type's default compression level will be used. .. note:: - When the filesystem is mounted using a kernel older than 7.X, the level set in the - property will be ignored. + When the filesystem is mounted using a kernel version < 7.X, *[:level]* will be ignored. This + applies also to the *type* check against the *compress* mount option. Subvolume properties From 7ae9e2aa7a35af5e7b656424957a558a9d0dd676 Mon Sep 17 00:00:00 2001 From: koraynilay Date: Tue, 11 Aug 2026 04:11:59 +0200 Subject: [PATCH 5/6] btrfs-progs: docs: explain how the extents are compressed There are 3 ways extents get compressed: * by -o compress: btrfs will use heuristics, if that succeeds it will try to compress, if that fails it will mark the file as NOCOMPRESS and new extents won't even be tested for compression and will be written to disk uncompressed; * by -o compress-force: btrfs will try to compress it directly, if there is no benefit it will keep it uncompressed. In any case it will limit the max extent size to 128K instead of 128M, increasing metadata usage; * by btrfs.compression: btrfs will behave like -o compress, using the heuristics -> compress flow, but will not set the NOCOMPRESS flag, so it will do the same flow for every new extent of that file. It also won't limit the max extent size. Explanation by Zygo (thanks!). Signed-off-by: koraynilay --- Documentation/btrfs-property.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/btrfs-property.rst b/Documentation/btrfs-property.rst index d87caa5fb..654ef259b 100644 --- a/Documentation/btrfs-property.rst +++ b/Documentation/btrfs-property.rst @@ -62,6 +62,12 @@ compression When the filesystem is mounted using a kernel version < 7.X, *[:level]* will be ignored. This applies also to the *type* check against the *compress* mount option. + The way this property works is a middle-ground between the *compress* mount option and the + *compress-force* mount option: it will try to compress every new extent of the file as *compress* + would, but will prevent the *NOCOMPRESS* flag from being set and won't limit extent size like + *compress-force* does. See :ref:`MOUNT OPTIONS` and + the **INCOMPRESSIBLE DATA** section of :ref:`COMPRESSION` for more information. + Subvolume properties ^^^^^^^^^^^^^^^^^^^^ From 21c242061f795114dfcfa01514b30a17f0a775de Mon Sep 17 00:00:00 2001 From: koraynilay Date: Tue, 11 Aug 2026 05:23:11 +0200 Subject: [PATCH 6/6] btrfs-progs: docs: add clearer warning about old behaviour TODO: re-read and fix, way too tired now Signed-off-by: koraynilay --- Documentation/btrfs-property.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Documentation/btrfs-property.rst b/Documentation/btrfs-property.rst index 654ef259b..bd333891a 100644 --- a/Documentation/btrfs-property.rst +++ b/Documentation/btrfs-property.rst @@ -59,8 +59,14 @@ compression the latter's level will be used. Otherwise, the type's default compression level will be used. .. note:: - When the filesystem is mounted using a kernel version < 7.X, *[:level]* will be ignored. This - applies also to the *type* check against the *compress* mount option. + When the filesystem is mounted using a kernel version < 7.X, *[:level]* will be ignored. + + .. warning:: + Furthermore, with kernels before 7.X, the level from the *compress* mount option always + carries through to this property, even if the type is different (but it will get clamped, + so it's still safe). This means that if e.g. the filesystem was mounted with -o *compress=zstd:15* + and a file has this property set to *zlib*, the file data will actually be compressed at *zlib:9* + (the max supported level for *zlib*). After 7.X, it will use the default, *zlib:3* in this case. The way this property works is a middle-ground between the *compress* mount option and the *compress-force* mount option: it will try to compress every new extent of the file as *compress*