diff options
Diffstat (limited to 'Documentation/mkfs.btrfs.8')
-rw-r--r-- | Documentation/mkfs.btrfs.8 | 626 |
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) |