1 .TH BTRFS 8 "" "btrfs" "btrfs"
3 .\" Man page written by Goffredo Baroncelli <kreijack@inwind.it> (Feb 2010)
6 btrfs \- control a btrfs filesystem
8 \fBbtrfs\fP \fBsubvolume snapshot\fP\fI [-r] <source> [<dest>/]<name>\fP
10 \fBbtrfs\fP \fBsubvolume delete\fP\fI <subvolume> [<subvolume>...]\fP
12 \fBbtrfs\fP \fBsubvolume create\fP\fI [<dest>/]<name>\fP
14 \fBbtrfs\fP \fBsubvolume list\fP\fI [-aprts] [-g [+|-]value] [-c [+|-]value] [--rootid=rootid,gen,ogen,path] <path>\fP
16 \fBbtrfs\fP \fBsubvolume set-default\fP\fI <id> <path>\fP
18 \fBbtrfs\fP \fBsubvolume get-default\fP\fI <path>\fP
20 \fBbtrfs\fP \fBsubvolume find-new\fP\fI <subvolume> <last_gen>\fP
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>...]
26 \fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP
28 \fBbtrfs\fP \fBfilesystem resize\fP\fI [devid:][+/\-]<size>[gkm]|[devid:]max <filesystem>\fP
30 \fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP
32 \fBbtrfs\fP \fBfilesystem balance\fP\fI <path> \fP
34 \fBbtrfs\fP \fBdevice scan\fP\fI [--all-devices|<device> [<device>...]]\fP
36 \fBbtrfs\fP \fBdevice stats\fP [-z] {\fI<path>\fP|\fI<device>\fP}
38 \fBbtrfs\fP \fBdevice add\fP\fI <device> [<device>...] <path> \fP
40 \fBbtrfs\fP \fBdevice delete\fP\fI <device> [<device>...] <path> \fP
42 \fBbtrfs\fP \fBreplace start\fP \fI[-Bfr] <srcdev>|<devid> <targetdev> <path>\fP
44 \fBbtrfs\fP \fBreplace status\fP \fI[-1] <path>\fP
46 \fBbtrfs\fP \fBreplace cancel\fP \fI<path>\fP
48 \fBbtrfs\fP \fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
50 \fBbtrfs\fP \fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP}
52 \fBbtrfs\fP \fBscrub resume\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
54 \fBbtrfs\fP \fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP}
56 \fBbtrfs\fP \fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP
58 \fBbtrfs\fP \fBinspect-internal logical-resolve\fP
59 [-Pv] [-s size] \fI<logical>\fP \fI<path>\fP
61 \fBbtrfs\fP \fBhelp|\-\-help \fP\fI\fP
63 \fBbtrfs\fP \fB<command> \-\-help \fP\fI\fP
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.
72 It is possible to abbreviate the commands unless the commands are ambiguous.
73 For example: it is possible to run
76 .I btrfs subvolume snapshot.
79 is not allowed, because
81 may be interpreted both as
87 returns filesystem sync
88 If a command is terminated by
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
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
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.
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).
117 \fBsubvolume list\fR\fI [-aprts][-g [+|-]value] [-c [+|-]value] [--sort=gen,ogen,rootid,path] <path>\fR
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
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.
131 \fB-t\fP print the result as a table.
133 \fB-a\fP print all the subvolumes in the filesystem and distinguish between
134 absolute and relative path with respect to the given <path>.
136 \fB-r\fP only readonly subvolumes in the filesystem wille be listed.
138 \fB-s\fP only snapshot subvolumes in the filesystem will be listed.
141 list subvolumes in the filesystem that its generation is
142 >=, <= or = value. '+' means >= value, '-' means <= value, If there is
143 neither '+' nor '-', it means = value.
146 list subvolumes in the filesystem that its ogeneration is
147 >=, <= or = value. The usage is the same to '-g' option.
149 \fB--sort=gen,ogen,path,rootid\fP
150 list subvolumes in order by specified items.
151 you can add '+' or '-' in front of each items, '+' means ascending,'-'
152 means descending. The default is ascending.
154 for \fB--sort\fP you can combine some items together by ',', just like
155 \f--sort=+ogen,-gen,path,rootid\fR.
159 \fBsubvolume set-default\fR\fI <id> <path>\fR
160 Set the subvolume of the filesystem \fI<path>\fR which is mounted as
161 \fIdefault\fR. The subvolume is identified by \fI<id>\fR, which
162 is returned by the \fBsubvolume list\fR command.
165 \fBsubvolume get-default\fR\fI <path>\fR
166 Get the default subvolume of the filesystem \fI<path>\fR. The output format
167 is similar to \fBsubvolume list\fR command.
170 \fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR
171 List the recently modified files in a subvolume, after \fI<last_gen>\fR ID.
174 \fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] [-s \fIstart\fR] \
175 [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> [<\fIfile\fR>|<\fIdir\fR>...]
177 Defragment file data and/or directory metadata. To defragment all files in a
178 directory you have to specify each one on its own or use your shell wildcards.
180 The start position and the number of bytes to defragment can be specified by
181 \fIstart\fR and \fIlen\fR. Any extent bigger than threshold will be
182 considered already defragged. Use 0 to take the kernel default, and use 1 to
183 say every single extent must be rewritten. You can also turn on compression in
184 defragment operations.
188 \fB-c\fP compress file contents while defragmenting
190 \fB-f\fP flush filesystem after defragmenting
192 \fB-s start\fP defragment only from byte \fIstart\fR onward
194 \fB-l len\fP defragment only up to \fIlen\fR bytes
196 \fB-t size\fP defragment only files at least \fIsize\fR bytes big
198 For \fBstart\fP, \fBlen\fP, \fBsize\fP it is possible to append a suffix
199 like \fBk\fP for 1 KBytes, \fBm\fP for 1 MBytes...
201 NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data,
202 don't use it if you use snapshots, have de-duplicated your data or made
203 copies with \fBcp --reflink\fP.
206 \fBfilesystem sync\fR\fI <path> \fR
207 Force a sync for the filesystem identified by \fI<path>\fR.
211 .\" Some wording are extracted by the resize2fs man page
214 \fBfilesystem resize\fR\fI [devid:][+/\-]<size>[gkm]|[devid:]max <path>\fR
215 Resize a filesystem identified by \fI<path>\fR for the underlying device
216 \fIdevid\fR. The \fIdevid\fR can be found with \fBbtrfs filesystem show\fR and
217 defaults to 1 if not specified.
218 The \fI<size>\fR parameter specifies the new size of the filesystem.
219 If the prefix \fI+\fR or \fI\-\fR is present the size is increased or decreased
220 by the quantity \fI<size>\fR.
221 If no units are specified, the unit of the \fI<size>\fR parameter defaults to
222 bytes. Optionally, the size parameter may be suffixed by one of the following
223 units designators: 'K', 'M', or 'G', kilobytes, megabytes, or gigabytes,
226 If 'max' is passed, the filesystem will occupy all available space on the
229 The \fBresize\fR command \fBdoes not\fR manipulate the size of underlying
230 partition. If you wish to enlarge/reduce a filesystem, you must make sure you
231 can expand the partition before enlarging the filesystem and shrink the
232 partition after reducing the size of the filesystem. This can done using
233 \fBfdisk(8)\fR or \fBparted(8)\fR to delete the existing partition and recreate
234 it with the new desired size. When recreating the partition make sure to use
235 the same starting disk cylinder as before.
238 \fBfilesystem label\fP\fI <dev> [newlabel]\fP
239 Show or update the label of a filesystem. \fI<dev>\fR is used to identify the
241 If a \fInewlabel\fR optional argument is passed, the label is changed. The
242 following constraints exist for a label:
244 - the maximum allowable length shall be less or equal than 256 chars
246 - the label shall not contain the '/' or '\\' characters.
248 NOTE: Currently there are the following limitations:
250 - the filesystem has to be unmounted
252 - the filesystem should not have more than one device.
255 \fBfilesystem show\fR [--all-devices|<uuid>|<label>]\fR
256 Show the btrfs filesystem with some additional info. If no \fIUUID\fP or
257 \fIlabel\fP is passed, \fBbtrfs\fR show info of all the btrfs filesystem.
258 If \fB--all-devices\fP is passed, all the devices under /dev are scanned;
259 otherwise the devices list is extracted from the /proc/partitions file.
262 \fBfilesystem balance\fR \fI<path>\fR
263 Balance the chunks of the filesystem identified by \fI<path>\fR
267 \fBdevice stats\fP [-z] {\fI<path>\fP|\fI<device>\fP}
268 Read and print the device IO stats for all devices of the filesystem
269 identified by \fI<path>\fR or for a single \fI<device>\fR.
275 Reset stats to zero after reading them.
279 \fBdevice add\fR\fI <dev> [<dev>..] <path>\fR
280 Add device(s) to the filesystem identified by \fI<path>\fR.
283 \fBdevice delete\fR\fI <dev> [<dev>..] <path>\fR
284 Remove device(s) from a filesystem identified by \fI<path>\fR.
287 \fBdevice scan\fR \fI[--all-devices|<device> [<device>...]\fR
288 If one or more devices are passed, these are scanned for a btrfs filesystem.
289 If no devices are passed, \fBbtrfs\fR scans all the block devices listed
290 in the /proc/partitions file.
291 Finally, if \fB--all-devices\fP is passed, all the devices under /dev are
295 \fBreplace start\fR \fI[-Bfr] <srcdev>|<devid> <targetdev> <path>\fR
296 Replace device of a btrfs filesystem.
297 On a live filesystem, duplicate the data to the target device which
298 is currently stored on the source device. If the source device is not
299 available anymore, or if the \fB-r\fR option is set, the data is built
300 only using the RAID redundancy mechanisms. After completion of the
301 operation, the source device is removed from the filesystem.
302 If the \fIsrcdev\fR is a numerical value, it is assumed to be the device id
303 of the filesystem which is mounted at mount_point, otherwise is is
304 the path to the source device. If the source device is disconnected,
305 from the system, you have to use the \fIdevid\fR parameter format.
306 The targetdev needs to be same size or larger than the \fIsrcdev\fR.
312 only read from \fIsrcdev\fR if no other zero-defect mirror exists (enable
313 this if your drive has lots of read errors, the access would be very slow)
316 force using and overwriting \fItargetdev\fR even if it looks like
317 containing a valid btrfs filesystem. A valid filesystem is
318 assumed if a btrfs superblock is found which contains a
319 correct checksum. Devices which are currently mounted are
320 never allowed to be used as the \fItargetdev\fR
327 \fBreplace status\fR \fI[-1] <path>\fR
328 Print status and progress information of a running device replace operation.
334 print once instead of print continously until the replace
335 operation finishes (or is canceled)
339 \fBreplace cancel\fR \fI<path>\fR
340 Cancel a running device replace operation.
343 \fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
344 Start a scrub on all devices of the filesystem identified by \fI<path>\fR or on
345 a single \fI<device>\fR. Without options, scrub is started as a background
346 process. Progress can be obtained with the \fBscrub status\fR command. Scrubbing
347 involves reading all data from all disks and verifying checksums. Errors are
348 corrected along the way if possible.
353 Do not background and print scrub statistics when finished.
355 Print separate statistics for each device of the filesystem (-B only).
357 Quiet. Omit error messages and statistics.
359 Read only mode. Do not attempt to correct anything.
361 Scrub unused space as well. (NOT IMPLEMENTED)
365 \fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP}
366 If a scrub is running on the filesystem identified by \fI<path>\fR, cancel it.
367 Progress is saved in the scrub progress file and scrubbing can be resumed later
368 using the \fBscrub resume\fR command.
369 If a \fI<device>\fR is given, the corresponding filesystem is found and
370 \fBscrub cancel\fP behaves as if it was called on that filesystem.
373 \fBscrub resume\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
374 Resume a canceled or interrupted scrub cycle on the filesystem identified by
375 \fI<path>\fR or on a given \fI<device>\fR. Does not start a new scrub if the
376 last scrub finished successfully.
381 see \fBscrub start\fP.
385 \fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP}
386 Show status of a running scrub for the filesystem identified by \fI<path>\fR or
387 for the specified \fI<device>\fR.
388 If no scrub is running, show statistics of the last finished or canceled scrub
389 for that filesystem or device.
394 Print separate statistics for each device of the filesystem.
398 \fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP
399 Resolves an <inode> in subvolume <path> to all filesystem paths.
404 verbose mode. print count of returned paths and ioctl() return value
408 \fBinspect-internal logical-resolve\fP [-Pv] [-s bufsize] \fI<logical>\fP \fI<path>\fP
409 Resolves a <logical> address in the filesystem mounted at <path> to all inodes.
410 By default, each inode is then resolved to a file system path (similar to the
411 \fBinode-resolve\fP subcommand).
416 skip the path resolving and print the inodes instead
418 verbose mode. print count of returned paths and all ioctl() return values
420 set inode container's size. This is used to increase inode container's size in case it is
421 not enough to read all the resolved results. The max value one can set is 64k.
425 \fBbtrfs\fR returns a zero exist status if it succeeds. Non zero is returned in
430 is part of btrfs-progs. Btrfs filesystem is currently under heavy development,
431 and not suitable for any uses other than benchmarking and review.
432 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for