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 NOTES
 137 -----
 138 Since mixed block group creation is optional, we allow small
 139 filesystem instances with differing values for sectorsize and nodesize
 140 to be created and could end up in the following situation,
 141
 142   [root@localhost ~]# mkfs.btrfs -f -n 65536 /dev/loop0
 143   btrfs-progs v3.19-rc2-405-g976307c
 144   See http://btrfs.wiki.kernel.org for more information.
 145
 146   Performing full device TRIM (512.00MiB) ...
 147   Label:              (null)
 148   UUID:               49fab72e-0c8b-466b-a3ca-d1bfe56475f0
 149   Node size:          65536
 150   Sector size:        4096
 151   Filesystem size:    512.00MiB
 152   Block group profiles:
 153     Data:             single            8.00MiB
 154     Metadata:         DUP              40.00MiB
 155     System:           DUP              12.00MiB
 156   SSD detected:       no
 157   Incompat features:  extref, skinny-metadata
 158   Number of devices:  1
 159   Devices:
 160     ID        SIZE  PATH
 161      1   512.00MiB  /dev/loop0
 162   [root@localhost ~]# mount /dev/loop0 /mnt/
 163   mount: mount /dev/loop0 on /mnt failed: No space left on device
 164
 165 The ENOSPC occurs during the creation of the UUID tree. This is
 166 because of things like large metadata block size, DUP mode used for
 167 metadata and global reservation consuming space.
 168
 169 AVAILABILITY
 170 ------------
 171 *mkfs.btrfs* is part of btrfs-progs.
 172 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 173 further details.
 174
 175 SEE ALSO
 176 --------
 177 `btrfs`(8)