btrfs receive fails with incremental streams: "File exists"

Question

For a btrfs sub-volume, I have a simple incremental backup created from two stages:

btrfs send old/@ > base.btrfs
btrfs send new/@ -p old/@ > update.btrfs

The two source sub-volumes are snapshots captured at separate times from the same actively mounted sub-volume.

On the target, I attempt to restore:

btrfs receive ./ < base.btrfs
btrfs receive ./ < update.btrfs

The expectation is that the prior command would create a restored snapshot of the initial backup stage and that the latter would apply the further incremental stage.

The prior command succeeds, but the latter fails:

ERROR: creating snapshot ./@ -> @ failed: File exists

Since it is obvious that I cannot usefully apply the latter stage to a target that does not exist, I am puzzled about why the process performs this check, as well as what is expected to have success applying the update.

How may I apply the update stage to the target generated by restoring the initial stage?

Answer 1

You can't have (as on the sending side) multiple subvolumes with the same name.

You can mv the base snapshot/subvolume on the target system:

mv @ @.old
btrfs receive ./ < update.btrfs

Answer 2

I have learned enough to answer the question since posting it.

The answer takes two parts.

First, the receive sub-command always creates a new entry in the target directory having the same name as the original sub-volume, whether the new sub-volume is created from a child or parent stream. Therefore, the target directory must be empty, at least of any name having the same as the original sub-volume. A plain technique would be to create a new empty directory each for the parent and every child sub-volume.

Second, although the invocation of the sub-command on a child gives no reference to a parent, it may utilize the necessary data from the parent as long as the parent had been restored to a sub-volume to the same partition. That is, the receive sub-command will have the desired effect for the child stream as long as it had been previously invoked on the same partition for the parent.

Once the parent and children have been restored, any parents may be deleted without harming the children.

Consequently, the following would be an effective command sequence for the original objective:

mkdir _tmp
btrfs receive _tmp/ < base.btrfs
btrfs receive ./ < update.btrfs
btrfs subvolume delete _tmp/@
rmdir _tmp

The entire content of the child stream would then be available through ./@.

Naturally, further commands would be required if the child stream targeted for preservation had multiple ancestors (e.g. base.btrfs had a parent of its own).