summaryrefslogtreecommitdiff
path: root/man/btrfs.8.in
blob: 5f017f8a8af1526f725743ea34ae8a4d1930eb13 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
.TH BTRFS 8 "" "btrfs" "btrfs"
.\"
.\" Man page written by Goffredo Baroncelli <kreijack@inwind.it> (Feb 2010)
.\"
.SH NAME
btrfs \- control a btrfs filesystem
.SH SYNOPSIS
\fBbtrfs\fP \fBsubvolume snapshot\fP\fI [-r] <source> [<dest>/]<name>\fP
.PP
\fBbtrfs\fP \fBsubvolume delete\fP\fI <subvolume> [<subvolume>...]\fP
.PP
\fBbtrfs\fP \fBsubvolume create\fP\fI [<dest>/]<name>\fP
.PP
\fBbtrfs\fP \fBsubvolume list\fP\fI [-aprts] [-g [+|-]value] [-c [+|-]value] [--rootid=rootid,gen,ogen,path] <path>\fP
.PP
\fBbtrfs\fP \fBsubvolume set-default\fP\fI <id> <path>\fP
.PP
\fBbtrfs\fP \fBsubvolume get-default\fP\fI <path>\fP
.PP
\fBbtrfs\fP \fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] \
[-s \fIstart\fR] [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> \
[<\fIfile\fR>|<\fIdir\fR>...]
.PP
\fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP
.PP
\fBbtrfs\fP \fBfilesystem resize\fP\fI [devid:][+/\-]<size>[gkm]|[devid:]max <filesystem>\fP
.PP
\fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP
.PP
\fBbtrfs\fP \fBsubvolume find-new\fP\fI <subvolume> <last_gen>\fP
.PP
\fBbtrfs\fP \fBfilesystem balance\fP\fI <path> \fP
.PP
\fBbtrfs\fP \fBdevice scan\fP\fI [--all-devices|<device> [<device>...]]\fP
.PP
\fBbtrfs\fP \fBdevice stats\fP [-z] {\fI<path>\fP|\fI<device>\fP}
.PP
\fBbtrfs\fP \fBdevice add\fP\fI <device> [<device>...] <path> \fP
.PP
\fBbtrfs\fP \fBdevice delete\fP\fI <device> [<device>...] <path> \fP
.PP
\fBbtrfs\fP \fBreplace start\fP \fI[-Bfr] <srcdev>|<devid> <targetdev> <path>\fP
.PP
\fBbtrfs\fP \fBreplace status\fP \fI[-1] <path>\fP
.PP
\fBbtrfs\fP \fBreplace cancel\fP \fI<path>\fP
.PP
\fBbtrfs\fP \fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
.PP
\fBbtrfs\fP \fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP}
.PP
\fBbtrfs\fP \fBscrub resume\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
.PP
\fBbtrfs\fP \fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP}
.PP
\fBbtrfs\fP \fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP
.PP
\fBbtrfs\fP \fBinspect-internal logical-resolve\fP
[-Pv] [-s size] \fI<logical>\fP \fI<path>\fP
.PP
\fBbtrfs\fP \fBhelp|\-\-help \fP\fI\fP
.PP
\fBbtrfs\fP \fB<command> \-\-help \fP\fI\fP
.PP
.SH DESCRIPTION
.B btrfs
is used to control the filesystem and the files and directories stored. It is
the tool to create or destroy a snapshot or a subvolume for the
filesystem, to defrag a file or a directory, flush the data to the disk,
to resize the filesystem, to scan the device.

It is possible to abbreviate the commands unless the commands  are ambiguous.
For example: it is possible to run
.I btrfs sub snaps
instead of
.I btrfs subvolume snapshot.
But
.I btrfs file s
is not allowed, because
.I file s
may be interpreted both as
.I filesystem show
and as
.I filesystem sync.
In this case
.I btrfs
returns filesystem sync
If a command is terminated by
.I --help
, the detailed help is showed. If the passed command matches more commands,
detailed help of all the matched commands is showed. For example
.I btrfs dev --help
shows the help of all
.I device*
commands.

