How to rename a BTRFS subvolume?

Question

I have a BTRFS filesystem with a set of subvolumes in it. So far so good. I need to change the name of a subvolume, unfortunately the btrfs program does not allow me to rename a subvolume. Searching with Google has yielded some results, one said I can just mv, the other said I can just snapshot to a new name and delete the old subvolume. Before I crash my partition and have to reload it from the backup (it's quite large), my question is:

• What is the currently best way to rename a subvolume?
• Is it ok to just mv it, or will it invalidate some internal structures?
• Is making a new snapshot and removing the old subvolume the way to go, or has this some drawbacks?

I know everything is still experimental, but for my purposes it has been working quite well (so far, and I have incremental backups for each day).

Answer 1

Just mv it. That's the recommended way in the Ubuntu community documentation.

And to further clarify why that is the right way to do it, here is a quote from the btrfs sysadmin guide:

Snapshots

A snapshot is simply a subvolume that shares its data (and metadata) with some other subvolume, using btrfs's COW capabilities. Once a [writable] snapshot is made, there is no difference in status between the original subvolume, and the new snapshot subvolume. To roll back to a snapshot, unmount the modified original subvolume, and mount the snapshot in its place. At this point, the original subvolume may be deleted if wished. Since a snapshot is a subvolume, snapshots of snapshots are also possible.

Answer 2

there are few important things to note. The namings:

btrfs Subvolume - independent data container inside file system. It is represented as directory of the existing FS. If you create new subvolume, it will be empty, ready to use logical data block inside filesystem. Very convenient to use where data should be logically separated e.g. different VM's or different clients on different subvolumes. This allows very fast removal of all logical data block with just subvolume delete command.

btrfs Snapshot - a copy of existing subvolume with all its data at the moment os snapshot done. Can be used as operational backup for reverting settings or changes, e.g. make subvolume snapshot, make changes (VM or data), test if everything is ok, after some grace period remove snapshot. Important to note: snapshots can be read only (-r switch) and thus can be used as increment blocks of FS changes and possibly transferred to absolutely another BTRFS!

Current (2016-12-30) BTRFS limitations:

Copying or moving data between subvolumes, e.g. mv dir1/dataset1 dir_subvolume1/ produces all real io to copy data to another subvolume and in case of move, removing from original one. And very efficient copying of tons of data just by making references and thus using COW feature of BTRFS:

cp -a --reflink=always dir1/dataset1 dir_subvolume1/

and if needed:

rm -rf dir1/dataset1

Read only Subvolume snapshot can be renamed (moved with mv) at the existing directory level, but cannot be renamed/moved to different subdirectory level. e.g. mv /btrfs/subvol_snap1 /btrfs/.snaphots is not possible, produces not much explained error: mv: cannot move 'subvol_snap1' to '.snapshots/subvol_snap1': Read-only file system. To be able to move such a snapshot, you need to create new read-only snapshot of existing read-only snapshot to the new preferred location, and then remove old one:

btrfs sub snap -r /btrfs/subvol_snap1 /btrfs/.snaphots/subvol_snap1
btrfs sub del /btrfs/subvol_snap1

Just for more easy live:

btrfs sub list /btrfs

I hope this will save tons of time to all new btrfs fans :)

Answer 3

If you wanted to rename the root volume to a nested subvolume, you would need to snapshot it and then do a find $ROOT_VOL -xdev -delete to remove the previous contents of the root volume. The reverse manipulation (renaming a subvolume to the root volume) doesn't seem possible.