diff options
author | Dimitri John Ledkov <xnox@ubuntu.com> | 2018-12-11 10:30:30 +1100 |
---|---|---|
committer | Dimitri John Ledkov <xnox@ubuntu.com> | 2018-12-11 10:30:30 +1100 |
commit | 5b162a39be9dec46a22c815f43fc337b920b4252 (patch) | |
tree | e9d6f16368ffe614a45eade6b0d6f9a860cea508 /Documentation/btrfs-device.8 | |
parent | 167651ca29ec522cff0d81b52dc0cc4ae4e3f535 (diff) |
New upstream version 4.19.1
Diffstat (limited to 'Documentation/btrfs-device.8')
-rw-r--r-- | Documentation/btrfs-device.8 | 410 |
1 files changed, 410 insertions, 0 deletions
diff --git a/Documentation/btrfs-device.8 b/Documentation/btrfs-device.8 new file mode 100644 index 00000000..082e66a5 --- /dev/null +++ b/Documentation/btrfs-device.8 @@ -0,0 +1,410 @@ +'\" t +.\" Title: btrfs-device +.\" 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 "BTRFS\-DEVICE" "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" +btrfs-device \- manage devices of btrfs filesystems +.SH "SYNOPSIS" +.sp +\fBbtrfs device\fR \fI<subcommand>\fR \fI<args>\fR +.SH "DESCRIPTION" +.sp +The \fBbtrfs device\fR command group is used to manage devices of the btrfs filesystems\&. +.SH "DEVICE MANAGEMENT" +.sp +Btrfs filesystem can be created on top of single or multiple block devices\&. Data and metadata are organized in allocation profiles with various redundancy policies\&. There\(cqs some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning\&. Due to the similarity, the RAID terminology is widely used in the documentation\&. See \fBmkfs\&.btrfs\fR(8) for more details and the exact profile capabilities and constraints\&. +.sp +The device management works on a mounted filesystem\&. Devices can be added, removed or replaced, by commands provided by \fBbtrfs device\fR and \fBbtrfs replace\fR\&. +.sp +The profiles can be also changed, provided there\(cqs enough workspace to do the conversion, using the \fBbtrfs balance\fR command and namely the filter \fIconvert\fR\&. +.PP +Profile +.RS 4 +A profile describes an allocation policy based on the redundancy/replication constraints in connection with the number of devices\&. The profile applies to data and metadata block groups separately\&. +.RE +.PP +RAID level +.RS 4 +Where applicable, the level refers to a profile that matches constraints of the standard RAID levels\&. At the moment the supported ones are: RAID0, RAID1, RAID10, RAID5 and RAID6\&. +.RE +.sp +See the section \fBTYPICAL USECASES\fR for some examples\&. +.SH "SUBCOMMAND" +.PP +\fBadd\fR [\-Kf] \fI<device>\fR [\fI<device>\fR\&...] \fI<path>\fR +.RS 4 +Add device(s) to the filesystem identified by +\fI<path>\fR\&. +.sp +If applicable, a whole device discard (TRIM) operation is performed prior to adding the device\&. A device with existing filesystem detected by +\fBblkid\fR(8) will prevent device addition and has to be forced\&. Alternatively the filesystem can be wiped from the device using eg\&. the +\fBwipefs\fR(8) tool\&. +.sp +The operation is instant and does not affect existing data\&. The operation merely adds the device to the filesystem structures and creates some block groups headers\&. +.sp +\fBOptions\fR +.PP +\-K|\-\-nodiscard +.RS 4 +do not perform discard (TRIM) by default +.RE +.PP +\-f|\-\-force +.RS 4 +force overwrite of existing filesystem on the given disk(s) +.RE +.RE +.PP +\fBremove\fR \fI<device>\fR|\fI<devid>\fR [\fI<device>\fR|\fI<devid>\fR\&...] \fI<path>\fR +.RS 4 +Remove device(s) from a filesystem identified by +\fI<path>\fR +.sp +Device removal must satisfy the profile constraints, otherwise the command fails\&. The filesystem must be converted to profile(s) that would allow the removal\&. This can typically happen when going down from 2 devices to 1 and using the RAID1 profile\&. See the +\fBTYPICAL USECASES\fR +section below\&. +.sp +The operation can take long as it needs to move all data from the device\&. +.sp +It is possible to delete the device that was used to mount the filesystem\&. The device entry in the mount table will be replaced by another device name with the lowest device id\&. +.sp +If the filesystem is mounted in degraded mode (\-o degraded), special term +\fImissing\fR +can be used for +\fIdevice\fR\&. In that case, the first device that is described by the filesystem metadata, but not present at the mount time will be removed\&. +.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 +In most cases, there is only one missing device in degraded mode, otherwise mount fails\&. If there are two or more devices missing (e\&.g\&. possible in RAID6), you need specify +\fImissing\fR +as many times as the number of missing devices to remove all of them\&. +.sp .5v +.RE +.RE +.PP +\fBdelete\fR \fI<device>\fR|\fI<devid>\fR [\fI<device>\fR|\fI<devid>\fR\&...] \fI<path>\fR +.RS 4 +Alias of remove kept for backward compatibility +.RE +.PP +\fBready\fR \fI<device>\fR +.RS 4 +Wait until all devices of a multiple\-device filesystem are scanned and registered within the kernel module\&. This is to provide a way for automatic filesystem mounting tools to wait before the mount can start\&. The device scan is only one of the preconditions and the mount can fail for other reasons\&. Normal users usually do not need this command and may safely ignore it\&. +.RE +.PP +\fBscan\fR [(\-\-all\-devices|\-d)|\fI<device>\fR [\fI<device>\fR\&...]] +.RS 4 +Scan devices for a btrfs filesystem and register them with the kernel module\&. This allows mounting multiple\-device filesystem by specifying just one from the whole group\&. +.sp +If no devices are passed, all block devices that blkid reports to contain btrfs are scanned\&. +.sp +The options +\fI\-\-all\-devices\fR +or +\fI\-d\fR +are deprecated and kept for backward compatibility\&. If used, behavior is the same as if no devices are passed\&. +.sp +The command can be run repeatedly\&. Devices that have been already registered remain as such\&. Reloading the kernel module will drop this information\&. There\(cqs an alternative way of mounting multiple\-device filesystem without the need for prior scanning\&. See the mount option +\fIdevice\fR\&. +.RE +.PP +\fBstats\fR [options] \fI<path>\fR|\fI<device>\fR +.RS 4 +Read and print the device IO error statistics for all devices of the given filesystem identified by +\fI<path>\fR +or for a single +\fI<device>\fR\&. The filesystem must be mounted\&. See section +\fBDEVICE STATS\fR +for more information about the reported statistics and the meaning\&. +.sp +\fBOptions\fR +.PP +\-z|\-\-reset +.RS 4 +Print the stats and reset the values to zero afterwards\&. +.RE +.PP +\-c|\-\-check +.RS 4 +Check if the stats are all zeros and return 0 if it is so\&. Set bit 6 of the return code if any of the statistics is no\-zero\&. The error values is 65 if reading stats from at least one device failed, otherwise it\(cqs 64\&. +.RE +.RE +.PP +\fBusage\fR [options] \fI<path>\fR [\fI<path>\fR\&...] +.RS 4 +Show detailed information about internal allocations in devices\&. +.sp +\fBOptions\fR +.PP +\-b|\-\-raw +.RS 4 +raw numbers in bytes, without the +\fIB\fR +suffix +.RE +.PP +\-h|\-\-human\-readable +.RS 4 +print human friendly numbers, base 1024, this is the default +.RE +.PP +\-H +.RS 4 +print human friendly numbers, base 1000 +.RE +.PP +\-\-iec +.RS 4 +select the 1024 base for the following options, according to the IEC standard +.RE +.PP +\-\-si +.RS 4 +select the 1000 base for the following options, according to the SI standard +.RE +.PP +\-k|\-\-kbytes +.RS 4 +show sizes in KiB, or kB with \-\-si +.RE +.PP +\-m|\-\-mbytes +.RS 4 +show sizes in MiB, or MB with \-\-si +.RE +.PP +\-g|\-\-gbytes +.RS 4 +show sizes in GiB, or GB with \-\-si +.RE +.PP +\-t|\-\-tbytes +.RS 4 +show sizes in TiB, or TB with \-\-si +.RE +.RE +.sp +If conflicting options are passed, the last one takes precedence\&. +.SH "TYPICAL USECASES" +.SS "STARTING WITH A SINGLE\-DEVICE FILESYSTEM" +.sp +Assume we\(cqve created a filesystem on a block device \fI/dev/sda\fR with profile \fIsingle/single\fR (data/metadata), the device size is 50GiB and we\(cqve used the whole device for the filesystem\&. The mount point is \fI/mnt\fR\&. +.sp +The amount of data stored is 16GiB, metadata have allocated 2GiB\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBADD NEW DEVICE\fR +.RS 4 +.sp +We want to increase the total size of the filesystem and keep the profiles\&. The size of the new device \fI/dev/sdb\fR is 100GiB\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ btrfs device add /dev/sdb /mnt +.fi +.if n \{\ +.RE +.\} +.sp +The amount of free data space increases by less than 100GiB, some space is allocated for metadata\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCONVERT TO RAID1\fR +.RS 4 +.sp +Now we want to increase the redundancy level of both data and metadata, but we\(cqll do that in steps\&. Note, that the device sizes are not equal and we\(cqll use that to show the capabilities of split data/metadata and independent profiles\&. +.sp +The constraint for RAID1 gives us at most 50GiB of usable space and exactly 2 copies will be stored on the devices\&. +.sp +First we\(cqll convert the metadata\&. As the metadata occupy less than 50GiB and there\(cqs enough workspace for the conversion process, we can do: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ btrfs balance start \-mconvert=raid1 /mnt +.fi +.if n \{\ +.RE +.\} +.sp +This operation can take a while, because all metadata have to be moved and all block pointers updated\&. Depending on the physical locations of the old and new blocks, the disk seeking is the key factor affecting performance\&. +.sp +You\(cqll note that the system block group has been also converted to RAID1, this normally happens as the system block group also holds metadata (the physical to logical mappings)\&. +.sp +What changed: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +available data space decreased by 3GiB, usable roughly (50 \- 3) + (100 \- 3) = 144 GiB +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +metadata redundancy increased +.RE +.sp +IOW, the unequal device sizes allow for combined space for data yet improved redundancy for metadata\&. If we decide to increase redundancy of data as well, we\(cqre going to lose 50GiB of the second device for obvious reasons\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ btrfs balance start \-dconvert=raid1 /mnt +.fi +.if n \{\ +.RE +.\} +.sp +The balance process needs some workspace (ie\&. a free device space without any data or metadata block groups) so the command could fail if there\(cqs too much data or the block groups occupy the whole first device\&. +.sp +The device size of \fI/dev/sdb\fR as seen by the filesystem remains unchanged, but the logical space from 50\-100GiB will be unused\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBREMOVE DEVICE\fR +.RS 4 +.sp +Device removal must satisfy the profile constraints, otherwise the command fails\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ btrfs device remove /dev/sda /mnt +ERROR: error removing device \*(Aq/dev/sda\*(Aq: unable to go below two devices on raid1 +.fi +.if n \{\ +.RE +.\} +.sp +In order to remove a device, you need to convert the profile in this case: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ btrfs balance start \-mconvert=dup \-dconvert=single /mnt +$ btrfs device remove /dev/sda /mnt +.fi +.if n \{\ +.RE +.\} +.RE +.SH "DEVICE STATS" +.sp +The device stats keep persistent record of several error classes related to doing IO\&. The current values are printed at mount time and updated during filesystem lifetime or from a scrub run\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ btrfs device stats /dev/sda3 +[/dev/sda3]\&.write_io_errs 0 +[/dev/sda3]\&.read_io_errs 0 +[/dev/sda3]\&.flush_io_errs 0 +[/dev/sda3]\&.corruption_errs 0 +[/dev/sda3]\&.generation_errs 0 +.fi +.if n \{\ +.RE +.\} +.PP +write_io_errs +.RS 4 +Failed writes to the block devices, means that the layers beneath the filesystem were not able to satisfy the write request\&. +.RE +.PP +read_io_errors +.RS 4 +Read request analogy to write_io_errs\&. +.RE +.PP +flush_io_errs +.RS 4 +Number of failed writes with the +\fIFLUSH\fR +flag set\&. The flushing is a method of forcing a particular order between write requests and is crucial for implementing crash consistency\&. In case of btrfs, all the metadata blocks must be permanently stored on the block device before the superblock is written\&. +.RE +.PP +corruption_errs +.RS 4 +A block checksum mismatched or a corrupted metadata header was found\&. +.RE +.PP +generation_errs +.RS 4 +The block generation does not match the expected value (eg\&. stored in the parent node)\&. +.RE +.SH "EXIT STATUS" +.sp +\fBbtrfs device\fR returns a zero exit status if it succeeds\&. Non zero is returned in case of failure\&. +.sp +If the \fI\-s\fR option is used, \fBbtrfs device stats\fR will add 64 to the exit status if any of the error counters is non\-zero\&. +.SH "AVAILABILITY" +.sp +\fBbtrfs\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 +\fBmkfs\&.btrfs\fR(8), \fBbtrfs\-replace\fR(8), \fBbtrfs\-balance\fR(8) |