btrfs-balance

title: btrfs-balance(8)

text:
# btrfs-balance(8)

## NAME
btrfs-balance - balance block groups on a btrfs filesystem

## SYNOPSIS
btrfs balance <subcommand> <args>

## DESCRIPTION
The primary purpose of the balance feature is to spread block groups across all devices so they match constraints defined by the respective profiles. See mkfs.btrfs(8) <> section PROFILES <#man-mkfs-profiles> for more details. The scope of the balancing process can be further tuned by use of filters that can select the block groups to process. Balance works only on a mounted filesystem. Extent sharing is preserved and reflinks are not broken. Files are not defragmented nor recompressed, file extents are preserved but the physical location on devices will change.

The balance operation is cancellable by the user. The on-disk state of the filesystem is always consistent so an unexpected interruption (e.g. system crash, reboot) does not corrupt the filesystem. The progress of the balance operation is temporarily stored as an internal state and will be resumed upon mount, unless the mount option skip_balance is specified.

Warning:

Running balance without filters will take a lot of time as it basically move data/metadata from the whole filesystem and needs to update all block pointers.

The filters can be used to perform following actions:

- convert block group profiles (filter convert)

- make block group usage more compact (filter usage)

- perform actions only on a given device (filters devid, drange)

The filters can be applied to a combination of block group types (data, metadata, system). Note that changing only the system type needs the force option. Otherwise system gets automatically converted whenever metadata profile is converted.

When metadata redundancy is reduced (e.g. from RAID1 to single) the force option is also required and it is noted in system log.

Note:

The balance operation needs enough work space, i.e. space that is completely unused in the filesystem, otherwise this may lead to ENOSPC reports. See the section ENOSPC for more details.

## COMPATIBILITY
Note:

The balance subcommand also exists under the btrfs filesystem namespace. This still works for backward compatibility but is deprecated and should not be used any more.

Note:

A short syntax btrfs balance <path> works due to backward compatibility but is deprecated and should not be used any more. Use btrfs balance start command instead.

## PERFORMANCE IMPLICATIONS
Balancing operations are very IO intensive and can also be quite CPU intensive, impacting other ongoing filesystem operations. Typically large amounts of data are copied from one location to another, with corresponding metadata updates.

Depending upon the block group layout, it can also be seek heavy. Performance on rotational devices is noticeably worse compared to SSDs or fast arrays.

## SUBCOMMAND
cancel <path>

cancels a running or paused balance, the command will block and wait until the current block group being processed completes Since kernel 5.7 the response time of the cancellation is significantly improved, on older kernels it might take a long time until currently processed chunk is completely finished.

pause <path>

pause running balance operation, this will store the state of the balance progress and used filters to the filesystem

resume <path>

resume interrupted balance, the balance status must be stored on the filesystem from previous run, e.g. after it was paused or forcibly interrupted and mounted again with skip_balance

start [options] <path>

start the balance operation according to the specified filters, without any filters the data and metadata from the whole filesystem are moved. The process runs in the foreground. Note:

The balance command without filters will basically move everything in the filesystem to a new physical location on devices (i.e. it does not affect the logical properties of file extents like offsets within files and extent sharing). The run time is potentially very long, depending on the filesystem size. To prevent starting a full balance by accident, the user is warned and has a few seconds to cancel the operation before it starts. The warning and delay can be skipped with --full-balance option.

Please note that the filters must be written together with the -d, -m and -s options, because they're optional and bare -d and -m also work and mean no filters.

Note:

When the target profile for conversion filter is raid5 or raid6, there's a safety timeout of 10 seconds to warn users about the status of the feature

Options

-d[<filters>]

act on data block groups, see section FILTERS for details about filters

-m[<filters>]

act on metadata chunks, see FILTERS for details about filters

-s[<filters>]

act on system chunks (requires -f), see FILTERS for details about filters.

-f

force a reduction of metadata integrity, e.g. when going from raid1 to single, or skip safety timeout when the target conversion profile is raid5 or raid6

--background|--bg

run the balance operation asynchronously in the background, uses fork(2) <https://man7.org/linux/man-pages/man2/fork.2.html> to start the process that calls the kernel ioctl

--enqueue

wait if there's another exclusive operation running, otherwise continue

-v

(deprecated) alias for global '-v' option

status [-v] <path>

Show status of running or paused balance. Options

-v

(deprecated) alias for global -v option

## FILTERS
From kernel 3.3 onwards, BTRFS balance can limit its action to a subset of the whole filesystem, and can be used to change the replication configuration (e.g. convert data from single to RAID1).

Balance can be limited to a block group profile with the following options:

- -d for data block groups

- -m for metadata block groups (also implicitly applies to -s)

- -s for system block groups

The options have an optional parameter which means that the parameter must start right after the option without a space (this is mandatory getopt syntax), like -dusage=10. Options for all block group types can be specified in one command.

A filter has the following structure: filter[=params][,filter=...]

To combine multiple filters use ,, without spaces. Example: -dconvert=raid1,soft Note that most filters can only be specified once per block group profile (data/metadata/system block groups).

BTRFS can have different profiles on a single device or the same profile on multiple device.

The main reason why you want to have different profiles for data and metadata is to provide additional protection of the filesystem's metadata when devices fail, since a single sector of unrecoverable metadata will break the filesystem, while a single sector of lost data can be trivially recovered by deleting the broken file.

Before changing profiles, make sure there is enough unallocated space on existing drives to create new metadata block groups (for filesystems over 50GiB, this is 1GB * (number_of_devices + 2)).

Default profiles on BTRFS are:

- data: single

-

metadata:

- single devices: dup

- multiple devices: raid1

The available filter types are:

### Filter types
profiles=<profiles>

Balances only block groups with the given profiles. Parameters are a list of profile names separated by | (pipe).

usage=<percent>, usage=<range>

Balances only block groups with usage under the given percentage. The value of 0 is allowed and will clean up completely unused block groups, this should not require any new work space allocated. You may want to use usage=0 in case balance is returning ENOSPC and your filesystem is not too full. The argument may be a single value or a range. The single value N means at most N percent used, equivalent to ..N range syntax. Kernels prior to 4.4 accept only the single value format. The minimum range boundary is inclusive, maximum is exclusive.

This filter can only be specified once per block group profile.

devid=<id>

Balances only block groups which have at least one chunk on the given device. To list devices with ids use btrfs filesystem show. This filter can only be specified once per block group profile.

drange=<range>

Balance only block groups which overlap with the given byte range on any device. Use in conjunction with devid to filter on a specific device. The parameter is a range specified as start..end. This filter can only be specified once per block group profile.

vrange=<range>

Balance only block groups which overlap with the given byte range in the filesystem's internal virtual address space. This is the address space that most reports from btrfs in the kernel log use. The parameter is a range specified as start..end. This filter can only be specified once per block group profile.

convert=<profile>

Convert each selected block group to the given profile name identified by parameters. This filter can only be specified once per block group profile.

Note:

Starting with kernel 4.5, the data chunks can be converted to/from the DUP profile on a single device. Starting with kernel 4.6, all profiles can be converted to/from DUP on multi-device filesystems.

Warning:

Bad or missing device are not detected immediately during runtime and this depends on some later event like failed write or failed transaction commit. If there's a known failing device, or a device deleted by /sys/block/<dev>/device/delete interface, the device will be still accessed and written to. In such case, one should not convert to a profile with lower redundancy (e.g. from RAID1 to SINGLE), as attempts to create new chunks on the new devices will cause various problems.

The proper action is to use btrfs replace or btrfs device remove to handle the failing/missing device first. Then convert will work with all devices correctly.

limit=<number>, limit=<range>

Process only given number of chunks, after all filters are applied. This can be used to specifically target a chunk in connection with other filters (drange, vrange) or just simply limit the amount of work done by a single balance run. The argument may be a single value or a range. The single value N means at most N chunks, equivalent to ..N range syntax. Kernels prior to 4.4 accept only the single value format. The range minimum and maximum are inclusive.

This filter can only be specified once per block group profile.

stripes=<range>

Balance only block groups which have the given number of stripes. The parameter is a range specified as start..end. Makes sense for block group profiles that utilize striping, i.e. RAID0/10/5/6. The range minimum and maximum are inclusive. This filter can only be specified once per block group profile.

soft

Takes no parameters. Only has meaning when converting between profiles, or When doing convert from one profile to another and soft mode is on, chunks that already have the target profile are left untouched. This is useful e.g. when half of the filesystem was converted earlier but got cancelled. The soft mode switch is (like every other filter) per-type. For example, this means that we can convert metadata chunks the "hard" way while converting data chunks selectively with soft switch.

This filter can only be specified once per block group profile.

Profile names, used in profiles and convert are one of:

- raid0

- raid1

- raid1c3

- raid1c4

- raid10

- raid5

- raid6

- dup

- single

The mixed data/metadata profiles can be converted in the same way, but conversion between mixed and non-mixed is not implemented. For the constraints of the profiles please refer to mkfs.btrfs(8) <> section PROFILES <#man-mkfs-profiles>.

## ENOSPC
The way balance operates, it usually needs to temporarily create a new block group and move the old data there, before the old block group can be removed. For that it needs the work space, otherwise it fails for ENOSPC reasons. This is not the same ENOSPC as if the free space is exhausted. This refers to the space on the level of block groups, which are bigger parts of the filesystem that contain many file extents.

The free work space can be calculated from the output of the btrfs filesystem show command:

```
Label: 'BTRFS'  uuid: 8a9d72cd-ead3-469d-b371-9c7203276265

        Total devices 2 FS bytes used 77.03GiB

        devid    1 size 53.90GiB used 51.90GiB path /dev/sdc2

        devid    2 size 53.90GiB used 51.90GiB path /dev/sde1
```

size - used = free work space

53.90GiB - 51.90GiB = 2.00GiB

An example of a filter that does not require workspace is usage=0. This will scan through all unused block groups of a given type and will reclaim the space. After that it might be possible to run other filters.

CONVERSIONS ON MULTIPLE DEVICES

Conversion to profiles based on striping (RAID0, RAID5/6) require the work space on each device. An interrupted balance may leave partially filled block groups that consume the work space.

## EXAMPLES
A more comprehensive example when going from one to multiple devices, and back, can be found in section TYPICAL USECASES of btrfs-device(8) <>.

### MAKING BLOCK GROUP LAYOUT MORE COMPACT
The layout of block groups is not normally visible; most tools report only summarized numbers of free or used space, but there are still some hints provided.

Let's use the following real life example and start with the output:

```
$ btrfs filesystem df /path
Data, single: total=75.81GiB, used=64.44GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.84GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

Roughly calculating for data, 75G - 64G = 11G, the used/total ratio is about 85%. How can we can interpret that:

- chunks are filled by 85% on average, i.e. the usage filter with anything smaller than 85 will likely not affect anything

- in a more realistic scenario, the space is distributed unevenly, we can assume there are completely used chunks and the remaining are partially filled

Compacting the layout could be used on both. In the former case it would spread data of a given chunk to the others and removing it. Here we can estimate that roughly 850 MiB of data have to be moved (85% of a 1 GiB chunk).

In the latter case, targeting the partially used chunks will have to move less data and thus will be faster. A typical filter command would look like:

```
# btrfs balance start -dusage=50 /path
Done, had to relocate 2 out of 97 chunks
$ btrfs filesystem df /path
Data, single: total=74.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.84GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

As you can see, the total amount of data is decreased by just 1 GiB, which is an expected result. Let's see what will happen when we increase the estimated usage filter.

```
# btrfs balance start -dusage=85 /path
Done, had to relocate 13 out of 95 chunks
$ btrfs filesystem df /path
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.85GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

Now the used/total ratio is about 94% and we moved about 74G - 68G = 6G of data to the remaining block groups, i.e. the 6GiB are now free of filesystem structures, and can be reused for new data or metadata block groups.

We can do a similar exercise with the metadata block groups, but this should not typically be necessary, unless the used/total ratio is really off. Here the ratio is roughly 50% but the difference as an absolute number is "a few gigabytes", which can be considered normal for a workload with snapshots or reflinks updated frequently.

```
# btrfs balance start -musage=50 /path
Done, had to relocate 4 out of 89 chunks
$ btrfs filesystem df /path
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=14.87GiB, used=8.85GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

Just 1 GiB decrease, which possibly means there are block groups with good utilization. Making the metadata layout more compact would in turn require updating more metadata structures, i.e. lots of IO. As running out of metadata space is a more severe problem, it's not necessary to keep the utilization ratio too high. For the purpose of this example, let's see the effects of further compaction:

```
# btrfs balance start -musage=70 /path
Done, had to relocate 13 out of 88 chunks
$ btrfs filesystem df .
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=11.97GiB, used=8.83GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

### GETTING RID OF COMPLETELY UNUSED BLOCK GROUPS
Normally the balance operation needs a work space, to temporarily move the data before the old block groups gets removed. If there's no work space, it ends with no space left.

There's a special case when the block groups are completely unused, possibly left after removing lots of files or deleting snapshots. Removing empty block groups is automatic since 3.18. The same can be achieved manually with a notable exception that this operation does not require the work space. Thus it can be used to reclaim unused block groups to make it available.

```
# btrfs balance start -dusage=0 /path
```

This should lead to decrease in the total numbers in the btrfs filesystem df output.

## EXIT STATUS
Unless indicated otherwise below, all btrfs balance subcommands return a zero exit status if they succeed, and non zero in case of failure.

The pause, cancel, and resume subcommands exit with a status of 2 if they fail because a balance operation was not running.

The status subcommand exits with a status of 0 if a balance operation is not running, 1 if the command-line usage is incorrect or a balance operation is still running, and 2 on other errors.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at <https://btrfs.readthedocs.io>.

## SEE ALSO
mkfs.btrfs(8) <>, btrfs-device(8) <>


btrfs-check

package: btrfs-progs

title: btrfs-check(8)

summary: check or repair a btrfs filesystem

text:
# btrfs-check(8)

## NAME
btrfs-check - check or repair a btrfs filesystem

## SYNOPSIS
btrfs check [options] <device>

## DESCRIPTION
The filesystem checker is used to verify structural integrity of a filesystem and attempt to repair it if requested. It is recommended to unmount the filesystem prior to running the check, but it is possible to start checking a mounted filesystem (see --force).

By default, btrfs check will not modify the device but you can reaffirm that by the option --readonly.

btrfsck is an alias of btrfs check command and is now deprecated.

Note:

Even though the filesystem checker requires a device argument, it scans for all devices belonging to the same filesystem, thus it should not cause a difference using different devices of the same filesystem. Furthermore btrfs-check(8) <> will automatically choose the good mirror, thus as long as there is a good copy for metadata, it will not report such case as an error.

Warning:

Do not use --repair unless you are advised to do so by a developer or an experienced user, and then only after having accepted that no fsck successfully repair all types of filesystem corruption. E.g. some other software or hardware bugs can fatally damage a volume.

The structural integrity check verifies if internal filesystem objects or data structures satisfy the constraints, point to the right objects or are correctly connected together.

There are several cross checks that can detect wrong reference counts of shared extents, backreferences, missing extents of inodes, directory and inode connectivity etc.

The amount of memory required can be high, depending on the size of the filesystem, similarly the run time. Check the modes that can also affect that.

## SAFE OR ADVISORY OPTIONS
-b|--backup

use the first valid set of backup roots stored in the superblock This can be combined with --super if some of the superblocks are damaged.

--check-data-csum

verify checksums of data blocks This expects that the filesystem is otherwise OK, and is basically an offline scrub that does not repair data from spare copies.

--chunk-root <bytenr>

use the given offset bytenr for the chunk tree root

-E|--subvol-extents <subvolid>

show extent state for the given subvolume

--mode <MODE>

select mode of operation regarding memory and IO The MODE can be one of:

original

The metadata are read into memory and verified, thus the requirements are high on large filesystems and can even lead to out-of-memory conditions. The possible workaround is to export the block device over network to a machine with enough memory.

lowmem

This mode is supposed to address the high memory consumption at the cost of increased IO when it needs to re-read blocks. This may increase run time.

-p|--progress

indicate progress at various checking phases

-Q|--qgroup-report

verify qgroup accounting and compare against filesystem accounting

-r|--tree-root <bytenr>

use the given offset 'bytenr' for the tree root

--readonly

(default) run in read-only mode, this option exists to calm potential panic when users are going to run the checker

-s|--super <N>

use Nth superblock copy, valid values are 0, 1 or 2 if the respective superblock offset is within the device size This can be used to use a different starting point if some of the primary superblock is damaged.

## DANGEROUS OPTIONS
--repair

enable the repair mode and attempt to fix problems where possible Note:

There's a warning and 10 second delay when this option is run without --force to give users a chance to think twice before running repair, the warnings in documentation have shown to be insufficient.

Note:

Please finish/cancel the running replace/balance before using this command.

--init-csum-tree

create a new checksum tree and recalculate checksums in all files Warning:

Do not blindly use this option to fix checksum mismatch problems.

--init-extent-tree

build the extent tree from scratch Warning:

Do not use unless you know what you're doing.

--force

allow work on a mounted filesystem and skip mount checks. Note that this should work fine on a quiescent or read-only mounted filesystem but may crash if the device is changed externally, e.g. by the kernel module. Note:

It is possible to run with --repair but on a mounted filesystem that will most likely lead to a corruption unless the filesystem is in a quiescent state which may not be possible to guarantee.

This option also skips the delay and warning in the repair mode (see --repair).

## DEPRECATED OR REMOVED OPTIONS
--clear-space-cache v1|v2

completely remove the free space cache of the given version See also the clear_cache mount option.

Warning:

This option is deprecated, please use btrfs rescue clear-space-cache instead, this option would be removed in the future eventually.

## EXIT STATUS
btrfs check returns a zero exit status if it succeeds. Non zero is returned in case of failure.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at <https://btrfs.readthedocs.io>.

## SEE ALSO
mkfs.btrfs(8) <>, btrfs-scrub(8) <>, btrfs-rescue(8) <>

branch: sisyphus


btrfs-convert

title: btrfs-convert(8)

text:
# btrfs-convert(8)

## NAME
btrfs-convert - convert from ext2/3/4 or reiserfs filesystem to btrfs in-place

## SYNOPSIS
btrfs-convert [options] <device>

## DESCRIPTION
The btrfs-convert tool can be used to convert existing source filesystem image to a btrfs filesystem in-place. The original filesystem image is accessible in subvolume named like ext2_saved as file image.

Supported filesystems:

- ext2, ext3, ext4 -- original feature, always built in

- reiserfs -- since version 4.13, optionally built, requires libreiserfscore 3.6.27

- NTFS -- external tool <https://github.com/maharmstone/ntfs2btrfs>

The list of supported source filesystem by a given binary is listed at the end of help (option --help).

Warning:

If you are going to perform rollback to the original filesystem, you should not execute btrfs balance command on the converted filesystem. This will change the extent layout and make btrfs-convert unable to rollback.

The conversion utilizes free space of the original filesystem. The exact estimate of the required space cannot be foretold. The final btrfs metadata might occupy several gigabytes on a hundreds-gigabyte filesystem.

If the ability to rollback is no longer important, the it is recommended to perform a few more steps to transition the btrfs filesystem to a more compact layout. This is because the conversion inherits the original data blocks' fragmentation, and also because the metadata blocks are bound to the original free space layout.

Due to different constraints, it is only possible to convert filesystems that have a supported data block size (i.e. the same that would be valid for mkfs.btrfs). This is typically the system page size (4KiB on x86_64 machines).

Note:

Always consider if a mkfs and file copy would not be a better option than the in-place conversion given what was said above. The conversion depends on 3rd party libraries and the other filesystems could still evolve and add new features. Not all combinations are covered or tested.

BEFORE YOU START

The source filesystem must be clean, e.g. no journal to replay or no repairs needed. The respective fsck utility must be run on the source filesystem prior to conversion. Please refer to the manual pages in case you encounter problems.

For ext2/3/4:

```
# e2fsck -fvy /dev/sdx
```

For reiserfs:

```
# reiserfsck -fy /dev/sdx
```

Skipping that step could lead to incorrect results on the target filesystem, but it may work.

REMOVE THE ORIGINAL FILESYSTEM METADATA

By removing the subvolume named like ext2_saved or reiserfs_saved, all metadata of the original filesystem will be removed:

```
# btrfs subvolume delete /mnt/ext2_saved
```

At this point it is not possible to do a rollback. The filesystem is usable but may be impacted by the fragmentation inherited from the original filesystem.

MAKE FILE DATA MORE CONTIGUOUS

An optional but recommended step is to run defragmentation on the entire filesystem. This will attempt to make file extents more contiguous.

```
# btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs
```

Verbose recursive defragmentation (-v, -r), flush data per-file (-f) with target extent size 32MiB (-t).

ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT

Optional but recommended step.

The metadata block groups after conversion may be smaller than the default size (256MiB or 1GiB). Running a balance will attempt to merge the block groups. This depends on the free space layout (and fragmentation) and may fail due to lack of enough work space. This is a soft error leaving the filesystem usable but the block group layout may remain unchanged.

Note that balance operation takes a lot of time, please see also btrfs-balance(8) <>.

```
# btrfs balance start -m /mnt/btrfs
```

## OPTIONS
--csum <type>, --checksum <type>

Specify the checksum algorithm. Default is crc32c. Valid values are crc32c, xxhash, sha256 or blake2. To mount such filesystem kernel must support the checksums as well.

-d|--no-datasum

disable data checksum calculations and set the NODATASUM file flag, this can speed up the conversion

-i|--no-xattr

ignore xattrs and ACLs of files

-n|--no-inline

disable inlining of small files to metadata blocks, this will decrease the metadata consumption and may help to convert a filesystem with low free space

-N|--nodesize <SIZE>

set filesystem nodesize, the tree block size in which btrfs stores its metadata. The default value is 16KiB (16384) or the page size, whichever is bigger. Must be a multiple of the sectorsize, but not larger than 65536. See mkfs.btrfs(8) <> for more details.

-r|--rollback

rollback to the original ext2/3/4 filesystem if possible

-l|--label <LABEL>

set filesystem label during conversion

-L|--copy-label

use label from the converted filesystem

-O|--features <feature1>[,<feature2>...]

A list of filesystem features enabled the at time of conversion. Not all features are supported by old kernels. To disable a feature, prefix it with ^. Description of the features is in section FILESYSTEM FEATURES <#man-mkfs-filesystem-features> of mkfs.btrfs(8) <>. To see all available features that btrfs-convert supports run:

```
btrfs-convert -O list-all
```

-p|--progress

show progress of conversion (a heartbeat indicator and number of inodes processed), on by default

--no-progress

disable progress and show only the main phases of conversion

--uuid <SPEC>

set the FSID of the new filesystem based on 'SPEC':

- new - (default) generate UUID for the FSID of btrfs

- copy - copy UUID from the source filesystem

- UUID - a conforming UUID value, the 36 byte string representation

--version

Print the btrfs-convert version, builtin features and exit.

## EXIT STATUS
btrfs-convert will return 0 if no error happened. If any problems happened, 1 will be returned.

## SEE ALSO
mkfs.btrfs(8) <>


btrfs-device

title: btrfs-device(8)

summary: manage devices of btrfs filesystems

text:
# btrfs-device(8)

## NAME
btrfs-device - manage devices of btrfs filesystems

## SYNOPSIS
btrfs device <subcommand> <args>

## DESCRIPTION
The btrfs device command group is used to manage devices of the btrfs filesystems.

## DEVICE MANAGEMENT
BTRFS filesystem can be created on top of single or multiple block devices. Devices can be then added, removed or replaced on demand. Data and metadata are organized in allocation profiles with various redundancy policies. There's some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation. See mkfs.btrfs(8) <> for more details and the exact profile capabilities and constraints.

The device management works on a mounted filesystem. Devices can be added, removed or replaced, by commands provided by btrfs device and btrfs replace.

The profiles can be also changed, provided there's enough workspace to do the conversion, using the btrfs balance command and namely the filter convert.

Type

The block group profile type is the main distinction of the information stored on the block device. User data are called Data, the internal data structures managed by filesystem are Metadata and System.

Profile

A profile describes an allocation policy based on the redundancy/replication constraints in connection with the number of devices. The profile applies to data and metadata block groups separately. E.g. single, RAID1.

RAID level

Where applicable, the level refers to a profile that matches constraints of the standard RAID levels. At the moment the supported ones are: RAID0, RAID1, RAID10, RAID5 and RAID6.

## TYPICAL USE CASES

### Starting with a single-device filesystem
Assume we've created a filesystem on a block device /dev/sda with profile single/single (data/metadata), the device size is 50GiB and we've used the whole device for the filesystem. The mount point is /mnt.

The amount of data stored is 16GiB, metadata have allocated 2GiB.

### Add new device
We want to increase the total size of the filesystem and keep the profiles. The size of the new device /dev/sdb is 100GiB.

```
$ btrfs device add /dev/sdb /mnt
```

The amount of free data space increases by less than 100GiB, some space is allocated for metadata.

### Convert to RAID1
Now we want to increase the redundancy level of both data and metadata, but we'll do that in steps. Note, that the device sizes are not equal and we'll use that to show the capabilities of split data/metadata and independent profiles.

The constraint for RAID1 gives us at most 50GiB of usable space and exactly 2 copies will be stored on the devices.

First we'll convert the metadata. As the metadata occupy less than 50GiB and there's enough workspace for the conversion process, we can do:

```
$ btrfs balance start -mconvert=raid1 /mnt
```

This operation can take a while, because all metadata have to be moved and all block pointers updated. Depending on the physical locations of the old and new blocks, the disk seeking is the key factor affecting performance.

You'll note that the system block group has been also converted to RAID1, this normally happens as the system block group also holds metadata (the physical to logical mappings).

What changed:

- available data space decreased by 3GiB, usable roughly (50 - 3) + (100 - 3) = 144 GiB

- metadata redundancy increased

In other words, the unequal device sizes allow for combined space for data yet improved redundancy for metadata. If we decide to increase redundancy of data as well, we're going to lose 50GiB of the second device for obvious reasons.

```
$ btrfs balance start -dconvert=raid1 /mnt
```

The balance process needs some workspace (i.e. a free device space without any data or metadata block groups) so the command could fail if there's too much data or the block groups occupy the whole first device.

The device size of /dev/sdb as seen by the filesystem remains unchanged, but the logical space from 50-100GiB will be unused.

### Remove device
Device removal must satisfy the profile constraints, otherwise the command fails. For example:

```
$ btrfs device remove /dev/sda /mnt
ERROR: error removing device '/dev/sda': unable to go below two devices on raid1
```

In order to remove a device, you need to convert the profile in this case:

```
$ btrfs balance start -mconvert=dup -dconvert=single /mnt
$ btrfs device remove /dev/sda /mnt
```

Warning:

Do not run balance to convert from a profile with more redundancy to one with less redundancy in order to remove a failing device from a filesystem. Balance is done by reading out the good metadata/data and write them into a new chunk. Thus it's possible the new chunk is written into the failing device.

Use btrfs device replace instead.

## SUBCOMMAND
add [-Kf] <device> [<device>...] <path>

Add device(s) to the filesystem identified by path. If applicable, a whole device discard (TRIM) operation is performed prior to adding the device. A device with existing filesystem detected by blkid(8) <https://man7.org/linux/man-pages/man8/blkid.8.html> will prevent device addition and has to be forced. Alternatively the filesystem can be wiped from the device using e.g. the wipefs(8) <https://man7.org/linux/man-pages/man8/wipefs.8.html> tool.

The operation is instant and does not affect existing data. The operation merely adds the device to the filesystem structures and creates some block groups headers.

Options

-K|--nodiscard

do not perform discard (TRIM) by default

-f|--force

force overwrite of existing filesystem on the given disk(s)

--enqueue

wait if there's another exclusive operation running, otherwise continue

remove [options] <device>|<devid> [<device>|<devid>...] <path>

Remove device(s) from a filesystem identified by <path> Device removal must satisfy the profile constraints, otherwise the command fails and cannot be enforced. The filesystem must be converted to profile(s) that would allow the removal. This can for example happen when going down from 2 devices to 1 and using the RAID1 profile. See the section Typical use cases <btrfs-device//#man-device-typical-use-cases>.

The operation can take long as it needs to move all data from the device.

Note:

It's possible to specify more than one device on the command line but the devices will be removed one by one, not at once. This means that the remaining devices to be deleted can be still used for writes. In that case there's a warning and safety timeout as this can be confusing and unexpected. The timeout can be overridden by option --force.

It is possible to delete the device that was used to mount the filesystem. The device entry in the mount table (/proc/self/mounts) will be replaced by another device name with the lowest device id.

If the filesystem is mounted in degraded mode (-o degraded), special term missing can be used for device. In that case, the first device that is described by the filesystem metadata, but not present at the mount time will be removed.

Note:

In most cases, there is only one missing device in degraded mode, otherwise mount fails. If there are two or more devices missing (e.g. possible in RAID6), you need specify missing as many times as the number of missing devices to remove all of them.

Options

--enqueue

wait if there's another exclusive operation running, otherwise continue

--force

skip the safety timeout when there are multiple devices for removal, this does not force removing devices that would break the profile constraints

delete <device>|<devid> [<device>|<devid>...] <path>

Alias of remove kept for backward compatibility

replace <command> [options] <path>

Alias of whole command group btrfs replace for convenience. See btrfs-replace(8) <>.

ready <device>

Wait until all devices of a multiple-device filesystem are scanned and registered within the kernel module. This is to provide a way for automatic filesystem mounting tools to wait before the mount can start. The device scan is only one of the preconditions and the mount can fail for other reasons. Normal users usually do not need this command and may safely ignore it.

scan [options] [<device> [<device>...]]

Scan devices for a btrfs filesystem and register them with the kernel module. This allows mounting multiple-device filesystem by specifying just one from the whole group. If no devices are passed, all block devices that blkid reports to contain btrfs are scanned.

The options --all-devices or -d can be used as a fallback in case blkid is not available. If used, behavior is the same as if no devices are passed.

The command can be run repeatedly. Devices that have been already registered remain as such. Reloading the kernel module will drop this information. There's an alternative way of mounting multiple-device filesystem without the need for prior scanning. See the mount option device (in btrfs-man5) <btrfs-man5//#mount-option-device>.

Options

-d|--all-devices

Enumerate and register all devices, use as a fallback in case blkid is not available.

-u|--forget

Unregister a given device or all stale devices if no path is given, the device must be unmounted otherwise it's an error.

stats [options] <path>|<device>|<file>

Read and print the device IO error statistics for all devices of the given filesystem identified by path or for a single device or file (the offline mode, unmounted filesystem). When the filesystem is mounted the path is expected to be a directory and the stats are read using an ioctl and can be reset or checked. Same for a block device of a mounted filesystem.

For an offline mode the path must be a file image or a block device, the option --offline is mandatory. As it's read-only access the option --reset does not work.

See section DEVICE STATS for more information about the reported statistics and the meaning.

Options

-z|--reset

Print the stats and reset the values to zero afterwards. Does not work in offline mode.

-c|--check

Check if the stats are all zeros and return 0 if it is so. Set bit 6 of the return code if any of the statistics is no-zero. The error values is 65 if reading stats from at least one device failed, otherwise it's 64.

--offline

Read the stats from the file image or directly from block device.

-T

Print stats in a tabular form, devices as rows and stats as columns

usage [options] <path> [<path>...]::

Show detailed information about internal allocations on devices. The level of detail can differ if the command is run under a regular or the root user (due to use of restricted ioctls). The first example below is for normal user (warning included) and the next one with root on the same filesystem:

```
WARNING: cannot read detailed chunk info, per-device usage will not be shown, run as root
/dev/sdc1, ID: 1

   Device size:           931.51GiB

   Device slack:              0.00B

   Unallocated:           931.51GiB