.SH COMMANDS
.TP

\fBsubvolume snapshot\fR\fI [-r] <source> [<dest>/]<name>\fR
Create a writable/readonly snapshot of the subvolume \fI<source>\fR with the
name \fI<name>\fR in the \fI<dest>\fR directory. If \fI<source>\fR is not a
subvolume, \fBbtrfs\fR returns an error. If \fI-r\fR is given, the snapshot
will be readonly.
.TP

\fBsubvolume delete\fR\fI <subvolume> [<subvolume>...]\fR
Delete the subvolume \fI<subvolume>\fR. If \fI<subvolume>\fR is not a
subvolume, \fBbtrfs\fR returns an error.
.TP

\fBsubvolume create\fR\fI [<dest>/]<name>\fR
Create a subvolume in \fI<dest>\fR (or in the current directory if
\fI<dest>\fR is omitted).
.TP

\fBsubvolume list\fR\fI [-aprts][-g [+|-]value] [-c [+|-]value] [--sort=gen,ogen,rootid,path] <path>\fR
.RS
List the subvolumes present in the filesystem \fI<path>\fR. For every
subvolume the following information is shown by default.
ID <ID> top level <ID> path <path>
where path is the relative path of the subvolume to the \fItop level\fR
subvolume.

The subvolume's ID may be used by the \fBsubvolume set-default\fR command, or
at mount time via the \fIsubvol=\fR option.
If \fI-p\fR is given, then \fIparent <ID>\fR is added to the output between ID
and top level. The parent's ID may be used at mount time via the
\fIsubvolrootid=\fR option.

\fB-t\fP print the result as a table.

\fB-a\fP print all the subvolumes in the filesystem.

\fB-r\fP only readonly subvolumes in the filesystem wille be listed.

\fB-s\fP only snapshot subvolumes in the filesystem will  be listed.

\fB-g [+|-]value\fP
list subvolumes in the filesystem that its generation is
>=, <= or = value. '+' means >= value, '-' means <= value, If there is
neither '+' nor '-', it means = value.

\fB-c [+|-]value\fP
list subvolumes in the filesystem that its ogeneration is
>=, <= or = value. The usage is the same to '-g' option.

\fB--sort=gen,ogen,path,rootid\fP
list subvolumes in order by specified items.
you can add '+' or '-' in front of each items, '+' means ascending,'-'
means descending. The default is ascending.

for \fB--sort\fP you can combine some items together by ',', just like
\f--sort=+ogen,-gen,path,rootid\fR.
.RE
.TP

\fBsubvolume set-default\fR\fI <id> <path>\fR
Set the subvolume of the filesystem \fI<path>\fR which is mounted as 
\fIdefault\fR. The subvolume is identified by \fI<id>\fR, which 
is returned by the \fBsubvolume list\fR command.
.TP

\fBsubvolume get-default\fR\fI <path>\fR
Get the default subvolume of the filesystem \fI<path>\fR. The output format
is similar to \fBsubvolume list\fR command.
.TP

\fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] [-s \fIstart\fR] \
[-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> [<\fIfile\fR>|<\fIdir\fR>...]

Defragment file data and/or directory metadata. To defragment all files in a
directory you have to specify each one on its own or use your shell wildcards.

The start position and the number of bytes to defragment can be specified by
\fIstart\fR and \fIlen\fR. Any extent bigger than threshold will be
considered already defragged. Use 0 to take the kernel default, and use 1 to
say every single extent must be rewritten. You can also turn on compression in
defragment operations.

\fB-v\fP be verbose

\fB-c\fP compress file contents while defragmenting

\fB-f\fP flush filesystem after defragmenting

\fB-s start\fP defragment only from byte \fIstart\fR onward

\fB-l len\fP defragment only up to \fIlen\fR bytes

\fB-t size\fP defragment only files at least \fIsize\fR bytes big

NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data,
don't use it if you use snapshots, have de-duplicated your data or made
copies with \fBcp --reflink\fP.
.TP

\fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR
List the recently modified files in a subvolume, after \fI<last_gen>\fR ID.
.TP

\fBfilesystem sync\fR\fI <path> \fR
Force a sync for the filesystem identified by \fI<path>\fR.
.TP

.\"
.\" Some wording are extracted by the resize2fs man page
.\"

\fBfilesystem resize\fR\fI [devid:][+/\-]<size>[gkm]|[devid:]max <path>\fR
Resize a filesystem identified by \fI<path>\fR for the underlying device
\fIdevid\fR.  The \fIdevid\fR can be found with \fBbtrfs filesystem show\fR and
defaults to 1 if not specified.
The \fI<size>\fR parameter specifies the new size of the filesystem.
If the prefix \fI+\fR or \fI\-\fR is present the size is increased or decreased
by the quantity \fI<size>\fR.
If no units are specified, the unit of the \fI<size>\fR parameter defaults to
bytes. Optionally, the size parameter may be suffixed by one of the following
units designators: 'K', 'M', or 'G', kilobytes, megabytes, or gigabytes,
respectively.

If 'max' is passed, the filesystem will occupy all available space on the
device \fIdevid\fR.

The \fBresize\fR command \fBdoes not\fR manipulate the size of underlying
partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
can expand the partition before enlarging the filesystem and shrink the
partition after reducing the size of the filesystem.  This can done using
\fBfdisk(8)\fR or \fBparted(8)\fR to delete the existing partition and recreate
it with the new desired size.  When recreating the partition make sure to use
the same starting disk cylinder as before.
.TP

\fBfilesystem label\fP\fI <dev> [newlabel]\fP
Show or update the label of a filesystem. \fI<dev>\fR is used to identify the
filesystem. 
If a \fInewlabel\fR optional argument is passed, the label is changed. The
following constraints exist for a label:
.IP
- the maximum allowable length shall be less or equal than 256 chars
.IP
- the label shall not  contain the '/' or '\\' characters.

NOTE: Currently there are the following limitations:
.IP
- the filesystem has to be unmounted
.IP
- the filesystem should not have more than one device.
.TP

\fBfilesystem show\fR [--all-devices|<uuid>|<label>]\fR
Show the btrfs filesystem with some additional info. If no \fIUUID\fP or 
\fIlabel\fP is passed, \fBbtrfs\fR show info of all the btrfs filesystem.
If \fB--all-devices\fP is passed, all the devices under /dev are scanned;
otherwise the devices list is extracted from the /proc/partitions file.
.TP

\fBfilesystem balance\fR \fI<path>\fR
Balance the chunks of the filesystem identified by \fI<path>\fR
across the devices.
.TP

\fBdevice stats\fP [-z] {\fI<path>\fP|\fI<device>\fP}
Read and print the device IO stats for all devices of the filesystem
identified by \fI<path>\fR or for a single \fI<device>\fR.

.RS
\fIOptions\fR
.TP
.B -z
Reset stats to zero after reading them.
.RE
.TP

\fBdevice add\fR\fI <dev> [<dev>..] <path>\fR
Add device(s) to the filesystem identified by \fI<path>\fR.
.TP

\fBdevice delete\fR\fI <dev> [<dev>..] <path>\fR
Remove device(s) from a filesystem identified by \fI<path>\fR.
.TP

\fBdevice scan\fR \fI[--all-devices|<device> [<device>...]\fR
If one or more devices are passed, these are scanned for a btrfs filesystem. 
If no devices are passed, \fBbtrfs\fR scans all the block devices listed
in the /proc/partitions file.
Finally, if \fB--all-devices\fP is passed, all the devices under /dev are 
scanned.
.TP

\fBreplace start\fR \fI[-Bfr] <srcdev>|<devid> <targetdev> <path>\fR
Replace device of a btrfs filesystem.
On a live filesystem, duplicate the data to the target device which
is currently stored on the source device. If the source device is not
available anymore, or if the \fB-r\fR option is set, the data is built
only using the RAID redundancy mechanisms. After completion of the
operation, the source device is removed from the filesystem.
If the \fIsrcdev\fR is a numerical value, it is assumed to be the device id
of the filesystem which is mounted at mount_point, otherwise is is
the path to the source device. If the source device is disconnected,
from the system, you have to use the \fIdevid\fR parameter format.
The targetdev needs to be same size or larger than the \fIsrcdev\fR.

.RS
\fIOptions\fR
.TP
.B -r
only read from \fIsrcdev\fR if no other zero-defect mirror exists (enable
this if your drive has lots of read errors, the access would be very slow)
.TP
.B -f
force using and overwriting \fItargetdev\fR even if it looks like
containing a valid btrfs filesystem. A valid filesystem is
assumed if a btrfs superblock is found which contains a
correct checksum. Devices which are currently mounted are
never allowed to be used as the \fItargetdev\fR
.TP
.B -B
do not background
.RE
.TP

\fBreplace status\fR \fI[-1] <path>\fR
Print status and progress information of a running device replace operation.

.RS
\fIOptions\fR
.TP
.B -1
print once instead of print continously until the replace
operation finishes (or is canceled)
.RE
.TP

\fBreplace cancel\fR \fI<path>\fR
Cancel a running device replace operation.
.TP

\fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
Start a scrub on all devices of the filesystem identified by \fI<path>\fR or on
a single \fI<device>\fR. Without options, scrub is started as a background
process. Progress can be obtained with the \fBscrub status\fR command. Scrubbing
involves reading all data from all disks and verifying checksums. Errors are
corrected along the way if possible.
.RS

\fIOptions\fR
.IP -B 5
Do not background and print scrub statistics when finished.
.IP -d 5
Print separate statistics for each device of the filesystem (-B only).
.IP -q 5
Quiet. Omit error messages and statistics.
.IP -r 5
Read only mode. Do not attempt to correct anything.
.IP -u 5
Scrub unused space as well. (NOT IMPLEMENTED)
.RE
.TP

\fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP}
If a scrub is running on the filesystem identified by \fI<path>\fR, cancel it.
Progress is saved in the scrub progress file and scrubbing can be resumed later
using the \fBscrub resume\fR command.
If a \fI<device>\fR is given, the corresponding filesystem is found and
\fBscrub cancel\fP behaves as if it was called on that filesystem.
.TP

\fBscrub resume\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP}
Resume a canceled or interrupted scrub cycle on the filesystem identified by
\fI<path>\fR or on a given \fI<device>\fR. Does not start a new scrub if the
last scrub finished successfully.
.RS

