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
On Tue, 2013-01-22 at 14:42 +0000, Richard W.M. Jones wrote:
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.
s/ugly/correct/ ;)
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.
We can discuss naming, but if a really fundamental API is broken, it needs to be fixed.
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
I can see 2 possible things you might be getting at here: 1. Add subvolume information as an optional argument This doesn't work, because an API which must return a subvolume can't use an equivalent optional return value. 2. Add a 'work correctly' flag to existing APIS e.g. $g->mount('subvol:/dev/sda1,root', '/', WORK_CORRECTLY => 1); You could do that, but it's a whole lot of extra arguments everywhere. This is even uglier than deprecating the existing apis and creating new ones. If you wanted to go down this route, I would instead add an option to launch which changed it universally for the entire session.
(b) the string returned from inspect_os can be treated as an opaque string, provided we return a device name for != btrfs OSes.
Sure, but I don't think this makes any significant difference to the solution.
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).
I disagree. btrfs is here now and the awkward nature of the problem isn't going to change by waiting. I also expect this to be critical to RHEL 7. Matt
Here's my suggestion. We add a new type 'Mountable' to the generator. This is the same as a string, so it doesn't change the strict C ABI (nor the semantics -- see below). Certain APIs that take a Device parameter would need to change to take a Mountable instead. Certain APIs that return RString/RStringList won't change their generator types, but what can be in the string may change. A Mountable string is normally just a device name, eg. "/dev/sda1". But for special filesystems it may contain an extended string. I suggest "/dev/sda1:btrfs:<subvolume_name>" for btrfs. Other weird filesystems may need other extensions in future. Inspection APIs take and return a Mountable (so Device "root" becomes Mountable "root"). 'list-filesystems' returns a list of Mountables (actually it still returns an RStringList, but it's a list of Mountables). 'mount' and friends take a Mountable instead of a Device. The generator will need to make a small change in the way it checks the Mountable parameter at runtime (q.v. the way Device is checked now, eg. the macro RESOLVE_DEVICE will need another macro RESOLVE_MOUNTABLE). Obviously the ABI doesn't change, since it's all still strings. But I also claim that the semantics of the API don't change: Any existing program that works now will continue to work unchanged. Only programs that would now fail (eg. they try to inspect btrfs guests) would be affected by this change, and in fact those programs would not need to be modified, they would just start to work correctly. Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones virt-df lists disk usage of guests without needing to install any software inside the virtual machine. Supports Linux and Windows. http://people.redhat.com/~rjones/virt-df/
On Tue, 2013-01-22 at 15:15 +0000, Richard W.M. Jones wrote:
Here's my suggestion.
We add a new type 'Mountable' to the generator. This is the same as a string, so it doesn't change the strict C ABI (nor the semantics -- see below). Certain APIs that take a Device parameter would need to change to take a Mountable instead.
Certain APIs that return RString/RStringList won't change their generator types, but what can be in the string may change.
A Mountable string is normally just a device name, eg. "/dev/sda1". But for special filesystems it may contain an extended string. I suggest "/dev/sda1:btrfs:<subvolume_name>" for btrfs. Other weird filesystems may need other extensions in future.
I'd make 1 change to this. Where a mountable isn't a bare device I'd put the device type first as I originally proposed. The reason for this is that a mountable doesn't necessarily reference a single block device, or indeed any block device (think nfs and iscsi). Also, I'd differentiate btrfs and a btrfs subvol. The former can be a bare device, the latter: btrfsvol:<device>,<subvolume_name> where <device> is any block device which is part of the filesystem.
Inspection APIs take and return a Mountable (so Device "root" becomes Mountable "root").
'list-filesystems' returns a list of Mountables (actually it still returns an RStringList, but it's a list of Mountables).
Hmm. I missed RHashtable in my search. I'd better check for others.
'mount' and friends take a Mountable instead of a Device.
The generator will need to make a small change in the way it checks the Mountable parameter at runtime (q.v. the way Device is checked now, eg. the macro RESOLVE_DEVICE will need another macro RESOLVE_MOUNTABLE).
Obviously the ABI doesn't change, since it's all still strings. But I also claim that the semantics of the API don't change: Any existing program that works now will continue to work unchanged. Only programs that would now fail (eg. they try to inspect btrfs guests) would be affected by this change, and in fact those programs would not need to be modified, they would just start to work correctly.
With the minor tweak above, I like this. It does change the semantics slightly, though. Previously, a program could assume that something returned by list_filesystems or inspect_os was a block device and use it as such, whereas now it can't. However, as you point out that was already broken. This change would mean it would be broken differently, though. How much do we care about this? I'm happy to start hacking on this now, Matt
On Tue, Jan 22, 2013 at 03:40:16PM +0000, Matthew Booth wrote:
On Tue, 2013-01-22 at 15:15 +0000, Richard W.M. Jones wrote:
Here's my suggestion.
We add a new type 'Mountable' to the generator. This is the same as a string, so it doesn't change the strict C ABI (nor the semantics -- see below). Certain APIs that take a Device parameter would need to change to take a Mountable instead.
Certain APIs that return RString/RStringList won't change their generator types, but what can be in the string may change.
A Mountable string is normally just a device name, eg. "/dev/sda1". But for special filesystems it may contain an extended string. I suggest "/dev/sda1:btrfs:<subvolume_name>" for btrfs. Other weird filesystems may need other extensions in future.
I'd make 1 change to this. Where a mountable isn't a bare device I'd put the device type first as I originally proposed. The reason for this is that a mountable doesn't necessarily reference a single block device, or indeed any block device (think nfs and iscsi). Also, I'd differentiate btrfs and a btrfs subvol. The former can be a bare device, the latter:
btrfsvol:<device>,<subvolume_name>
where <device> is any block device which is part of the filesystem.
Sure. However be careful about subvolume names that contain commas. Complex escaping rules are something I would very much like to avoid ...
Inspection APIs take and return a Mountable (so Device "root" becomes Mountable "root").
'list-filesystems' returns a list of Mountables (actually it still returns an RStringList, but it's a list of Mountables).
Hmm. I missed RHashtable in my search. I'd better check for others.
'mount' and friends take a Mountable instead of a Device.
The generator will need to make a small change in the way it checks the Mountable parameter at runtime (q.v. the way Device is checked now, eg. the macro RESOLVE_DEVICE will need another macro RESOLVE_MOUNTABLE).
Obviously the ABI doesn't change, since it's all still strings. But I also claim that the semantics of the API don't change: Any existing program that works now will continue to work unchanged. Only programs that would now fail (eg. they try to inspect btrfs guests) would be affected by this change, and in fact those programs would not need to be modified, they would just start to work correctly.
With the minor tweak above, I like this.
It does change the semantics slightly, though. Previously, a program could assume that something returned by list_filesystems or inspect_os was a block device and use it as such, whereas now it can't. However, as you point out that was already broken. This change would mean it would be broken differently, though. How much do we care about this?
I'm happy to start hacking on this now,
Shall we dwell on this a bit more? Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones virt-top is 'top' for virtual machines. Tiny program with many powerful monitoring features, net stats, disk stats, logging, etc. http://people.redhat.com/~rjones/virt-top
participants (2)
-
Matthew Booth -
Richard W.M. Jones