NAME¶

btrfs - control a btrfs filesystem

SYNOPSIS¶

btrfs subvolume snapshot [-r] <source> [<dest>/]<name> btrfs subvolume delete <subvolume> btrfs subvolume create [<dest>/]<name> btrfs subvolume list [-p] <path> btrfs subvolume set-default <id> <path> btrfs subvolume get-default <path> btrfs filesystem df <path> btrfs filesystem sync <path> btrfs filesystem resize [+/-]<size>[gkm]|max <filesystem> btrfs filesystem label <dev> [newlabel] btrfs filesystem defrag [options] <file>|<dir> [<file>|<dir>...] btrfs subvolume find-new <subvolume> <last_gen> btrfs filesystem balance <path> btrfs filesystem defragment <file>|<dir> [<file>|<dir>...] btrfs filesystem show [--all-devices|<uuid>|<label>] btrfs device scan [--all-devices|<device> [<device>...]] btrfs device add <device> [<device>...] <path> btrfs device delete <device> [<device>...] <path> btrfs scrub start [-Bdqru] {<path>|<device>} btrfs scrub cancel {<path>|<device>} btrfs scrub resume [-Bdqru] {<path>|<device>} btrfs scrub status [-d] {<path>|<device>} btrfs inspect-internal inode-resolve [-v] <inode> <path> btrfs inspect-internal logical-resolve [-Pv] <logical> <path> btrfs help|--help|-h btrfs <command> --help

DESCRIPTION¶

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 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 returnsfilesystem sync If a command is terminated 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* commands.

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 snapshot will be readonly.

 

subvolume delete <subvolume>

Delete the subvolume <subvolume>. If <subvolume> is not a subvolume, btrfs returns an error.

 

subvolume create [<dest>/]<name>

Create a subvolume in <dest> (or in the current directory if <dest> is omitted).

 

subvolume list [-p] <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 command, or at mount time via the subvol= 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.

 

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.

 

filesystem df <path>

Resize a filesystem identified by <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 deframention can be specified by start and len. Any extent bigger than thresh 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.

 

-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

 

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. subvolume find-new <subvolume> <last_gen> List the recently modified files in a subvolume, after <last_gen> ID.

 

filesystem sync <path>

Force a sync for the filesystem identified by <path>.

 

 

filesystem resize [+/-]<size>[gkm]|max <path>

Resize a filesystem identified by <path>. The <size> parameter specifies 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 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 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.

 

btrfs filesystem label <dev> [newlabel]

Show or update the label of a filesystem. <dev> is used to identify the filesystem. If a newlabel optional argument is passed, the label is changed. The following costraints exist for a label:

- the maximum allowable lenght 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 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.

 

scrub start [-Bdqru] {<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 reading all data from all disks and verifying checksums. Errors are corrected along the way if possible.

 

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] {<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.

 

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.

 

inspect-internal inode-resolve [-v] <inode> <path>

Resolves an <inode> in subvolume <path> to all filesystem paths.

 

inspect-internal logical-resolve [-Pv] <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).

EXIT STATUS¶

btrfs returns a zero exist status if it succeeds. Non zero is returned in case of failure.

AVAILABILITY¶

btrfs is part of btrfs-tools. 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 ALSO¶

mkfs.btrfs(8)