/dev/sdc1, ID: 1

   Device size:           931.51GiB

   Device slack:              0.00B

   Data,single:           641.00GiB

   Data,RAID0/3:            1.00GiB

   Metadata,single:        19.00GiB

   System,single:          32.00MiB

   Unallocated:           271.48GiB
```

- Device size -- size of the device as seen by the filesystem (may be different than actual device size)

- Device slack -- portion of device not used by the filesystem but still available in the physical space provided by the device, e.g. after a device shrink

- Data,single, Metadata,single, System,single -- in general, list of block group type (Data, Metadata, System) and profile (single, RAID1, ...) allocated on the device

- Data,RAID0/3 -- in particular, striped profiles RAID0/RAID10/RAID5/RAID6 with the number of devices on which the stripes are allocated, multiple occurrences of the same profile can appear in case a new device has been added and all new available stripes have been used for writes

- Unallocated -- remaining space that the filesystem can still use for new block groups

Options

-b|--raw

raw numbers in bytes, without the B suffix

-h|--human-readable

print human friendly numbers, base 1024, this is the default

-H

print human friendly numbers, base 1000

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

-k|--kbytes

show sizes in KiB, or kB with --si

-m|--mbytes

show sizes in MiB, or MB with --si

-g|--gbytes

show sizes in GiB, or GB with --si

-t|--tbytes

show sizes in TiB, or TB with --si

If conflicting options are passed, the last one takes precedence.

## DEVICE STATS
The device stats keep persistent record of several error classes related to doing IO. The current values are printed at mount time and updated during filesystem lifetime or from a scrub run.

```
$ btrfs device stats /dev/sda3
[/dev/sda3].write_io_errs   0
[/dev/sda3].read_io_errs    0
[/dev/sda3].flush_io_errs   0
[/dev/sda3].corruption_errs 0
[/dev/sda3].generation_errs 0
```

write_io_errs

Failed writes to the block devices, means that the layers beneath the filesystem were not able to satisfy the write request.

read_io_errs

Read request analogy to write_io_errs.

flush_io_errs

Number of failed writes with the FLUSH flag set. The flushing is a method of forcing a particular order between write requests and is crucial for implementing crash consistency. In case of btrfs, all the metadata blocks must be permanently stored on the block device before the superblock is written.

corruption_errs

A block checksum mismatched or a corrupted metadata header was found.

generation_errs

The block generation does not match the expected value (e.g. stored in the parent node).

Since kernel 5.14 the device stats are also available in textual form in /sys/fs/btrfs/FSID/devinfo/DEVID/error_stats.

## EXIT STATUS
btrfs device returns a zero exit status if it succeeds. Non zero is returned in case of failure.

If the -c option is used, btrfs device stats will add 64 to the exit status if any of the error counters is non-zero.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at <https://btrfs.readthedocs.io>.

## SEE ALSO
btrfs-balance(8) <> btrfs-device(8) <>, btrfs-replace(8) <>, mkfs.btrfs(8) <>


btrfs-filesystem

title: btrfs-filesystem(8)

text:
# btrfs-filesystem(8)

## NAME
btrfs-filesystem - command group that primarily does work on the whole filesystems

## SYNOPSIS
btrfs filesystem <subcommand> <args>

## DESCRIPTION
btrfs filesystem is used to perform several whole filesystem level tasks, including all the regular filesystem operations like resizing, space stats, label setting/getting, and defragmentation. There are other whole filesystem tasks like scrub or balance that are grouped in separate commands (btrfs-scrub(8) <>, btrfs-balance(8) <>).

## SUBCOMMAND
df [options] <path>

Show a terse summary information about allocation of block group types of a given mount point. The original purpose of this command was a debugging helper. The output needs to be further interpreted and is not suitable for quick overview. An example with description:

- device size: 1.9TiB, one device, no RAID

- filesystem size: 1.9TiB

- created with: mkfs.btrfs -d single -m single

```
$ btrfs filesystem df /path
Data, single: total=1.15TiB, used=1.13TiB
System, single: total=32.00MiB, used=144.00KiB
Metadata, single: total=12.00GiB, used=6.45GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

- Data, System and Metadata are separate block group types. GlobalReserve is an artificial and internal emergency space, see below.

- single -- the allocation profile, defined at mkfs time

- total -- sum of space reserved for all allocation profiles of the given type, i.e. all Data/single. Note that it's not total size of filesystem.

- used -- sum of used space of the above, i.e. file extents, metadata blocks

GlobalReserve is an artificial and internal emergency space. It is used e.g. when the filesystem is full. Its total size is dynamic based on the filesystem size, usually not larger than 512MiB, used may fluctuate.

The GlobalReserve is a portion of Metadata. In case the filesystem metadata is exhausted, GlobalReserve/total + Metadata/used = Metadata/total. Otherwise there appears to be some unused space of Metadata.

Options

-b|--raw

raw numbers in bytes, without the B suffix

-h|--human-readable

print human friendly numbers, base 1024, this is the default

-H

print human friendly numbers, base 1000

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

-k|--kbytes

show sizes in KiB, or kB with --si

-m|--mbytes

show sizes in MiB, or MB with --si

-g|--gbytes

show sizes in GiB, or GB with --si

-t|--tbytes

show sizes in TiB, or TB with --si

If conflicting options are passed, the last one takes precedence.

defragment [options] <file>|<dir> [<file>|<dir>...]

Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer. If -r is passed, files in dir will be defragmented recursively (not descending to subvolumes, mount points and directory symlinks). The start position and the number of bytes to defragment can be specified by start and length using -s and -l options below. Extents bigger than value given by -t will be skipped, otherwise this value is used as a target extent size, but is only advisory and may not be reached if the free space is too fragmented. Use 0 to take the kernel default, which is 256KiB but may change in the future. You can also turn on compression in defragment operations.

Warning:

Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up the reflinks of COW data (for example files copied with cp --reflink, snapshots or de-duplicated data). This may cause considerable increase of space usage depending on the broken up reflinks.

