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