summaryrefslogtreecommitdiff
path: root/Documentation/mkfs.btrfs.8
diff options
context:
space:
mode:
authorDimitri John Ledkov <xnox@ubuntu.com>2018-12-11 10:30:30 +1100
committerDimitri John Ledkov <xnox@ubuntu.com>2018-12-11 10:30:30 +1100
commit5b162a39be9dec46a22c815f43fc337b920b4252 (patch)
treee9d6f16368ffe614a45eade6b0d6f9a860cea508 /Documentation/mkfs.btrfs.8
parent167651ca29ec522cff0d81b52dc0cc4ae4e3f535 (diff)
New upstream version 4.19.1
Diffstat (limited to 'Documentation/mkfs.btrfs.8')
-rw-r--r--Documentation/mkfs.btrfs.8626
1 files changed, 626 insertions, 0 deletions
diff --git a/Documentation/mkfs.btrfs.8 b/Documentation/mkfs.btrfs.8
new file mode 100644
index 00000000..fbcd1203
--- /dev/null
+++ b/Documentation/mkfs.btrfs.8
@@ -0,0 +1,626 @@
+'\" t
+.\" Title: mkfs.btrfs
+.\" 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
+.\" Manual: Btrfs Manual
+.\" Source: Btrfs v4.19.1
+.\" Language: English
+.\"
+.TH "MKFS\&.BTRFS" "8" "12/05/2018" "Btrfs v4\&.19\&.1" "Btrfs Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+mkfs.btrfs \- create a btrfs filesystem
+.SH "SYNOPSIS"
+.sp
+\fBmkfs\&.btrfs\fR [options] \fI<device>\fR [\fI<device>\fR\&...]
+.SH "DESCRIPTION"
+.sp
+\fBmkfs\&.btrfs\fR is used to create the btrfs filesystem on a single or multiple devices\&. \fI<device>\fR is typically a block device but can be a file\-backed image as well\&. Multiple devices are grouped by UUID of the filesystem\&.
+.sp
+Before mounting such filesystem, the kernel module must know all the devices either via preceding execution of \fBbtrfs device scan\fR or using the \fBdevice\fR mount option\&. See section \fBMULTIPLE DEVICES\fR for more details\&.
+.SH "OPTIONS"
+.PP
+\fB\-b|\-\-byte\-count \fR\fB\fI<size>\fR\fR
+.RS 4
+Specify the size of the filesystem\&. If this option is not used, then mkfs\&.btrfs uses the entire device space for the filesystem\&.
+.RE
+.PP
+\fB\-d|\-\-data \fR\fB\fI<profile>\fR\fR
+.RS 4
+Specify the profile for the data block groups\&. Valid values are
+\fIraid0\fR,
+\fIraid1\fR,
+\fIraid5\fR,
+\fIraid6\fR,
+\fIraid10\fR
+or
+\fIsingle\fR
+or dup (case does not matter)\&.
+.sp
+See
+\fIDUP PROFILES ON A SINGLE DEVICE\fR
+for more\&.
+.RE
+.PP
+\fB\-m|\-\-metadata \fR\fB\fI<profile>\fR\fR
+.RS 4
+Specify the profile for the metadata block groups\&. Valid values are
+\fIraid0\fR,
+\fIraid1\fR,
+\fIraid5\fR,
+\fIraid6\fR,
+\fIraid10\fR,
+\fIsingle\fR
+or
+\fIdup\fR, (case does not matter)\&.
+.sp
+A single device filesystem will default to
+\fIDUP\fR, unless a SSD is detected\&. Then it will default to
+\fIsingle\fR\&. The detection is based on the value of
+\fB/sys/block/DEV/queue/rotational\fR, where
+\fIDEV\fR
+is the short name of the device\&.
+.sp
+Note that the rotational status can be arbitrarily set by the underlying block device driver and may not reflect the true status (network block device, memory\-backed SCSI devices etc)\&. Use the options
+\fI\-\-data/\-\-metadata\fR
+to avoid confusion\&.
+.sp
+See
+\fIDUP PROFILES ON A SINGLE DEVICE\fR
+for more details\&.
+.RE
+.PP
+\fB\-M|\-\-mixed\fR
+.RS 4
+Normally the data and metadata block groups are isolated\&. The
+\fImixed\fR
+mode will remove the isolation and store both types in the same block group type\&. This helps to utilize the free space regardless of the purpose and is suitable for small devices\&. The separate allocation of block groups leads to a situation where the space is reserved for the other block group type, is not available for allocation and can lead to ENOSPC state\&.
+.sp
+The recommended size for the mixed mode is for filesystems less than 1GiB\&. The soft recommendation is to use it for filesystems smaller than 5GiB\&. The mixed mode may lead to degraded performance on larger filesystems, but is otherwise usable, even on multiple devices\&.
+.sp
+The
+\fInodesize\fR
+and
+\fIsectorsize\fR
+must be equal, and the block group types must match\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+versions up to 4\&.2\&.x forced the mixed mode for devices smaller than 1GiB\&. This has been removed in 4\&.3+ as it caused some usability issues\&.
+.sp .5v
+.RE
+.RE
+.PP
+\fB\-l|\-\-leafsize \fR\fB\fI<size>\fR\fR
+.RS 4
+Alias for \-\-nodesize\&. Deprecated\&.
+.RE
+.PP
+\fB\-n|\-\-nodesize \fR\fB\fI<size>\fR\fR
+.RS 4
+Specify the nodesize, the tree block size in which btrfs stores metadata\&. The default value is 16KiB (16384) or the page size, whichever is bigger\&. Must be a multiple of the sectorsize and a power of 2, but not larger than 64KiB (65536)\&. Leafsize always equals nodesize and the options are aliases\&.
+.sp
+Smaller node size increases fragmentation but leads to taller b\-trees which in turn leads to lower locking contention\&. Higher node sizes give better packing and less fragmentation at the cost of more expensive memory operations while updating the metadata blocks\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+versions up to 3\&.11 set the nodesize to 4k\&.
+.sp .5v
+.RE
+.RE
+.PP
+\fB\-s|\-\-sectorsize \fR\fB\fI<size>\fR\fR
+.RS 4
+Specify the sectorsize, the minimum data block allocation unit\&.
+.sp
+The default value is the page size and is autodetected\&. If the sectorsize differs from the page size, the created filesystem may not be mountable by the kernel\&. Therefore it is not recommended to use this option unless you are going to mount it on a system with the appropriate page size\&.
+.RE
+.PP
+\fB\-L|\-\-label \fR\fB\fI<string>\fR\fR
+.RS 4
+Specify a label for the filesystem\&. The
+\fIstring\fR
+should be less than 256 bytes and must not contain newline characters\&.
+.RE
+.PP
+\fB\-K|\-\-nodiscard\fR
+.RS 4
+Do not perform whole device TRIM operation on devices that are capable of that\&. This does not affect discard/trim operation when the filesystem is mounted\&. Please see the mount option
+\fIdiscard\fR
+for that in
+\fBbtrfs\fR(5)\&.
+.RE
+.PP
+\fB\-r|\-\-rootdir \fR\fB\fI<rootdir>\fR\fR
+.RS 4
+Populate the toplevel subvolume with files from
+\fIrootdir\fR\&. This does not require root permissions to write the new files or to mount the filesystem\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+This option may enlarge the image or file to ensure it\(cqs big enough to contain the files from
+\fIrootdir\fR\&. Since version 4\&.14\&.1 the filesystem size is not minimized\&. Please see option
+\fI\-\-shrink\fR
+if you need that functionality\&.
+.sp .5v
+.RE
+.RE
+.PP
+\fB\-\-shrink\fR
+.RS 4
+Shrink the filesystem to its minimal size, only works with
+\fI\-\-rootdir\fR
+option\&.
+.sp
+If the destination is a regular file, this option will also truncate the file to the minimal size\&. Otherwise it will reduce the filesystem available space\&. Extra space will not be usable unless the filesystem is mounted and resized using
+\fIbtrfs filesystem resize\fR\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+prior to version 4\&.14\&.1, the shrinking was done automatically\&.
+.sp .5v
+.RE
+.RE
+.PP
+\fB\-O|\-\-features \fR\fB\fI<feature1>\fR\fR\fB[,\fR\fB\fI<feature2>\fR\fR\fB\&...]\fR
+.RS 4
+A list of filesystem features turned on at mkfs time\&. Not all features are supported by old kernels\&. To disable a feature, prefix it with
+\fI^\fR\&.
+.sp
+See section
+\fBFILESYSTEM FEATURES\fR
+for more details\&. To see all available features that mkfs\&.btrfs supports run:
+.sp
+\fBmkfs\&.btrfs \-O list\-all\fR
+.RE
+.PP
+\fB\-f|\-\-force\fR
+.RS 4
+Forcibly overwrite the block devices when an existing filesystem is detected\&. By default, mkfs\&.btrfs will utilize
+\fIlibblkid\fR
+to check for any known filesystem on the devices\&. Alternatively you can use the
+\fBwipefs\fR
+utility to clear the devices\&.
+.RE
+.PP
+\fB\-q|\-\-quiet\fR
+.RS 4
+Print only error or warning messages\&. Options \-\-features or \-\-help are unaffected\&.
+.RE
+.PP
+\fB\-U|\-\-uuid \fR\fB\fI<UUID>\fR\fR
+.RS 4
+Create the filesystem with the given
+\fIUUID\fR\&. The UUID must not exist on any filesystem currently present\&.
+.RE
+.PP
+\fB\-V|\-\-version\fR
+.RS 4
+Print the
+\fBmkfs\&.btrfs\fR
+version and exit\&.
+.RE
+.PP
+\fB\-\-help\fR
+.RS 4
+Print help\&.
+.RE
+.PP
+\fB\-A|\-\-alloc\-start \fR\fB\fI<offset>\fR\fR
+.RS 4
+\fBdeprecated, will be removed\fR
+(An option to help debugging chunk allocator\&.) Specify the (physical) offset from the start of the device at which allocations start\&. The default value is zero\&.
+.RE
+.SH "SIZE UNITS"
+.sp
+The default unit is \fIbyte\fR\&. All size parameters accept suffixes in the 1024 base\&. The recognized suffixes are: \fIk\fR, \fIm\fR, \fIg\fR, \fIt\fR, \fIp\fR, \fIe\fR, both uppercase and lowercase\&.
+.SH "MULTIPLE DEVICES"
+.sp
+Before mounting a multiple device filesystem, the kernel module must know the association of the block devices that are attached to the filesystem UUID\&.
+.sp
+There is typically no action needed from the user\&. On a system that utilizes a udev\-like daemon, any new block device is automatically registered\&. The rules call \fBbtrfs device scan\fR\&.
+.sp
+The same command can be used to trigger the device scanning if the btrfs kernel module is reloaded (naturally all previous information about the device registration is lost)\&.
+.sp
+Another possibility is to use the mount options \fBdevice\fR to specify the list of devices to scan at the time of mount\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# mount \-o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+that this means only scanning, if the devices do not exist in the system, mount will fail anyway\&. This can happen on systems without initramfs/initrd and root partition created with RAID1/10/5/6 profiles\&. The mount action can happen before all block devices are discovered\&. The waiting is usually done on the initramfs/initrd systems\&.
+.sp .5v
+.RE
+.sp
+As of kernel 4\&.14, RAID5/6 is still considered experimental and shouldn\(cqt be employed for production use\&.
+.SH "FILESYSTEM FEATURES"
+.sp
+Features that can be enabled during creation time\&. See also \fBbtrfs\fR(5) section \fIFILESYSTEM FEATURES\fR\&.
+.PP
+\fBmixed\-bg\fR
+.RS 4
+(kernel support since 2\&.6\&.37)
+.sp
+mixed data and metadata block groups, also set by option
+\fI\-\-mixed\fR
+.RE
+.PP
+\fBextref\fR
+.RS 4
+(default since btrfs\-progs 3\&.12, kernel support since 3\&.7)
+.sp
+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
+\fBraid56\fR
+.RS 4
+(kernel support since 3\&.9)
+.sp
+extended format for RAID5/6, also enabled if raid5 or raid6 block groups are selected
+.RE
+.PP
+\fBskinny\-metadata\fR
+.RS 4
+(default since btrfs\-progs 3\&.18, kernel support since 3\&.10)
+.sp
+reduced\-size metadata for extent references, saves a few percent of metadata
+.RE
+.PP
+\fBno\-holes\fR
+.RS 4
+(kernel support since 3\&.14)
+.sp
+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
+.RE
+.SH "BLOCK GROUPS, CHUNKS, RAID"
+.sp
+The highlevel organizational units of a filesystem are block groups of three types: data, metadata and system\&.
+.PP
+\fBDATA\fR
+.RS 4
+store data blocks and nothing else
+.RE
+.PP
+\fBMETADATA\fR
+.RS 4
+store internal metadata in b\-trees, can store file data if they fit into the inline limit
+.RE
+.PP
+\fBSYSTEM\fR
+.RS 4
+store structures that describe the mapping between the physical devices and the linear logical space representing the filesystem
+.RE
+.sp
+Other terms commonly used:
+.PP
+\fBblock group\fR, \fBchunk\fR
+.RS 4
+a logical range of space of a given profile, stores data, metadata or both; sometimes the terms are used interchangeably
+.sp
+A typical size of metadata block group is 256MiB (filesystem smaller than 50GiB) and 1GiB (larger than 50GiB), for data it\(cqs 1GiB\&. The system block group size is a few megabytes\&.
+.RE
+.PP
+\fBRAID\fR
+.RS 4
+a block group profile type that utilizes RAID\-like features on multiple devices: striping, mirroring, parity
+.RE
+.PP
+\fBprofile\fR
+.RS 4
+when used in connection with block groups refers to the allocation strategy and constraints, see the section
+\fIPROFILES\fR
+for more details
+.RE
+.SH "PROFILES"
+.sp
+There are the following block group types available:
+.TS
+allbox tab(:);
+ct c s s ct
+^ c c ct ^
+ct ct ct ct ct
+ct ct ct ct ct
+ct ct ct ct ct
+ct ct ct ct ct
+ct ct ct ct ct
+ct ct ct ct ct
+ct ct ct ct ct.
+T{
+.sp
+\fBProfile\fR
+T}:T{
+.sp
+\fBRedundancy\fR
+T}:T{
+.sp
+\fBMin/max devices\fR
+T}
+:T{
+.sp
+\fBCopies\fR
+T}:T{
+.sp
+\fBParity\fR
+T}:T{
+.sp
+\fBStriping\fR
+T}:
+T{
+.sp
+single
+T}:T{
+.sp
+1
+T}:T{
+.sp
+T}:T{
+.sp
+T}:T{
+.sp
+1/any
+T}
+T{
+.sp
+DUP
+T}:T{
+.sp
+2 / 1 device
+T}:T{
+.sp
+T}:T{
+.sp
+T}:T{
+.sp
+1/any ^(see note 1)
+T}
+T{
+.sp
+RAID0
+T}:T{
+.sp
+T}:T{
+.sp
+T}:T{
+.sp
+1 to N
+T}:T{
+.sp
+2/any
+T}
+T{
+.sp
+RAID1
+T}:T{
+.sp
+2
+T}:T{
+.sp
+T}:T{
+.sp
+T}:T{
+.sp
+2/any
+T}
+T{
+.sp
+RAID10
+T}:T{
+.sp
+2
+T}:T{
+.sp
+T}:T{
+.sp
+1 to N
+T}:T{
+.sp
+4/any
+T}
+T{
+.sp
+RAID5
+T}:T{
+.sp
+1
+T}:T{
+.sp
+1
+T}:T{
+.sp
+2 to N \- 1
+T}:T{
+.sp
+2/any ^(see note 2)
+T}
+T{
+.sp
+RAID6
+T}:T{
+.sp
+1
+T}:T{
+.sp
+2
+T}:T{
+.sp
+3 to N \- 2
+T}:T{
+.sp
+3/any ^(see note 3)
+T}
+.TE
+.sp 1
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBWarning\fR
+.ps -1
+.br
+.sp
+It\(cqs not recommended to build btrfs with RAID0/1/10/5/6 profiles on partitions from the same device\&. Neither redundancy nor performance will be improved\&.
+.sp .5v
+.RE
+.sp
+\fINote 1:\fR DUP may exist on more than 1 device if it starts on a single device and another one is added\&. Since version 4\&.5\&.1, \fBmkfs\&.btrfs\fR will let you create DUP on multiple devices\&.
+.sp
+\fINote 2:\fR It\(cqs not recommended to use 2 devices with RAID5\&. In that case, parity stripe will contain the same data as the data stripe, making RAID5 degraded to RAID1 with more overhead\&.
+.sp
+\fINote 3:\fR It\(cqs also not recommended to use 3 devices with RAID6, unless you want to get effectively 3 copies in a RAID1\-like manner (but not exactly that)\&. N\-copies RAID1 is not implemented\&.
+.SH "DUP PROFILES ON A SINGLE DEVICE"
+.sp
+The mkfs utility will let the user create a filesystem with profiles that write the logical blocks to 2 physical locations\&. Whether there are really 2 physical copies highly depends on the underlying device type\&.
+.sp
+For example, a SSD drive can remap the blocks internally to a single copy\(emthus deduplicating them\&. This negates the purpose of increased redundancy and just wastes filesystem space without providing the expected level of redundancy\&.
+.sp
+The duplicated data/metadata may still be useful to statistically improve the chances on a device that might perform some internal optimizations\&. The actual details are not usually disclosed by vendors\&. For example we could expect that not all blocks get deduplicated\&. This will provide a non\-zero probability of recovery compared to a zero chance if the single profile is used\&. The user should make the tradeoff decision\&. The deduplication in SSDs is thought to be widely available so the reason behind the mkfs default is to not give a false sense of redundancy\&.
+.sp
+As another example, the widely used USB flash or SD cards use a translation layer between the logical and physical view of the device\&. The data lifetime may be affected by frequent plugging\&. The memory cells could get damaged, hopefully not destroying both copies of particular data in case of DUP\&.
+.sp
+The wear levelling techniques can also lead to reduced redundancy, even if the device does not do any deduplication\&. The controllers may put data written in a short timespan into the same physical storage unit (cell, block etc)\&. In case this unit dies, both copies are lost\&. BTRFS does not add any artificial delay between metadata writes\&.
+.sp
+The traditional rotational hard drives usually fail at the sector level\&.
+.sp
+In any case, a device that starts to misbehave and repairs from the DUP copy should be replaced! \fBDUP is not backup\fR\&.
+.SH "KNOWN ISSUES"
+.sp
+\fBSMALL FILESYSTEMS AND LARGE NODESIZE\fR
+.sp
+The combination of small filesystem size and large nodesize is not recommended in general and can lead to various ENOSPC\-related issues during mount time or runtime\&.
+.sp
+Since mixed block group creation is optional, we allow small filesystem instances with differing values for \fIsectorsize\fR and \fInodesize\fR to be created and could end up in the following situation:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# mkfs\&.btrfs \-f \-n 65536 /dev/loop0
+btrfs\-progs v3\&.19\-rc2\-405\-g976307c
+See http://btrfs\&.wiki\&.kernel\&.org for more information\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+Performing full device TRIM (512\&.00MiB) \&.\&.\&.
+Label: (null)
+UUID: 49fab72e\-0c8b\-466b\-a3ca\-d1bfe56475f0
+Node size: 65536
+Sector size: 4096
+Filesystem size: 512\&.00MiB
+Block group profiles:
+ Data: single 8\&.00MiB
+ Metadata: DUP 40\&.00MiB
+ System: DUP 12\&.00MiB
+SSD detected: no
+Incompat features: extref, skinny\-metadata
+Number of devices: 1
+Devices:
+ ID SIZE PATH
+ 1 512\&.00MiB /dev/loop0
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# mount /dev/loop0 /mnt/
+mount: mount /dev/loop0 on /mnt failed: No space left on device
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The ENOSPC occurs during the creation of the UUID tree\&. This is caused by large metadata blocks and space reservation strategy that allocates more than can fit into the filesystem\&.
+.SH "AVAILABILITY"
+.sp
+\fBmkfs\&.btrfs\fR is part of btrfs\-progs\&. Please refer to the btrfs wiki \m[blue]\fBhttp://btrfs\&.wiki\&.kernel\&.org\fR\m[] for further details\&.
+.SH "SEE ALSO"
+.sp
+\fBbtrfs\fR(5), \fBbtrfs\fR(8), \fBwipefs\fR(8)