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:

Contains file names, consider that if you're asked to send the dump for analysis. Does not contain file data.

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

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

Print raw numbers in bytes.

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

package: btrfs-progs

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) or lsattr(1).

### 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), chattr(1)


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.

WARNING:

Qgroup is not stable yet and will impact performance in current mainline kernel (v4.14).

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

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 create and assign.

NOTE:

If the qgroup of a subvolume is destroyed, quota about 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.

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.

## 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/referred 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),


btrfs-quota

title: btrfs-quota(8)

text:
# btrfs-quota(8)

## NAME
btrfs-quota - control the global quota status of a btrfs filesystem

## SYNOPSIS
btrfs quota <subcommand> <args>

## DESCRIPTION
The commands under btrfs quota are used to affect the global status of quotas of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand btrfs-qgroup(8).

NOTE:

Qgroups are different than the traditional user quotas and designed to track shared and exclusive data per-subvolume. Please refer to the section HIERARCHICAL QUOTA GROUP CONCEPTS for a detailed description.

### PERFORMANCE IMPLICATIONS
When quotas are activated, they affect all extent processing, which takes a performance hit. Activation of qgroups is not recommended unless the user intends to actually use them.

### STABILITY STATUS
The qgroup implementation has turned out to be quite difficult as it affects the core of the filesystem operation. Qgroup users have hit various corner cases over time, such as incorrect accounting or system instability. The situation is gradually improving and issues found and fixed.

## HIERARCHICAL QUOTA GROUP CONCEPTS
The concept of quota has a long-standing tradition in the Unix world. Ever since computers allow multiple users to work simultaneously in one filesystem, there is the need to prevent one user from using up the entire space. Every user should get his fair share of the available resources.

In case of files, the solution is quite straightforward. Each file has an owner recorded along with it, and it has a size. Traditional quota just restricts the total size of all files that are owned by a user. The concept is quite flexible: if a user hits his quota limit, the administrator can raise it on the fly.

On the other hand, the traditional approach has only a poor solution to restrict directories. At installation time, the harddisk can be partitioned so that every directory (e.g. /usr, /var/, ...) that needs a limit gets its own partition. The obvious problem is that those limits cannot be changed without a reinstallation. The btrfs subvolume feature builds a bridge. Subvolumes correspond in many ways to partitions, as every subvolume looks like its own filesystem. With subvolume quota, it is now possible to restrict each subvolume like a partition, but keep the flexibility of quota. The space for each subvolume can be expanded or restricted on the fly.

As subvolumes are the basis for snapshots, interesting questions arise as to how to account used space in the presence of snapshots. If you have a file shared between a subvolume and a snapshot, whom to account the file to? The creator? Both? What if the file gets modified in the snapshot, should only these changes be accounted to it? But wait, both the snapshot and the subvolume belong to the same user home. I just want to limit the total space used by both! But somebody else might not want to charge the snapshots to the users.

Btrfs subvolume quota solves these problems by introducing groups of subvolumes and let the user put limits on them. It is even possible to have groups of groups. In the following, we refer to them as qgroups.

Each qgroup primarily tracks two numbers, the amount of total referenced space and the amount of exclusively referenced space.

referenced

space is the amount of data that can be reached from any of the subvolumes contained in the qgroup, while

exclusive

is the amount of data where all references to this data can be reached from within this qgroup.

### Subvolume quota groups
The basic notion of the Subvolume Quota feature is the quota group, short qgroup. Qgroups are notated as level/id, e.g. the qgroup 3/2 is a qgroup of level 3. For level 0, the leading '0/' can be omitted. Qgroups of level 0 get created automatically when a subvolume/snapshot gets created. The ID of the qgroup corresponds to the ID of the subvolume, so 0/5 is the qgroup for the root subvolume. For the btrfs qgroup command, the path to the subvolume can also be used instead of 0/ID. For all higher levels, the ID can be chosen freely.

Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy of qgroups. Figure 1 shows an example qgroup tree.

```
                          +---+

                          |2/1|

                          +---+

                         /     \

                   +---+/       \+---+

                   |1/1|         |1/2|

                   +---+         +---+

                  /     \       /     \

            +---+/       \+---+/       \+---+
qgroups     |0/1|         |0/2|         |0/3|

            +-+-+         +---+         +---+

              |          /     \       /     \

              |         /       \     /       \

              |        /         \   /         \
extents       1       2            3            4
Figure 1: Sample qgroup hierarchy
```

At the bottom, some extents are depicted showing which qgroups reference which extents. It is important to understand the notion of referenced vs exclusive. In the example, qgroup 0/2 references extents 2 and 3, while 1/2 references extents 2-4, 2/1 references all extents.

On the other hand, extent 1 is exclusive to 0/1, extent 2 is exclusive to 0/2, while extent 3 is neither exclusive to 0/2 nor to 0/3. But because both references can be reached from 1/2, extent 3 is exclusive to 1/2. All extents are exclusive to 2/1.

So exclusive does not mean there is no other way to reach the extent, but it does mean that if you delete all subvolumes contained in a qgroup, the extent will get deleted.

Exclusive of a qgroup conveys the useful information how much space will be freed in case all subvolumes of the qgroup get deleted.

All data extents are accounted this way. Metadata that belongs to a specific subvolume (i.e. its filesystem tree) is also accounted. Checksums and extent allocation information are not accounted.

In turn, the referenced count of a qgroup can be limited. All writes beyond this limit will lead to a 'Quota Exceeded' error.

### Inheritance
Things get a bit more complicated when new subvolumes or snapshots are created. The case of (empty) subvolumes is still quite easy. If a subvolume should be part of a qgroup, it has to be added to the qgroup at creation time. To add it at a later time, it would be necessary to at least rescan the full subvolume for a proper accounting.

Creation of a snapshot is the hard case. Obviously, the snapshot will reference the exact amount of space as its source, and both source and destination now have an exclusive count of 0 (the filesystem nodesize to be precise, as the roots of the trees are not shared). But what about qgroups of higher levels? If the qgroup contains both the source and the destination, nothing changes. If the qgroup contains only the source, it might lose some exclusive.

But how much? The tempting answer is, subtract all exclusive of the source from the qgroup, but that is wrong, or at least not enough. There could have been an extent that is referenced from the source and another subvolume from that qgroup. This extent would have been exclusive to the qgroup, but not to the source subvolume. With the creation of the snapshot, the qgroup would also lose this extent from its exclusive set.

So how can this problem be solved? In the instant the snapshot gets created, we already have to know the correct exclusive count. We need to have a second qgroup that contains all the subvolumes as the first qgroup, except the subvolume we want to snapshot. The moment we create the snapshot, the exclusive count from the second qgroup needs to be copied to the first qgroup, as it represents the correct value. The second qgroup is called a tracking qgroup. It is only there in case a snapshot is needed.

### Use cases
Below are some use cases that do not mean to be extensive. You can find your own way how to integrate qgroups.

### Single-user machine
Replacement for partitions

The simplest use case is to use qgroups as simple replacement for partitions. Btrfs takes the disk as a whole, and /, /usr, /var, etc. are created as subvolumes. As each subvolume gets it own qgroup automatically, they can simply be restricted. No hierarchy is needed for that.

Track usage of snapshots

When a snapshot is taken, a qgroup for it will automatically be created with the correct values. 'Referenced' will show how much is in it, possibly shared with other subvolumes. 'Exclusive' will be the amount of space that gets freed when the subvolume is deleted.

### Multi-user machine
Restricting homes

When you have several users on a machine, with home directories probably under /home, you might want to restrict /home as a whole, while restricting every user to an individual limit as well. This is easily accomplished by creating a qgroup for /home , e.g. 1/1, and assigning all user subvolumes to it. Restricting this qgroup will limit /home, while every user subvolume can get its own (lower) limit.

Accounting snapshots to the user

Let's say the user is allowed to create snapshots via some mechanism. It would only be fair to account space used by the snapshots to the user. This does not mean the user doubles his usage as soon as he takes a snapshot. Of course, files that are present in his home and the snapshot should only be accounted once. This can be accomplished by creating a qgroup for each user, say '1/UID'. The user home and all snapshots are assigned to this qgroup. Limiting it will extend the limit to all snapshots, counting files only once. To limit /home as a whole, a higher level group 2/1 replacing 1/1 from the previous example is needed, with all user qgroups assigned to it.

Do not account snapshots

