summaryrefslogtreecommitdiff
path: root/Documentation/btrfs-device.asciidoc
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/btrfs-device.asciidoc')
-rw-r--r--Documentation/btrfs-device.asciidoc142
1 files changed, 142 insertions, 0 deletions
diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc
new file mode 100644
index 00000000..075ccc5a
--- /dev/null
+++ b/Documentation/btrfs-device.asciidoc
@@ -0,0 +1,142 @@
+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>.
+
+*ready* <device>::
+Check device to see if it has all of it's devices in cache for mounting.
+
+*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.
+
+*stats* [-z] <path>|<device>::
+Read and print the device IO stats for all mounted 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|--human-readable::::
+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)