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

package: btrfs-progs

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 (see more in Inode numbers (in Subvolumes)).

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, 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 subvolumes appear in the snapshot. Instead, there's a stub subvolume, also sometimes called empty subvolume, with the same name as original subvolume and with inode number 2. This can be used intentionally but could be confusing in case of nested layouts.

```
$ btrfs subvolume create subvol1
$ btrfs subvolume create subvol1/subvol2
$ btrfs subvolume snapshot subvol1 snap1
$ find -ls
121093  0  drwxr-xr-x  1  user  users    24  Jul 30  12:34  .

   256  0  drwxr-xr-x  1  user  users    14  Jul 30  12:34  ./subvol1

   256  0  drwxr-xr-x  1  user  users     0  Jul 30  12:34  ./subvol1/subvol2

   257  0  -rw-r--r--  1  user  users     0  Jul 30  12:34  ./subvol1/subvol2/file

   256  0  drwxr-xr-x  1  user  users    14  Jul 30  12:34  ./snap1

     2  0  drwxr-xr-x  1  user  users     0  Jul 30  12:34  ./snap1/subvol2
```

The numbers in the first columns are inode numbers, 256 is for a regular subvolume (or snapshot), 2 is the empty subvolume. The snapshotted directory representing subvol2 does not contain the file.

NOTE:

The empty subvolume will not be sent (btrfs-send(8)) and thus will not be created on the receive side (btrfs-receive(8)).

### 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, making each directory that stores data to be preserved across rollbacks its 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.

The fact 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

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

Examples of whole filesystem options are 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. Also, 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 directory representing a subvolume has always inode number 256 (sometimes also called a root of the subvolume):

```
$ ls -lis
total 0
389111 0 drwxr-xr-x 1 user users 0 Jan 20 12:13 dir
389110 0 -rw-r--r-- 1 user users 0 Jan 20 12:13 file

   256 0 drwxr-xr-x 1 user users 0 Jan 20 12:13 snap1

   256 0 drwxr-xr-x 1 user users 0 Jan 20 12:13 subv1
```

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 the subvolumeid:inodenumber pair for that purpose. The subvolume id can be read by btrfs inspect-internal rootid or by the ioctl BTRFS_IOC_INO_LOOKUP.

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

Snapshot deletion has two phases: first its directory is deleted and the subvolume is added to a queuing 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 [options] [<dest>/]<name> [[<dest2>/]<name2> ...]

Create subvolume(s) at the destination(s). If dest part of the path is not given, subvolume name will be created in the current directory.

If multiple destinations are given, then the given options are applied to all subvolumes.

If failure happens for any of the destinations, the command would still retry the remaining destinations, but would return 1 to indicate the failure (similar to what mkdir would do.

Options

-i <qgroupid>

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

-p|--parents

Create any missing parent directories for each argument (like mkdir -p).

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(8)) 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

-R|--recursive

delete subvolumes beneath each subvolume recursively This requires either CAP_SYS_ADMIN or the filesystem must be mounted with user_subvol_rm_allowed mount option. In the unprivileged case, subvolumes which cannot be accessed are skipped. The deletion is not atomic.

-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>. Note that this is not a recursive command, and won't show nested subvolumes under <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. If the filesystem status changes to read-only then the waiting is interrupted.

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 Feature by version page. 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 group 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).

--enable-simple-quota

(since kernel 6.7) Enable simple quota accounting (squota mkfs feature). This is an alternative to qgroups with a smaller performance impact but no notion of shared vs. exclusive usage.

--remove-simple-quota

Remove simple quota accounting related structures.

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

--version

Print the btrfstune version, builtin features and exit.

## 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 section 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 section 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 section 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. NOTE:

Versions prior to 6.7 set the sectorsize matching the host CPU page size, starting in 6.7 this is 4KiB for cross-architecture compatibility. Please read more about the subpage block size support and its status.

By default, the value is 4KiB, but it can be manually set to match the system page size (e.g. using command getconf PAGE_SIZE). However, if the sector size is different from the page size, the resulting filesystem may not be mountable by the current kernel, apart from the default 4KiB. Hence, using this option is not advised unless you intend to mount it on a system with the suitable 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. Directories can be created as subvolumes, see also option --subvol. Hardlinks are detected and created in the filesystem image.

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.