\fIOptions\fR
.TP
see \fBscrub start\fP.
.RE
.TP

\fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP}
Show status of a running scrub for the filesystem identified by \fI<path>\fR or
for the specified \fI<device>\fR.
If no scrub is running, show statistics of the last finished or canceled scrub
for that filesystem or device.
.RS

\fIOptions\fR
.IP -d 5
Print separate statistics for each device of the filesystem.
.RE
.TP

\fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP
Resolves an <inode> in subvolume <path> to all filesystem paths.
.RS

\fIOptions\fR
.IP -v 5
verbose mode. print count of returned paths and ioctl() return value
.RE
.TP

\fBinspect-internal logical-resolve\fP [-Pv] [-s bufsize] \fI<logical>\fP \fI<path>\fP
Resolves a <logical> address in the filesystem mounted at <path> to all inodes.
By default, each inode is then resolved to a file system path (similar to the
\fBinode-resolve\fP subcommand).
.RS

\fIOptions\fR
.IP -P 5
skip the path resolving and print the inodes instead
.IP -v 5
verbose mode. print count of returned paths and all ioctl() return values
.IP -s bufsize 5
set inode container's size. This is used to increase inode container's size in case it is
not enough to read all the resolved results. The max value one can set is 64k.
.RE

.SH EXIT STATUS
\fBbtrfs\fR returns a zero exist status if it succeeds. Non zero is returned in
case of failure.

.SH AVAILABILITY
.B btrfs
is part of btrfs-progs. Btrfs filesystem is currently under heavy development,
and not suitable for any uses other than benchmarking and review.
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
further details.
.SH SEE ALSO
.BR mkfs.btrfs (8)