Add support for BTRFS stream

[qkaiser]

Summary

Send stream format represents a linear sequence of commands describing actions to be performed on the target filesystem (receive side), created on the source filesystem (send side). The stream is currently used in two ways: to generate a stream representing a standalone subvolume (full mode) or a difference between two snapshots of the same subvolume (incremental mode). The stream can be generated using a set of other subvolumes to look for extent references that could lead to a more efficient stream by transferring only the references and not full data.

The stream format is abstracted from on-disk structures (though it may share some BTRFS specifics), the stream instructions could be generated by other means than the send ioctl.

The header looks like this:

00000000  62 74 72 66 73 2d 73 74  72 65 61 6d 00 01 00 00  |btrfs-stream....|
00000010  00 35 00 00 00 01 00 10  50 4a b8 0f 00 11 00 6d  |.5......PJ.....m|
00000020  6d 63 62 6c 6b 30 78 5f  73 6e 61 70 73 68 6f 74  |mcblk0x_snapshot|
00000030  01 00 10 00 0c 72 af 27  a6 48 a7 47 bb c7 fa a1  |.....r.'.H.G....|
00000040  55 fc b2 e6 02 00 08 00  31 00 00 00 00 00 00 00  |U.......1.......|
00000050  1c 00 00 00 13 00 02 37  2d 8c 0f 00 00 00 06 00  |.......7-.......|
00000060  08 00 00 00 00 00 00 00  00 00 07 00 08 00 00 00  |................|
00000070  00 00 00 00 00 00 10 00  00 00 12 00 59 55 75 35  |............YUu5|
00000080  0f 00 00 00 05 00 08 00  ed 01 00 00 00 00 00 00  |................|
00000090  34 00 00 00 14 00 27 d1  4f 47 0f 00 00 00 0b 00  |4.....'.OG......|

There is no extraction tool, you need to mount a BTRFS filesystem and receive the content to get the files:

sudo apt install btrfs-progs
truncate -s 2G /tmp/btrfs-container.img
mkfs.btrfs /tmp/btrfs-container.img
sudo mkdir /mnt/root
sudo mount -o loop /tmp/btrfs-container.img /mnt/root
sudo btrfs receive /mnt/root < sample.bin

It's possible to dump what BTRFS is instructed to do by the stream, using the --dump parameter:

btrfs receive --dump -f sample.bin
... instructions like chown, chmod, etc

The format is just a list of TLV encoded instructions telling the filesystem manager to perform operations such as directory creation, file creation, ownership change, datetime changes, permission changes, file content write, etc

The format is well documented but would require significant work to get into unblob.

Basic example

TODO: create a sample and either upload here or provide instructions to recreate.

References

• https://btrfs.readthedocs.io/en/latest/dev/dev-send-stream.html