“btrfs” command examples to Create and Manage Btrfs File System

Btrfs is an open-source, general-purpose file system for Linux. The name derives from the use of B-trees to store internal file system structures. Different names are used for the file system, including “Butter F S” and “B-tree F S.” Development of Btrfs began at Oracle in 2007, and now a number of companies (including Red Hat, Fujitsu, Intel, SUSE, and many others) are contributing to the development effort. Btrfs is included in the mainline Linux kernel.

btrfs Utility

Use the btrfs command to manage and display information about a Btrfs file system. The command requires a subcommand. Enter btrfs without any arguments to list the subcommands:

# btrfs
usage: btrfs [--help] [--version] [group] [[group]...] [command] [args]

Command groups:
  subvolume         manage subvolumes: create, delete, list, etc
  filesystem        overall filesystem tasks and information
  balance           balance data across devices, or change block groups using filters
  device            manage and query devices in the filesystem
  scrub             verify checksums of data and metadata
  rescue            toolbox for specific rescue operations
  inspect-internal  query various internal information
  property          modify properties of filesystem objects
  quota             manage filesystem quota settings
  qgroup            manage quota groups
  replace           replace a device in the filesystem

Commands:
  check             Check structural integrity of a filesystem (unmounted).
  restore           Try to restore files from a damaged filesystem (unmounted)
  send              Send the subvolume(s) to stdout.
  receive           Receive subvolumes from a stream
  help              Display help information
  version           Display btrfs-progs version

For an overview of a given command use 'btrfs command --help'
or 'btrfs [command...] --help --full' to print all available options.
Any command name can be shortened as far as it stays unambiguous,
however it is recommended to use full command names in scripts.
All command groups have their manual page named 'btrfs-[group]'.

btrfs subvolume utilities

Use the btrfs subvolume command to manage and report on Btrfs subvolumes. Below are some of the examples of creating btrfs subvolumes and viewing information about them.

1. Create a btrfs subvolume

Use the btrfs subvolume create command to create a subvolume. The following example creates a subvolume named SV1 on a Btrfs file system mounted on /btrfs:

# btrfs subvolume create /btrfs/SV1
Create subvolume '/btrfs/SV1'

2. View btrfs subvolumes

Use the btrfs subvolume list command to view only the subvolumes in a Btrfs file system, as in this example:

# btrfs subvolume list /btrfs
ID 257 gen 12 top level 5 path SV1
ID 258 gen 9 top level 5 path SV1-snap

This command also displays the subvolume ID (257), root ID generation of the B-tree (12), and the top-level ID (5).

2. Create btrfs subvolume snapshots

Use the btrfs subvolume snapshot command to create a writable/readable snapshot of a subvolume. The following example creates a snapshot of the SV1 subvolume:

# btrfs subvolume snapshot /btrfs/SV1 /btrfs/SV1-snap
Create a snapshot of ‘/btrfs/SV1’ in ‘/btrfs/SV1-snap’

Use the btrfs subvolume snapshot -r option to create a read-only snapshot:

# btrfs subvolume snapshot –r /btrfs/SV1 /btrfs/SV1-rosnap 
Create a readonly snapshot of ‘/btrfs/SV1’ in ‘/btrfs/SV1-rosnap’

btrfs filesystem Utilities

Use the btrfs filesystem command to manage and report on Btrfs file systems. The list of the available commands is as follows:

• btrfs filesystem df
• btrfs filesystem show
• btrfs filesystem sync
• btrfs filesystem defragment
• btrfs filesystem resize
• btrfs filesystem balance
• btrfs filesystem label

1. btrfs filesystem df Utility

When the file system is mounted and has a file copied to it, the output of the df command may produce inaccurate information for the Btrfs file system. To get accurate space information for a Btrfs file system, use the btrfs filesystem df command:

# btrfs filesystem df /btrfs
Data, single: total=8.00MiB, used=5.87MiB
System, DUP: total=8.00MiB, used=16.00KiB
Metadata, DUP: total=1.00GiB, used=144.00KiB
GlobalReserve, single: total=16.00MiB, used=0.00B