On the other hand, when the snapshots get created automatically, the user has no chance to control them, so the space used by them should not be accounted to him. This is already the case when creating snapshots in the example from the previous section.

Snapshots for backup purposes

This scenario is a mixture of the previous two. The user can create snapshots, but some snapshots for backup purposes are being created by the system. The user's snapshots should be accounted to the user, not the system. The solution is similar to the one from section 'Accounting snapshots to the user', but do not assign system snapshots to user's qgroup.

## SUBCOMMAND
disable <path>

Disable subvolume quota support for a filesystem.

enable <path>

Enable subvolume quota support for a filesystem.

rescan [options] <path>

Trash all qgroup numbers and scan the metadata again with the current config. Options

-s|--status

show status of a running rescan operation.

-w|--wait

start rescan and wait for it to finish (can be already in progress)

-W|--wait-norescan

wait for rescan to finish without starting it

## EXIT STATUS
btrfs quota 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-qgroup(8), btrfs-subvolume(8), mkfs.btrfs(8)


btrfs-receive

title: btrfs-receive(8)

summary: receive subvolumes from send stream

text:
# btrfs-receive(8)

## NAME
btrfs-receive - receive subvolumes from send stream

## SYNOPSIS
btrfs receive [options] <path>

or

btrfs receive --dump [options]

## DESCRIPTION
Receive a stream of changes and replicate one or more subvolumes that were previously generated by btrfs send. The received subvolumes are stored to path, unless --dump option is given.

If --dump option is specified, btrfs receive will only do the validation of the stream, and print the stream metadata, one operation per line.

btrfs receive will fail in the following cases:

1.

receiving subvolume already exists

2.

previously received subvolume has been changed after it was received

3.

default subvolume has changed or you didn't mount the filesystem at the toplevel subvolume

A subvolume is made read-only after the receiving process finishes successfully (see BUGS below).

Options

-f <FILE>

read the stream from FILE instead of stdin,

-C|--chroot

confine the process to path using chroot(1)

-e

terminate after receiving an end cmd marker in the stream. Without this option the receiver side terminates only in case of an error on end of file.

-E|--max-errors <NERR>

terminate as soon as NERR errors occur while stream processing commands from the stream Default value is 1. A value of 0 means no limit.

-m <ROOTMOUNT>

the root mount point of the destination filesystem By default the mount point is searched in /proc/self/mounts. If /proc is not accessible, e.g. in a chroot environment, use this option to tell us where this filesystem is mounted.

--force-decompress

if the stream contains compressed data (see --compressed-data in btrfs-send(8)), always decompress it instead of writing it with encoded I/O

--dump

dump the stream metadata, one line per operation Does not require the path parameter. The filesystem remains unchanged.

-q|--quiet

(deprecated) alias for global -q option

-v

(deprecated) alias for global -v option

Global options

-v|--verbose

increase verbosity about performed actions, print details about each operation

-q|--quiet

suppress all messages except errors

## BUGS
btrfs receive sets the subvolume read-only after it completes successfully. However, while the receive is in progress, users who have write access to files or directories in the receiving path can add, remove, or modify files, in which case the resulting read-only subvolume will not be an exact copy of the sent subvolume.

If the intention is to create an exact copy, the receiving path should be protected from access by users until the receive operation has completed and the subvolume is set to read-only.

Additionally, receive does not currently do a very good job of validating that an incremental send stream actually makes sense, and it is thus possible for a specially crafted send stream to create a subvolume with reflinks to arbitrary files in the same filesystem. Because of this, users are advised to not use btrfs receive on send streams from untrusted sources, and to protect trusted streams when sending them across untrusted networks.

## EXIT STATUS
btrfs receive 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-send(8), mkfs.btrfs(8)


btrfs-replace

title: btrfs-replace(8)

text:
# btrfs-replace(8)

## NAME
btrfs-replace - replace devices managed by btrfs with other device

## SYNOPSIS
btrfs replace <subcommand> <args>

## DESCRIPTION
btrfs replace is used to replace btrfs managed devices with other device.

## SUBCOMMAND
cancel <mount_point>

Cancel a running device replace operation.

start [options] <srcdev>|<devid> <targetdev> <path>

Replace device of a btrfs filesystem. On a live filesystem, duplicate the data to the target device which is currently stored on the source device. If the source device is not available anymore, or if the -r option is set, the data is built only using the RAID redundancy mechanisms. After completion of the operation, the source device is removed from the filesystem. If the srcdev is a numerical value, it is assumed to be the device id of the filesystem which is mounted at path, otherwise it is the path to the source device. If the source device is disconnected, from the system, you have to use the devid parameter format. The targetdev needs to be same size or larger than the srcdev.

NOTE:

The filesystem has to be resized to fully take advantage of a larger target device; this can be achieved with btrfs filesystem resize <devid>:max /path

Options

-r

only read from srcdev if no other zero-defect mirror exists. (enable this if your drive has lots of read errors, the access would be very slow)

-f

force using and overwriting targetdev even if it looks like it contains a valid btrfs filesystem. A valid filesystem is assumed if a btrfs superblock is found which contains a correct checksum. Devices that are currently mounted are never allowed to be used as the targetdev.

-B

no background replace.

--enqueue

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

-K|--nodiscard

Do not perform whole device TRIM operation on devices that are capable of that. This does not affect discard/trim operation when the filesystem is mounted. Please see the mount option discard for that in btrfs(5).

status [-1] <mount_point>

Print status and progress information of a running device replace operation. Options

-1

print once instead of print continuously until the replace operation finishes (or is cancelled)

## EXAMPLES

### Replacing an online drive with a bigger one
Given the following filesystem mounted at /mnt/my-vault

```
Label: 'MyVault'  uuid: ae20903e-b72d-49ba-b944-901fc6d888a1

        Total devices 2 FS bytes used 1TiB

        devid    1 size 1TiB used 500.00GiB path /dev/sda

        devid    2 size 1TiB used 500.00GiB path /dev/sdb
```

In order to replace /dev/sda (devid 1) with a bigger drive located at /dev/sdc you would run the following:

```
btrfs replace start 1 /dev/sdc /mnt/my-vault/
```

You can monitor progress via:

```
btrfs replace status /mnt/my-vault/
```

After the replacement is complete, as per the docs at btrfs-filesystem(8) in order to use the entire storage space of the new drive you need to run:

```
btrfs filesystem resize 1:max /mnt/my-vault/
```

## EXIT STATUS
btrfs replace 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-device(8), btrfs-filesystem(8), mkfs.btrfs(8)


btrfs-rescue

title: btrfs-rescue(8)

summary: recover a damaged btrfs filesystem

text:
# btrfs-rescue(8)

## NAME
btrfs-rescue - recover a damaged btrfs filesystem

## SYNOPSIS
btrfs rescue <subcommand> <args>

## DESCRIPTION
btrfs rescue is used to try to recover a damaged btrfs filesystem.

## SUBCOMMAND
chunk-recover [options] <device>

Recover the chunk tree by scanning the devices Options

-y

assume an answer of yes to all questions.

-h

help.

-v

(deprecated) alias for global -v option

NOTE:

Since chunk-recover will scan the whole device, it will be very slow especially executed on a large device.

fix-device-size <device>

fix device size and super block total bytes values that are do not match Kernel 4.11 starts to check the device size more strictly and this might mismatch the stored value of total bytes. See the exact error message below. Newer kernel will refuse to mount the filesystem where the values do not match. This error is not fatal and can be fixed. This command will fix the device size values if possible.

```
BTRFS error (device sdb): super_total_bytes 92017859088384 mismatch with fs_devices total_rw_bytes 92017859094528
```

The mismatch may also exhibit as a kernel warning:

```
WARNING: CPU: 3 PID: 439 at fs/btrfs/ctree.h:1559 btrfs_update_device+0x1c5/0x1d0 [btrfs]
```

clear-uuid-tree <device>

Clear UUID tree, so that kernel can re-generate it at next read-write mount. Since kernel v4.16 there are more sanity check performed, and sometimes non-critical trees like UUID tree can cause problems and reject the mount. In such case, clearing UUID tree may make the filesystem to be mountable again without much risk as it's built from other trees.

super-recover [options] <device>

Recover bad superblocks from good copies. Options

-y

assume an answer of yes to all questions.

-v

(deprecated) alias for global -v option

zero-log <device>

clear the filesystem log tree This command will clear the filesystem log tree. This may fix a specific set of problem when the filesystem mount fails due to the log replay. See below for sample stack traces that may show up in system log.

