summaryrefslogtreecommitdiff
path: root/Documentation/btrfs.5
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/btrfs.5')
-rw-r--r--Documentation/btrfs.568
1 files changed, 60 insertions, 8 deletions
diff --git a/Documentation/btrfs.5 b/Documentation/btrfs.5
index 433e6dd..ea2b18c 100644
--- a/Documentation/btrfs.5
+++ b/Documentation/btrfs.5
@@ -2,12 +2,12 @@
.\" Title: btrfs-man5
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.\" Date: 12/05/2018
+.\" Date: 01/23/2019
.\" Manual: Btrfs Manual
-.\" Source: Btrfs v4.19.1
+.\" Source: Btrfs v4.20.1
.\" Language: English
.\"
-.TH "BTRFS\-MAN5" "5" "12/05/2018" "Btrfs v4\&.19\&.1" "Btrfs Manual"
+.TH "BTRFS\-MAN5" "5" "01/23/2019" "Btrfs v4\&.20\&.1" "Btrfs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -74,7 +74,7 @@ filesystem limits
.sp -1
.IP " 4." 4.2
.\}
-file attributes
+bootloader support
.RE
.sp
.RS 4
@@ -85,6 +85,17 @@ file attributes
.sp -1
.IP " 5." 4.2
.\}
+file attributes
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 6.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP " 6." 4.2
+.\}
control device
.RE
.SH "MOUNT OPTIONS"
@@ -895,6 +906,14 @@ 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
.RE
.PP
+\fBmetadata_uuid\fR
+.RS 4
+(since: 5\&.0)
+.sp
+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
+\fBbtrfstune\fR(8) for more
+.RE
+.PP
\fBmixed_backref\fR
.RS 4
(since: 2\&.6\&.31)
@@ -939,6 +958,34 @@ indicate that
.sp
reduced\-size metadata for extent references, saves a few percent of metadata
.RE
+.SS "SWAPFILE SUPPORT"
+.sp
+The swapfile is supported since kernel 5\&.0\&. Use \fBswapon\fR(8) to activate the swapfile\&. There are some limitations of the implementation in btrfs and linux swap subystem:
+.sp
++ * 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
+.sp
++ 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\(cqve been attached to swap\&.
+.sp
++ 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
+.sp
++ 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\&.
+.sp
++
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# truncate \-s 0 swapfile
+# chattr +C swapfile
+# fallocate \-l 2G swapfile
+# chmod 0600 swapfile
+# mkswap swapfile
+# swapon swapfile
+.fi
+.if n \{\
+.RE
+.\}
.SH "FILESYSTEM LIMITS"
.PP
maximum file name length
@@ -950,9 +997,9 @@ maximum symlink target length
.RS 4
depends on the
\fInodesize\fR
-value, for 4k it\(cqs 3949 bytes, for larger nodesize it\(cqs 4095
+value, for 4k it\(cqs 3949 bytes, for larger nodesize it\(cqs 4095 due to the system limit PATH_MAX
.sp
-The symlink target may not be a valid path, ie the path name components can exceed the limits, there\(cqs no content validation at
+The symlink target may not be a valid path, ie\&. the path name components can exceed the limits (NAME_MAX), there\(cqs no content validation at
\fBsymlink\fR(3) creation\&.
.RE
.PP
@@ -973,7 +1020,7 @@ inherent limit of btrfs is 2^64 (16 EiB) but the linux VFS limit is 2^63 (8 EiB)
.PP
maximum number of subvolumes
.RS 4
-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)
.RE
.PP
maximum number of hardlinks of a file in a directory
@@ -982,6 +1029,11 @@ maximum number of hardlinks of a file in a directory
\fBextref\fR
feature is turned on during mkfs (default), roughly 100 otherwise
.RE
+.SH "BOOTLOADER SUPPORT"
+.sp
+GRUB2 (\m[blue]\fBhttps://www\&.gnu\&.org/software/grub\fR\m[]) has the most advanced support of booting from BTRFS with respect to features\&.
+.sp
+EXTLINUX (from the \m[blue]\fBhttps://syslinux\&.org\fR\m[] project) can boot but does not support all features\&. Please check the upstream documentation before you use it\&.
.SH "FILE ATTRIBUTES"
.sp
The btrfs filesystem supports setting the following file attributes using the \fBchattr\fR(1) utility:
@@ -1128,4 +1180,4 @@ The device is usually created by a system device node manager (eg\&. udev), but
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 \fIdevice\fR can trigger the device scanning during mount\&.
.SH "SEE ALSO"
.sp
-\fBacl\fR(5), \fBbtrfs\fR(8), \fBchattr\fR(1), \fBfstrim\fR(8), \fBioctl\fR(2), \fBmkfs\&.btrfs\fR(8), \fBmount\fR(8)
+\fBacl\fR(5), \fBbtrfs\fR(8), \fBchattr\fR(1), \fBfstrim\fR(8), \fBioctl\fR(2), \fBmkfs\&.btrfs\fR(8), \fBmount\fR(8), \fBswapon\fR(8)