|
|
| (One intermediate revision by one user not shown) |
| Line 1: |
Line 1: |
| − | =btrfs-device(8) manual page=
| |
| | {{GeneratedManpage | | {{GeneratedManpage |
| | |name=btrfs-device}} | | |name=btrfs-device}} |
| − |
| |
| − | ==NAME==
| |
| − | btrfs-device - manage devices of btrfs filesystems
| |
| − |
| |
| − | ==SYNOPSIS==
| |
| − |
| |
| − | <p><b>btrfs device</b> <em><subcommand></em> <em><args></em></p>
| |
| − | ==DESCRIPTION==
| |
| − |
| |
| − | <p>The <b>btrfs device</b> command group is used to manage devices of the btrfs filesystems.</p>
| |
| − | ==DEVICE MANAGEMENT==
| |
| − |
| |
| − | <p>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’s 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
| |
| − | [[Manpage/mkfs.btrfs|mkfs.btrfs(8)]] for more details and the exact profile capabilities and
| |
| − | constraints.</p>
| |
| − | <p>The device management works on a mounted filesystem. Devices can be added,
| |
| − | removed or replaced, by commands provided by <b>btrfs device</b> and <b>btrfs replace</b>.</p>
| |
| − | <p>The profiles can be also changed, provided there’s enough workspace to do the
| |
| − | conversion, using the <b>btrfs balance</b> command and namely the filter <em>convert</em>.</p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | Profile
| |
| − | <dd>
| |
| − | <p>
| |
| − | 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.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | RAID level
| |
| − | <dd>
| |
| − | <p>
| |
| − | 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.
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − | <p>See the section <b>TYPICAL USECASES</b> for some examples.</p>
| |
| − | ==SUBCOMMAND==
| |
| − |
| |
| − | <dl>
| |
| − | <dt>
| |
| − | <b>add</b> [-Kf] <em><device></em> [<em><device></em>…] <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Add device(s) to the filesystem identified by <em><path></em>.
| |
| − | </p>
| |
| − | <p>If applicable, a whole device discard (TRIM) operation is performed prior to
| |
| − | adding the device. A device with existing filesystem detected by [http://man7.org/linux/man-pages/man8/blkid.8.html blkid(8)]
| |
| − | will prevent device addition and has to be forced. Alternatively the filesystem
| |
| − | can be wiped from the device using eg. the [http://man7.org/linux/man-pages/man8/wipefs.8.html wipefs(8)] tool.</p>
| |
| − | <p>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.</p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -K|--nodiscard
| |
| − | <dd>
| |
| − | <p>
| |
| − | do not perform discard (TRIM) by default
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -f|--force
| |
| − | <dd>
| |
| − | <p>
| |
| − | force overwrite of existing filesystem on the given disk(s)
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | <b>remove</b> <em><device></em>|<em><devid></em> [<em><device></em>|<em><devid></em>…] <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Remove device(s) from a filesystem identified by <em><path></em>
| |
| − | </p>
| |
| − | <p>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 example section below.</p>
| |
| − | <p>The operation can take long as it needs to move all data from the device.</p>
| |
| − | <p>It is possible to delete the device that was used to mount the filesystem. The
| |
| − | device entry in mount table will be replaced by another device name with the
| |
| − | lowest device id.</p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>delete</b> <em><device></em>|<em><devid></em> [<em><device></em>|<em><devid></em>…] <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Alias of remove kept for backward compatibility
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>ready</b> <em><device></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | 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.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>scan</b> [(--all-devices|-d)|<em><device></em> [<em><device></em>…]]
| |
| − | <dd>
| |
| − | <p>
| |
| − | 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.
| |
| − | </p>
| |
| − | <p>If no devices are passed, all block devices that blkid reports to contain btrfs
| |
| − | are scanned.</p>
| |
| − | <p>The options <em>--all-devices</em> or <em>-d</em> are deprecated and kept for backward compatibility.
| |
| − | If used, behavior is the same as if no devices are passed.</p>
| |
| − | <p>The command can be run repeatedly. Devices that have been already registered
| |
| − | remain as such. Reloading the kernel module will drop this information. There’s
| |
| − | an alternative way of mounting multiple-device filesystem without the need for
| |
| − | prior scanning. See the mount option <em>device</em>.</p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>stats</b> [options] <em><path></em>|<em><device></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Read and print the device IO error statistics for all devices of the given
| |
| − | filesystem identified by <em><path></em> or for a single <em><device></em>. The filesystem must
| |
| − | be mounted. See section <b>DEVICE STATS</b> for more information about the reported
| |
| − | statistics and the meaning.
| |
| − | </p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -z|--reset
| |
| − | <dd>
| |
| − | <p>
| |
| − | Print the stats and reset the values to zero afterwards.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -c|--check
| |
| − | <dd>
| |
| − | <p>
| |
| − | Check if the stats are all zeros and return 0 it 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’s 64.
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | <b>usage</b> [options] <em><path></em> [<em><path></em>…]
| |
| − | <dd>
| |
| − | <p>
| |
| − | Show detailed information about internal allocations in devices.
| |
| − | </p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -b|--raw
| |
| − | <dd>
| |
| − | <p>
| |
| − | raw numbers in bytes, without the <em>B</em> suffix
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -h|--human-readable
| |
| − | <dd>
| |
| − | <p>
| |
| − | print human friendly numbers, base 1024, this is the default
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -H
| |
| − | <dd>
| |
| − | <p>
| |
| − | print human friendly numbers, base 1000
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | --iec
| |
| − | <dd>
| |
| − | <p>
| |
| − | select the 1024 base for the following options, according to the IEC standard
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | --si
| |
| − | <dd>
| |
| − | <p>
| |
| − | select the 1000 base for the following options, according to the SI standard
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -k|--kbytes
| |
| − | <dd>
| |
| − | <p>
| |
| − | show sizes in KiB, or kB with --si
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -m|--mbytes
| |
| − | <dd>
| |
| − | <p>
| |
| − | show sizes in MiB, or MB with --si
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -g|--gbytes
| |
| − | <dd>
| |
| − | <p>
| |
| − | show sizes in GiB, or GB with --si
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -t|--tbytes
| |
| − | <dd>
| |
| − | <p>
| |
| − | show sizes in TiB, or TB with --si
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | </dl>
| |
| − | <p>If conflicting options are passed, the last one takes precedence.</p>
| |
| − | ==TYPICAL USECASES==
| |
| − |
| |
| − | ===STARTING WITH A SINGLE-DEVICE FILESYSTEM===
| |
| − |
| |
| − | <p>Assume we’ve created a filesystem on a block device <em>/dev/sda</em> with profile
| |
| − | <em>single/single</em> (data/metadata), the device size is 50GiB and we’ve used the
| |
| − | whole device for the filesystem. The mount point is <em>/mnt</em>.</p>
| |
| − | <p>The amount of data stored is 16GiB, metadata have allocated 2GiB.</p>
| |
| − | ====ADD NEW DEVICE====
| |
| − |
| |
| − | <p>We want to increase the total size of the filesystem and keep the profiles. The
| |
| − | size of the new device <em>/dev/sdb</em> is 100GiB.</p>
| |
| − | <pre>$ btrfs device add /dev/sdb /mnt</pre>
| |
| − | <p>The amount of free data space increases by less than 100GiB, some space is
| |
| − | allocated for metadata.</p>
| |
| − | ====CONVERT TO RAID1====
| |
| − |
| |
| − | <p>Now we want to increase the redundancy level of both data and metadata, but
| |
| − | we’ll do that in steps. Note, that the device sizes are not equal and we’ll use
| |
| − | that to show the capabilities of split data/metadata and independent profiles.</p>
| |
| − | <p>The constraint for RAID1 gives us at most 50GiB of usable space and exactly 2
| |
| − | copies will be stored on the devices.</p>
| |
| − | <p>First we’ll convert the metadata. As the metadata occupy less than 50GiB and
| |
| − | there’s enough workspace for the conversion process, we can do:</p>
| |
| − | <pre>$ btrfs balance start -mconvert=raid1 /mnt</pre>
| |
| − | <p>This operation can take a while as the 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.</p>
| |
| − | <p>You’ll 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).</p>
| |
| − | <p>What changed:</p>
| |
| − | <ul>
| |
| − | <li>
| |
| − | <p>
| |
| − | available data space decreased by 3GiB, usable roughly (50 - 3) + (100 - 3) = 144 GiB
| |
| − | </p>
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>
| |
| − | metadata redundancy increased
| |
| − | </p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>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’re going to lose 50GiB of the second device for obvious reasons.</p>
| |
| − | <pre>$ btrfs balance start -dconvert=raid1 /mnt</pre>
| |
| − | <p>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’s too much
| |
| − | data or the block groups occupy the whole first device.</p>
| |
| − | <p>The device size of <em>/dev/sdb</em> as seen by the filesystem remains unchanged, but
| |
| − | the logical space from 50-100GiB will be unused.</p>
| |
| − | ==DEVICE STATS==
| |
| − |
| |
| − | <p>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.</p>
| |
| − | <pre>$ 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</pre>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | write_io_errs
| |
| − | <dd>
| |
| − | <p>
| |
| − | Failed writes to the block devices, means that the layers beneath the
| |
| − | filesystem were not able to satisfy the write request.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | read_io_errors
| |
| − | <dd>
| |
| − | <p>
| |
| − | Read request analogy to write_io_errs.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | flush_io_errs
| |
| − | <dd>
| |
| − | <p>
| |
| − | Number of failed writes with the <em>FLUSH</em> 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.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | corruption_errs
| |
| − | <dd>
| |
| − | <p>
| |
| − | A block checksum mismatched or a corrupted metadata header was found.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | generation_errs
| |
| − | <dd>
| |
| − | <p>
| |
| − | The block generation does not match the expected value (eg. stored in the
| |
| − | parent node).
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − | ==EXIT STATUS==
| |
| − |
| |
| − | <p><b>btrfs device</b> returns a zero exit status if it succeeds. Non zero is
| |
| − | returned in case of failure.</p>
| |
| − | <p>If the <em>-s</em> option is used, <b>btrfs device stats</b> will add 64 to the
| |
| − | exit status if any of the error counters is non-zero.</p>
| |
| − | ==AVAILABILITY==
| |
| − |
| |
| − | <p><b>btrfs</b> is part of btrfs-progs.
| |
| − | Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
| |
| − | further details.</p>
| |
| − | ==SEE ALSO==
| |
| − |
| |
| − | <p>[[Manpage/mkfs.btrfs|mkfs.btrfs(8)]],
| |
| − | [[Manpage/btrfs-replace|btrfs-replace(8)]],
| |
| − | [[Manpage/btrfs-balance|btrfs-balance(8)]]</p>
| |
| − | [[Category:Manpage]]
| |