2. btrfs filesystem show|sync Utilities

Use the btrfs filesystem show command to display the structure of a file system. The syntax follows:

# btrfs filesystem show [options|[path]|[uuid]]

1. If you omit the optional path and uuid, the command shows information about all the Btrfs file systems. The following example displays the structure of a Btrfs file system:

# btrfs filesystem show
Label: none  uuid: 11fdc4b4-fe4f-4a73-9d7c-35859edbcecd
	Total devices 1 FS bytes used 6.03MiB
	devid    1 size 10.00GiB used 2.02GiB path /dev/sda

2. Use the btrfs filesystem sync command to force a sync for the file system. The file system must be mounted. To force a sync of the file system mounted on /btrfs:

# btrfs filesystem sync /btrfs 
FSSync '/btrfs'

3. btrfs filesystem defragment Utility

Btrfs provides online defragmentation of a file system, file, or directory. The online defragmentation facility reorganizes data into contiguous chunks wherever possible to create larger sections of available disk space and to improve read and write performance. Use the btrfs filesystem defragment command to defragment a file or a directory.

# btrfs filesystem defragment [options] [file]|[dir] [...]

The available options include the following:

You can set up automatic defragmentation by specifying the "-o autodefrag" option when you mount the file system. Do not defragment with kernels up to version 2.6.37 if you have created snapshots or made snapshots of files by using the "cp --reflink" option. Btrfs in these earlier kernels unlinks the copy-on-write copies of data.

4. btrfs filesystem resize Utility

Btrfs provides online resizing of a file system. Use the "btrfs filesystem resize" command to resize a file system. You must have space available to accommodate the resizing because the command has no effect on the underlying devices. The syntax is as follows:

btrfs filesystem resize [devid:][+/-][newsize][gkm]|[devid:]max [path]

Descriptions of the parameters:

• + newsize – Increases the file system size by newsize amount
• - newsize – Decreases the file system size by newsize amount
• newsize – Specifies the newsize amount
• g, k, or m – Specifies the unit of newsize (GB, KB, or MB). If no units are specified, the parameter defaults to bytes.
• max – Specifies that the file system occupies all available space

For example, to reduce the size of the file system by 2 GB:

# btrfs filesystem resize -2G /btrfs 
Resize '/btrfs/'' of '-2G'

5. btrfs device Utilities

Use the btrfs device command to manage devices on Btrfs file systems. The "btrfs device scan" command scans physical devices looking for members of a Btrfs volume. This command allows a multiple-disk Btrfs file system to be mounted without specifying all the disks on the mount command. You do not need to run btrfs device scan from the command line, because udev automatically runs btrfs device scan on boot.

1. Use the btrfs device add command to add a device to a mounted file system, as in this example:

# btrfs device add /dev/sdd /btrfs

2. Use the btrfs filesystem balance command after adding a device:

# btrfs filesystem balance /btrfs

3. Use the btrfs device delete command to remove a device from a file system:

# btrfs device delete /dev/sdd /btrfs

6. btrfs scrub Utilities

Use the btrfs scrub command to manage scrubbing on Btrfs file systems. Scrubbing is performed in the background by default. It attempts to report and repair bad blocks on the file system. Available commands include:

• btrfs scrub start
• btrfs scrub cancel
• btrfs scrub resume
• btrfs scrub status

1. Use the btrfs scrub start command to start a scrub on all the devices of a file system or on a single device.

# btrfs scrub start /btrfs

2. Use the btrfs scrub status command to get the status of a scrub job. The following example includes detailed scrub information about each device in the file system:

# btrfs scrub status –dR /btrfs

3. Use the btrfs scrub cancel command to cancel a running scrub job:

# btrfs scrub cancel /btrfs

4. Use the btrfs scrub resume command to resume a previously canceled or interrupted scrub:

# btrfs scrub resume /btrfs

7. btrfs filesyetm label

Use the "btrfs filesystem label" command to display the filesystem label. For example:

# btrfs filesystem label /btrfs
Btrfs