btrfs-progs/Documentation/btrfs-device.txt

btrfs-device(8)
===============

NAME
----
btrfs-device - control btrfs devices

SYNOPSIS
--------
*btrfs device* <subcommand> <args>

DESCRIPTION
-----------
*btrfs device* is used to control the btrfs devices, since btrfs can be used
across several devices, *btrfs device* is used for multiple device management.

DEVICE MANAGEMENT
-----------------
Btrfs filesystem is capable to manage multiple devices.

Btrfs filesystem uses different profiles to manage different RAID level, and
use balance to rebuild chunks, also devices can be added/removed/replace
online.

Profile::
Btrfs filesystem uses data/metadata profiles to manage allocation/duplication
mechanism. +
Profiles like RAID level can be assigned to data and metadata separately.
+
See `mkfs.btrfs`(8) for more details.

RAID level::
Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10. +
RAID levels can be assigned at mkfs time or online.
+
See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for
online RAID level assign.
+
NOTE: Since btrfs is under heavy development especially the RAID5/6 support,
it is *highly* recommended to read the follow btrfs wiki page to get more
updated details on RAID5/6: +
https://btrfs.wiki.kernel.org/index.php/RAID56

Balance::
`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the
desired profile.
+
Due to the fact that balance can rebuild/recovery chunks according to its RAID
duplication if possible, so when using RAID1/5/6/10 with some devices failed
and you just added a new device to btrfs using `btrfs-device`(8), you should
run `btrfs-balance`(8) to rebuild the chunks.
+
See `btrfs-balance`(8) for more details.

Device add/remove/replace::
Device can be added/removed using `btrfs-replace`(8) subcommand and replaced
using `btrfs-replace`(8).
+
When device is removed or replaced, btrfs will do the chunk rebuild if needed.
+
See `btrfs-replace`(8) and this man page for more details.

SUBCOMMAND
----------
*add* [-Kf] <dev> [<dev>...] <path>::
Add device(s) to the filesystem identified by <path>.
+
If applicable, a whole device discard (TRIM) operation is performed.
+
`Options`
+
-K|--nodiscard::::
do not perform discard by default
-f|--force::::
force overwrite of existing filesystem on the given disk(s)

*delete* <dev> [<dev>...] <path>::
Remove device(s) from a filesystem identified by <path>.

*scan* [(--all-devices|-d)|<device> [<device>...]]::
Scan devices for a btrfs filesystem.
+
If one or more devices are passed, these are scanned for a btrfs filesystem. 
If no devices are passed, btrfs uses block devices containing btrfs
filesystem as listed by blkid.
Finally, if '--all-devices' or '-d' is passed, all the devices under /dev are 
scanned.

*ready* <device>::
Check device to see if it has all of it's devices in cache for mounting.

*stats* [-z] <path>|<device>::
Read and print the device IO stats for all devices of the filesystem
identified by <path> or for a single <device>.
+
`Options`
+
-z::::
Reset stats to zero after reading them.

*usage* [options] <path> [<path>...]::
Show detailed information about internal allocations in devices.
+
`Options`
+
-b|--raw::::
raw numbers in bytes, without the 'B' suffix
-h::::
print human friendly numbers, base 1024, this is the default
-H::::
print human friendly numbers, base 1000
--iec::::
select the 1024 base for the following options, according to the IEC standard
--si::::
select the 1000 base for the following options, according to the SI standard
-k|--kbytes::::
show sizes in KiB, or kB with --si
-m|--mbytes::::
show sizes in MiB, or MB with --si
-g|--gbytes::::
show sizes in GiB, or GB with --si
-t|--tbytes::::
show sizes in TiB, or TB with --si

If conflicting options are passed, the last one takes precedence.

EXIT STATUS
-----------
*btrfs device* returns a zero exit status if it succeeds. Non zero is
returned in case of failure.

AVAILABILITY
------------
*btrfs* is part of btrfs-progs.
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
further details.

SEE ALSO
--------
`mkfs.btrfs`(8),
`btrfs-replace`(8),
`btrfs-balance`(8)