Diffstat (limited to 'Documentation/btrfs-man5.asciidoc')
1 files changed, 73 insertions, 9 deletions
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index c358cef1..916311db 100644
@@ -16,9 +16,11 @@ tools. Currently covers:
3. filesystem limits
-4. file attributes
+4. bootloader support
-5. control device
+5. file attributes
+6. control device
@@ -585,6 +587,13 @@ 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 main filesystem UUID is the metadata_uuid, which stores the new UUID only
+in the superblock while all metadata blocks still have the UUID set at mkfs
+time, see `btrfstune`(8) for more
@@ -624,6 +633,47 @@ ordinary directory. Note that this feature only depends on the kernel version.
reduced-size metadata for extent references, saves a few percent of metadata
+The swapfile is supported since kernel 5.0. Use `swapon`(8) to activate the
+swapfile. There are some limitations of the implementation in btrfs and linux
+* filesystem - must be only single device
+* swapfile - the containing subvolume cannot be snapshotted
+* swapfile - must be preallocated
+* swapfile - must be nodatacow (ie. also nodatasum)
+* swapfile - must not be compressed
+The limitations come namely from the COW-based design and mapping layer of
+blocks that allows the advanced features like relocation and multi-device
+filesystems. However, the swap subsystem expects simpler mapping and no
+background changes of the file blocks once they've been attached to swap.
+With active swapfiles, the following whole-filesystem operations will skip
+swapfile extents or may fail:
+* balance - block groups with swapfile extents are skipped and reported, the rest will be processed normally
+* resize grow - unaffected
+* resize shrink - works as long as the extents are outside of the shrunk range
+* device add - a new device does not interfere with existing swapfile and this operation will work, though no new swapfile can be activated afterwards
+* device delete - if the device has been added as above, it can be also deleted
+* device replace - dtto
+When there are no active swapfiles and a whole-filesystem exclusive operation
+is running (ie. balance, device delete, shrink), the swapfiles cannot be
+temporarily activated. The operation must finish first.
+# truncate -s 0 swapfile
+# chattr +C swapfile
+# fallocate -l 2G swapfile
+# chmod 0600 swapfile
+# mkswap swapfile
+# swapon swapfile
@@ -632,10 +682,11 @@ maximum file name length::
maximum symlink target length::
depends on the 'nodesize' value, for 4k it's 3949 bytes, for larger nodesize
+it's 4095 due to the system limit PATH_MAX
-The symlink target may not be a valid path, ie the path name components
-can exceed the limits, there's no content validation at `symlink`(3) creation.
+The symlink target may not be a valid path, ie. the path name components
+can exceed the limits (NAME_MAX), there's no content validation at `symlink`(3)
maximum number of inodes::
2^64^ but depends on the available metadata space as the inodes are created
@@ -648,15 +699,25 @@ maximum file length::
inherent limit of btrfs is 2^64^ (16 EiB) but the linux VFS limit is 2^63^ (8 EiB)
maximum number of subvolumes::
-2^64^ but depends on the available metadata space, the space consumed by all
-subvolume metadata includes bookkeeping of the shared extents can be large (MiB,
+the subvolume ids can go up to 2^64^ but the number of actual subvolumes
+depends on the available metadata space, the space consumed by all subvolume
+metadata includes bookkeeping of shared extents can be large (MiB, GiB)
maximum number of hardlinks of a file in a directory::
65536 when the `extref` feature is turned on during mkfs (default), roughly
+GRUB2 (https://www.gnu.org/software/grub) has the most advanced support of
+booting from BTRFS with respect to features.
+EXTLINUX (from the https://syslinux.org project) can boot but does not support
+all features. Please check the upstream documentation before you use it.
The btrfs filesystem supports setting the following file attributes using the
@@ -708,6 +769,7 @@ When set on a directory, all newly created files will inherit this attribute.
No other attributes are supported. For the complete list please refer to the
`chattr`(1) manual page.
@@ -739,6 +801,7 @@ The control device is not strictly required but the device scanning will not
work and a workaround would need to be used to mount a multi-device filesystem.
The mount option 'device' can trigger the device scanning during mount.
@@ -747,4 +810,5 @@ SEE ALSO