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