btrfs-receive

Receive a btrfs send stream and recreate subvolumes on a destination filesystem

TLDR

Receive a stream from stdin

$ btrfs receive [/path/to/destination]

Receive from a file

$ btrfs receive -f [backup.send] [/path/to/destination]

Send and receive in one pipeline

$ btrfs send [/path/to/snapshot] | btrfs receive [/path/to/destination]

Receive incremental over SSH

$ btrfs send -p [/snapshots/old] [/snapshots/new] | ssh [user@host] btrfs receive [/backup]

Dump stream metadata without writing to the filesystem

$ btrfs receive --dump -f [backup.send]

Quiet receive (errors only)

$ btrfs receive -q -f [backup.send] [/path/to/destination]

Confine the receiver with chroot

$ btrfs receive -C [/path/to/destination]

SYNOPSIS

btrfs receive [options] pathbtrfs receive --dump [options]

btrfs receive applies a stream previously generated by btrfs send and recreates one or more subvolumes under path. The stream is a sequence of encoded commands (file data, metadata, clone, rename, delete) that reconstruct a subvolume equivalent to the source snapshot. The result is not a bit-identical copy: inode numbers and subvolume UUIDs differ. Received subvolumes get a received_uuid that identifies the source subvolume used to produce the stream.By default the stream is read from stdin. After a successful receive the new subvolume is set read-only so it can serve as the parent for a later incremental send. --dump validates the stream and prints one metadata line per operation without changing the filesystem.Receive fails if the destination subvolume already exists, if a previously received subvolume was modified after it was received, or if the destination filesystem was not mounted at its toplevel subvolume (or the default subvolume has changed). Use -m to name the root mount point when `/proc` is not available, for example inside a chroot.

PARAMETERS

-f FILE

Read the stream from FILE instead of stdin.

-C, --chroot

Confine the process to path using chroot(1).

-e

Stop after an *end cmd* marker in the stream. Without this option the receiver exits on error or end of file.

-E, --max-errors NERR

Stop after NERR stream-processing errors. Default is 1; 0 means no limit.

-m ROOTMOUNT

Root mount point of the destination filesystem. Default is searched in `/proc/self/mounts`.

--force-decompress

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

--dump

Print stream metadata, one operation per line. Does not require path and does not modify the filesystem. Special characters in paths and xattrs are C-escaped.

-v, --verbose

Increase verbosity; print details about each operation.

-q, --quiet

Suppress all messages except errors.

INSTALL

sudo apt install btrfs-progs

sudo dnf install btrfs-progs

sudo pacman -S btrfs-progs

sudo apk add btrfs-progs

brew install btrfs-progs

nix profile install nixpkgs#btrfs-progs

CAVEATS

Source snapshots on the send side must be read-only. For incremental receive the parent snapshot must already exist on the destination. While receive is in progress, writers under path can change files, so the finished read-only subvolume may not be an exact copy; keep path private until the operation completes. Receive does not fully validate that an incremental stream is consistent, and a crafted stream can create reflinks to arbitrary files on the same filesystem — do not receive streams from untrusted sources, and protect trusted streams on untrusted networks. Interrupting send/receive can leave an incomplete subvolume. Restoring ownership and permissions needs sufficient privileges.

HISTORY

btrfs send/receive was introduced in Linux kernel 3.6 (released September 2012) as part of btrfs-progs. Kernel 3.12 added a UUID tree that sped up receive lookups. Send protocol v2 (kernel 6.0) can transfer compressed extents as-is; --force-decompress controls whether the receiver writes those extents encoded or expanded.

RESOURCES

Source code · Documentation