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> [<subvolume>...]\fP
  11 .PP
  12 \fBbtrfs\fP \fBsubvolume create\fP\fI [<dest>/]<name>\fP
  13 .PP
  14 \fBbtrfs\fP \fBsubvolume list\fP\fI [-acgoprts] [-G [+|-]value] [-C [+|-]value] [--sort=rootid,gen,ogen,path] <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 \fBsubvolume find-new\fP\fI <subvolume> <last_gen>\fP
  21 .PP
  22 \fBbtrfs\fP \fBsubvolume show\fP\fI <path>\fP
  23 .PP
  24 \fBbtrfs\fP \fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] \
  25 [-s \fIstart\fR] [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> \
  26 [<\fIfile\fR>|<\fIdir\fR>...]
  27 .PP
  28 \fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP
  29 .PP
  30 \fBbtrfs\fP \fBfilesystem resize\fP\fI [devid:][+/\-]<size>[gkm]|[devid:]max <filesystem>\fP
  31 .PP
  32 \fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP
  33 .PP
  34 \fBbtrfs\fP \fBfilesystem show\fP\fI [--all-devices|<uuid>|<label>]\fP
  35 .PP
  36 \fBbtrfs\fP \fBfilesystem balance\fP\fI <path> \fP
  37 .PP
  38 \fBbtrfs\fP \fBdevice scan\fP\fI [--all-devices|<device> [<device>...]]\fP
  39 .PP
  40 \fBbtrfs\fP \fBdevice stats\fP [-z] {\fI<path>\fP|\fI<device>\fP}
  41 .PP
  42 \fBbtrfs\fP \fBdevice add\fP\fI <device> [<device>...] <path> \fP
  43 .PP
  44 \fBbtrfs\fP \fBdevice delete\fP\fI <device> [<device>...] <path> \fP
  45 .PP
  46 \fBbtrfs\fP \fBreplace start\fP \fI[-Bfr] <srcdev>|<devid> <targetdev> <path>\fP
  47 .PP
  48 \fBbtrfs\fP \fBreplace status\fP \fI[-1] <path>\fP
  49 .PP
  50 \fBbtrfs\fP \fBreplace cancel\fP \fI<path>\fP
  51 .PP
  52 \fBbtrfs\fP \fBscrub start\fP [-Bdqru] [-c ioprio_class -n ioprio_classdata] {\fI<path>\fP|\fI<device>\fP}
  53 .PP
  54 \fBbtrfs\fP \fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP}
  55 .PP
  56 \fBbtrfs\fP \fBscrub resume\fP [-Bdqru] [-c ioprio_class -n ioprio_classdata] {\fI<path>\fP|\fI<device>\fP}
  57 .PP
  58 \fBbtrfs\fP \fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP}
  59 .PP
  60 \fBbtrfs\fP \fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP
  61 .PP
  62 \fBbtrfs\fP \fBinspect-internal logical-resolve\fP
  63 [-Pv] [-s size] \fI<logical>\fP \fI<path>\fP
  64 .PP
  65 \fBbtrfs\fP \fBinspect-internal subvolid-resolve\fP \fI<subvolid>\fP \fI<path>\fP
  66 .PP
  67 \fBbtrfs\fP \fBqgroup assign\fP \fI<src>\fP \fI<dst>\fP \fI<path>\fP
  68 .PP
  69 \fBbtrfs\fP \fBqgroup remove\fP \fI<src>\fP \fI<dst>\fP \fI<path>\fP
  70 .PP
  71 \fBbtrfs\fP \fBqgroup create\fP \fI<qgroupid>\fP \fI<path>\fP
  72 .PP
  73 \fBbtrfs\fP \fBqgroup destroy\fP \fI<qgroupid>\fP \fI<path>\fP
  74 .PP
  75 \fBbtrfs\fP \fBqgroup show\fP \fI<path>\fP
  76 .PP
  77 \fBbtrfs\fP \fBqgroup limit\fP [options] \fI<size>\fP|\fBnone\fP [\fI<qgroupid>\fP] \fI<path>\fP
  78 .PP
  79 \fBbtrfs\fP \fBhelp|\-\-help \fP\fI\fP
  80 .PP
  81 \fBbtrfs\fP \fB<command> \-\-help \fP\fI\fP
  82 .PP
  83 .SH DESCRIPTION
  84 .B btrfs
  85 is used to control the filesystem and the files and directories stored. It is
  86 the tool to create or destroy a snapshot or a subvolume for the
  87 filesystem, to defrag a file or a directory, flush the data to the disk,
  88 to resize the filesystem, to scan the device.
  89
  90 It is possible to abbreviate the commands unless the commands  are ambiguous.
  91 For example: it is possible to run
  92 .I btrfs sub snaps
  93 instead of
  94 .I btrfs subvolume snapshot.
  95 But
  96 .I btrfs file s
  97 is not allowed, because
  98 .I file s
  99 may be interpreted both as
 100 .I filesystem show
 101 and as
 102 .I filesystem sync.
 103 In this case
 104 .I btrfs
 105 returns filesystem sync
 106 If a command is terminated by
 107 .I --help
 108 , the detailed help is showed. If the passed command matches more commands,
 109 detailed help of all the matched commands is showed. For example
 110 .I btrfs dev --help
 111 shows the help of all
 112 .I device*
 113 commands.
 114
 115 .SH COMMANDS
 116 .TP
 117
 118 \fBsubvolume snapshot\fR\fI [-r] <source> [<dest>/]<name>\fR
 119 Create a writable/readonly snapshot of the subvolume \fI<source>\fR with the
 120 name \fI<name>\fR in the \fI<dest>\fR directory. If \fI<source>\fR is not a
 121 subvolume, \fBbtrfs\fR returns an error. If \fI-r\fR is given, the snapshot
 122 will be readonly.
 123 .TP
 124
 125 \fBsubvolume delete\fR\fI <subvolume> [<subvolume>...]\fR
 126 Delete the subvolume \fI<subvolume>\fR. If \fI<subvolume>\fR is not a
 127 subvolume, \fBbtrfs\fR returns an error.
 128 .TP
 129
 130 \fBsubvolume create\fR\fI [<dest>/]<name>\fR
 131 Create a subvolume in \fI<dest>\fR (or in the current directory if
 132 \fI<dest>\fR is omitted).
 133 .TP
 134
 135 \fBsubvolume list\fR\fI [-acgoprts] [-G [+|-]value] [-C [+|-]value] [--sort=rootid,gen,ogen,path] <path>\fR
 136 .RS
 137 List the subvolumes present in the filesystem \fI<path>\fR. For every
 138 subvolume the following information is shown by default.
 139 ID <ID> top level <ID> path <path>
 140 where path is the relative path of the subvolume to the \fItop level\fR
 141 subvolume.
 142
 143 The subvolume's ID may be used by the \fBsubvolume set-default\fR command, or
 144 at mount time via the \fIsubvolid=\fR option.
 145 If \fI-p\fR is given, then \fIparent <ID>\fR is added to the output between ID
 146 and top level. The parent's ID may be used at mount time via the
 147 \fIsubvolrootid=\fR option.
 148
 149 \fB-t\fP print the result as a table.
 150
 151 \fB-a\fP print all the subvolumes in the filesystem and distinguish between
 152 absolute and relative path with respect to the given <path>.
 153
 154 \fB-c\fP print the ogeneration of the subvolume, aliases: ogen or origin generation
 155
 156 \fB-g\fP print the generation of the subvolume
 157
 158 \fB-u\fP print the UUID of the subvolume
 159
 160 \fB-o\fP print only subvolumes bellow specified <path>.
 161
 162 \fB-r\fP only readonly subvolumes in the filesystem will be listed.
 163
 164 \fB-s\fP only snapshot subvolumes in the filesystem will be listed.
 165
 166 \fB-G [+|-]value\fP
 167 list subvolumes in the filesystem that its generation is
 168 >=, <= or = value. '+' means >= value, '-' means <= value, If there is
 169 neither '+' nor '-', it means = value.
 170
 171 \fB-C [+|-]value\fP
 172 list subvolumes in the filesystem that its ogeneration is
 173 >=, <= or = value. The usage is the same to '-g' option.
 174
 175 \fB--sort=rootid,gen,ogen,path\fP
 176 list subvolumes in order by specified items.
 177 you can add '+' or '-' in front of each items, '+' means ascending, '-'
 178 means descending. The default is ascending.
 179
 180 for \fB--sort\fP you can combine some items together by ',', just like
 181 \f--sort=+ogen,-gen,path,rootid\fR.
 182 .RE
 183 .TP
 184
 185 \fBsubvolume set-default\fR\fI <id> <path>\fR
 186 Set the subvolume of the filesystem \fI<path>\fR which is mounted as
 187 \fIdefault\fR. The subvolume is identified by \fI<id>\fR, which
 188 is returned by the \fBsubvolume list\fR command.
 189 .TP
 190
 191 \fBsubvolume get-default\fR\fI <path>\fR
 192 Get the default subvolume of the filesystem \fI<path>\fR. The output format
 193 is similar to \fBsubvolume list\fR command.
 194 .TP
 195
 196 \fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR
 197 List the recently modified files in a subvolume, after \fI<last_gen>\fR ID.
 198 .TP
 199
 200 \fBsubvolume show\fR\fI <path>\fR
 201 Show information of a given subvolume in the \fI<path>\fR.
 202 .TP
 203
 204 \fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] [-s \fIstart\fR] \
 205 [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> [<\fIfile\fR>|<\fIdir\fR>...]
 206
 207 Defragment file data and/or directory metadata. To defragment all files in a
 208 directory you have to specify each one on its own or use your shell wildcards.
 209
 210 The start position and the number of bytes to defragment can be specified by
 211 \fIstart\fR and \fIlen\fR. Any extent bigger than threshold will be
 212 considered already defragged. Use 0 to take the kernel default, and use 1 to
 213 say every single extent must be rewritten. You can also turn on compression in
 214 defragment operations.
 215
 216 \fB-v\fP be verbose
 217
 218 \fB-c\fP compress file contents while defragmenting
 219
 220 \fB-f\fP flush filesystem after defragmenting
 221
 222 \fB-s start\fP defragment only from byte \fIstart\fR onward
 223
 224 \fB-l len\fP defragment only up to \fIlen\fR bytes
 225
 226 \fB-t size\fP defragment only files at least \fIsize\fR bytes big
 227
 228 For \fBstart\fP, \fBlen\fP, \fBsize\fP it is possible to append a suffix
 229 like \fBk\fP for 1 KBytes, \fBm\fP for 1 MBytes...
 230
 231 NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data,
 232 don't use it if you use snapshots, have de-duplicated your data or made
 233 copies with \fBcp --reflink\fP.
 234 .TP
 235
 236 \fBfilesystem sync\fR\fI <path> \fR
 237 Force a sync for the filesystem identified by \fI<path>\fR.
 238 .TP
 239
 240 .\"
 241 .\" Some wording are extracted by the resize2fs man page
 242 .\"
 243
 244 \fBfilesystem resize\fR\fI [devid:][+/\-]<size>[gkm]|[devid:]max <path>\fR
 245 Resize a filesystem identified by \fI<path>\fR for the underlying device
 246 \fIdevid\fR.  The \fIdevid\fR can be found with \fBbtrfs filesystem show\fR and
 247 defaults to 1 if not specified.
 248 The \fI<size>\fR parameter specifies the new size of the filesystem.
 249 If the prefix \fI+\fR or \fI\-\fR is present the size is increased or decreased
 250 by the quantity \fI<size>\fR.
 251 If no units are specified, the unit of the \fI<size>\fR parameter defaults to
 252 bytes. Optionally, the size parameter may be suffixed by one of the following
 253 units designators: 'K', 'M', or 'G', kilobytes, megabytes, or gigabytes,
 254 respectively.
 255
 256 If 'max' is passed, the filesystem will occupy all available space on the
 257 device \fIdevid\fR.
 258
 259 The \fBresize\fR command \fBdoes not\fR manipulate the size of underlying
 260 partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
 261 can expand the partition before enlarging the filesystem and shrink the
 262 partition after reducing the size of the filesystem.  This can done using
 263 \fBfdisk(8)\fR or \fBparted(8)\fR to delete the existing partition and recreate
 264 it with the new desired size.  When recreating the partition make sure to use
 265 the same starting disk cylinder as before.
 266 .TP
 267
 268 \fBfilesystem label\fP\fI <dev> [newlabel]\fP
 269 Show or update the label of a filesystem. \fI<dev>\fR is used to identify the
 270 filesystem.
 271 If a \fInewlabel\fR optional argument is passed, the label is changed. The
 272 following constraints exist for a label:
 273 .IP
 274 - the maximum allowable length shall be less or equal than 256 chars
 275 .IP
 276 - the label shall not  contain the '/' or '\\' characters.
 277
 278 NOTE: Currently there are the following limitations:
 279 .IP
 280 - the filesystem has to be unmounted
 281 .IP
 282 - the filesystem should not have more than one device.
 283 .TP
 284
 285 \fBfilesystem show\fR [--all-devices|<uuid>|<label>]\fR
 286 Show the btrfs filesystem with some additional info. If no \fIUUID\fP or
 287 \fIlabel\fP is passed, \fBbtrfs\fR show info of all the btrfs filesystem.
 288 If \fB--all-devices\fP is passed, all the devices under /dev are scanned;
 289 otherwise the devices list is extracted from the /proc/partitions file.
 290 .TP
 291
 292 \fBfilesystem balance\fR \fI<path>\fR
 293 Balance the chunks of the filesystem identified by \fI<path>\fR
 294 across the devices.
 295 .TP
 296
 297 \fBdevice stats\fP [-z] {\fI<path>\fP|\fI<device>\fP}
 298 Read and print the device IO stats for all devices of the filesystem
 299 identified by \fI<path>\fR or for a single \fI<device>\fR.
 300
 301 .RS
 302 \fIOptions\fR
 303 .TP
 304 .B -z
 305 Reset stats to zero after reading them.
 306 .RE
 307 .TP
 308
 309 \fBdevice add\fR\fI <dev> [<dev>..] <path>\fR
 310 Add device(s) to the filesystem identified by \fI<path>\fR.
 311 .TP
 312
 313 \fBdevice delete\fR\fI <dev> [<dev>..] <path>\fR
 314 Remove device(s) from a filesystem identified by \fI<path>\fR.
 315 .TP
 316
 317 \fBdevice scan\fR \fI[--all-devices|<device> [<device>...]\fR
 318 If one or more devices are passed, these are scanned for a btrfs filesystem.
 319 If no devices are passed, \fBbtrfs\fR scans all the block devices listed
 320 in the /proc/partitions file.
 321 Finally, if \fB--all-devices\fP is passed, all the devices under /dev are
 322 scanned.
 323 .TP
 324
 325 \fBreplace start\fR \fI[-Bfr] <srcdev>|<devid> <targetdev> <path>\fR
 326 Replace device of a btrfs filesystem.
 327 On a live filesystem, duplicate the data to the target device which
 328 is currently stored on the source device. If the source device is not
 329 available anymore, or if the \fB-r\fR option is set, the data is built
 330 only using the RAID redundancy mechanisms. After completion of the
 331 operation, the source device is removed from the filesystem.
 332 If the \fIsrcdev\fR is a numerical value, it is assumed to be the device id
 333 of the filesystem which is mounted at mount_point, otherwise is is
 334 the path to the source device. If the source device is disconnected,
 335 from the system, you have to use the \fIdevid\fR parameter format.
 336 The targetdev needs to be same size or larger than the \fIsrcdev\fR.
 337
 338 .RS
 339 \fIOptions\fR
 340 .TP
 341 .B -r
 342 only read from \fIsrcdev\fR if no other zero-defect mirror exists (enable
 343 this if your drive has lots of read errors, the access would be very slow)
 344 .TP
 345 .B -f
 346 force using and overwriting \fItargetdev\fR even if it looks like
 347 containing a valid btrfs filesystem. A valid filesystem is
 348 assumed if a btrfs superblock is found which contains a
 349 correct checksum. Devices which are currently mounted are
 350 never allowed to be used as the \fItargetdev\fR
 351 .TP
 352 .B -B
 353 do not background
 354 .RE
 355 .TP
 356
 357 \fBreplace status\fR \fI[-1] <path>\fR
 358 Print status and progress information of a running device replace operation.
 359
 360 .RS
 361 \fIOptions\fR
 362 .TP
 363 .B -1
 364 print once instead of print continously until the replace
 365 operation finishes (or is canceled)
 366 .RE
 367 .TP
 368
 369 \fBreplace cancel\fR \fI<path>\fR
 370 Cancel a running device replace operation.
 371 .TP
 372
 373 \fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
 374 \fBscrub start\fP [-Bdqru] [-c ioprio_class -n ioprio_classdata] {\fI<path>\fP|\fI<device>\fP}
 375 Start a scrub on all devices of the filesystem identified by \fI<path>\fR or on
 376 a single \fI<device>\fR. Without options, scrub is started as a background
 377 process. Progress can be obtained with the \fBscrub status\fR command. Scrubbing
 378 involves reading all data from all disks and verifying checksums. Errors are
 379 corrected along the way if possible.
 380 .IP
 381 The default IO priority of scrub is the idle class. The priority can be configured similar to the
 382 .BR ionice (1)
 383 syntax.
 384 .RS
 385
 386 \fIOptions\fR
 387 .IP -B 5
 388 Do not background and print scrub statistics when finished.
 389 .IP -d 5
 390 Print separate statistics for each device of the filesystem (-B only).
 391 .IP -q 5
 392 Quiet. Omit error messages and statistics.
 393 .IP -r 5
 394 Read only mode. Do not attempt to correct anything.
 395 .IP -u 5
 396 Scrub unused space as well. (NOT IMPLEMENTED)
 397 .IP -c 5
 398 Set IO priority class (see
 399 .BR ionice (1)
 400 manpage).
 401 .IP -n 5
 402 Set IO priority classdata (see
 403 .BR ionice (1)
 404 manpage).
 405 .RE
 406 .TP
 407
 408 \fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP}
 409 If a scrub is running on the filesystem identified by \fI<path>\fR, cancel it.
 410 Progress is saved in the scrub progress file and scrubbing can be resumed later
 411 using the \fBscrub resume\fR command.
 412 If a \fI<device>\fR is given, the corresponding filesystem is found and
 413 \fBscrub cancel\fP behaves as if it was called on that filesystem.
 414 .TP
 415
 416 \fBscrub resume\fP [-Bdqru] [-c ioprio_class -n ioprio_classdata] {\fI<path>\fP|\fI<device>\fP}
 417 Resume a canceled or interrupted scrub cycle on the filesystem identified by
 418 \fI<path>\fR or on a given \fI<device>\fR. Does not start a new scrub if the
 419 last scrub finished successfully.
 420 .RS
 421
 422 \fIOptions\fR
 423 .TP
 424 see \fBscrub start\fP.
 425 .RE
 426 .TP
 427
 428 \fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP}
 429 Show status of a running scrub for the filesystem identified by \fI<path>\fR or
 430 for the specified \fI<device>\fR.
 431 If no scrub is running, show statistics of the last finished or canceled scrub
 432 for that filesystem or device.
 433 .RS
 434
 435 \fIOptions\fR
 436 .IP -d 5
 437 Print separate statistics for each device of the filesystem.
 438 .RE
 439 .TP
 440
 441 \fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP
 442 Resolves an <inode> in subvolume <path> to all filesystem paths.
 443 .RS
 444
 445 \fIOptions\fR
 446 .IP -v 5
 447 verbose mode. print count of returned paths and ioctl() return value
 448 .RE
 449 .TP
 450
 451 \fBinspect-internal logical-resolve\fP [-Pv] [-s bufsize] \fI<logical>\fP \fI<path>\fP
 452 Resolves a <logical> address in the filesystem mounted at <path> to all inodes.
 453 By default, each inode is then resolved to a file system path (similar to the
 454 \fBinode-resolve\fP subcommand).
 455 .RS
 456
 457 \fIOptions\fR
 458 .IP -P 5
 459 skip the path resolving and print the inodes instead
 460 .IP -v 5
 461 verbose mode. print count of returned paths and all ioctl() return values
 462 .IP -s bufsize 5
 463 set inode container's size. This is used to increase inode container's size in case it is
 464 not enough to read all the resolved results. The max value one can set is 64k.
 465 .RE
 466 .TP
 467
 468 \fBinspect-internal subvolid-resolve\fP \fI<subvolid>\fP \fI<path>\fP
 469 Get file system paths for the given subvolume ID.
 470 .TP
 471
 472 \fBbtrfs qgroup assign\fP \fI<src>\fP \fI<dst>\fP \fI<path>\fP
 473 Enable subvolume qgroup support for a filesystem.
 474 .TP
 475
 476 \fBbtrfs qgroup remove\fP \fI<src>\fP \fI<dst>\fP \fI<path>\fP
 477 Remove a subvol from a quota group.
 478 .TP
 479
 480 \fBbtrfs qgroup create\fP \fI<qgroupid>\fP \fI<path>\fP
 481 Create a subvolume quota group.
 482 .TP
 483
 484 \fBbtrfs qgroup destroy\fP \fI<qgroupid>\fP \fI<path>\fP
 485 Destroy a subvolume quota group.
 486 .TP
 487
 488 \fBbtrfs qgroup show\fP \fI<path>\fP
 489 Show all subvolume quota groups.
 490 .TP
 491
 492 \fBbtrfs\fP \fBqgroup limit\fP [options] \fI<size>\fP|\fBnone\fP [\fI<qgroupid>\fP] \fI<path>\fP
 493 Limit the size of a subvolume quota group.
 494 .RE
 495
 496 .SH EXIT STATUS
 497 \fBbtrfs\fR returns a zero exist status if it succeeds. Non zero is returned in
 498 case of failure.
 499
 500 .SH AVAILABILITY
 501 .B btrfs
 502 is part of btrfs-progs. Btrfs filesystem is currently under heavy development,
 503 and not suitable for any uses other than benchmarking and review.
 504 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 505 further details.
 506 .SH SEE ALSO
 507 .BR mkfs.btrfs (8),
 508 .BR ionice (1)