Note:

Directory arguments without -r do not defragment files recursively but will defragment certain internal trees (extent tree and the subvolume tree). This has been confusing and could be removed in the future.

For start, len, size it is possible to append units designator: K, M, G, T, P, or E, which represent KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).

Options

-c[<algo>]

compress file contents while defragmenting. Optional argument selects the compression algorithm, zlib (default), lzo or zstd. Currently it's not possible to select no compression. See also section EXAMPLES.

-L|--level <level>

Since kernel 6.15 the compression can also take the level parameter which will be used only for the defragmentation and overrides the eventual mount option compression level. Valid levels depend on the compression algorithms: zlib 1..9, lzo does not have any levels, zstd the standard levels 1..15 and also the realtime -1..-15.

--nocomp

Do not compress while defragmenting, uncompress extents if needed.

-r

defragment files recursively in given directories, does not descend to subvolumes or mount points

-f

flush data for each file before going to the next file. This will limit the amount of dirty data to current file, otherwise the amount accumulates from several files and will increase system load. This can also lead to ENOSPC if there's too much dirty data to write and it's not possible to make the reservations for the new data (i.e. how the COW design works).

-s <start>[kKmMgGtTpPeE]

defragmentation will start from the given offset, default is beginning of a file

-l <len>[kKmMgGtTpPeE]

defragment only up to len bytes, default is the file size

-t <size>[kKmMgGtTpPeE]

target extent size, do not touch extents bigger than size, default: 32MiB The value is only advisory and the final size of the extents may differ, depending on the state of the free space and fragmentation or other internal logic. Reasonable values are from tens to hundreds of megabytes.

--step SIZE

Perform defragmentation in the range in SIZE steps and flush (-f) after each one. The range is default (the whole file) or given by -s and -l, split into the steps or done in one go if the step is larger. Minimum range size is 256KiB. With verbosity options the progress of defragmentation will be also printed.

-v

(deprecated) alias for global -v option

du [options] <path> [<path>..]

Calculate disk usage of the target files using FIEMAP. For individual files, it will report a count of total bytes, and exclusive (not shared) bytes. We also calculate a 'set shared' value which is described below. Each argument to btrfs filesystem du will have a set shared value calculated for it. We define each set as those files found by a recursive search of an argument (recursion descends to subvolumes but not mount points). The set shared value then is a sum of all shared space referenced by the set.

set shared takes into account overlapping shared extents, hence it isn't as simple as adding up shared extents.

Options

-s|--summarize

display only a total for each argument

--raw

raw numbers in bytes, without the B suffix.

--human-readable

print human friendly numbers, base 1024, this is the default

--iec

select the 1024 base for the following options, according to the IEC standard.

--si

select the 1000 base for the following options, according to the SI standard.

--kbytes

show sizes in KiB, or kB with --si.

--mbytes

show sizes in MiB, or MB with --si.

--gbytes

show sizes in GiB, or GB with --si.

--tbytes

show sizes in TiB, or TB with --si.

label [<device>|<mountpoint>] [<newlabel>]

Show or update the label of a filesystem. This works on a mounted filesystem or a filesystem image. The newlabel argument is optional. Current label is printed if the argument is omitted.

Note:

The maximum allowable length shall be less than 256 chars and must not contain a newline. The trailing newline is stripped automatically.

mkswapfile [-s size] file

Create a new file that's suitable and formatted as a swapfile. Default size is 2GiB, fixed page size 4KiB, minimum size is 40KiB. A swapfile must be created in a specific way: NOCOW and preallocated. Subvolume containing a swapfile cannot be snapshotted and blocks of an activated swapfile cannot be balanced.

Swapfile creation can be achieved by standalone commands too. Activation needs to be done by command swapon(8) <https://man7.org/linux/man-pages/man8/swapon.8.html>. See also command btrfs inspect-internal map-swapfile and the Swapfile feature <> description.

Note:

The command is a simplified version of 'mkswap', if you want to set label, page size, or other parameters please use 'mkswap' proper.

Options

-s|--size SIZE

Create swapfile of a given size SIZE (accepting k/m/g/e/p suffix).

-U|--uuid UUID

specify UUID to use, or a special value: clear (all zeros), random, time (time-based random)

resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>

Resize a mounted filesystem identified by path. A particular device can be resized by specifying a devid. Note:

To resize a file containing a BTRFS image, please use the --offline flag.

The devid can be found in the output of btrfs filesystem show and defaults to 1 if not specified. 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, bytes are assumed for size. Optionally, the size parameter may be suffixed by one of the following unit designators: K, M, G, T, P, or E, which represent KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).

If max is passed, the filesystem will occupy all available space on the device respecting devid (remember, devid 1 by default).

The resize command does not manipulate the size of underlying partition. If you wish to enlarge/reduce a filesystem, you must make sure you expand the partition before enlarging the filesystem and shrink the partition after reducing the size of the filesystem. This can be done using fdisk(8) <https://man7.org/linux/man-pages/man8/fdisk.8.html> or parted(8) <https://man7.org/linux/man-pages/man8/parted.8.html> to delete the existing partition and recreate it with the new desired size. When recreating the partition make sure to use the same starting partition offset as before.

