Documentation/btrfs-device.asciidoc

   1 btrfs-device(8)
   2 ===============
   3
   4 NAME
   5 ----
   6 btrfs-device - control btrfs devices
   7
   8 SYNOPSIS
   9 --------
  10 *btrfs device* <subcommand> <args>
  11
  12 DESCRIPTION
  13 -----------
  14 *btrfs device* is used to control the btrfs devices, since btrfs can be used
  15 across several devices, *btrfs device* is used for multiple device management.
  16
  17 DEVICE MANAGEMENT
  18 -----------------
  19 Btrfs filesystem is capable to manage multiple devices.
  20
  21 Btrfs filesystem uses different profiles to manage different RAID level, and
  22 use balance to rebuild chunks, also devices can be added/removed/replace
  23 online.
  24
  25 Profile::
  26 Btrfs filesystem uses data/metadata profiles to manage allocation/duplication
  27 mechanism. +
  28 Profiles like RAID level can be assigned to data and metadata separately.
  29 +
  30 See `mkfs.btrfs`(8) for more details.
  31
  32 RAID level::
  33 Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10. +
  34 RAID levels can be assigned at mkfs time or online.
  35 +
  36 See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for
  37 online RAID level assign.
  38 +
  39 NOTE: Since btrfs is under heavy development especially the RAID5/6 support,
  40 it is *highly* recommended to read the follow btrfs wiki page to get more
  41 updated details on RAID5/6: +
  42 https://btrfs.wiki.kernel.org/index.php/RAID56
  43
  44 Balance::
  45 `btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the
  46 desired profile.
  47 +
  48 Due to the fact that balance can rebuild/recovery chunks according to its RAID
  49 duplication if possible, so when using RAID1/5/6/10 with some devices failed
  50 and you just added a new device to btrfs using `btrfs-device`(8), you should
  51 run `btrfs-balance`(8) to rebuild the chunks.
  52 +
  53 See `btrfs-balance`(8) for more details.
  54
  55 Device add/remove/replace::
  56 Device can be added/removed using `btrfs-device`(8) subcommand and replaced
  57 using `btrfs-replace`(8).
  58 +
  59 When device is removed or replaced, btrfs will do the chunk rebuild if needed.
  60 +
  61 See `btrfs-replace`(8) man page for more details on device replace.
  62
  63 SUBCOMMAND
  64 ----------
  65 *add* [-Kf] <dev> [<dev>...] <path>::
  66 Add device(s) to the filesystem identified by <path>.
  67 +
  68 If applicable, a whole device discard (TRIM) operation is performed.
  69 +
  70 `Options`
  71 +
  72 -K|--nodiscard::::
  73 do not perform discard by default
  74 -f|--force::::
  75 force overwrite of existing filesystem on the given disk(s)
  76
  77 *remove* <dev> [<dev>...] <path>::
  78 Remove device(s) from a filesystem identified by <path>.
  79
  80 *delete* <dev> [<dev>...] <path>::
  81 Alias of remove kept for backwards compatability
  82
  83 *ready* <device>::
  84 Check device to see if it has all of it's devices in cache for mounting.
  85
  86 *scan* [(--all-devices|-d)|<device> [<device>...]]::
  87 Scan devices for a btrfs filesystem.
  88 +
  89 If one or more devices are passed, these are scanned for a btrfs filesystem.
  90 If no devices are passed, btrfs uses block devices containing btrfs
  91 filesystem as listed by blkid.
  92 Finally, if '--all-devices' or '-d' is passed, all the devices under /dev are
  93 scanned.
  94
  95 *stats* [-z] <path>|<device>::
  96 Read and print the device IO stats for all mounted devices of the filesystem
  97 identified by <path> or for a single <device>.
  98 +
  99 `Options`
 100 +
 101 -z::::
 102 Reset stats to zero after reading them.
 103
 104 *usage* [options] <path> [<path>...]::
 105 Show detailed information about internal allocations in devices.
 106 +
 107 `Options`
 108 +
 109 -b|--raw::::
 110 raw numbers in bytes, without the 'B' suffix
 111 -h|--human-readable::::
 112 print human friendly numbers, base 1024, this is the default
 113 -H::::
 114 print human friendly numbers, base 1000
 115 --iec::::
 116 select the 1024 base for the following options, according to the IEC standard
 117 --si::::
 118 select the 1000 base for the following options, according to the SI standard
 119 -k|--kbytes::::
 120 show sizes in KiB, or kB with --si
 121 -m|--mbytes::::
 122 show sizes in MiB, or MB with --si
 123 -g|--gbytes::::
 124 show sizes in GiB, or GB with --si
 125 -t|--tbytes::::
 126 show sizes in TiB, or TB with --si
 127
 128 If conflicting options are passed, the last one takes precedence.
 129
 130 EXIT STATUS
 131 -----------
 132 *btrfs device* returns a zero exit status if it succeeds. Non zero is
 133 returned in case of failure.
 134
 135 AVAILABILITY
 136 ------------
 137 *btrfs* is part of btrfs-progs.
 138 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 139 further details.
 140
 141 SEE ALSO
 142 --------
 143 `mkfs.btrfs`(8),
 144 `btrfs-replace`(8),
 145 `btrfs-balance`(8)