|author||David Sterba <firstname.lastname@example.org>||2016-09-01 18:51:18 +0200|
|committer||David Sterba <email@example.com>||2016-09-05 10:05:30 +0200|
btrfs-progs: docs: describe filesystem features
Signed-off-by: David Sterba <firstname.lastname@example.org>
Diffstat (limited to 'Documentation')
3 files changed, 122 insertions, 7 deletions
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index 467f11bf..a1f364e0 100644
@@ -12,9 +12,12 @@ tools. Currently covers:
1. mount options
-2. file attributes
+2. filesystem features
+3. file attributes
+4. control device
-3. control device
@@ -406,6 +409,91 @@ NOTE: This option has replaced 'recovery'.
Allow subvolumes to be deleted by their respective owner. Otherwise, only the
root user can do that.
+The basic set of filesystem features gets extended over time. The backward
+compatibility is maintained and the features are optional, need to be
+explicitly asked for so accidental use will not create incompatibilities.
+There are several classes and the respective tools to manage the features:
+at mkfs time only::
+This is namely for core structures, like the b-tree nodesize, see
+`mkfs.btrfs`(8) for more details.
+after mkfs, on an unmounted filesystem::
+Features that may optimize internal structures or add new structures to support
+new functionality, see `btrfstune`(8). The command *btrfs inspect-internal
+dump-super device* will dump a superblock, you can map the value of
+'incompat_flags' to the features listed below
+after mkfs, on a mounted filesystem::
+The features of a filesystem (with a given UUID) are listed in
+`/sys/fs/btrfs/UUID/features/`, one file per feature. The status of is stored
+insid the file. The value '1' is for enabled, '0' means the feature was had
+been enabled at the mount time and turned off afterwards.
+Whether a particular feature can be turned on a mounted filesystem can be found
+in the directory `/sys/fs/btrfs/features/`, one file per feature. The value '1'
+means the feature can be enabled.
+List of features (see also `mkfs.btrfs`(8) section 'FILESYSTEM FEATURES'):
+the filesystem uses 'nodesize' bigger than the page size
+the 'lzo' compression has been used on the filesystem, either as a mount option
+or via *btrfs filesystem defrag*.
+the default subvolume has been set on the filesystem
+increased hardlink limit per file in a directory to 65536, older kernels
+supported a varying number of hardlinks depending on the sum of all file name
+sizes that can be stored into one metadata block
+the last major disk format change, improved backreferences
+mixed data and metadata block groups, ie. the data and metadata are not
+separated and occupy the same block groups, this mode is suitable for small
+volumes as there are no constraints how the remaining space should be used
+(compared to the split mode, where empty metadata space cannot be used for data
+and vice versa)
+on the other hand, the final layout is quite unpredictable and possibly highly
+fragmented, which means worse performance
+improved representation of file extents where holes are not explicitly
+stored as an extent, saves a few percent of metadata if sparse files are used
+the filesystem contains or contained a raid56 profile of block groups
+reduced-size metadata for extent references, saves a few percent of metadata
The btrfs filesystem supports setting the following file attributes using the
diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
index 68fec4c9..1e9aa703 100644
@@ -17,7 +17,11 @@ parameters. The filesystem must be unmounted.
The common usecase is to enable features that were not enabled at mkfs time.
Please make sure that you have kernel support for the features. You can find a
complete list of features and kernel version of their introduction at
+https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature . Also, the
+manual page `mkfs.btrfs`(8) contains more details about the features.
+Some of the features could be enabled on a mounted filesytem. Please refer to
+the respective section in `btrfs`(5).
@@ -26,14 +30,24 @@ Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it
A seeding filesystem is forced to be mounted read-only. A new device can be added
to the filesystem and will capture all writes keeping the seeding device intact.
+(since kernel: 3.7)
Enable extended inode refs (hardlink limit per file in a directory is 65536),
-enabled by mkfs feature 'extref'. Since kernel 3.7.
+enabled by mkfs feature 'extref'.
+(since kernel: 3.10)
Enable skinny metadata extent refs (more efficient representation of extents),
-enabled by mkfs feature 'skinny-metadata'. Since kernel 3.10.
+enabled by mkfs feature 'skinny-metadata'.
+All newly created extents will use the new representation. To completely switch
+the entire filesystem, run a full balance of the metadata. Please refer to
+(since kernel: 3.14)
Enable no-holes feature (more efficient representation of file holes), enabled
-by mkfs feature 'no-holes'. Since kernel 3.14.
+by mkfs feature 'no-holes'.
Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure
that you are aware of the dangers.
@@ -72,4 +86,6 @@ will become deprecated and removed afterwards.
diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc
index 5d79e24f..98fe694b 100644
@@ -185,7 +185,12 @@ initramfs/initrd systems.
+Features that can be enabled during creation time. See also `btrfs`(5) section
+(kernel support since 2.6.37)
mixed data and metadata block groups, also set by option '--mixed'
@@ -196,6 +201,8 @@ supported a varying number of hardlinks depending on the sum of all file name
sizes that can be stored into one metadata block
+(kernel support since 3.9)
extended format for RAID5/6, also enabled if raid5 or raid6 block groups
@@ -205,6 +212,8 @@ are selected
reduced-size metadata for extent references, saves a few percent of metadata
+(kernel support since 3.14)
improved representation of file extents where holes are not explicitly
stored as an extent, saves a few percent of metadata if sparse files are used
@@ -351,4 +360,6 @@ further details.