The common case where this happens was fixed a long time ago, so it is unlikely that you will see this particular problem, but the command is kept around.

NOTE:

Clearing the log may lead to loss of changes that were made since the last transaction commit. This may be up to 30 seconds (default commit period) or less if the commit was implied by other filesystem activity.

One can determine whether zero-log is needed according to the kernel backtrace:

```
? replay_one_dir_item+0xb5/0xb5 [btrfs]
? walk_log_tree+0x9c/0x19d [btrfs]
? btrfs_read_fs_root_no_radix+0x169/0x1a1 [btrfs]
? btrfs_recover_log_trees+0x195/0x29c [btrfs]
? replay_one_dir_item+0xb5/0xb5 [btrfs]
? btree_read_extent_buffer_pages+0x76/0xbc [btrfs]
? open_ctree+0xff6/0x132c [btrfs]
```

If the errors are like above, then zero-log should be used to clear the log and the filesystem may be mounted normally again. The keywords to look for are 'open_ctree' which says that it's during mount and function names that contain replay, recover or log_tree.

## EXIT STATUS
btrfs rescue 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-check(8), btrfs-scrub(8), mkfs.btrfs(8)


btrfs-restore

title: btrfs-restore(8)

text:
# btrfs-restore(8)

## NAME
btrfs-restore - try to restore files from a damaged filesystem image

## SYNOPSIS
btrfs restore [options] <device> <path> | -l <device>

## DESCRIPTION
btrfs restore is used to try to salvage files from a damaged filesystem and restore them into path or just list the subvolume tree roots. The filesystem image is not modified.

If the filesystem is damaged and cannot be repaired by the other tools (btrfs-check(8) or btrfs-rescue(8)), btrfs restore could be used to retrieve file data, as far as the metadata are readable. The checks done by restore are less strict and the process is usually able to get far enough to retrieve data from the whole filesystem. This comes at a cost that some data might be incomplete or from older versions if they're available.

There are several options to attempt restoration of various file metadata type. You can try a dry run first to see how well the process goes and use further options to extend the set of restored metadata.

For images with damaged tree structures, there are several options to point the process to some spare copy.

NOTE:

It is recommended to read the following btrfs wiki page if your data is not salvaged with default option: https://btrfs.wiki.kernel.org/index.php/Restore

## OPTIONS
-s|--snapshots

get also snapshots that are skipped by default

-x|--xattr

get extended attributes

-m|--metadata

restore owner, mode and times for files and directories

-S|--symlinks

restore symbolic links as well as normal files

-i|--ignore-errors

ignore errors during restoration and continue

-o|--overwrite

overwrite directories/files in path, e.g. for repeated runs

-t <bytenr>

use bytenr to read the root tree

-f <bytenr>

only restore files that are under specified subvolume root pointed by bytenr

-u|--super <mirror>

use given superblock mirror identified by <mirror>, it can be 0,1 or 2

-r|--root <rootid>

only restore files that are under a specified subvolume whose objectid is rootid

-d

find directory

-l|--list-roots

list subvolume tree roots, can be used as argument for -r

-D|--dry-run

dry run (only list files that would be recovered)

--path-regex <regex>

restore only filenames matching a regular expression (regex(7)) with a mandatory format ^/(|home(|/username(|/Desktop(|/.*))))$

The format is not very comfortable and restores all files in the directories in the whole path, so this is not useful for restoring single file in a deep hierarchy.

-c

ignore case (--path-regex only)

-v|--verbose

(deprecated) alias for global -v option

Global options

-v|--verbose

be verbose and print what is being restored

## EXIT STATUS
btrfs restore 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-check(8), btrfs-rescue(8), mkfs.btrfs(8)


btrfs-scrub

title: btrfs-scrub(8)

text:
# btrfs-scrub(8)

## NAME
btrfs-scrub - scrub btrfs filesystem, verify block checksums

## SYNOPSIS
btrfs scrub <subcommand> <args>

## DESCRIPTION
Scrub is a pass over all filesystem data and metadata and verifying the checksums. If a valid copy is available (replicated block group profiles) then the damaged one is repaired. All copies of the replicated profiles are validated.

NOTE:

Scrub is not a filesystem checker (fsck) and does not verify nor repair structural damage in the filesystem. It really only checks checksums of data and tree blocks, it doesn't ensure the content of tree blocks is valid and consistent. There's some validation performed when metadata blocks are read from disk but it's not extensive and cannot substitute full btrfs check run.

The user is supposed to run it manually or via a periodic system service. The recommended period is a month but could be less. The estimated device bandwidth utilization is about 80% on an idle filesystem. The IO priority class is by default idle so background scrub should not significantly interfere with normal filesystem operation. The IO scheduler set for the device(s) might not support the priority classes though.

The scrubbing status is recorded in /var/lib/btrfs/ in textual files named scrub.status.UUID for a filesystem identified by the given UUID. (Progress state is communicated through a named pipe in file scrub.progress.UUID in the same directory.) The status file is updated every 5 seconds. A resumed scrub will continue from the last saved position.

Scrub can be started only on a mounted filesystem, though it's possible to scrub only a selected device. See btrfs scrub start for more.

## SUBCOMMAND
cancel <path>|<device>

If a scrub is running on the filesystem identified by path or device, cancel it. If a device is specified, the corresponding filesystem is found and btrfs scrub cancel behaves as if it was called on that filesystem. The progress is saved in the status file so btrfs scrub resume can continue from the last position.

resume [-BdqrR] <path>|<device>

Resume a cancelled or interrupted scrub on the filesystem identified by path or on a given device. The starting point is read from the status file if it exists. This does not start a new scrub if the last scrub finished successfully.

Options

see scrub start.

start [-BdrRf] <path>|<device>

Start a scrub on all devices of the mounted filesystem identified by path or on a single device. If a scrub is already running, the new one will not start. A device of an unmounted filesystem cannot be scrubbed this way. Without options, scrub is started as a background process. The automatic repairs of damaged copies are performed by default for block group profiles with redundancy. No-repair can be enabled by option -r.

Options

-B

do not background and print scrub statistics when finished

-d

print separate statistics for each device of the filesystem (-B only) at the end

-r

run in read-only mode, do not attempt to correct anything, can be run on a read-only filesystem

-R

raw print mode, print full data instead of summary

-f

force starting new scrub even if a scrub is already running, this can useful when scrub status file is damaged and reports a running scrub although it is not, but should not normally be necessary

Deprecated options

-c <ioprio_class>

set IO priority class (see ionice(1) manpage) if the IO scheduler configured for the device supports ionice. This is not supported byg BFQ or Kyber but is not supported by mq-deadline.

-n <ioprio_classdata>

set IO priority classdata (see ionice(1) manpage)

-q

(deprecated) alias for global -q option

status [options] <path>|<device>

Show status of a running scrub for the filesystem identified by path or for the specified device. If no scrub is running, show statistics of the last finished or cancelled scrub for that filesystem or device.

Options

-d

print separate statistics for each device of the filesystem

-R

print all raw statistics without postprocessing as returned by the status ioctl

--raw

print all numbers raw values 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

A status on a filesystem without any error looks like the following:

```
# btrfs scrub start /
# btrfs scrub status /
UUID:             76fac721-2294-4f89-a1af-620cde7a1980
Scrub started:    Wed Apr 10 12:34:56 2023
Status:           running
Duration:         0:00:05
Time left:        0:00:05
ETA:              Wed Apr 10 12:35:01 2023
Total to scrub:   28.32GiB
Bytes scrubbed:   13.76GiB  (48.59%)
Rate:             2.75GiB/s
Error summary:    no errors found
```

With some errors found:

```
Error summary:    csum=72

  Corrected:      2

  Uncorrectable:  72

  Unverified:     0
```

- Corrected -- number of bad blocks that were repaired from another copy

- Uncorrectable -- errors detected at read time but not possible to repair from other copy

- Unverified -- transient errors, first read failed but a retry succeeded, may be affected by lower layers that group or split IO requests

- Error summary -- followed by a more detailed list of errors found

- csum -- checksum mismatch

- super -- super block errors, unless the error is fixed immediately, the next commit will overwrite superblock

- verify -- metadata block header errors

- read -- blocks can't be read due to IO errors

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

1

scrub couldn't be performed

2

there is nothing to resume

3

scrub found uncorrectable errors

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

## SEE ALSO
mkfs.btrfs(8)


btrfs-select-super

