man/btrfs.8.in

   1 .TH BTRFS 8 "" "btrfs" "btrfs"
   2 .\"
   3 .\" Man page written by Goffredo Baroncelli <kreijack@inwind.it> (Feb 2010)
   4 .\"
   5 .SH NAME
   6 btrfs \- control a btrfs filesystem
   7 .SH SYNOPSIS
   8 \fBbtrfs\fP \fBsubvolume snapshot\fP\fI [-r] <source> [<dest>/]<name>\fP
   9 .PP
  10 \fBbtrfs\fP \fBsubvolume delete\fP\fI <subvolume>\fP
  11 .PP
  12 \fBbtrfs\fP \fBsubvolume create\fP\fI [<dest>/]<name>\fP
  13 .PP
  14 \fBbtrfs\fP \fBsubvolume list\fP\fI [-p] <path>\fP
  15 .PP
  16 \fBbtrfs\fP \fBsubvolume set-default\fP\fI <id> <path>\fP
  17 .PP
  18 \fBbtrfs\fP \fBsubvolume get-default\fP\fI <path>\fP
  19 .PP
  20 \fBbtrfs\fP \fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] \
  21 [-s \fIstart\fR] [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> \
  22 [<\fIfile\fR>|<\fIdir\fR>...]
  23 .PP
  24 \fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP
  25 .PP
  26 \fBbtrfs\fP \fBfilesystem resize\fP\fI [devid:][+/\-]<size>[gkm]|[devid:]max <filesystem>\fP
  27 .PP
  28 \fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP
  29 .PP
  30 \fBbtrfs\fP \fBsubvolume find-new\fP\fI <subvolume> <last_gen>\fP
  31 .PP
  32 \fBbtrfs\fP \fBfilesystem balance\fP\fI <path> \fP
  33 .PP
  34 \fBbtrfs\fP \fBdevice scan\fP\fI [--all-devices|<device> [<device>...]]\fP
  35 .PP
  36 \fBbtrfs\fP \fBdevice show\fP\fI [--all-devices|<uuid>|<label>]\fP
  37 .PP
  38 \fBbtrfs\fP \fBdevice add\fP\fI <device> [<device>...] <path> \fP
  39 .PP
  40 \fBbtrfs\fP \fBdevice delete\fP\fI <device> [<device>...] <path> \fP
  41 .PP
  42 \fBbtrfs\fP \fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
  43 .PP
  44 \fBbtrfs\fP \fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP}
  45 .PP
  46 \fBbtrfs\fP \fBscrub resume\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
  47 .PP
  48 \fBbtrfs\fP \fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP}
  49 .PP
  50 \fBbtrfs\fP \fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP
  51 .PP
  52 \fBbtrfs\fP \fBinspect-internal logical-resolve\fP
  53 [-Pv] \fI<logical>\fP \fI<path>\fP
  54 .PP
  55 \fBbtrfs\fP \fBhelp|\-\-help|\-h \fP\fI\fP
  56 .PP
  57 \fBbtrfs\fP \fB<command> \-\-help \fP\fI\fP
  58 .PP
  59 .SH DESCRIPTION
  60 .B btrfs
  61 is used to control the filesystem and the files and directories stored. It is
  62 the tool to create or destroy a snapshot or a subvolume for the
  63 filesystem, to defrag a file or a directory, flush the data to the disk,
  64 to resize the filesystem, to scan the device.
  65
  66 It is possible to abbreviate the commands unless the commands  are ambiguous.
  67 For example: it is possible to run
  68 .I btrfs sub snaps
  69 instead of
  70 .I btrfs subvolume snapshot.
  71 But
  72 .I btrfs file s
  73 is not allowed, because
  74 .I file s
  75 may be interpreted both as
  76 .I filesystem show
  77 and as
  78 .I filesystem sync.
  79 In this case
  80 .I btrfs
  81 returns filesystem sync
  82 If a command is terminated by
  83 .I --help
  84 , the detailed help is showed. If the passed command matches more commands,
  85 detailed help of all the matched commands is showed. For example
  86 .I btrfs dev --help
  87 shows the help of all
  88 .I device*
  89 commands.
  90
  91 .SH COMMANDS
  92 .TP
  93
  94 \fBsubvolume snapshot\fR\fI [-r] <source> [<dest>/]<name>\fR
  95 Create a writable/readonly snapshot of the subvolume \fI<source>\fR with the
  96 name \fI<name>\fR in the \fI<dest>\fR directory. If \fI<source>\fR is not a
  97 subvolume, \fBbtrfs\fR returns an error. If \fI-r\fR is given, the snapshot
  98 will be readonly.
  99 .TP
 100
 101 \fBsubvolume delete\fR\fI <subvolume>\fR
 102 Delete the subvolume \fI<subvolume>\fR. If \fI<subvolume>\fR is not a
 103 subvolume, \fBbtrfs\fR returns an error.
 104 .TP
 105
 106 \fBsubvolume create\fR\fI [<dest>/]<name>\fR
 107 Create a subvolume in \fI<dest>\fR (or in the current directory if
 108 \fI<dest>\fR is omitted).
 109 .TP
 110
 111 \fBsubvolume list\fR\fI [-p] <path>\fR
 112 List the subvolumes present in the filesystem \fI<path>\fR. For every
 113 subvolume the following information is shown by default.
 114 ID <ID> top level <ID> path <path>
 115 where path is the relative path of the subvolume to the \fItop level\fR
 116 subvolume.
 117 The subvolume's ID may be used by the \fBsubvolume set-default\fR command, or
 118 at mount time via the \fIsubvol=\fR option.
 119 If \fI-p\fR is given, then \fIparent <ID>\fR is added to the output between ID
 120 and top level. The parent's ID may be used at mount time via the
 121 \fIsubvolrootid=\fR option.
 122 .TP
 123
 124 \fBsubvolume set-default\fR\fI <id> <path>\fR
 125 Set the subvolume of the filesystem \fI<path>\fR which is mounted as
 126 \fIdefault\fR. The subvolume is identified by \fI<id>\fR, which
 127 is returned by the \fBsubvolume list\fR command.
 128 .TP
 129
 130 \fBsubvolume get-default\fR\fI <path>\fR
 131 Get the default subvolume of the filesystem \fI<path>\fR. The output format
 132 is similar to \fBsubvolume list\fR command.
 133 .TP
 134
 135 \fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] [-s \fIstart\fR] \
 136 [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> [<\fIfile\fR>|<\fIdir\fR>...]
 137
 138 Defragment file data and/or directory metadata. To defragment all files in a
 139 directory you have to specify each one on its own or use your shell wildcards.
 140
 141 The start position and the number of bytes to defragment can be specified by
 142 \fIstart\fR and \fIlen\fR. Any extent bigger than threshold will be
 143 considered already defragged. Use 0 to take the kernel default, and use 1 to
 144 say every single extent must be rewritten. You can also turn on compression in
 145 defragment operations.
 146
 147 \fB-v\fP be verbose
 148
 149 \fB-c\fP compress file contents while defragmenting
 150
 151 \fB-f\fP flush filesystem after defragmenting
 152
 153 \fB-s start\fP defragment only from byte \fIstart\fR onward
 154
 155 \fB-l len\fP defragment only up to \fIlen\fR bytes
 156
 157 \fB-t size\fP defragment only files at least \fIsize\fR bytes big
 158
 159 NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data,
 160 don't use it if you use snapshots, have de-duplicated your data or made
 161 copies with \fBcp --reflink\fP.
 162 .TP
 163
 164 \fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR
 165 List the recently modified files in a subvolume, after \fI<last_gen>\fR ID.
 166 .TP
 167
 168 \fBfilesystem sync\fR\fI <path> \fR
 169 Force a sync for the filesystem identified by \fI<path>\fR.
 170 .TP
 171
 172 .\"
 173 .\" Some wording are extracted by the resize2fs man page
 174 .\"
 175
 176 \fBfilesystem resize\fR\fI [devid:][+/\-]<size>[gkm]|[devid:]max <path>\fR
 177 Resize a filesystem identified by \fI<path>\fR for the underlying device
 178 \fIdevid\fR.  The \fIdevid\fR can be found with \fBbtrfs filesystem show\fR and
 179 defaults to 1 if not specified.
 180 The \fI<size>\fR parameter specifies the new size of the filesystem.
 181 If the prefix \fI+\fR or \fI\-\fR is present the size is increased or decreased
 182 by the quantity \fI<size>\fR.
 183 If no units are specified, the unit of the \fI<size>\fR parameter defaults to
 184 bytes. Optionally, the size parameter may be suffixed by one of the following
 185 units designators: 'K', 'M', or 'G', kilobytes, megabytes, or gigabytes,
 186 respectively.
 187
 188 If 'max' is passed, the filesystem will occupy all available space on the
 189 device \fIdevid\fR.
 190
 191 The \fBresize\fR command \fBdoes not\fR manipulate the size of underlying
 192 partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
 193 can expand the partition before enlarging the filesystem and shrink the
 194 partition after reducing the size of the filesystem.  This can done using
 195 \fBfdisk(8)\fR or \fBparted(8)\fR to delete the existing partition and recreate
 196 it with the new desired size.  When recreating the partition make sure to use
 197 the same starting disk cylinder as before.
 198 .TP
 199
 200 \fBfilesystem label\fP\fI <dev> [newlabel]\fP
 201 Show or update the label of a filesystem. \fI<dev>\fR is used to identify the
 202 filesystem.
 203 If a \fInewlabel\fR optional argument is passed, the label is changed. The
 204 following constraints exist for a label:
 205 .IP
 206 - the maximum allowable length shall be less or equal than 256 chars
 207 .IP
 208 - the label shall not  contain the '/' or '\\' characters.
 209
 210 NOTE: Currently there are the following limitations:
 211 .IP
 212 - the filesystem has to be unmounted
 213 .IP
 214 - the filesystem should not have more than one device.
 215 .TP
 216
 217 \fBfilesystem show\fR [--all-devices|<uuid>|<label>]\fR
 218 Show the btrfs filesystem with some additional info. If no \fIUUID\fP or
 219 \fIlabel\fP is passed, \fBbtrfs\fR show info of all the btrfs filesystem.
 220 If \fB--all-devices\fP is passed, all the devices under /dev are scanned;
 221 otherwise the devices list is extracted from the /proc/partitions file.
 222 .TP
 223
 224 \fBfilesystem balance\fR \fI<path>\fR
 225 Balance the chunks of the filesystem identified by \fI<path>\fR
 226 across the devices.
 227 .TP
 228
 229 \fBdevice add\fR\fI <dev> [<dev>..] <path>\fR
 230 Add device(s) to the filesystem identified by \fI<path>\fR.
 231 .TP
 232
 233 \fBdevice delete\fR\fI <dev> [<dev>..] <path>\fR
 234 Remove device(s) from a filesystem identified by \fI<path>\fR.
 235 .TP
 236
 237 \fBdevice scan\fR \fI[--all-devices|<device> [<device>...]\fR
 238 If one or more devices are passed, these are scanned for a btrfs filesystem.
 239 If no devices are passed, \fBbtrfs\fR scans all the block devices listed
 240 in the /proc/partitions file.
 241 Finally, if \fB--all-devices\fP is passed, all the devices under /dev are
 242 scanned.
 243 .TP
 244
 245 \fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
 246 Start a scrub on all devices of the filesystem identified by \fI<path>\fR or on
 247 a single \fI<device>\fR. Without options, scrub is started as a background
 248 process. Progress can be obtained with the \fBscrub status\fR command. Scrubbing
 249 involves reading all data from all disks and verifying checksums. Errors are
 250 corrected along the way if possible.
 251 .RS
 252
 253 \fIOptions\fR
 254 .IP -B 5
 255 Do not background and print scrub statistics when finished.
 256 .IP -d 5
 257 Print separate statistics for each device of the filesystem (-B only).
 258 .IP -q 5
 259 Quiet. Omit error messages and statistics.
 260 .IP -r 5
 261 Read only mode. Do not attempt to correct anything.
 262 .IP -u 5
 263 Scrub unused space as well. (NOT IMPLEMENTED)
 264 .RE
 265 .TP
 266
 267 \fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP}
 268 If a scrub is running on the filesystem identified by \fI<path>\fR, cancel it.
 269 Progress is saved in the scrub progress file and scrubbing can be resumed later
 270 using the \fBscrub resume\fR command.
 271 If a \fI<device>\fR is given, the corresponding filesystem is found and
 272 \fBscrub cancel\fP behaves as if it was called on that filesystem.
 273 .TP
 274
 275 \fBscrub resume\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
 276 Resume a canceled or interrupted scrub cycle on the filesystem identified by
 277 \fI<path>\fR or on a given \fI<device>\fR. Does not start a new scrub if the
 278 last scrub finished successfully.
 279 .RS
 280
 281 \fIOptions\fR
 282 .TP
 283 see \fBscrub start\fP.
 284 .RE
 285 .TP
 286
 287 \fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP}
 288 Show status of a running scrub for the filesystem identified by \fI<path>\fR or
 289 for the specified \fI<device>\fR.
 290 If no scrub is running, show statistics of the last finished or canceled scrub
 291 for that filesystem or device.
 292 .RS
 293
 294 \fIOptions\fR
 295 .IP -d 5
 296 Print separate statistics for each device of the filesystem.
 297 .RE
 298 .TP
 299
 300 \fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP
 301 Resolves an <inode> in subvolume <path> to all filesystem paths.
 302 .RS
 303
 304 \fIOptions\fR
 305 .IP -v 5
 306 verbose mode. print count of returned paths and ioctl() return value
 307 .RE
 308 .TP
 309
 310 \fBinspect-internal logical-resolve\fP [-Pv] \fI<logical>\fP \fI<path>\fP
 311 Resolves a <logical> address in the filesystem mounted at <path> to all inodes.
 312 By default, each inode is then resolved to a file system path (similar to the
 313 \fBinode-resolve\fP subcommand).
 314 .RS
 315
 316 \fIOptions\fR
 317 .IP -P 5
 318 skip the path resolving and print the inodes instead
 319 .IP -v 5
 320 verbose mode. print count of returned paths and all ioctl() return values
 321 .RE
 322
 323 .SH EXIT STATUS
 324 \fBbtrfs\fR returns a zero exist status if it succeeds. Non zero is returned in
 325 case of failure.
 326
 327 .SH AVAILABILITY
 328 .B btrfs
 329 is part of btrfs-progs. Btrfs filesystem is currently under heavy development,
 330 and not suitable for any uses other than benchmarking and review.
 331 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 332 further details.
 333 .SH SEE ALSO
 334 .BR mkfs.btrfs (8)