The size of the portion that the filesystem uses of an underlying device can be determined via the btrfs filesystem show --raw command on the filesystem’s mount point (where it’s given for each devid after the string size or via the btrfs inspect-internal dump-super command on the specific device (where it’s given as the value of dev_item.total_bytes, which is not to be confused with total_bytes). The value is also the address of the first byte not used by the filesystem.

Growing is usually instant as it only updates the size. However, shrinking could take a long time if there are data in the device area that's beyond the new end. Relocation of the data takes time.

Note that there's a lower limit on the new size (either specified as an absolute size or difference) that is checked by kernel and rejected eventually as invalid. Lower values will print a warning but still pass the request to kernel. The currently known value is 256MiB.

See also section EXAMPLES.

Options

--enqueue

wait if there's another exclusive operation running, otherwise continue

--offline

resize an unmounted (offline) filesystem Warning:

The offline resize functionality currently supports only increasing the size of single-device filesystems. IOW, shrinking and multi-device filesystems are not supported with this option.

For filesystems stored in regular files, the file will be truncated to the new size as part of the resize operation. This flag is cannot be used together with with --enqueue since offline resizing is synchronous.

show [options] [<path>|<uuid>|<device>|<label>]

Show the btrfs filesystem with some additional info about devices and space allocation. If no option none of path/uuid/device/label is passed, information about all the BTRFS filesystems is shown, both mounted and unmounted.

Options

-m|--mounted

probe kernel for mounted BTRFS filesystems

-d|--all-devices

scan all devices under /dev, otherwise the devices list is extracted from the /proc/partitions file. This is a fallback option if there's no device node manager (like udev) available in the system.

--raw

raw numbers in bytes, without the B suffix

--human-readable

print human friendly numbers, base 1024, this is the default

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

--kbytes

show sizes in KiB, or kB with --si

--mbytes

show sizes in MiB, or MB with --si

--gbytes

show sizes in GiB, or GB with --si

--tbytes

show sizes in TiB, or TB with --si

commit-stats

Print number of commits and time stats since mount. This is also available in /sys/fs/btrfs/FSID/commit_stats. The stats are not persistent and are collected since mount of the filesystem, one of them can be reset to zero (Max commit duration).

```
UUID: bd18ebe1-7e1d-414f-a3d5-2644388b51cc
Commit stats since mount:

  Total commits:                  1133

  Last commit duration:              0ms

  Max commit duration:              10ms

  Total time spent in commit:     4543ms
```

Options

-z|--reset

print stats and reset 'max_commit_ms' (needs root)

sync <path>

Force a sync of the filesystem at path, similar to the sync(1) <https://man7.org/linux/man-pages/man1/sync.1.html> command. In addition, it starts cleaning of deleted subvolumes. To wait for the subvolume deletion to complete use the btrfs subvolume sync command.

usage [options] <path> [<path>...]

Show detailed information about internal filesystem usage. This is supposed to replace the btrfs filesystem df command in the long run. The level of detail can differ if the command is run under a regular or the root user (due to use of restricted ioctl). For both there's a summary section with information about space usage:

```
$ btrfs filesystem usage /path
WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
Overall:

    Device size:                   1.82TiB

    Device allocated:              1.17TiB

    Device unallocated:          669.99GiB

    Device missing:                  0.00B

    Device slack:                  1.00GiB

    Used:                          1.14TiB

    Free (estimated):            692.57GiB      (min: 692.57GiB)

    Free (statfs, df)            692.57GiB

    Data ratio:                       1.00

    Metadata ratio:                   1.00

    Global reserve:              512.00MiB      (used: 0.00B)

    Multiple profiles:                  no
```

- Device size -- sum of raw device capacity available to the filesystem, note that this may not be the same as the total device size (the difference is accounted as slack)

- Device allocated -- sum of total space allocated for data/metadata/system profiles, this also accounts space reserved but not yet used for extents

- Device unallocated -- the remaining unallocated space for future allocations (difference of the above two numbers)

- Device missing -- sum of capacity of all missing devices

- Device slack -- sum of slack space on all devices (difference between entire device size and the space occupied by filesystem)

- Used -- sum of the used space of data/metadata/system profiles, not including the reserved space

- Free (estimated) -- approximate size of the remaining free space usable for data, including currently allocated space and estimating the usage of the unallocated space based on the block group profiles, the min is the lower bound of the estimate in case multiple profiles are present

- Free (statfs, df) -- the amount of space available for data as reported by the statfs/statvfs syscall, also returned as Avail in the output of df. The value is calculated in a different way and may not match the estimate in some cases (e.g. multiple profiles).

- Data ratio -- ratio of total space for data including redundancy or parity to the effectively usable data space, e.g. single is 1.0, RAID1 is 2.0 and for RAID5/6 it depends on the number of devices

- Metadata ratio -- ditto, for metadata

- Global reserve -- portion of metadata currently used for global block reserve, used for emergency purposes (like deletion on a full filesystem)

- Multiple profiles -- what block group types (data, metadata) have more than one profile (single, raid1, ...), see btrfs(5) <> section FILESYSTEMS WITH MULTIPLE PROFILES <#man-btrfs5-filesystem-with-multiple-profiles>.

And on a zoned filesystem there are two more lines in the Device section:

```
Device zone unusable:          5.13GiB
Device zone size:            256.00MiB
```

- Device zone unusable -- sum of of space that's been used in the past but now is not due to COW and not referenced anymore, the chunks have to be reclaimed and zones reset to make it usable again

- Device zone size -- the reported zone size of the host-managed device, same for all devices

The root user will also see stats broken down by block group types:

```
Data,single: Size:1.15TiB, Used:1.13TiB (98.26%)

   /dev/sdb        1.15TiB
Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%)

   /dev/sdb       12.00GiB
System,single: Size:32.00MiB, Used:144.00KiB (0.44%)

   /dev/sdb       32.00MiB
Unallocated:

   /dev/sdb      669.99GiB
```

Data is block group type, single is block group profile, Size is total size occupied by this type, Used is the actually used space, the percent is ratio of Used/Size. The Unallocated is remaining space.

Options

-b|--raw

raw numbers in bytes, without the B suffix

-h|--human-readable

print human friendly numbers, base 1024, this is the default

-H

print human friendly numbers, base 1000

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

-k|--kbytes

show sizes in KiB, or kB with --si

-m|--mbytes

show sizes in MiB, or MB with --si

-g|--gbytes

show sizes in GiB, or GB with --si

-t|--tbytes

show sizes in TiB, or TB with --si

-T

show data in tabular format

If conflicting options are passed, the last one takes precedence.

## EXAMPLES
$ btrfs filesystem defrag -v -r dir/

Recursively defragment files under dir/, print files as they are processed. The file names will be printed in batches, similarly the amount of data triggered by defragmentation will be proportional to last N printed files. The system dirty memory throttling will slow down the defragmentation but there can still be a lot of IO load and the system may stall for a moment.

$ btrfs filesystem defrag -v -r -f dir/

Recursively defragment files under dir/, be verbose and wait until all blocks are flushed before processing next file. You can note slower progress of the output and lower IO load (proportional to currently defragmented file).

$ btrfs filesystem defrag -v -r -f -clzo dir/

Recursively defragment files under dir/, be verbose, wait until all blocks are flushed and force file compression.

$ btrfs filesystem defrag -v -r -t 64M dir/

Recursively defragment files under dir/, be verbose and try to merge extents to be about 64MiB. As stated above, the success rate depends on actual free space fragmentation and the final result is not guaranteed to meet the target even if run repeatedly.

$ btrfs filesystem resize -1G /path

$ btrfs filesystem resize 1:-1G /path

Shrink size of the filesystem's device id 1 by 1GiB. The first syntax expects a device with id 1 to exist, otherwise fails. The second is equivalent and more explicit. For a single-device filesystem it's typically not necessary to specify the devid though.

$ btrfs filesystem resize max /path

$ btrfs filesystem resize 1:max /path

Let's assume that devid 1 exists and the filesystem does not occupy the whole block device, e.g. it has been enlarged and we want to grow the filesystem. By simply using max as size we will achieve that.

Note:

There are two ways to minimize the filesystem on a given device. The btrfs inspect-internal min-dev-size command, or iteratively shrink in steps.

## EXIT STATUS
btrfs filesystem returns a zero exit status if it succeeds. Non zero is returned in case of failure.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at <https://btrfs.readthedocs.io>.

## SEE ALSO
btrfs-subvolume(8) <>, mkfs.btrfs(8) <>


btrfs-find-root

title: btrfs-find-root(8)

summary: filter to find btrfs root

text:
# btrfs-find-root(8)

## NAME
btrfs-find-root - filter to find btrfs root

## SYNOPSIS
btrfs-find-root [options] <device>

## DESCRIPTION
btrfs-find-root is used to find the satisfied root, you can filter by root tree's objectid, generation, level.

## OPTIONS
-a

Search through all metadata extents, even the root has been already found.

-g <generation>

Filter root tree by it's original transaction id, tree root's generation in default.

-o <objectid>

Filter root tree by it's objectid,tree root's objectid in default.

-l <level>

Filter root tree by b-tree's level, level 0 in default.

## EXIT STATUS
btrfs-find-root will return 0 if no error happened. If any problems happened, 1 will be returned.

## SEE ALSO
mkfs.btrfs(8) <>


btrfs-image

title: btrfs-image(8)

text:
# btrfs-image(8)

## NAME
btrfs-image - create/restore an image of the filesystem

## SYNOPSIS
btrfs-image [options] <source> <target>

## DESCRIPTION
btrfs-image is used to create an image of a btrfs filesystem. All data will be zeroed, but metadata and the like is preserved. Mainly used for debugging purposes.

In the dump mode, source is the btrfs device/file and target is the output file (use - for stdout).

In the restore mode (option -r), source is the dumped image and target is the btrfs device/file.

## OPTIONS
-r

Restore metadump image. By default, this fixes super's chunk tree, by using 1 stripe pointing to primary device, so that file system can be restored by running tree log reply if possible. To restore without changing number of stripes in chunk tree check -o option.

-c <value>

Compression level (0 ~ 9).

-t <value>

Number of threads (1 ~ 32) to be used to process the image dump or restore.

-o

Use the old restore method, this does not fixup the chunk tree so the restored file system will not be able to be mounted.

-s

Sanitize the file names when generating the image. Not recommended as this would introduce new file name hash mismatches, thus if your problem involves subvolume tress, it can even mask existing problems. Furthermore kernels can not do proper path resolution due to the introduced hash mismatches. One -s means just generate random garbage, which means that the directory hash won't match its file names. Using two -s will calculate a collision for the file name so that the hashes match, and if it can't calculate a collision then it will just generate garbage. The collision calculator is very time and CPU intensive.

-w

Walk all the trees manually and copy any blocks that are referenced. Use this option if your extent tree is corrupted to make sure that all of the metadata is captured.

-m

Restore for multiple devices, more than 1 device should be provided.

--version

Print the btrfs-image version, builtin features and exit.

## EXIT STATUS
btrfs-image will return 0 if no error happened. If any problems happened, 1 will be returned.

## SEE ALSO
mkfs.btrfs(8) <>


btrfs-inspect-internal

title: btrfs-inspect-internal(8)

summary: query various internal information

text:
# btrfs-inspect-internal(8)

## NAME
btrfs-inspect-internal - query various internal information

## SYNOPSIS
btrfs inspect-internal <subcommand> <args>

## DESCRIPTION
This command group provides an interface to query internal information. The functionality ranges from a simple UI to an ioctl or a more complex query that assembles the result from several internal structures. The latter usually requires calls to privileged ioctls.

## SUBCOMMAND
dump-super [options] <device> [device...]

Show btrfs superblock information stored on given devices in textual form. By default the first superblock is printed, more details about all copies or additional backup data can be printed. Besides verification of the filesystem signature, there are no other sanity checks. The superblock checksum status is reported, the device item and filesystem UUIDs are checked and reported.

Note:

The meaning of option -s has changed in version 4.8 to be consistent with other tools to specify superblock copy rather the offset. The old way still works, but prints a warning. Please update your scripts to use --bytenr instead. The option -i has been deprecated.

Options

-f|--full

print full superblock information, including the system chunk array and backup roots

-a|--all

print information about all present superblock copies (cannot be used together with -s option)

-i <super>

(deprecated since 4.8, same behaviour as --super)

--bytenr <bytenr>

specify offset to a superblock in a non-standard location at bytenr, useful for debugging (disables the -f option) If there are multiple options specified, only the last one applies.

-F|--force

attempt to print the superblock even if a valid BTRFS signature is not found; the result may be completely wrong if the data does not resemble a superblock

-s|--super <bytenr>

(see compatibility note above) specify which mirror to print, valid values are 0, 1 and 2 and the superblock must be present on the device with a valid signature, can be used together with --force

dump-tree [options] <device> [device...]

Dump tree structures from a given device in textual form, expand keys to human readable equivalents where possible. This is useful for analyzing filesystem state or inconsistencies and has a positive educational effect on understanding the internal filesystem structure. Note:

By default contains file names, consider that if you're asked to send the dump for analysis and use --hide-names eventually. Does not contain file data.

Special characters in file names, xattr names and values are escaped, in the C style like \n and octal encoding \NNN.

Options

-e|--extents

print only extent-related information: extent and device trees

-d|--device

print only device-related information: tree root, chunk and device trees

-r|--roots

print only short root node information, i.e. the root tree keys

-R|--backups

same as --roots plus print backup root info, i.e. the backup root keys and the respective tree root block offset

-u|--uuid

print only the uuid tree information, empty output if the tree does not exist

-b <block_num>

print info of the specified block only, can be specified multiple times

--follow

use with -b, print all children tree blocks of <block_num>

--dfs

(default up to 5.2) use depth-first search to print trees, the nodes and leaves are intermixed in the output

--bfs

(default since 5.3) use breadth-first search to print trees, the nodes are printed before all leaves

--hide-names

print a placeholder HIDDEN instead of various names, useful for developers to inspect the dump while keeping potentially sensitive information hidden This is:

- directory entries (files, directories, subvolumes)

- default subvolume

- extended attributes (name, value)

- hardlink names (if stored inside another item or as extended references in standalone items)

Note:

Lengths are not hidden because they can be calculated from the item size anyway.

--csum-headers

print b-tree node checksums stored in headers (metadata)

--csum-items

print checksums stored in checksum items (data)

--noscan

do not automatically scan the system for other devices from the same filesystem, only use the devices provided as the arguments

-t <tree_id>

print only the tree with the specified ID, where the ID can be numerical or common name in a flexible human readable form The tree id name recognition rules:

- case does not matter

- the C source definition, e.g. BTRFS_ROOT_TREE_OBJECTID

- short forms without BTRFS_ prefix, without _TREE and _OBJECTID suffix, e.g. ROOT_TREE, ROOT

- convenience aliases, e.g. DEVICE for the DEV tree, CHECKSUM for CSUM

- unrecognized ID is an error

inode-resolve [-v] <ino> <path>

(needs root privileges) resolve paths to all files with given inode number ino in a given subvolume at path, i.e. all hardlinks

Options

-v

(deprecated) alias for global -v option

logical-resolve [-Pvo] [-s <bufsize>] <logical> <path>

(needs root privileges) resolve paths to all files at given logical address in the linear filesystem space

Options

-P

skip the path resolving and print the inodes instead

-o

ignore offsets, find all references to an extent instead of a single block. Requires kernel support for the V2 ioctl (added in 4.15). The results might need further processing to filter out unwanted extents by the offset that is supposed to be obtained by other means.

-s <bufsize>

set internal buffer for storing the file names to bufsize, default is 64KiB, maximum 16MiB. Buffer sizes over 64KiB require kernel support for the V2 ioctl (added in 4.15).

-v

(deprecated) alias for global -v option

list-chunks [options] <path>

(needs root privileges) Enumerate chunks on all devices. The chunks represent the physical range on devices (not to be confused with block groups that represent the logical ranges, but the terms are often used interchangeably).

Example output:

```
Devid PNumber      Type/profile    PStart    Length      PEnd LNumber    LStart Usage%
----- ------- ----------------- --------- --------- --------- ------- --------- ------

    1       1       Data/single   1.00MiB  84.00MiB  85.00MiB      68 191.60GiB  62.77

    1       2     System/DUP     85.00MiB  32.00MiB 117.00MiB      39 140.17GiB   0.05

    1       3     System/DUP    117.00MiB  32.00MiB 149.00MiB      40 140.17GiB   0.05

    1       4   Metadata/DUP    149.00MiB 192.00MiB 341.00MiB      59 188.41GiB  45.00

    1       5   Metadata/DUP    341.00MiB 192.00MiB 533.00MiB      60 188.41GiB  45.00

    1       6       Data/single 533.00MiB   1.00GiB   1.52GiB      49 169.91GiB  72.23

    1       7       Data/single   1.52GiB  16.00MiB   1.54GiB      69 191.68GiB  79.83

    1       8       Data/single   1.54GiB   1.00GiB   2.54GiB      17 100.90GiB  46.39

    1       9       Data/single   2.54GiB   1.00GiB   3.54GiB      16  99.90GiB  40.68

    1      10       Data/single   3.54GiB   1.00GiB   4.54GiB       1  71.40GiB  62.97

    1      11       Data/single   4.54GiB   1.00GiB   5.54GiB      33 125.04GiB  26.00

    1      12       Data/single   5.54GiB   1.00GiB   6.54GiB      50 170.91GiB  60.44

    1      13       Data/single   6.54GiB 512.00MiB   7.04GiB      63 189.16GiB  67.34

    1      14       Data/single   7.04GiB   1.00GiB   8.04GiB      51 171.91GiB  70.94
```

- Devid -- the device id

- PNumber -- the number of the chunk on the device (in order)

- Type/profile -- the chunk type and profile

- PStart -- the chunk start on the device

- Length -- the chunk length (same for physical and logical address space)

- PEnd -- the chunk end, effectively PStart + Length

- LNumber -- the number of the chunk, in the logical address space of the whole filesystem

- LStart -- the chunk start in the logical address space of the whole filesystem, as it's a single space it's also called offset

- Usage -- chunk usage, percentage of used data/metadata of the chunk length

The chunks in the output can be sorted by one or more sorting criteria, evaluated as specified, in the ascending order (or descending when used like -devid,-pstart). By default the chunks are sorted by devid and pstart, this is most convenient for single device filesystems.

On multi-device filesystems it's up to the user what is preferred as the layout of chunks on e.g. striped profiles (RAID0 etc) cannot be easily represented. A logical view with corresponding underlying structure would be better, but sorting by lstart,devid at least groups devices of the given logical range. Can be also combined with usage.

This output can provide information for balance filters.

Options

--sort MODE

sort by a column (ascending, prepend '-' for descending): MODE is a comma separated list of:

devid - by device id (default, with pstart) pstart - physical start (relative to the beginning of the device)

lstart - logical offset (in the logical address space)

usage - by chunk usage (percentage)

length - by chunk length

type - by chunk type (data, metadata, system)

profile - by chunk profile (single, DUP, RAID0, RAID1, ...)

--raw

raw numbers in bytes, without the B suffix

--human-readable

print human friendly numbers, base 1024, this is the default

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

--kbytes

show sizes in KiB, or kB with --si

--mbytes

show sizes in MiB, or MB with --si

--gbytes

show sizes in GiB, or GB with --si

--tbytes

show sizes in TiB, or TB with --si

map-swapfile [options] <file>

(needs root privileges) Find device-specific physical offset of file that can be used for hibernation. Also verify that the file is suitable as a swapfile. See also command btrfs filesystem mkswapfile and the Swapfile feature <> description.

Note:

Do not use filefrag or FIEMAP ioctl values reported as physical, this is different due to internal filesystem mappings. The hibernation expects offset relative to the physical block device.

Options

-r|--resume-offset

print only the value suitable as resume offset for file /sys/power/resume_offset

min-dev-size [options] <path>

(needs root privileges) return the minimum size the device can be shrunk to, without performing any resize operation, this may be useful before executing the actual resize operation

Options

--id <id>

specify the device id to query, default is 1 if this option is not used

rootid <path>

for a given file or directory, return the containing tree root id, but for a subvolume itself return its own tree id (i.e. subvol id) Note:

The result is undefined for the so-called empty subvolumes (identified by inode number 2), but such a subvolume does not contain any files anyway

subvolid-resolve <subvolid> <path>

(needs root privileges) resolve the absolute path of the subvolume id subvolid

tree-stats [options] <device>

(needs root privileges) Print sizes and statistics of trees. This takes a device as an argument and not a mount point unlike other commands.

Note:

In case the the filesystem is still mounted it's possible to run the command but the results may be inaccurate or various errors may be printed in case there are ongoing writes to the filesystem. A warning is printed in such case.

Options

-b|--raw

raw numbers in bytes, without the B suffix

-t <tree_id>

print only the tree with the specified ID, where the ID can be numerical or common name in a flexible human readable form The tree id name recognition rules:

- case does not matter

- the C source definition, e.g. BTRFS_ROOT_TREE_OBJECTID

- short forms without BTRFS_ prefix, without _TREE and _OBJECTID suffix, e.g. ROOT_TREE, ROOT

- convenience aliases, e.g. DEVICE for the DEV tree, CHECKSUM for CSUM

- unrecognized ID is an error

--human-readable

print human friendly numbers, base 1024, this is the default

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

--kbytes

show sizes in KiB, or kB with --si

--mbytes

show sizes in MiB, or MB with --si

--gbytes

show sizes in GiB, or GB with --si

--tbytes

show sizes in TiB, or TB with --si

## EXIT STATUS
btrfs inspect-internal returns a zero exit status if it succeeds. Non zero is returned in case of failure.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at <https://btrfs.readthedocs.io>.

## SEE ALSO
mkfs.btrfs(8) <>


btrfs-map-logical

title: btrfs-map-logical(8)

text:
# btrfs-map-logical(8)

## NAME
btrfs-map-logical - map btrfs logical extent to physical extent

## SYNOPSIS
btrfs-map-logical <options> <device>

## DESCRIPTION
btrfs-map-logical can be used to find out what the physical offsets are on the mirrors, the result is dumped to stdout by default.

Mainly used for debug purpose.

## OPTIONS
-l|--logical <logical_num>

Logical extent to map.

-c|--copy <copy>

Copy of the extent to read(usually 1 or 2).

-o|--output <filename>

Output file to hold the extent.

-b|--bytes <bytes>

Number of bytes to read.

## EXIT STATUS
btrfs-map-logical will return 0 if no error happened. If any problems happened, 1 will be returned.

## SEE ALSO
mkfs.btrfs(8) <>


btrfs-property

title: btrfs-property(8)

text:
# btrfs-property(8)

## NAME
btrfs-property - get/set/list properties for given filesystem object

## SYNOPSIS
btrfs property <subcommand> <args>

## DESCRIPTION
btrfs property is used to get/set/list property for given filesystem object. The object can be an inode (file or directory), subvolume or the whole filesystem.

btrfs property provides an unified and user-friendly method to tune different btrfs properties instead of using the traditional method like chattr(1) <https://man7.org/linux/man-pages/man1/chattr.1.html> or lsattr(1) <https://man7.org/linux/man-pages/man1/lsattr.1.html>.

### Object types
A property might apply to several object types so in some cases it's necessary to specify that explicitly, however it's not needed in the most common case of files and directories.

The subcommands take parameter -t, use first letter as a shortcut (f/s/d/i) of the type:

- filesystem

- subvolume

- device

- inode (file or directory)

### Inode properties
compression

compression algorithm set for an inode (it's not possible to set the compression level this way), possible values:

- lzo

- zlib

- zstd

- no or none - disable compression (equivalent to chattr +m)

- "" (empty string) - set the default value

Note:

This has changed in version 5.18 of btrfs-progs and requires kernel 5.14 or newer to work.

### Subvolume properties
ro

read-only flag of subvolume: true or false. Please also see section SUBVOLUME FLAGS in btrfs-subvolume(8) <> for possible implications regarding incremental send.

### Filesystem properties
label

label of the filesystem. For an unmounted filesystem, provide a path to a block device as object. For a mounted filesystem, specify a mount point.

## SUBCOMMAND
get [-t <type>] <object> [<name>]

Read value of a property name of btrfs object of given type, empty name will read all of them

list [-t <type>] <object>

List available properties with their descriptions for the given object.

set [-f] [-t <type>] <object> <name> <value>

Set value of property name on a given btrfs object. Options

-f

Force the change. Changing some properties may involve safety checks or additional changes that depend on the properties semantics.

## EXAMPLES
Set compression on a file:

```
$ touch file1
$ btrfs prop get file1
[ empty output ]
$ btrfs prop set file1 compression zstd
$ btrfs prop get file1
compression=zstd
```

Make a writeable subvolume read-only:

```
$ btrfs subvol create subvol1
[ fill subvol1 with data ]
$ btrfs prop get subvol1
ro=false
$ btrfs prop set subvol1 ro true
ro=true
```

## EXIT STATUS
btrfs property returns a zero exit status if it succeeds. Non zero is returned in case of failure.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at <https://btrfs.readthedocs.io>.

## SEE ALSO
mkfs.btrfs(8) <>, lsattr(1) <https://man7.org/linux/man-pages/man1/lsattr.1.html>, chattr(1) <https://man7.org/linux/man-pages/man1/chattr.1.html>


btrfs-qgroup

title: btrfs-qgroup(8)

text:
# btrfs-qgroup(8)

## NAME
btrfs-qgroup - control the quota group of a btrfs filesystem

## SYNOPSIS
btrfs qgroup <subcommand> <args>

## DESCRIPTION
btrfs qgroup is used to control quota group (qgroup) of a btrfs filesystem.

Note:

To use qgroup you need to enable quota first using btrfs quota enable command, see btrfs-quota(8) <>.

## QGROUP
Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups are attached to subvolumes. The size limits are set per qgroup and apply when any limit is reached in tree that contains a given subvolume.

The limits are separated between shared and exclusive and reflect the extent ownership. For example a fresh snapshot shares almost all the blocks with the original subvolume, new writes to either subvolume will raise towards the exclusive limit. Extent sharing is also result of reflink or deduplication.

Note:

Qgroup limit only works when qgroup is in a consistent state. If some workload marks qgroup inconsistent (like assigning a qgroup to another qgroup), the limit will no longer work until the inconsistent flag is cleared by btrfs quota rescan.

The qgroup identifiers conform to level/id where level 0 is reserved to the qgroups associated with subvolumes. Such qgroups are created automatically.

The qgroup hierarchy is built by commands btrfs qgroup create and btrfs qgroup assign.

Note:

If the qgroup of a subvolume is destroyed, quota related to the subvolume will not be functional until qgroup 0/<subvolume id> is created again.

## SUBCOMMAND
assign [options] <src> <dst> <path>

Assign qgroup src as the child qgroup of dst in the btrfs filesystem identified by path. Options

--rescan

(default since: 4.19) Automatically schedule quota rescan if the new qgroup assignment would lead to quota inconsistency. See QUOTA RESCAN for more information.

--no-rescan

Explicitly ask not to do a rescan, even if the assignment will make the quotas inconsistent. This may be useful for repeated calls where the rescan would add unnecessary overhead.

create <qgroupid> <path>

Create a subvolume quota group. For the 0/<subvolume id> qgroup, a qgroup can be created even before the subvolume is created.

destroy <qgroupid> <path>

Destroy a qgroup. If a qgroup is not isolated, meaning it is a parent or child qgroup, then it can only be destroyed after the relationship is removed.

clear-stale <path>

Clear all stale qgroups whose subvolume does not exist anymore, this is the level 0 qgroup like 0/subvolid. Higher level qgroups are not deleted even if they don't have any child qgroups as they are always created by the user and their deletion should be verified first.

limit [options] <size>|none [<qgroupid>] <path>

Limit the size of a qgroup to size or no limit in the btrfs filesystem identified by path. If qgroupid is not given, qgroup of the subvolume identified by path is used if possible.

Options

-c

limit amount of data after compression. This is the default, it is currently not possible to turn off this option.

-e

limit space exclusively assigned to this qgroup.

remove <src> <dst> <path>

Remove the relationship between child qgroup src and parent qgroup dst in the btrfs filesystem identified by path. Options

--rescan

(default since: 4.19) Automatically schedule quota rescan if the removed qgroup relation would lead to quota inconsistency. See QUOTA RESCAN for more information.

--no-rescan

Explicitly ask not to do a rescan, even if the removal will make the quotas inconsistent. This may be useful for repeated calls where the rescan would add unnecessary overhead.

show [options] <path>

Show all qgroups in the btrfs filesystem identified by <path>. Options

-p

print parent qgroup id.

-c

print child qgroup id.

-r

print limit of referenced size of qgroup.

-e

print limit of exclusive size of qgroup.

-F

list all qgroups which impact the given path(include ancestral qgroups)

-f

list all qgroups which impact the given path(exclude ancestral qgroups)

--raw

raw numbers in bytes, without the B suffix.

--human-readable

print human friendly numbers, base 1024, this is the default

--iec

select the 1024 base for the following options, according to the IEC standard.

--si

select the 1000 base for the following options, according to the SI standard.

--kbytes

show sizes in KiB, or kB with --si.

--mbytes

show sizes in MiB, or MB with --si.

--gbytes

show sizes in GiB, or GB with --si.

--tbytes

show sizes in TiB, or TB with --si.

--sort=[+/-]<attr>[,[+/-]<attr>]...

list qgroups in order of <attr>. <attr> can be one or more of qgroupid,rfer,excl,max_rfer,max_excl.

Prefix + means ascending order and - means descending order of attr. If no prefix is given, use ascending order by default.

If multiple attr values are given, use comma to separate.

--sync

To retrieve information after updating the state of qgroups, force sync of the filesystem identified by path before getting information.

## SPECIAL PATHS
For btrfs qgroup show command, the path column can print special values:

<toplevel>

The toplevel subvolume.

<under deletion>

The subvolume has been deleted (its directory removed), but the subvolume metadata not not yet fully cleaned.

<squota space holder>

For simple quota mode only. By its design, a fully deleted subvolume may still have accounting on it, so even if the subvolume is gone, the numbers are still here for future accounting.

<stale>

The qgroup has no corresponding subvolume anymore, and the qgroup can be cleaned up under most cases. The only exception is that, if the qgroup numbers are inconsistent and the qgroup numbers are not all zeros, some older kernels may refuse to delete such qgroups until a full rescan.

## QUOTA RESCAN
The rescan reads all extent sharing metadata and updates the respective qgroups accordingly.

The information consists of bytes owned exclusively (excl) or shared/referenced to (rfer). There's no explicit information about which extents are shared or owned exclusively. This means when qgroup relationship changes, extent owners change and qgroup numbers are no longer consistent unless we do a full rescan.

However there are cases where we can avoid a full rescan, if a subvolume whose rfer number equals its excl number, which means all bytes are exclusively owned, then assigning/removing this subvolume only needs to add/subtract rfer number from its parent qgroup. This can speed up the rescan.

## EXAMPLES

### Make a parent group that has two quota group children
Given the following filesystem mounted at /mnt/my-vault

```
Label: none  uuid: 60d2ab3b-941a-4f22-8d1a-315f329797b2

       Total devices 1 FS bytes used 128.00KiB

       devid    1 size 5.00GiB used 536.00MiB path /dev/vdb
```

Enable quota and create subvolumes. Check subvolume ids.

```
$ cd /mnt/my-vault
$ btrfs quota enable .
$ btrfs subvolume create a
$ btrfs subvolume create b
$ btrfs subvolume list .
ID 261 gen 61 top level 5 path a
ID 262 gen 62 top level 5 path b
```

Create qgroup and set limit to 10MiB.

```
$ btrfs qgroup create 1/100 .
$ btrfs qgroup limit 10M 1/100 .
$ btrfs qgroup assign 0/261 1/100 .
$ btrfs qgroup assign 0/262 1/100 .
```

And check qgroups.

```
$ btrfs qgroup show .
qgroupid         rfer         excl
--------         ----         ----
0/5          16.00KiB     16.00KiB
0/261        16.00KiB     16.00KiB
0/262        16.00KiB     16.00KiB
1/100        32.00KiB     32.00KiB
```

## EXIT STATUS
btrfs qgroup returns a zero exit status if it succeeds. Non zero is returned in case of failure.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at <https://btrfs.readthedocs.io>.

## SEE ALSO
btrfs-quota(8) <>, btrfs-subvolume(8) <>, mkfs.btrfs(8) <>