title: btrfs-select-super(8)

text:
# btrfs-select-super(8)

## NAME
btrfs-select-super - overwrite primary superblock with a backup copy

## SYNOPSIS
btrfs-select-super -s number <device>

## DESCRIPTION
Destructively overwrite all copies of the superblock with a specified copy. This helps in certain cases, for example when write barriers were disabled during a power failure and not all superblocks were written, or if the primary superblock is damaged, e.g. accidentally overwritten.

The filesystem specified by device must not be mounted.

NOTE:

Prior to overwriting the primary superblock, please make sure that the backup copies are valid!

To dump a superblock use the btrfs inspect-internal dump-super command.

Then run the check (in the non-repair mode) using the command btrfs check -s where -s specifies the superblock copy to use.

Superblock copies exist in the following offsets on the device:

- primary: 64KiB (65536)

- 1st copy: 64MiB (67108864)

- 2nd copy: 256GiB (274877906944)

A superblock size is 4KiB (4096).

## OPTIONS
-s|--super <N>

use Nth superblock copy, valid values are 0 1 or 2 if the respective superblock offset is within the device size

## SEE ALSO
btrfs(8)


btrfs-send

title: btrfs-send(8)

text:
# btrfs-send(8)

## NAME
btrfs-send - generate a stream of changes between two subvolume snapshots

## SYNOPSIS
btrfs send [-ve] [-p <parent>] [-c <clone-src>] [-f <outfile>] <subvol> [<subvol>...]

## DESCRIPTION
This command will generate a stream of instructions that describe changes between two subvolume snapshots. The stream can be consumed by the btrfs receive command to replicate the sent snapshot on a different filesystem. The command operates in two modes: full and incremental.

All snapshots involved in one send command must be read-only, and this status cannot be changed as long as there's a running send operation that uses the snapshot. Read-only mount of the subvolume is not sufficient, there's no way to guarantee that there won't be any other writable mount of the same subvolume that would potentially write while send would be running.

In the full mode, the entire snapshot data and metadata will end up in the stream.

In the incremental mode (options -p and -c), previously sent snapshots that are available on both the sending and receiving side can be used to reduce the amount of information that has to be sent to reconstruct the sent snapshot on a different filesystem.

The -p <parent> option can be omitted when -c <clone-src> options are given, in which case btrfs send will determine a suitable parent from among the clone sources.

You must not specify clone sources unless you guarantee that these snapshots are exactly in the same state on both sides--both for the sender and the receiver. For implications of changed read-write status of a received snapshot please see section SUBVOLUME FLAGS in btrfs-subvolume(8).

Options

-e

if sending multiple subvolumes at once, use the new format and omit the 'end cmd' marker in the stream separating the subvolumes

-p <parent>

send an incremental stream from parent to subvol

-c <clone-src>

use this snapshot as a clone source for an incremental send (multiple allowed)

-f <outfile>

output is normally written to standard output so it can be, for example, piped to btrfs receive. Use this option to write it to a file instead.

--no-data

send in NO_FILE_DATA mode The output stream does not contain any file data and thus cannot be used to transfer changes. This mode is faster and is useful to show the differences in metadata.

--proto <N>

use send protocol version N The default is 1, which was the original protocol version. Version 2 encodes file data slightly more efficiently; it is also required for sending compressed data directly (see --compressed-data). Version 2 requires at least btrfs-progs 6.0 on both the sender and receiver and at least Linux 6.0 on the sender. Passing 0 means to use the highest version supported by the running kernel.

--compressed-data

send data that is compressed on the filesystem directly without decompressing it If the receiver supports the BTRFS_IOC_ENCODED_WRITE ioctl (added in Linux 6.0), it can also write it directly without decompressing it. Otherwise, the receiver will fall back to decompressing it and writing it normally.

This requires protocol version 2 or higher. If --proto was not used, then --compressed-data implies --proto 2.

-q|--quiet

(deprecated) alias for global -q option

-v|--verbose

(deprecated) alias for global -v option

Global options

-q|--quiet

suppress all messages except errors

-v|--verbose

increase output verbosity, print generated commands in a readable form

## EXIT STATUS
btrfs send 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-receive(8), btrfs-subvolume(8), mkfs.btrfs(8)


btrfs-subvolume

title: btrfs-subvolume(8)

summary: manage btrfs subvolumes

text:
# btrfs-subvolume(8)

## NAME
btrfs-subvolume - manage btrfs subvolumes

## SYNOPSIS
btrfs subvolume <subcommand> [<args>]

## DESCRIPTION
btrfs subvolume is used to create/delete/list/show btrfs subvolumes and snapshots.

A BTRFS subvolume is a part of filesystem with its own independent file/directory hierarchy and inode number namespace. Subvolumes can share file extents. A snapshot is also subvolume, but with a given initial content of the original subvolume. A subvolume has always inode number 256.

NOTE:

A subvolume in BTRFS is not like an LVM logical volume, which is block-level snapshot while BTRFS subvolumes are file extent-based.

A subvolume looks like a normal directory, with some additional operations described below. Subvolumes can be renamed or moved, nesting subvolumes is not restricted but has some implications regarding snapshotting. The numeric id (called subvolid or rootid) of the subvolume is persistent and cannot be changed.

A subvolume in BTRFS can be accessed in two ways:

- like any other directory that is accessible to the user

- like a separately mounted filesystem (options subvol or subvolid)

In the latter case the parent directory is not visible and accessible. This is similar to a bind mount, and in fact the subvolume mount does exactly that.

A freshly created filesystem is also a subvolume, called top-level, internally has an id 5. This subvolume cannot be removed or replaced by another subvolume. This is also the subvolume that will be mounted by default, unless the default subvolume has been changed (see btrfs subvolume set-default).

A snapshot is a subvolume like any other, with given initial content. By default, snapshots are created read-write. File modifications in a snapshot do not affect the files in the original subvolume.

Subvolumes can be given capacity limits, through the qgroups/quota facility, but otherwise share the single storage pool of the whole btrfs filesystem. They may even share data between themselves (through deduplication or snapshotting).

NOTE:

A snapshot is not a backup: snapshots work by use of BTRFS' copy-on-write behaviour. A snapshot and the original it was taken from initially share all of the same data blocks. If that data is damaged in some way (cosmic rays, bad disk sector, accident with dd to the disk), then the snapshot and the original will both be damaged. Snapshots are useful to have local online "copies" of the filesystem that can be referred back to, or to implement a form of deduplication, or to fix the state of a filesystem for making a full backup without anything changing underneath it. They do not in themselves make your data any safer.

## SUBVOLUME FLAGS
The subvolume flag currently implemented is the ro property (read-only status). Read-write subvolumes have that set to false, snapshots as true. In addition to that, a plain snapshot will also have last change generation and creation generation equal.

Read-only snapshots are building blocks of incremental send (see btrfs-send(8)) and the whole use case relies on unmodified snapshots where the relative changes are generated from. Thus, changing the subvolume flags from read-only to read-write will break the assumptions and may lead to unexpected changes in the resulting incremental stream.

A snapshot that was created by send/receive will be read-only, with different last change generation, read-only and with set received_uuid which identifies the subvolume on the filesystem that produced the stream. The use case relies on matching data on both sides. Changing the subvolume to read-write after it has been received requires to reset the received_uuid. As this is a notable change and could potentially break the incremental send use case, performing it by btrfs property set requires force if that is really desired by user.

NOTE:

The safety checks have been implemented in 5.14.2, any subvolumes previously received (with a valid received_uuid) and read-write status may exist and could still lead to problems with send/receive. You can use btrfs subvolume show to identify them. Flipping the flags to read-only and back to read-write will reset the received_uuid manually. There may exist a convenience tool in the future.

## NESTED SUBVOLUMES
There are no restrictions for subvolume creation, so it's up to the user how to organize them, whether to have a flat layout (all subvolumes are direct descendants of the toplevel one), or nested.

What should be mentioned early is that a snapshotting is not recursive, so a subvolume or a snapshot is effectively a barrier and no files in the nested appear in the snapshot. Instead there's a stub subvolume (also sometimes empty subvolume with the same name as original subvolume, with inode number 2). This can be used intentionally but could be confusing in case of nested layouts.

### Case study: system root layouts
There are two ways how the system root directory and subvolume layout could be organized. The interesting use case for root is to allow rollbacks to previous version, as one atomic step. If the entire filesystem hierarchy starting in "/" is in one subvolume, taking snapshot will encompass all files. This is easy for the snapshotting part but has undesirable consequences for rollback. For example, log files would get rolled back too, or any data that are stored on the root filesystem but are not meant to be rolled back either (database files, VM images, ...).

