Libguestfs - Jan 2013 - APIs affected by btrfs subvolumes

We have a problem with btrfs subvolumes, as they can hold a filesystem
which can be mounted, but aren't describable using only the name of a
block device. Specifically they need at least a block device and a
subvolume name.

There are several APIs which operate on filesystems which currently
describe it using only a block device. I've listed them all below.

In all cases, these APIs need to use a more fully specified 'mountable'
object. There are currently 2 cases we need to support: bare device, and
device + subvolume. As this is a significant API change, I believe we
should also allow the mountable description to be safely extended
without breaking the api again.

I propose a string which contains a descriptor followed by data custom
to the descriptor. For the 2 existing cases this would be:

device:/dev/sda3
subvol:/dev/sda1,root

Any other solution must convey the same information. Could we achieve
this with a union, for e.g.? How would this work with bindings?

I would deprecate all of the apis below and replace them with
alternative versions with a _ext suffix. The replacement apis would
accept and return the enhanced descriptor.

Inspection APIS:

All take a root filesystem as an argument, which may not be a block
device.

inspect_get_arch
inspect_get_distro
inspect_get_drive_mappings
inspect_get_filesystems
inspect_get_format
inspect_get_hostname
inspect_get_icon
inspect_get_major_version
inspect_get_minor_version
inspect_get_mountpoints
inspect_get_package_format
inspect_get_package_management
inspect_get_product_name
inspect_get_product_variant
inspect_get_type
inspect_get_windows_current_control_set
inspect_get_windows_systemroot
inspect_is_live
inspect_is_multipart
inspect_is_netinst
inspect_list_applications
inspect_list_applications2

The following return filesystem descriptors.

inspect_get_filesystems
inspect_get_roots
inspect_os


Mount APIS:

All currently take a block device, but need to accept any filesystem
descriptor.

mount
mount_options
mount_ro
mount_vfs

Label APIs:

All these currently take a block device, but are arguably applicable to
btrfs subvolumes. A subvolume doesn't have a label itself, but its root
filesystem does. A btrfs subvolume can still be mounted by label, as
long as the subvolume is also given.

set_label: note that this would also affect other subvolumes
vfs_label
vfs_type
vfs_uuid

Device name mangling:

These apis are used to return sanitised device names. I'm not 100%
convinced we need to modify them. However, we may want additional apis
which handle filesystem descriptors.

canonical_device_name
part_to_dev

Misc:

zerofree: only actually supports ext2 and ext3, but the operation makes
sense for any filesystem. We should update the api and consider the
implementation later.

findfs_label
findfs_uuid: These return a device which contains the btrfs filesystem.
This device will be mountable, even if the filesystem spans many
devices. Not 100% convinced about this one, although it feels deficient.

On Tue, Jan 22, 2013 at 02:07:08PM +0000, Matthew Booth
wrote:
> We have a problem with btrfs subvolumes, as they can hold a filesystem
> which can be mounted, but aren't describable using only the name of a
> block device. Specifically they need at least a block device and a
> subvolume name.
> 
> There are several APIs which operate on filesystems which currently
> describe it using only a block device. I've listed them all below.
> 
> In all cases, these APIs need to use a more fully specified
'mountable'
> object. There are currently 2 cases we need to support: bare device, and
> device + subvolume. As this is a significant API change, I believe we
> should also allow the mountable description to be safely extended
> without breaking the api again.
> 
> I propose a string which contains a descriptor followed by data custom
> to the descriptor. For the 2 existing cases this would be:
> 
> device:/dev/sda3
> subvol:/dev/sda1,root
>
> Any other solution must convey the same information. Could we achieve
> this with a union, for e.g.? How would this work with bindings?
Yikes, this is ugly.
> I would deprecate all of the apis below and replace them with
> alternative versions with a _ext suffix. The replacement apis would
> accept and return the enhanced descriptor.
_ext is also ugly, and deprecating really fundamental APIs like mount
is wrong.

Thanks for doing the analysis, but I don't think this is a good thing
to do (not that I see any other good way right now either).

Also I think the analysis misses out:

(a) that we can extend existing APIs by adding optional arguments

(b) the string returned from inspect_os can be treated as an opaque
string, provided we return a device name for != btrfs OSes.

I think we should sit on this problem for longer.

After all, btrfs isn't going to be the default filesystem for anyone
who cares about their data for quite a while (given we've had a data
corrupting bug open upstream for 4 months now, and precisely zero has
been done to fix it).

Rich.
> Inspection APIS:
> 
> All take a root filesystem as an argument, which may not be a block
> device.
> 
> inspect_get_arch
> inspect_get_distro
> inspect_get_drive_mappings
> inspect_get_filesystems
> inspect_get_format
> inspect_get_hostname
> inspect_get_icon
> inspect_get_major_version
> inspect_get_minor_version
> inspect_get_mountpoints
> inspect_get_package_format
> inspect_get_package_management
> inspect_get_product_name
> inspect_get_product_variant
> inspect_get_type
> inspect_get_windows_current_control_set
> inspect_get_windows_systemroot
> inspect_is_live
> inspect_is_multipart
> inspect_is_netinst
> inspect_list_applications
> inspect_list_applications2
> 
> The following return filesystem descriptors.
> 
> inspect_get_filesystems
> inspect_get_roots
> inspect_os
> 
> 
> Mount APIS:
> 
> All currently take a block device, but need to accept any filesystem
> descriptor.
> 
> mount
> mount_options
> mount_ro
> mount_vfs
> 
> Label APIs:
> 
> All these currently take a block device, but are arguably applicable to
> btrfs subvolumes. A subvolume doesn't have a label itself, but its root
> filesystem does. A btrfs subvolume can still be mounted by label, as
> long as the subvolume is also given.
> 
> set_label: note that this would also affect other subvolumes
> vfs_label
> vfs_type
> vfs_uuid
> 
> Device name mangling:
> 
> These apis are used to return sanitised device names. I'm not 100%
> convinced we need to modify them. However, we may want additional apis
> which handle filesystem descriptors.
> 
> canonical_device_name
> part_to_dev
> 
> Misc:
> 
> zerofree: only actually supports ext2 and ext3, but the operation makes
> sense for any filesystem. We should update the api and consider the
> implementation later.
> 
> findfs_label
> findfs_uuid: These return a device which contains the btrfs filesystem.
> This device will be mountable, even if the filesystem spans many
> devices. Not 100% convinced about this one, although it feels deficient.
> 
> _______________________________________________
> Libguestfs mailing list
> Libguestfs@redhat.com
> https://www.redhat.com/mailman/listinfo/libguestfs
-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v