summaryrefslogtreecommitdiff
path: root/Documentation/btrfs-man5.asciidoc
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/btrfs-man5.asciidoc')
-rw-r--r--Documentation/btrfs-man5.asciidoc82
1 files changed, 73 insertions, 9 deletions
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index c358cef1..916311db 100644
--- a/Documentation/btrfs-man5.asciidoc
+++ b/Documentation/btrfs-man5.asciidoc
@@ -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
MOUNT OPTIONS
@@ -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
+*metadata_uuid*::
+(since: 5.0)
++
+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
+
*mixed_backref*::
(since: 2.6.31)
+
@@ -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
+SWAPFILE SUPPORT
+~~~~~~~~~~~~~~~~
+
+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
+swap subystem:
++
+* 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
+--------------------
+
+
FILESYSTEM LIMITS
-----------------
@@ -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
+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)
+creation.
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,
-GiB)
+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
100 otherwise
+BOOTLOADER SUPPORT
+------------------
+
+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.
+
+
FILE ATTRIBUTES
---------------
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.
+
CONTROL DEVICE
--------------
@@ -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.
+
SEE ALSO
--------
`acl`(5),
@@ -747,4 +810,5 @@ SEE ALSO
`fstrim`(8),
`ioctl`(2),
`mkfs.btrfs`(8),
-`mount`(8)
+`mount`(8),
+`swapon`(8)