Here we could utilize the snapshotting barrier mentioned above, each directory that stores data to be preserved across rollbacks is it's own subvolume. This could be e.g. /var. Further more-fine grained partitioning could be done, e.g. adding separate subvolumes for /var/log, /var/cache etc.

That there are separate subvolumes requires separate actions to take the snapshots (here it gets disconnected from the system root snapshots). This needs to be taken care of by system tools, installers together with selection of which directories are highly recommended to be separate subvolumes.

## MOUNT OPTIONS
Mount options are of two kinds, generic (that are handled by VFS layer) and specific, handled by the filesystem. The following list shows which are applicable to individual subvolume mounts, while there are more options that always affect the whole filesystem:

- generic: noatime/relatime/..., nodev, nosuid, ro, rw, dirsync

- fs-specific: compress, autodefrag, nodatacow, nodatasum

An example of whole filesystem options is e.g. space_cache, rescue, device, skip_balance, etc. The exceptional options are subvol and subvolid that are actually used for mounting a given subvolume and can be specified only once for the mount.

Subvolumes belong to a single filesystem and as implemented now all share the same specific mount options, changes done by remount have immediate effect. This may change in the future.

Mounting a read-write snapshot as read-only is possible and will not change the ro property and flag of the subvolume.

The name of the mounted subvolume is stored in file /proc/self/mountinfo in the 4th column:

```
27 21 0:19 /subv1 /mnt rw,relatime - btrfs /dev/sda rw,space_cache

           ^^^^^^
```

## INODE NUMBERS
A proper subvolume has always inode number 256. If a subvolume is nested and then a snapshot is taken, then the cloned directory entry representing the subvolume becomes empty and the inode has number 2. All other files and directories in the target snapshot preserve their original inode numbers.

NOTE:

Inode number is not a filesystem-wide unique identifier, some applications assume that. Please use pair subvolumeid:inodenumber for that purpose.

## PERFORMANCE
Subvolume creation needs to flush dirty data that belong to the subvolume, this step may take some time, otherwise once there's nothing else to do, the snapshot is instant and in the metadata it only creates a new tree root copy.

Snapshot deletion has two phases: first its directory is deleted and the subvolume is added to a list, then the list is processed one by one and the data related to the subvolume get deleted. This is usually called cleaning and can take some time depending on the amount of shared blocks (can be a lot of metadata updates), and the number of currently queued deleted subvolumes.

## SUBVOLUME AND SNAPSHOT
A subvolume is a part of filesystem with its own independent file/directory hierarchy. Subvolumes can share file extents. A snapshot is also subvolume, but with a given initial content of the original subvolume.

NOTE:

A subvolume in btrfs is not like an LVM logical volume, which is block-level snapshot while btrfs subvolumes are file extent-based.

A subvolume looks like a normal directory, with some additional operations described below. Subvolumes can be renamed or moved, nesting subvolumes is not restricted but has some implications regarding snapshotting.

A subvolume in btrfs can be accessed in two ways:

- like any other directory that is accessible to the user

- like a separately mounted filesystem (options subvol or subvolid)

In the latter case the parent directory is not visible and accessible. This is similar to a bind mount, and in fact the subvolume mount does exactly that.

A freshly created filesystem is also a subvolume, called top-level, internally has an id 5. This subvolume cannot be removed or replaced by another subvolume. This is also the subvolume that will be mounted by default, unless the default subvolume has been changed (see subcommand set-default).

A snapshot is a subvolume like any other, with given initial content. By default, snapshots are created read-write. File modifications in a snapshot do not affect the files in the original subvolume.

## SUBCOMMAND
create [-i <qgroupid>] [<dest>/]<name>

Create a subvolume name in dest. If dest is not given, subvolume name will be created in the current directory.

Options

-i <qgroupid>

Add the newly created subvolume to a qgroup. This option can be given multiple times.

delete [options] [<subvolume> [<subvolume>...]], delete -i|--subvolid <subvolid> <path>

Delete the subvolume(s) from the filesystem. If subvolume is not a subvolume, btrfs returns an error but continues if there are more arguments to process.

If --subvolid is used, path must point to a btrfs filesystem. See btrfs subvolume list or btrfs inspect-internal rootid how to get the subvolume id.

The corresponding directory is removed instantly but the data blocks are removed later in the background. The command returns immediately. See btrfs subvolume sync how to wait until the subvolume gets completely removed.

The deletion does not involve full transaction commit by default due to performance reasons. As a consequence, the subvolume may appear again after a crash. Use one of the --commit options to wait until the operation is safely stored on the device.

Deleting subvolume needs sufficient permissions, by default the owner cannot delete it unless it's enabled by a mount option user_subvol_rm_allowed, or deletion is run as root. The default subvolume (see btrfs subvolume set-default) cannot be deleted and returns error (EPERM) and this is logged to the system log. A subvolume that's currently involved in send (see btrfs send) also cannot be deleted until the send is finished. This is also logged in the system log.

Options

-c|--commit-after

wait for transaction commit at the end of the operation.

-C|--commit-each

wait for transaction commit after deleting each subvolume.

-i|--subvolid <subvolid>

subvolume id to be removed instead of the <path> that should point to the filesystem with the subvolume

-v|--verbose

(deprecated) alias for global -v option

find-new <subvolume> <last_gen>

List the recently modified files in a subvolume, after last_gen generation.

get-default <path>

Get the default subvolume of the filesystem path. The output format is similar to subvolume list command.