--compress <algo>[:<level>]

Try to compress files when using --rootdir. Supported values for algo are no (the default), zstd, lzo or zlib. The optional value level is a compression level, 1..15 for zstd, 1..9 for zlib. It is recommended to use the highest level to achieve maximum space savings. Compression at mkfs time is not as constrained as in kernel where it's desirable to use the less CPU load. Otherwise the default level is 3.

As with the kernel, mkfs.btrfs won't write compressed extents when they would be larger than the uncompressed versions, and will set file attribute NOCOMPRESS if its beginning is found to be incompressible.

NOTE:

The support for ZSTD and LZO is a compile-time option, please check the output of mkfs.btrfs --version for the actual support.

-u|--subvol <type>:<subdir>

Specify that subdir is to be created as a subvolume rather than a regular directory. The option --rootdir must also be specified, and subdir must be an existing subdirectory within it. This option can be specified multiple times. The type is an optional additional modifier. Valid choices are:

- default: create as default subvolume

- ro: create as read-only subvolume

- rw: create as read-write subvolume (the default)

- default-ro: create as read-only default subvolume

Only one of default and default-ro may be specified.

If you wish to create a subvolume with a name containing a colon and you don't want this to be parsed as containing a modifier, you can prefix the path with ./:

```
$ mkfs.btrfs --rootdir dir --subvol ./ro:subdir /dev/loop0
```

If there are hardlinks inside rootdir and subdir will split the subvolumes, like the following case:

```
rootdir/
|- hardlink1
|- hardlink2
|- subdir/  <- will be a subvolume

   |- hardlink3
```

In that case we cannot create hardlink3 as hardlinks of hardlink1 and hardlink2 because hardlink3 will be inside a new subvolume.

--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. For a single-device filesystem, you can duplicate the UUID. However, for a multi-device filesystem, the UUID must not already exist on any currently present filesystem.

--device-uuid <UUID>

Create the filesystem with the given device-uuid UUID (also known as UUID_SUB in blkid). For a single device filesystem, you can duplicate the device-uuid. However, used for a multi-device filesystem this option will not work at the moment.

-v|--verbose

Increase verbosity level, default is 1.

-V|--version

Print the mkfs.btrfs version, builtin features and exit.

--help

Print help.

## DEPRECATED OPTIONS
-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 in a b-tree. This is built on top of the COW mechanism and has better performance than v1.

Offline conversion from filesystems that don't have this feature enabled at mkfs time is possible, see btrfstune(8).

Online conversion can be done by mounting with space_cache=v2, this is sufficient to be done one time.

block-group-tree

(kernel support since 6.1) Enable a dedicated b-tree for block group items, this greatly reduces mount time for large filesystems due to better data locality that avoids seeking. On rotational devices the large size is considered starting from the 2-4TiB. Can be used on other types of devices (SSD, NVMe, ...) as well.

Offline conversion from filesystems that don't have this feature enabled at mkfs time is possible, see btrfstune(8). Online conversion is not possible.

raid-stripe-tree

(kernel support since 6.7, CONFIG_BTRFS_DEBUG/CONFIG_BTRFS_EXPERIMENTAL) Separate tree for logical file extent mapping where the physical mapping may not match on multiple devices. This is now used in zoned mode to implement RAID0/RAID1* profiles, but can be used in non-zoned mode as well. The support for RAID56 is in development and will eventually fix the problems with the current implementation. This is a backward incompatible feature and has to be enabled at mkfs time.

NOTE:

Due to the status of implementation it is enabled only in builds with CONFIG_BTRFS_DEBUG/CONFIG_BTRFS_EXPERIMENTAL. Support by the kernel module can be found in the sysfs feature list.

squota

(kernel support since 6.7) Enable simple quota accounting (squotas). This is an alternative to qgroups with a smaller performance impact but no notion of shared vs. exclusive usage.

## 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 time span 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 https://btrfs.readthedocs.io 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.