1BTRFS(8) btrfs BTRFS(8)
2
6 btrfs - control a btrfs filesystem
7
9 btrfs subvolume snapshot [-r] <source> [<dest>/]<name>
10 btrfs subvolume delete <subvolume> [<subvolume>...]
12 btrfs subvolume create [<dest>/]<name>
14 btrfs subvolume list [-aprts] [-g [+|-]value] [-c [+|-]value]
16 [--rootid=rootid,gen,ogen,path] <path>
17 btrfs subvolume set-default <id> <path>
19 btrfs subvolume get-default <path>
21 btrfs filesystem defragment -c[zlib|lzo] [-l len] [-s start] [-t size]
23 -[vf] <file>|<dir> [<file>|<dir>...]
24 btrfs filesystem sync <path>
26 btrfs filesystem resize [devid:][+/-]<size>[gkm]|[devid:]max <filesys‐
28 tem>
29 btrfs filesystem label <dev> [newlabel]
31 btrfs subvolume find-new <subvolume> <last_gen>
33 btrfs filesystem balance <path>
35 btrfs device scan [--all-devices|<device> [<device>...]]
37 btrfs device show [--all-devices|<uuid>|<label>]
39 btrfs device add <device> [<device>...] <path>
41 btrfs device delete <device> [<device>...] <path>
43 btrfs scrub start [-Bdqru] {<path>|<device>}
45 btrfs scrub cancel {<path>|<device>}
47 btrfs scrub resume [-Bdqru] {<path>|<device>}
49 btrfs scrub status [-d] {<path>|<device>}
51 btrfs inspect-internal inode-resolve [-v] <inode> <path>
53 btrfs inspect-internal logical-resolve [-Pv] [-s size] <logical> <path>
55 btrfs help|--help|-h
57 btrfs <command> --help
59
61 btrfs is used to control the filesystem and the files and directories
62 stored. It is the tool to create or destroy a snapshot or a subvolume
63 for the filesystem, to defrag a file or a directory, flush the data to
64 the disk, to resize the filesystem, to scan the device.
65 It is possible to abbreviate the commands unless the commands are
67 ambiguous. For example: it is possible to run btrfs sub snaps instead
68 of btrfs subvolume snapshot. But btrfs file s is not allowed, because
69 file s may be interpreted both as filesystem show and as filesystem
70 sync. In this case btrfs returns filesystem sync If a command is ter‐
71 minated by --help , the detailed help is showed. If the passed command
72 matches more commands, detailed help of all the matched commands is
73 showed. For example btrfs dev --help shows the help of all device* com‐
74 mands.
75
78 subvolume snapshot [-r] <source> [<dest>/]<name>
79 Create a writable/readonly snapshot of the subvolume <source>
80 with the name <name> in the <dest> directory. If <source> is not
81 a subvolume, btrfs returns an error. If -r is given, the snap‐
82 shot will be readonly.
83 subvolume delete <subvolume> [<subvolume>...]
86 Delete the subvolume <subvolume>. If <subvolume> is not a sub‐
87 volume, btrfs returns an error.
88 subvolume create [<dest>/]<name>
91 Create a subvolume in <dest> (or in the current directory if
92 <dest> is omitted).
93 subvolume list [-aprts][-g [+|-]value] [-c [+|-]value]
96 [--sort=gen,ogen,rootid,path] <path>
97 List the subvolumes present in the filesystem <path>. For every
98 subvolume the following information is shown by default. ID
99 <ID> top level <ID> path <path> where path is the relative path
100 of the subvolume to the top level subvolume.
101 The subvolume's ID may be used by the subvolume set-default com‐
103 mand, or at mount time via the subvol= option. If -p is given,
104 then parent <ID> is added to the output between ID and top
105 level. The parent's ID may be used at mount time via the subvol‐
106 rootid= option.
107 -t print the result as a table.
109 -a print all the subvolumes in the filesystem.
111 -r only readonly subvolumes in the filesystem wille be listed.
113 -s only snapshot subvolumes in the filesystem will be listed.
115 -g [+|-]value list subvolumes in the filesystem that its genera‐
117 tion is >=, <= or = value. '+' means >= value, '-' means <=
118 value, If there is neither '+' nor '-', it means = value.
119 -c [+|-]value list subvolumes in the filesystem that its ogener‐
121 ation is >=, <= or = value. The usage is the same to '-g'
122 option.
123 --sort=gen,ogen,path,rootid list subvolumes in order by speci‐
125 fied items. you can add '+' or '-' in front of each items, '+'
126 means ascending,'-' means descending. The default is ascending.
127 for --sort you can combine some items together by ',', just like
129 -sort=+ogen,-gen,path,rootid.
130 subvolume set-default <id> <path>
133 Set the subvolume of the filesystem <path> which is mounted as
134 default. The subvolume is identified by <id>, which is returned
135 by the subvolume list command.
136 subvolume get-default <path>
139 Get the default subvolume of the filesystem <path>. The output
140 format is similar to subvolume list command.
141 filesystem defragment -c[zlib|lzo] [-l len] [-s start] [-t size] -[vf]
144 <file>|<dir> [<file>|<dir>...]
145 Defragment file data and/or directory metadata. To defragment
147 all files in a directory you have to specify each one on its own
148 or use your shell wildcards.
149 The start position and the number of bytes to defragment can be
151 specified by start and len. Any extent bigger than threshold
152 will be considered already defragged. Use 0 to take the kernel
153 default, and use 1 to say every single extent must be rewritten.
154 You can also turn on compression in defragment operations.
155 -v be verbose
157 -c compress file contents while defragmenting
159 -f flush filesystem after defragmenting
161 -s start defragment only from byte start onward
163 -l len defragment only up to len bytes
165 -t size defragment only files at least size bytes big
167 NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed
169 copies of data, don't use it if you use snapshots, have de-
170 duplicated your data or made copies with cp --reflink.
171 subvolume find-new <subvolume> <last_gen>
174 List the recently modified files in a subvolume, after
175 <last_gen> ID.
176 filesystem sync <path>
179 Force a sync for the filesystem identified by <path>.
180 filesystem resize [devid:][+/-]<size>[gkm]|[devid:]max <path>
184 Resize a filesystem identified by <path> for the underlying
185 device devid. The devid can be found with btrfs filesystem show
186 and defaults to 1 if not specified. The <size> parameter speci‐
187 fies the new size of the filesystem. If the prefix + or - is
188 present the size is increased or decreased by the quantity
189 <size>. If no units are specified, the unit of the <size>
190 parameter defaults to bytes. Optionally, the size parameter may
191 be suffixed by one of the following units designators: 'K', 'M',
192 or 'G', kilobytes, megabytes, or gigabytes, respectively.
193 If 'max' is passed, the filesystem will occupy all available
195 space on the device devid.
196 The resize command does not manipulate the size of underlying
198 partition. If you wish to enlarge/reduce a filesystem, you must
199 make sure you can expand the partition before enlarging the
200 filesystem and shrink the partition after reducing the size of
201 the filesystem. This can done using fdisk(8) or parted(8) to
202 delete the existing partition and recreate it with the new
203 desired size. When recreating the partition make sure to use
204 the same starting disk cylinder as before.
205 filesystem label <dev> [newlabel]
208 Show or update the label of a filesystem. <dev> is used to iden‐
209 tify the filesystem. If a newlabel optional argument is passed,
210 the label is changed. The following constraints exist for a
211 label:
212 - the maximum allowable length shall be less or equal than 256
214 chars
215 - the label shall not contain the '/' or '\' characters.
217 NOTE: Currently there are the following limitations:
219 - the filesystem has to be unmounted
221 - the filesystem should not have more than one device.
223 filesystem show [--all-devices|<uuid>|<label>]
226 Show the btrfs filesystem with some additional info. If no UUID
227 or label is passed, btrfs show info of all the btrfs filesystem.
228 If --all-devices is passed, all the devices under /dev are
229 scanned; otherwise the devices list is extracted from the
230 /proc/partitions file.
231 filesystem balance <path>
234 Balance the chunks of the filesystem identified by <path> across
235 the devices.
236 device add <dev> [<dev>..] <path>
239 Add device(s) to the filesystem identified by <path>.
240 device delete <dev> [<dev>..] <path>
243 Remove device(s) from a filesystem identified by <path>.
244 device scan [--all-devices|<device> [<device>...]
247 If one or more devices are passed, these are scanned for a btrfs
248 filesystem. If no devices are passed, btrfs scans all the block
249 devices listed in the /proc/partitions file. Finally, if --all-
250 devices is passed, all the devices under /dev are scanned.
251 scrub start [-Bdqru] {<path>|<device>}
254 Start a scrub on all devices of the filesystem identified by
255 <path> or on a single <device>. Without options, scrub is
256 started as a background process. Progress can be obtained with
257 the scrub status command. Scrubbing involves reading all data
258 from all disks and verifying checksums. Errors are corrected
259 along the way if possible.
260 Options
262 -B Do not background and print scrub statistics when finished.
264 -d Print separate statistics for each device of the filesystem
266 (-B only).
267 -q Quiet. Omit error messages and statistics.
269 -r Read only mode. Do not attempt to correct anything.
271 -u Scrub unused space as well. (NOT IMPLEMENTED)
273 scrub cancel {<path>|<device>}
276 If a scrub is running on the filesystem identified by <path>,
277 cancel it. Progress is saved in the scrub progress file and
278 scrubbing can be resumed later using the scrub resume command.
279 If a <device> is given, the corresponding filesystem is found
280 and scrub cancel behaves as if it was called on that filesystem.
281 scrub resume [-Bdqru] {<path>|<device>}
284 Resume a canceled or interrupted scrub cycle on the filesystem
285 identified by <path> or on a given <device>. Does not start a
286 new scrub if the last scrub finished successfully.
287 Options
289 see scrub start.
291 scrub status [-d] {<path>|<device>}
294 Show status of a running scrub for the filesystem identified by
295 <path> or for the specified <device>. If no scrub is running,
296 show statistics of the last finished or canceled scrub for that
297 filesystem or device.
298 Options
300 -d Print separate statistics for each device of the filesys‐
302 tem.
303 inspect-internal inode-resolve [-v] <inode> <path>
306 Resolves an <inode> in subvolume <path> to all filesystem paths.
307 Options
309 -v verbose mode. print count of returned paths and ioctl()
311 return value
312 inspect-internal logical-resolve [-Pv] [-s bufsize] <logical> <path>
315 Resolves a <logical> address in the filesystem mounted at <path>
316 to all inodes. By default, each inode is then resolved to a
317 file system path (similar to the inode-resolve subcommand).
318 Options
320 -P skip the path resolving and print the inodes instead
322 -v verbose mode. print count of returned paths and all ioctl()
324 return values
325 -s set inode container's size. This is used to increase inode
327 container's size in case it is not enough to read all the
328 resolved results. The max value one can set is 64k.
329
332 btrfs returns a zero exist status if it succeeds. Non zero is returned
333 in case of failure.
334
337 btrfs is part of btrfs-progs. Btrfs filesystem is currently under heavy
338 development, and not suitable for any uses other than benchmarking and
339 review. Please refer to the btrfs wiki http://btrfs.wiki.kernel.org
340 for further details.
341
343 mkfs.btrfs(8)
344btrfs BTRFS(8)