list [options] [-G [+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>

List the subvolumes present in the filesystem path. For every subvolume the following information is shown by default:

ID ID gen generation top level parent_ID path path

where ID is subvolume's (root)id, generation is an internal counter which is updated every transaction, parent_ID is the same as the parent subvolume's id, and path is the relative path of the subvolume to the top level subvolume. The subvolume's ID may be used by the subvolume set-default command, or at mount time via the subvolid= option.

Options

Path filtering:

-o

print only subvolumes below specified <path>.

-a

print all the subvolumes in the filesystem and distinguish between absolute and relative path with respect to the given path.

Field selection:

-p

print the parent ID (parent here means the subvolume which contains this subvolume).

-c

print the ogeneration of the subvolume, aliases: ogen or origin generation.

-g

print the generation of the subvolume (default).

-u

print the UUID of the subvolume.

-q

print the parent UUID of the subvolume (parent here means subvolume of which this subvolume is a snapshot).

-R

print the UUID of the sent subvolume, where the subvolume is the result of a receive operation.

Type filtering:

-s

only snapshot subvolumes in the filesystem will be listed.

-r

only readonly subvolumes in the filesystem will be listed.

-d

list deleted subvolumes that are not yet cleaned.

Other:

-t

print the result as a table.

Sorting:

By default the subvolumes will be sorted by subvolume ID ascending.

-G [+|-]<value>

list subvolumes in the filesystem that its generation is >=, <= or = value. '+' means >= value, '-' means <= value, If there is neither '+' nor '-', it means = value.

-C [+|-]<value>

list subvolumes in the filesystem that its ogeneration is >=, <= or = value. The usage is the same to -G option.

--sort=rootid,gen,ogen,path

list subvolumes in order by specified items. you can add + or - in front of each items, + means ascending, - means descending. The default is ascending. for --sort you can combine some items together by ,, just like --sort=+ogen,-gen,path,rootid.

set-default [<subvolume>|<id> <path>]

Set the default subvolume for the (mounted) filesystem. Set the default subvolume for the (mounted) filesystem at path. This will hide the top-level subvolume (i.e. the one mounted with subvol=/ or subvolid=5). Takes action on next mount.

There are two ways how to specify the subvolume, by id or by the subvolume path. The id can be obtained from btrfs subvolume list, btrfs subvolume show or btrfs inspect-internal rootid.

show [options] <path>

Show more information about a subvolume (UUIDs, generations, times, flags, related snapshots).

```
/mnt/btrfs/subvolume

        Name:                   subvolume

        UUID:                   5e076a14-4e42-254d-ac8e-55bebea982d1

        Parent UUID:            -

        Received UUID:          -

        Creation time:          2018-01-01 12:34:56 +0000

        Subvolume ID:           79

        Generation:             2844

        Gen at creation:        2844

        Parent ID:              5

        Top level ID:           5

        Flags:                  -

        Snapshot(s):
```

Options

-r|--rootid <ID>

show details about subvolume with root ID, looked up in path

-u|--uuid UUID

show details about subvolume with the given UUID, looked up in path

snapshot [-r] [-i <qgroupid>] <source> <dest>|[<dest>/]<name>

Create a snapshot of the subvolume source with the name name in the dest directory. If only dest is given, the subvolume will be named the basename of source. If source is not a subvolume, btrfs returns an error.

Options

-r

Make the new snapshot read only.

-i <qgroupid>

Add the newly created subvolume to a qgroup. This option can be given multiple times.

sync <path> [subvolid...]

Wait until given subvolume(s) are completely removed from the filesystem after deletion. If no subvolume id is given, wait until all current deletion requests are completed, but do not wait for subvolumes deleted in the meantime. Options

-s <N>

sleep N seconds between checks (default: 1)

## EXAMPLES

### Deleting a subvolume
If we want to delete a subvolume called foo from a btrfs volume mounted at /mnt/bar we could run the following:

```
btrfs subvolume delete /mnt/bar/foo
```

## EXIT STATUS
btrfs subvolume returns a zero exit status if it succeeds. A non-zero value 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-qgroup(8), btrfs-quota(8), btrfs-send(8), mkfs.btrfs(8), mount(8)


btrfstune

title: btrfstune(8)

summary: tune various filesystem parameters

text:
# btrfstune(8)

## NAME
btrfstune - tune various filesystem parameters

## SYNOPSIS
btrfstune [options] <device> [<device>...]

## DESCRIPTION
btrfstune can be used to enable, disable, or set various filesystem parameters. The filesystem must be unmounted.

The common use case is to enable features that were not enabled at mkfs time. Please make sure that you have kernel support for the features. You can find a complete list of features and kernel version of their introduction at https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature . Also, the manual page mkfs.btrfs(8) contains more details about the features.

Some of the features could be also enabled on a mounted filesystem by other means. Please refer to the FILESYSTEM FEATURES in btrfs(5).

## OPTIONS
--convert-to-block-group-tree

(since kernel 6.1) Convert portions of extent tree that tracks block groups to a separate block gruop tree. This greatly reduces mount time. Can be also enabled at mkfs time.

--convert-from-block-group-tree

(since kernel 6.1) Convert block groups tracked in standalone block group tree back to extent tree and remove 'block-group-tree' feature bit from the filesystem.

--convert-to-free-space-tree

(since kernel 4.5) Convert to free-space-tree feature (v2 of space cache).

-f

Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure that you are aware of the dangers.

-m

(since kernel: 5.0) change fsid stored as 'metadata_uuid' to a randomly generated UUID, see also '-U'

-M <UUID>

(since kernel: 5.0) change fsid stored as metadata_uuid to a given UUID, see also -U

The metadata_uuid is stored only in the superblock and is a backward incompatible change. The fsid in metadata blocks remains unchanged and is not overwritten, thus the whole operation is significantly faster than -U.

The new metadata_uuid can be used for mount by UUID and is also used to identify devices of a multi-device filesystem.

-n

(since kernel: 3.14) Enable no-holes feature (more efficient representation of file holes), enabled by mkfs feature no-holes.

-r

(since kernel: 3.7) Enable extended inode refs (hardlink limit per file in a directory is 65536), enabled by mkfs feature extref.

-S <0|1>

Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it. A seeding filesystem is forced to be mounted read-only. A new device can be added to the filesystem and will capture all writes keeping the seeding device intact. See also section SEEDING DEVICE in btrfs(5). WARNING:

Clearing the seeding flag on a device may be dangerous. If a previously-seeding device is changed, all filesystems that used that device will become unmountable. Setting the seeding flag back will not fix that. A valid usecase is 'seeding device as a base image'. Clear the seeding flag, update the filesystem and make it seeding again, provided that it's OK to throw away all filesystems built on top of the previous base.

-u

Change fsid to a randomly generated UUID or continue previous fsid change operation in case it was interrupted.

-U <UUID>

Change fsid to 'UUID' in all metadata blocks. The UUID should be a 36 bytes string in printf(3) format "%08x-%04x-%04x-%04x-%012x". If there is a previous unfinished fsid change, it will continue only if the UUID matches the unfinished one or if you use the option -u.

All metadata blocks are rewritten, this may take some time, but the final filesystem compatibility is unaffected, unlike -M.

WARNING:

Cancelling or interrupting a UUID change operation will make the filesystem temporarily unmountable. To fix it, rerun btrfstune -u and let it complete.

-x

(since kernel: 3.10) Enable skinny metadata extent refs (more efficient representation of extents), enabled by mkfs feature skinny-metadata.

All newly created extents will use the new representation. To completely switch the entire filesystem, run a full balance of the metadata. Please refer to btrfs-balance(8).

## EXIT STATUS
btrfstune returns 0 if no error happened, 1 otherwise.

## COMPATIBILITY NOTE
This deprecated tool exists for historical reasons but is still in use today. Its functionality will be merged to the main tool, at which time btrfstune will be declared obsolete and scheduled for removal.

## SEE ALSO
btrfs(5), btrfs-balance(8), mkfs.btrfs(8)


fsck.btrfs

title: fsck.btrfs(8)

summary: do nothing, successfully

text:
# fsck.btrfs(8)

## NAME
fsck.btrfs - do nothing, successfully

## SYNOPSIS
fsck.btrfs [-aApy] [<device>...]

## DESCRIPTION
fsck.btrfs is a type of utility that should exist for any filesystem and is called during system setup when the corresponding /etc/fstab entries contain non-zero value for fs_passno, see fstab(5) for more.

Traditional filesystems need to run their respective fsck utility in case the filesystem was not unmounted cleanly and the log needs to be replayed before mount. This is not needed for BTRFS. You should set fs_passno to 0.

If you wish to check the consistency of a BTRFS filesystem or repair a damaged filesystem, see btrfs-check(8). By default filesystem consistency is checked, the repair mode is enabled via the --repair option (use with care!).

## OPTIONS
The options are all the same and detect if fsck.btrfs is executed in non-interactive mode and exits with success, otherwise prints a message about btrfs check.

## EXIT STATUS
There are two possible exit codes returned:

0

No error

8

Operational error, e.g. device does not exist

## FILES
/etc/fstab

## SEE ALSO
btrfs(8), fsck(8), fstab(5)


mkfs.btrfs

title: mkfs.btrfs(8)

summary: create a btrfs filesystem

text:
# mkfs.btrfs(8)

## NAME
mkfs.btrfs - create a btrfs filesystem

## SYNOPSIS
mkfs.btrfs [options] <device> [<device>...]

## DESCRIPTION
mkfs.btrfs is used to create the btrfs filesystem on a single or multiple devices. The device is typically a block device but can be a file-backed image as well. Multiple devices are grouped by UUID of the filesystem.

Before mounting such filesystem, the kernel module must know all the devices either via preceding execution of btrfs device scan or using the device mount option. See section MULTIPLE DEVICES for more details.

The default block group profiles for data and metadata depend on number of devices and possibly other factors. It's recommended to use specific profiles but the defaults should be OK and allowing future conversions to other profiles. Please see options -d and -m for further details and btrfs-balance(8) for the profile conversion post mkfs.

## OPTIONS
-b|--byte-count <size>

Specify the size of each device as seen by the filesystem. If not set, the entire device size is used. The total filesystem size will be sum of all device sizes, for a single device filesystem the option effectively specifies the size of the filesystem.

--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. See CHECKSUM ALGORITHMS in btrfs(5).

-d|--data <profile>

Specify the profile for the data block groups. Valid values are raid0, raid1, raid1c3, raid1c4, raid5, raid6, raid10 or single or dup (case does not matter). See DUP PROFILES ON A SINGLE DEVICE for more details.

On multiple devices, the default was raid0 until version 5.7, while it is single since version 5.8. You can still select raid0 manually, but it was not suitable as default.

-m|--metadata <profile>

Specify the profile for the metadata block groups. Valid values are raid0, raid1, raid1c3, raid1c4, raid5, raid6, raid10, single or dup (case does not matter). Default on a single device filesystem is DUP and is recommended for metadata in general. The duplication might not be necessary in some use cases and it's up to the user to changed that at mkfs time or later. This depends on hardware that could potentially deduplicate the blocks again but this cannot be detected at mkfs time.

NOTE:

Up to version 5.14 there was a detection of a SSD device (more precisely if it's a rotational device, determined by the contents of file /sys/block/DEV/queue/rotational) that used to select single. This has changed in version 5.15 to be always dup. Note that the rotational status can be arbitrarily set by the underlying block device driver and may not reflect the true status (network block device, memory-backed SCSI devices, real block device behind some additional device mapper layer, etc). It's recommended to always set the options --data/--metadata to avoid confusion and unexpected results.

See DUP PROFILES ON A SINGLE DEVICE for more details.

On multiple devices the default is raid1.

-M|--mixed

Normally the data and metadata block groups are isolated. The mixed mode will remove the isolation and store both types in the same block group type. This helps to utilize the free space regardless of the purpose and is suitable for small devices. The separate allocation of block groups leads to a situation where the space is reserved for the other block group type, is not available for allocation and can lead to ENOSPC state. The recommended size for the mixed mode is for filesystems less than 1GiB. The soft recommendation is to use it for filesystems smaller than 5GiB. The mixed mode may lead to degraded performance on larger filesystems, but is otherwise usable, even on multiple devices.

The nodesize and sectorsize must be equal, and the block group types must match.

NOTE:

Versions up to 4.2.x forced the mixed mode for devices smaller than 1GiB. This has been removed in 4.3+ as it caused some usability issues. Mixed profile cannot be used together with other profiles. It can only be set at creation time. Conversion to or from mixed profile is not implemented.

-n|--nodesize <size>

Specify the nodesize, the tree block size in which btrfs stores metadata. The default value is 16KiB (16384) or the page size, whichever is bigger. Must be a multiple of the sectorsize and a power of 2, but not larger than 64KiB (65536). Leafsize always equals nodesize and the options are aliases. Smaller node size increases fragmentation but leads to taller b-trees which in turn leads to lower locking contention. Higher node sizes give better packing and less fragmentation at the cost of more expensive memory operations while updating the metadata blocks.

NOTE:

Versions up to 3.11 set the nodesize to 4KiB.

-s|--sectorsize <size>

Specify the sectorsize, the minimum data block allocation unit. The default value is the page size and is autodetected. If the sectorsize differs from the page size, the created filesystem may not be mountable by the running kernel. Therefore it is not recommended to use this option unless you are going to mount it on a system with the appropriate page size.

-L|--label <string>

Specify a label for the filesystem. The string should be less than 256 bytes and must not contain newline characters.

-K|--nodiscard

Do not perform whole device TRIM operation on devices that are capable of that. This does not affect discard/trim operation when the filesystem is mounted. Please see the mount option discard for that in btrfs(5).

-r|--rootdir <rootdir>

Populate the toplevel subvolume with files from rootdir. This does not require root permissions to write the new files or to mount the filesystem. NOTE:

This option may enlarge the image or file to ensure it's big enough to contain the files from rootdir. Since version 4.14.1 the filesystem size is not minimized. Please see option --shrink if you need that functionality.

--shrink

Shrink the filesystem to its minimal size, only works with --rootdir option. If the destination block device is a regular file, this option will also truncate the file to the minimal size. Otherwise it will reduce the filesystem available space. Extra space will not be usable unless the filesystem is mounted and resized using btrfs filesystem resize.

NOTE:

Prior to version 4.14.1, the shrinking was done automatically.

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

A list of filesystem features turned on at mkfs time. Not all features are supported by old kernels. To disable a feature, prefix it with ^. See section FILESYSTEM FEATURES for more details. To see all available features that mkfs.btrfs supports run:

```
$ mkfs.btrfs -O list-all
```

-f|--force

Forcibly overwrite the block devices when an existing filesystem is detected. By default, mkfs.btrfs will utilize libblkid to check for any known filesystem on the devices. Alternatively you can use the wipefs utility to clear the devices.

-q|--quiet

Print only error or warning messages. Options --features or --help are unaffected. Resets any previous effects of --verbose.

-U|--uuid <UUID>

Create the filesystem with the given UUID. The UUID must not exist on any filesystem currently present.

-v|--verbose

Increase verbosity level, default is 1.

-V|--version

Print the mkfs.btrfs version and exit.

--help

Print help.

-l|--leafsize <size>

Removed in 6.0, used to be alias for --nodesize.

-R|--runtime-features <feature1>[,<feature2>...]

Removed in 6.3, was used to specify features not affecting on-disk format. Now all such features are merged into -O|--features option. The option -R will stay for backward compatibility.

## SIZE UNITS
The default unit is byte. All size parameters accept suffixes in the 1024 base. The recognized suffixes are: k, m, g, t, p, e, both uppercase and lowercase.

## MULTIPLE DEVICES
Before mounting a multiple device filesystem, the kernel module must know the association of the block devices that are attached to the filesystem UUID.

There is typically no action needed from the user. On a system that utilizes a udev-like daemon, any new block device is automatically registered. The rules call btrfs device scan.

The same command can be used to trigger the device scanning if the btrfs kernel module is reloaded (naturally all previous information about the device registration is lost).

Another possibility is to use the mount options device to specify the list of devices to scan at the time of mount.

```
# mount -o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt
```

NOTE:

This means only scanning, if the devices do not exist in the system, mount will fail anyway. This can happen on systems without initramfs/initrd and root partition created with RAID1/10/5/6 profiles. The mount action can happen before all block devices are discovered. The waiting is usually done on the initramfs/initrd systems.

WARNING:

RAID5/6 has known problems and should not be used in production.

## FILESYSTEM FEATURES
Features that can be enabled during creation time. See also btrfs(5) section FILESYSTEM FEATURES.

mixed-bg

(kernel support since 2.6.37) mixed data and metadata block groups, also set by option --mixed

extref

(default since btrfs-progs 3.12, kernel support since 3.7) increased hardlink limit per file in a directory to 65536, older kernels supported a varying number of hardlinks depending on the sum of all file name sizes that can be stored into one metadata block

raid56

(kernel support since 3.9) extended format for RAID5/6, also enabled if RAID5 or RAID6 block groups are selected

skinny-metadata

(default since btrfs-progs 3.18, kernel support since 3.10) reduced-size metadata for extent references, saves a few percent of metadata

no-holes

(default since btrfs-progs 5.15, kernel support since 3.14) improved representation of file extents where holes are not explicitly stored as an extent, saves a few percent of metadata if sparse files are used

zoned

(kernel support since 5.12) zoned mode, data allocation and write friendly to zoned/SMR/ZBC/ZNS devices, see ZONED MODE in btrfs(5), the mode is automatically selected when a zoned device is detected

quota

(kernel support since 3.4) Enable quota support (qgroups). The qgroup accounting will be consistent, can be used together with --rootdir. See also btrfs-quota(8).

free-space-tree

(default since btrfs-progs 5.15, kernel support since 4.5) Enable the free space tree (mount option space_cache=v2) for persisting the free space cache.

block-group-tree

(kernel support since 6.1) Enable the block group tree to greatly reduce mount time for large filesystems.

## BLOCK GROUPS, CHUNKS, RAID
The highlevel organizational units of a filesystem are block groups of three types: data, metadata and system.

DATA

store data blocks and nothing else

METADATA

store internal metadata in b-trees, can store file data if they fit into the inline limit

SYSTEM

store structures that describe the mapping between the physical devices and the linear logical space representing the filesystem

Other terms commonly used:

block group, chunk

a logical range of space of a given profile, stores data, metadata or both; sometimes the terms are used interchangeably A typical size of metadata block group is 256MiB (filesystem smaller than 50GiB) and 1GiB (larger than 50GiB), for data it's 1GiB. The system block group size is a few megabytes.

RAID

a block group profile type that utilizes RAID-like features on multiple devices: striping, mirroring, parity

profile

when used in connection with block groups refers to the allocation strategy and constraints, see the section PROFILES for more details

## PROFILES
There are the following block group types available:

Profiles

Redundancy Copies

Redundancy Parity

Redundancy Striping

Space utilization

Min/max devices

single

1

100%

1/any

DUP

2 / 1 device

50%

1/any (see note 1)

RAID0

1

1 to N

100%

1/any (see note 5)

RAID1

2

50%

2/any

RAID1C3

3

33%

3/any

RAID1C4

4

25%

4/any

RAID10

2

1 to N

50%

2/any (see note 5)

RAID5

1

1

2 to N-1

(N-1)/N

2/any (see note 2)

RAID6

1

2

3 to N-2

(N-2)/N

3/any (see note 3)

WARNING:

It's not recommended to create filesystems with RAID0/1/10/5/6 profiles on partitions from the same device. Neither redundancy nor performance will be improved.

Note 1: DUP may exist on more than 1 device if it starts on a single device and another one is added. Since version 4.5.1, mkfs.btrfs will let you create DUP on multiple devices without restrictions.

Note 2: It's not recommended to use 2 devices with RAID5. In that case, parity stripe will contain the same data as the data stripe, making RAID5 degraded to RAID1 with more overhead.

Note 3: It's also not recommended to use 3 devices with RAID6, unless you want to get effectively 3 copies in a RAID1-like manner (but not exactly that).

Note 4: Since kernel 5.5 it's possible to use RAID1C3 as replacement for RAID6, higher space cost but reliable.

Note 5: Since kernel 5.15 it's possible to use (mount, convert profiles) RAID0 on one device and RAID10 on two devices.

### PROFILE LAYOUT
For the following examples, assume devices numbered by 1, 2, 3 and 4, data or metadata blocks A, B, C, D, with possible stripes e.g. A1, A2 that would be logically A, etc. For parity profiles PA and QA are parity and syndrome, associated with the given stripe. The simple layouts single or DUP are left out. Actual physical block placement on devices depends on current state of the free/allocated space and may appear random. All devices are assumed to be present at the time of the blocks would have been written.

### RAID1
device 1

device 2

device 3

device 4

A

D

B

C

C

D

A

B

### RAID1C3
device 1

device 2

device 3

device 4

A

A

D

B

B

C

A

C

D

D

C

B

### RAID0
device 1

device 2

device 3

device 4

A2

C3

A3

C2

B1

A1

D2

B3

C1

D3

B4

D1

D4

B2

C4

A4

### RAID5
device 1

device 2

device 3

device 4

A2

C3

A3

C2

B1

A1

D2

B3

C1

D3

PB

D1

PD

B2

PC

PA

### RAID6
device 1

device 2

device 3

device 4

A2

QC

QA

C2

B1

A1

D2

QB

C1

QD

PB

D1

PD

B2

PC

PA

## DUP PROFILES ON A SINGLE DEVICE
The mkfs utility will let the user create a filesystem with profiles that write the logical blocks to 2 physical locations. Whether there are really 2 physical copies highly depends on the underlying device type.

For example, a SSD drive can remap the blocks internally to a single copy--thus deduplicating them. This negates the purpose of increased redundancy and just wastes filesystem space without providing the expected level of redundancy.

The duplicated data/metadata may still be useful to statistically improve the chances on a device that might perform some internal optimizations. The actual details are not usually disclosed by vendors. For example we could expect that not all blocks get deduplicated. This will provide a non-zero probability of recovery compared to a zero chance if the single profile is used. The user should make the tradeoff decision. The deduplication in SSDs is thought to be widely available so the reason behind the mkfs default is to not give a false sense of redundancy.

As another example, the widely used USB flash or SD cards use a translation layer between the logical and physical view of the device. The data lifetime may be affected by frequent plugging. The memory cells could get damaged, hopefully not destroying both copies of particular data in case of DUP.

The wear levelling techniques can also lead to reduced redundancy, even if the device does not do any deduplication. The controllers may put data written in a short timespan into the same physical storage unit (cell, block etc). In case this unit dies, both copies are lost. BTRFS does not add any artificial delay between metadata writes.

The traditional rotational hard drives usually fail at the sector level.

In any case, a device that starts to misbehave and repairs from the DUP copy should be replaced! DUP is not backup.

## KNOWN ISSUES
SMALL FILESYSTEMS AND LARGE NODESIZE

The combination of small filesystem size and large nodesize is not recommended in general and can lead to various ENOSPC-related issues during mount time or runtime.

Since mixed block group creation is optional, we allow small filesystem instances with differing values for sectorsize and nodesize to be created and could end up in the following situation:

```
# mkfs.btrfs -f -n 65536 /dev/loop0
btrfs-progs v3.19-rc2-405-g976307c
See http://btrfs.wiki.kernel.org for more information.
Performing full device TRIM (512.00MiB) ...
Label:              (null)
UUID:               49fab72e-0c8b-466b-a3ca-d1bfe56475f0
Node size:          65536
Sector size:        4096
Filesystem size:    512.00MiB
Block group profiles:

  Data:             single            8.00MiB

  Metadata:         DUP              40.00MiB

  System:           DUP              12.00MiB
SSD detected:       no
Incompat features:  extref, skinny-metadata
Number of devices:  1
Devices:

  ID        SIZE  PATH

   1   512.00MiB  /dev/loop0
# mount /dev/loop0 /mnt/
mount: mount /dev/loop0 on /mnt failed: No space left on device
```

The ENOSPC occurs during the creation of the UUID tree. This is caused by large metadata blocks and space reservation strategy that allocates more than can fit into the filesystem.

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

## SEE ALSO
btrfs(5), btrfs(8), btrfs-balance(8), wipefs(8)


bedup

package: burp

title: bedup(8)

text:
# bedup(8)

## NAME
bedup - deduplication program with additional knowledge of burp

## SYNOPSIS
bedup [options]

A file deduplication program with additional knowledge of burp protocol 1 storage directories. This program comes with the burp backup and restore package.

## OPTIONS
-c path

Path to config file (default: /etc/burp/burp.conf).

-g <list of group names>

Only run on the directories of clients that are in one of the groups specified. The list is comma-separated. To put a client in a group, use the 'dedup_group' option in the client configuration file on the server.

-h|-?

Print help text and exit.

-d

Delete any duplicate files found. (non-burp mode only, use with caution!)

-l

Hard link any duplicate files found.

-m <number>

Maximum number of hard links to a single file. (non-burp mode only - in burp mode, use the max_hardlinks option in the configuration file) The default is 10000. On ext3, the maximum number of links possible is 32000, but space is needed for the normal operation of burp.

-n <list of directories>

Non-burp mode. Deduplicate any (set of) directories.

-v

Print duplicate paths. Useful if you want to double check the files that would be hard linked or deleted before running with one of those options turned on.

-V

Print version and exit.

By default, bedup will read /etc/burp/burp.conf and deduplicate protocol 1 client storage directories using special knowledge of the structure.

With '-n', this knowledge is turned off and you have to specify the directories to deduplicate on the command line. Running with '-n' is therefore dangerous if you are deduplicating burp storage directories.

## BUGS
If you find bugs, please report them to the email list. See the website <http://burp.grke.net/> for details.

## AUTHOR
The main author of Burp is Graham Keeling.

## COPYRIGHT
See the LICENCE file included with the source distribution.


bsigs

title: bsigs(8)

text:
# bsigs(8)

## NAME
bsigs - program for debugging burp protocol2 manifest files and indexes

## SYNOPSIS
bsigs [filename]

A program for debugging burp protocol2 manifest files and indexes. It reads a file containing binary signatures and checksums, converts them to hex, and writes them to stdout. This program comes with the burp backup and restore package.

## EXAMPLES
cd /var/spool/burp

bsigs global/clients/testclient/current/manifest/00000022

bsigs global/clients/testclient/current/manifest/dfiles

bsigs global/clients/testclient/current/manifest/dindex/00000002

bsigs global/clients/testclient/current/manifest/hooks/00000002

bsigs global/clients/testclient/current/manifest/sparse

bsigs global/data/sparse

## BUGS
If you find bugs, please report them to the email list. See the website <http://burp.grke.net/> for details.

## AUTHOR
The main author of Burp is Graham Keeling.

## COPYRIGHT
See the LICENCE file included with the source distribution.


bsparse

title: bsparse(8)

text:
# bsparse(8)

## NAME
bsparse - program for regenerating burp protocol2 sparse files

## SYNOPSIS
bsparse [OPTIONS] [PATH_TO_DEDUP_GROUP]

A program for regenerating burp protocol2 sparse files.

## OPTIONS
-c path

Path to config file (default: /etc/burp/burp.conf).

## EXAMPLES
bsparse -c /etc/burp/burp-server.conf /var/spool/burp/global

Regenerates the sparse index for the dedup_group 'global', using the client storage directories under /var/spool/burp/global/clients.

## BUGS
If you find bugs, please report them to the email list. See the website <http://burp.grke.net/> for details.

## AUTHOR
The main author of Burp is Graham Keeling.

## COPYRIGHT
See the LICENCE file included with the source distribution.