Btrfs(command)

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
(Note about the snapshot: Removing my incorrect statement about being able to snapshot a directory with 'btrfsctl -s')
m (superfluous category removed)
Line 188: Line 188:
  
  
[[Category:Documentation]] [[Category:Btrfs]]
+
[[Category:Documentation]]

Revision as of 17:20, 4 April 2011

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 dev s is not allowed, because dev s may be interpreted both as device show and as device scan. In this case btrfs returns an error.

If a command is terminated by --help , the relevant help is showed. If the passed command matches more commands, the help of all the matched commands are showed. For example btrfs dev --help shows the help of all device* command.

Contents

Usage

btrfs help
Usage:
        btrfs subvolume snapshot <source> [<dest>/]<name>
                Create a writable snapshot of the subvolume <source> with
                the name <name> in the <dest> directory.
        btrfs subvolume delete <subvolume>
                Delete the subvolume <subvolume>.
        btrfs subvolume create [<dest>/]<name>
                Create a subvolume in <dest> (or the current directory if
                not passed).
        btrfs subvolume list <path>
                List the snapshot/subvolume of a filesystem.
        btrfs subvolume find-new <path> <last_gen>
                List the recently modified files in a filesystem.
        btrfs filesystem defragment [-vcf] [-s start] [-l len] [-t size] <file>|<dir> [<file>|<dir>...]
                Defragment a file or a directory.
        btrfs subvolume set-default <id> <path>
                Set the subvolume of the filesystem <path> which will be mounted
                as default.
        btrfs filesystem sync <path>
                Force a sync on the filesystem <path>.
        btrfs filesystem resize [<devid>:][+/-]<newsize>[gkm]|max <filesystem>
                Resize the file system. If 'max' is passed, the filesystem
                will occupe all available space on the device. <devid> refers to
                the device which was grow or shrink.
        btrfs filesystem show [<uuid>|<label>]
                Show the info of a btrfs filesystem. If no <uuid> or <label>
                is passed, info of all the btrfs filesystem are shown.
        btrfs filesystem df <path>
                Show space usage information for a mount point.
        btrfs filesystem balance <path>
                Balance the chunks across the device.
        btrfs device scan [<device> [<device>..]
                Scan all device for or the passed device for a btrfs
                filesystem.
        btrfs device add <dev> [<dev>..] <path>
                Add a device to a filesystem.
        btrfs device delete <dev> [<dev>..] <path>
                Remove a device from a filesystem.

        btrfs help|--help|-h
                Show the help.

COMMANDS

Note: some btrfs subcommand may require the filesystem to be mounted.
  • subvolume snapshot <source> [<dest>/]<name>

Create a writable snapshot of the subvolume <source> with the name <name> in the <dest> directory. If <source> is not a sub- volume, btrfs returns an error.

  • subvolume delete <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 <path>

List the subvolumes present in the filesystem <path>. For every subvolume is showed the subvolume ID (second column), the ID of the top level subvolume (fifth column), and the path (seventh column) relative to the top level subvolume. These <ID> may be used by the subvolume set-default command, or at mount time via the subvol= 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.

  • filesystem defragment <file>|<dir> [<file>|<dir>...]

Defragment files and/or directories.

  • device scan [<device> [<device>..]]

Scan devices for a btrfs filesystem. If no devices are passed, btrfs scans all the block devices.

  • filesystem sync <path>

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

  • filesystem resize [<devid>:][+/-]<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.

<devid> is the id of the device which was grow or shrink, as show by the command btrfs filesystem show. If nothing is passed, the device devid=1 is used.

  • filesystem show [<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.

  • filesystem balance <path>

Balance the chunks of the filesystem identified by <path> across the devices.

  • subvolume find-new <subvolume> <last_gen>

List the recently modified files in a subvolume, after <last_gen> ID.

  • 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>.

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

Note about the snapshot

It is possible to snapshot only the root volume or a subvolume. It is not possible to snapshot a directory.

A snapshot is not recursive. If a [sub]volume is snapshotted, the snapshot will not contain the enclosed subvolumes.

EXAMPLES

Suppose your BTRFS filesystem mountpoint is /mnt:

create a subvolume under /mnt/test. The new subvolume will be called NewSubVol

btrfs subvolume create /mnt/test/NewSubVol 

Create a snapshot of the subvolume NewSubVol.

btrfs subvolume snapshot /mnt/test/NewSubVol /mnt/test/NewSnapShot 

Delete a snapshot and a subvolume

btrfs subvolume delete /mnt/test/NewSnapShot
btrfs subvolume delete /mnt/test/NewSubVol

Add 2GB to the FS

btrfs filesystem resize +2g /mnt

Shrink the FS by 4GB

btrfs filesystem resize -4g /mnt

Explicitly set the FS size

btrfs filesystem resize 20g /mnt

Use 'max' to grow the FS to the limit of the device

btrfs filesystem resize max /mnt
Personal tools