BTRFS(8)btrfsBTRFS(8)NAMEbtrfs - control a btrfs filesystem
SYNOPSISbtrfs subvolume snapshot [-r] <source> [<dest>/]<name>
btrfs subvolume delete <subvolume> [<subvolume>...]
btrfs subvolume create [<dest>/]<name>
btrfs subvolume list [-acgoprts] [-G [+|-]value] [-C [+|-]value]
[--sort=rootid,gen,ogen,path] <path>
btrfs subvolume set-default <id> <path>
btrfs subvolume get-default <path>
btrfs subvolume find-new <subvolume> <last_gen>
btrfs subvolume show <path>
btrfs filesystem defragment -c[zlib|lzo] [-l len] [-s start] [-t size]
-[vf] <file>|<dir> [<file>|<dir>...]
btrfs filesystem sync <path>
btrfs filesystem resize [devid:][+/-]<size>[gkm]|[devid:]max <filesys‐
tem>
btrfs filesystem label <dev> [newlabel]
btrfs filesystem balance <path>
btrfs device scan [--all-devices|<device> [<device>...]]
btrfs device stats [-z] {<path>|<device>}
btrfs device add <device> [<device>...] <path>
btrfs device delete <device> [<device>...] <path>
btrfs replace start [-Bfr] <srcdev>|<devid> <targetdev> <path>
btrfs replace status [-1] <path>
btrfs replace cancel <path>
btrfs scrub start [-Bdqru] [-c ioprio_class -n ioprio_classdata]
{<path>|<device>}
btrfs scrub cancel {<path>|<device>}
btrfs scrub resume [-Bdqru] [-c ioprio_class -n ioprio_classdata]
{<path>|<device>}
btrfs scrub status [-d] {<path>|<device>}
btrfs inspect-internal inode-resolve [-v] <inode> <path>
btrfs inspect-internal logical-resolve [-Pv] [-s size] <logical> <path>
btrfs inspect-internal subvolid-resolve <subvolid> <path>
btrfs qgroup assign <src> <dst> <path>
btrfs qgroup remove <src> <dst> <path>
btrfs qgroup create <qgroupid> <path>
btrfs qgroup destroy <qgroupid> <path>
btrfs qgroup show <path>
btrfs qgroup limit [options] <size>|none [<qgroupid>] <path>
btrfs help|--help
btrfs <command> --help
DESCRIPTIONbtrfs 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 btrfs sub snaps instead
of btrfs subvolume snapshot. But btrfs file s is not allowed, because
file s may be interpreted both as filesystem show and as filesystem
sync. In this case btrfs returns filesystem sync If a command is ter‐
minated by --help , the detailed help is showed. If the passed command
matches more commands, detailed help of all the matched commands is
showed. For example btrfs dev --help shows the help of all device* com‐
mands.
COMMANDS
subvolume snapshot [-r] <source> [<dest>/]<name>
Create a writable/readonly snapshot of the subvolume <source>
with the name <name> in the <dest> directory. If <source> is not
a subvolume, btrfs returns an error. If -r is given, the snap‐
shot will be readonly.
subvolume delete <subvolume> [<subvolume>...]
Delete the subvolume <subvolume>. If <subvolume> is not a sub‐
volume, btrfs returns an error.
subvolume create [<dest>/]<name>
Create a subvolume in <dest> (or in the current directory if
<dest> is omitted).
subvolume list [-acgoprts] [-G [+|-]value] [-C [+|-]value]
[--sort=rootid,gen,ogen,path] <path>
List the subvolumes present in the filesystem <path>. 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 top level subvolume.
The subvolume's ID may be used by the subvolume set-default com‐
mand, or at mount time via the subvolid= option. If -p is
given, then parent <ID> is added to the output between ID and
top level. The parent's ID may be used at mount time via the
subvolrootid= option.
-t print the result as a table.
-a print all the subvolumes in the filesystem and distinguish
between absolute and relative path with respect to the given
<path>.
-c print the ogeneration of the subvolume, aliases: ogen or ori‐
gin generation
-g print the generation of the subvolume
-u print the UUID of the subvolume
-o print only subvolumes bellow specified <path>.
-r only readonly subvolumes in the filesystem will be listed.
-s only snapshot subvolumes in the filesystem will be listed.
-G [+|-]value list subvolumes in the filesystem that its genera‐
tion is >=, <= or = value. '+' means >= value, '-' means <=
value, If there is neither '+' nor '-', it means = value.
-C [+|-]value list subvolumes in the filesystem that its ogener‐
ation is >=, <= or = value. The usage is the same to '-g'
option.
--sort=rootid,gen,ogen,path list subvolumes in order by speci‐
fied items. you can add '+' or '-' in front of each items, '+'
means ascending, '-' means descending. The default is ascending.
for --sort you can combine some items together by ',', just like
-sort=+ogen,-gen,path,rootid.
subvolume set-default <id> <path>
Set the subvolume of the filesystem <path> which is mounted as
default. The subvolume is identified by <id>, which is returned
by the subvolume list command.
subvolume get-default <path>
Get the default subvolume of the filesystem <path>. The output
format is similar to subvolume list command.
subvolume find-new <subvolume> <last_gen>
List the recently modified files in a subvolume, after
<last_gen> ID.
subvolume show <path>
Show information of a given subvolume in the <path>.
filesystem defragment -c[zlib|lzo] [-l len] [-s start] [-t size] -[vf]
<file>|<dir> [<file>|<dir>...]
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 start and len. 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.
-v be verbose
-c compress file contents while defragmenting
-f flush filesystem after defragmenting
-s start defragment only from byte start onward
-l len defragment only up to len bytes
-t size defragment only files at least size bytes big
For start, len, size it is possible to append a suffix like k
for 1 KBytes, m for 1 MBytes...
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 cp --reflink.
filesystem sync <path>
Force a sync for the filesystem identified by <path>.
filesystem resize [devid:][+/-]<size>[gkm]|[devid:]max <path>
Resize a filesystem identified by <path> for the underlying
device devid. The devid can be found with btrfs filesystem show
and defaults to 1 if not specified. The <size> parameter speci‐
fies the new size of the filesystem. If the prefix + or - is
present the size is increased or decreased by the quantity
<size>. If no units are specified, the unit of the <size>
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 devid.
The resize command does not 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 fdisk(8) or parted(8) 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.
filesystem label <dev> [newlabel]
Show or update the label of a filesystem. <dev> is used to iden‐
tify the filesystem. If a newlabel optional argument is passed,
the label is changed. The following constraints exist for a
label:
- the maximum allowable length shall be less or equal than 256
chars
- the label shall not contain the '/' or '\' characters.
NOTE: Currently there are the following limitations:
- the filesystem has to be unmounted
- the filesystem should not have more than one device.
filesystem show [--all-devices|<uuid>|<label>]
Show the btrfs filesystem with some additional info. If no UUID
or label is passed, btrfs show info of all the btrfs filesystem.
If --all-devices is passed, all the devices under /dev are
scanned; otherwise the devices list is extracted from the
/proc/partitions file.
filesystem balance <path>
Balance the chunks of the filesystem identified by <path> across
the devices.
device stats [-z] {<path>|<device>}
Read and print the device IO stats for all devices of the
filesystem identified by <path> or for a single <device>.
Options
-z Reset stats to zero after reading them.
device add <dev> [<dev>..] <path>
Add device(s) to the filesystem identified by <path>.
device delete <dev> [<dev>..] <path>
Remove device(s) from a filesystem identified by <path>.
device scan [--all-devices|<device> [<device>...]
If one or more devices are passed, these are scanned for a btrfs
filesystem. If no devices are passed, btrfs scans all the block
devices listed in the /proc/partitions file. Finally, if --all-
devices is passed, all the devices under /dev are scanned.
replace start [-Bfr] <srcdev>|<devid> <targetdev> <path>
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 avail‐
able anymore, or if the -r 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 srcdev 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 devid parame‐
ter format. The targetdev needs to be same size or larger than
the srcdev.
Options
-r only read from srcdev if no other zero-defect mirror
exists (enable this if your drive has lots of read
errors, the access would be very slow)
-f force using and overwriting targetdev 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 cur‐
rently mounted are never allowed to be used as the tar‐
getdev
-B do not background
replace status [-1] <path>
Print status and progress information of a running device
replace operation.
Options
-1 print once instead of print continously until the replace
operation finishes (or is canceled)
replace cancel <path>
Cancel a running device replace operation.
scrub start [-Bdqru] {<path>|<device>}
scrub start [-Bdqru] [-c ioprio_class -n ioprio_classdata]
{<path>|<device>} Start a scrub on all devices of the filesystem
identified by <path> or on a single <device>. Without options,
scrub is started as a background process. Progress can be
obtained with the scrub status command. Scrubbing involves read‐
ing all data from all disks and verifying checksums. Errors are
corrected along the way if possible.
The default IO priority of scrub is the idle class. The priority
can be configured similar to the ionice(1) syntax.
Options
-B Do not background and print scrub statistics when finished.
-d Print separate statistics for each device of the filesystem
(-B only).
-q Quiet. Omit error messages and statistics.
-r Read only mode. Do not attempt to correct anything.
-u Scrub unused space as well. (NOT IMPLEMENTED)
-c Set IO priority class (see ionice(1) manpage).
-n Set IO priority classdata (see ionice(1) manpage).
scrub cancel {<path>|<device>}
If a scrub is running on the filesystem identified by <path>,
cancel it. Progress is saved in the scrub progress file and
scrubbing can be resumed later using the scrub resume command.
If a <device> is given, the corresponding filesystem is found
and scrub cancel behaves as if it was called on that filesystem.
scrub resume [-Bdqru] [-c ioprio_class -n ioprio_classdata]
{<path>|<device>}
Resume a canceled or interrupted scrub cycle on the filesystem
identified by <path> or on a given <device>. Does not start a
new scrub if the last scrub finished successfully.
Options
see scrub start.
scrub status [-d] {<path>|<device>}
Show status of a running scrub for the filesystem identified by
<path> or for the specified <device>. If no scrub is running,
show statistics of the last finished or canceled scrub for that
filesystem or device.
Options
-d Print separate statistics for each device of the filesys‐
tem.
inspect-internal inode-resolve [-v] <inode> <path>
Resolves an <inode> in subvolume <path> to all filesystem paths.
Options
-v verbose mode. print count of returned paths and ioctl()
return value
inspect-internal logical-resolve [-Pv] [-s bufsize] <logical> <path>
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 inode-resolve subcommand).
Options
-P skip the path resolving and print the inodes instead
-v verbose mode. print count of returned paths and all ioctl()
return values
-s 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.
inspect-internal subvolid-resolve <subvolid> <path>
Get file system paths for the given subvolume ID.
btrfs qgroup assign <src> <dst> <path>
Enable subvolume qgroup support for a filesystem.
btrfs qgroup remove <src> <dst> <path>
Remove a subvol from a quota group.
btrfs qgroup create <qgroupid> <path>
Create a subvolume quota group.
btrfs qgroup destroy <qgroupid> <path>
Destroy a subvolume quota group.
btrfs qgroup show <path>
Show all subvolume quota groups.
btrfs qgroup limit [options] <size>|none [<qgroupid>] <path>
Limit the size of a subvolume quota group.
EXIT STATUSbtrfs returns a zero exist status if it succeeds. Non zero is returned
in case of failure.
AVAILABILITYbtrfs 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.
SEE ALSOmkfs.btrfs(8), ionice(1)btrfsBTRFS(8)