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