Documentation/mkfs.btrfs.asciidoc

   1 mkfs.btrfs(8)
   2 =============
   3
   4 NAME
   5 ----
   6 mkfs.btrfs - create a btrfs filesystem
   7
   8 SYNOPSIS
   9 --------
  10 *mkfs.btrfs*
  11 $$[-A|--alloc-start <alloc-start>]$$
  12 $$[-b|--byte-count <byte-count>]$$
  13 $$[-d|--data <data-profile>]$$
  14 $$[-f|--force]$$
  15 $$[-n|--nodesize <nodesize>]$$
  16 $$[-l|--leafsize <leafsize>]$$
  17 $$[-L|--label <label>]$$
  18 $$[-m|--metadata <metadata profile>]$$
  19 $$[-M|--mixed]$$
  20 $$[-q|--quiet]$$
  21 $$[-s|--sectorsize <sectorsize>]$$
  22 $$[-r|--rootdir <rootdir>]$$
  23 $$[-K|--nodiscard]$$
  24 $$[-O|--features <feature1>[,<feature2>...]]$$
  25 $$[-U|--uuid <UUID>]$$
  26 $$[-h]$$
  27 $$[-V|--version]$$
  28 $$<device> [<device>...]$$
  29
  30 DESCRIPTION
  31 -----------
  32 *mkfs.btrfs*
  33 is used to create a btrfs filesystem (usually in a disk partition, or an array
  34 of disk partitions).
  35
  36 <device>
  37 is the special file corresponding to the device (e.g /dev/sdXX ).
  38 If multiple devices are specified, btrfs is created
  39 spanning across the specified  devices.
  40
  41 OPTIONS
  42 -------
  43 -A|--alloc-start <offset>::
  44 Specify the offset from the start of the device at which to start allocations
  45 in this btrfs filesystem. The default value is zero, or the start of the
  46 device.  This option is intended only for debugging filesystem resize
  47 operations.
  48
  49 -b|--byte-count <size>::
  50 Specify the size of the resultant filesystem. If this option is not used,
  51 mkfs.btrfs uses all the available storage for the filesystem.
  52
  53 -d|--data <type>::
  54 Specify how the data must be spanned across the devices specified. Valid
  55 values are 'raid0', 'raid1', 'raid5', 'raid6', 'raid10' or 'single'.
  56
  57 -f|--force::
  58 Force overwrite when an existing filesystem is detected on the device.
  59 By default, mkfs.btrfs will not write to the device if it suspects that
  60 there is a filesystem or partition table on the device already.
  61
  62 -l|--leafsize <size>::
  63 Alias for --nodesize. Deprecated.
  64
  65 -n|--nodesize <size>::
  66 Specify the nodesize, the tree block size in which btrfs stores
  67 data. The default value is 16KB (16384) or the page size, whichever is
  68 bigger. Must be a multiple of the sectorsize, but not larger than 65536.
  69 Leafsize always equals nodesize and the options are aliases.
  70
  71 -L|--label <name>::
  72 Specify a label for the filesystem.
  73 +
  74 NOTE: <name> should be less than 256 characters.
  75
  76 -m|--metadata <profile>::
  77 Specify how metadata must be spanned across the devices specified. Valid
  78 values are 'raid0', 'raid1', 'raid5', 'raid6', 'raid10', 'single' or 'dup'.
  79 +
  80 Single device
  81 will have dup set by default except in the case of SSDs which will default to
  82 single. This is because SSDs can remap blocks internally so duplicate blocks
  83 could end up in the same erase block which negates the benefits of doing
  84 metadata duplication.
  85
  86 -M|--mixed::
  87 Mix data and metadata chunks together for more efficient space
  88 utilization.  This feature incurs a performance penalty in
  89 larger filesystems.  It is recommended for use with filesystems
  90 of 1 GiB or smaller.
  91
  92 -q|--quiet::
  93 Print only error or warning messages. Options --features or --help are unaffected.
  94
  95 -s|--sectorsize <size>::
  96 Specify the sectorsize, the minimum data block allocation unit.
  97 +
  98 The default
  99 value is the page size. If the sectorsize differs from the page size, the
 100 created filesystem may not be mountable by current kernel. Therefore it is not
 101 recommended to use this option unless you are going to mount it on a system
 102 with the appropriate page size.
 103
 104 -r|--rootdir <rootdir>::
 105 Specify a directory to copy into the newly created btrfs filesystem.
 106 +
 107 NOTE: '-r' option is done completely in userland, and don't need root
 108 privilege to mount the filesystem.
 109
 110 -K|--nodiscard::
 111 Do not perform whole device TRIM operation by default.
 112
 113 -O|--features <feature1>[,<feature2>...]::
 114 A list of filesystem features turned on at mkfs time. Not all features are
 115 supported by old kernels. To disable a feature, prefix it with '^'.
 116 +
 117 To see all features run:
 118 +
 119 +mkfs.btrfs -O list-all+
 120
 121 -U|--uuid <UUID>::
 122 Create the filesystem with the specified UUID, which must not already exist on
 123 the system.
 124
 125 -V|--version::
 126 Print the *mkfs.btrfs* version and exit.
 127
 128 -h::
 129 Print help.
 130
 131 UNIT
 132 ----
 133 As default the unit is the byte, however it is possible to append a suffix
 134 to the arguments like 'k' for KBytes, 'm' for MBytes...
 135
 136 AVAILABILITY
 137 ------------
 138 *btrfs* is part of btrfs-progs.
 139 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 140 further details.
 141
 142 SEE ALSO
 143 --------
 144 `btrfs`(8)