216 lines
7.2 KiB
Groff
216 lines
7.2 KiB
Groff
.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 <source> [<dest>/]<name>\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBsubvolume delete\fP\fI <subvolume>\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBsubvolume create\fP\fI [<dest>/]<name>\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBsubvolume list\fP\fI <path>\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBsubvolume set-default\fP\fI <id> <path>\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP
|
|
.PP
|
|
\fBbtrfs\fP \fBfilesystem resize\fP\fI [+/\-]<size>[gkm]|max <filesystem>\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBfilesystem defrag\fP\fI [options] <file>|<dir> [<file>|<dir>...]\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 \fBfilesystem defragment\fP\fI <file>|<dir> [<file>|<dir>...]\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBdevice scan\fP\fI [<device>...]\fP
|
|
.PP
|
|
\fBbtrfs\fP \fBdevice show\fP\fI [<device>|<uuid>|<label>]\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 \fBhelp|\-\-help|\-h \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
|
|
returnsfilesystem 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 <source> [<dest>/]<name>\fR
|
|
Create a writable 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.
|
|
.TP
|
|
|
|
\fBsubvolume delete\fR\fI <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 <path>\fR
|
|
List the subvolumes present in the filesystem \fI<path>\fR. For every
|
|
subvolume is showed the subvolume ID (second column),
|
|
the ID of the \fItop level\fR
|
|
subvolume (fifth column), and the path (seventh column) relative to the
|
|
\fItop level\fR subvolume.
|
|
These <ID> may be used by the \fBsubvolume set-default\fR command, or at
|
|
mount time via the \fIsubvol=\fR option.
|
|
.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
|
|
|
|
\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 deframention can be specified by \fIstart\fR and \fIlen\fR. Any extent bigger than \fIthresh\fR will be considered already defragged. Use 0 to take the kernel default, and use 1 to say eveery 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.
|
|
\fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR
|
|
List the recently modified files in a subvolume, after \fI<last_gen>\fR ID.
|
|
.TP
|
|
|
|
\fBdevice scan\fR \fI[<device>...]\fR
|
|
Scan devices for a btrfs filesystem. If no devices are passed, \fBbtrfs\fR scans
|
|
all the block devices.
|
|
.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 [+/\-]<size>[gkm]|max <path>\fR
|
|
Resize a filesystem identified by \fI<path>\fR.
|
|
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
|
|
the units designators: 'K', 'M', or 'G', kilobytes, megabytes, or gigabytes,
|
|
respectively.
|
|
|
|
If 'max' is passed, the filesystem will occupy all available space on the
|
|
volume(s).
|
|
|
|
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.
|
|
.TP
|
|
|
|
\fBbtrfs\fP \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 costraints exist for a label:
|
|
.IP
|
|
- the maximum allowable lenght 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 [<uuid>|<label>]\fR
|
|
Show the btrfs filesystem with some additional info. If no UUID or label is
|
|
passed, \fBbtrfs\fR show info of all the btrfs filesystem.
|
|
.TP
|
|
|
|
\fBdevice balance\fR \fI<path>\fR
|
|
Balance the chunks of the filesystem identified by \fI<path>\fR
|
|
across the devices.
|
|
.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.
|
|
.PP
|
|
|
|
.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)
|