[Libguestfs] Proposed API for guestconv library

[Richard W.M. Jones]

On Mon, Feb 25, 2013 at 03:00:55PM +0000, Matthew Booth wrote:
> guestconv will be a new, re-usable library to perform guest OS
> conversions when moving between hypervisors.
> 
> I've attached 3 files to this email which are relevant to the proposed
> API.
> 
> guestconv.h is the proposed C binding.
> 
> example.c is the simplest possible usage of the API. It converts the
> first detected root of the guest, accepting all defaults.
> 
> root.xml is an example description returned by inspection.
> 
> The first 2 should be self-explanatory, but root.xml requires more
> explanation.
> 
> /guestconv/info contains generic information about the detected guest
> OS. It can't be modified.
> 
> /guestconv/devices contains a list of detected devices. It can be
> modified to affect the choice of driver for each device. Each element
> has an id which uniquely identifies the specific device of a particular
> type, and the selected driver. Available driver options are given as
> child elements.
> 
> If an element is deleted from /guestconv/devices it will be
> unconfigured.
> 
> There are a couple of potential issues I see with it myself:
> 
> Firstly, modifying XML isn't the cleanest API ever. However, I can't
> think of a better solution which would be similarly flexible, and work
> well with language bindings.

Agreed :-(

> Secondly, it doesn't cover the case of an EC2->KVM conversion where you
> will need to do additional transformations before conversion.
> Specifically you'll need to add a partition table and boot loader.
>
> You could potentially argue that this kind of transformation is out of
> scope for the tool. However, it would introduce changes that you would
> have to take into account during conversion due to altered device names.
> I think we need to be able to support it without a major API change,
> even if we don't support it initially. I'll try to post an update which
> supports this, although ideas are welcome in the meantime.

I think EC2 -> KVM ought to be in scope for the tool.  BUT I would
also say you wouldn't want the client to be having to make complex XML
transformations (and have to know to do this when the source is EC2).
This should not be visible in the XML, or at least, not something the
caller is required to know about.

> #include <guestconv.h>
> 
> int
> main(int argc, char *argv[])
> {
>     guestconv_err *err = NULL;
> 
>     guestconv_h *h = guestconv_create(&err);
>     if (h == NULL) goto error;
>
>     if (guestconv_add_drive(h, "test.img", "sda", &err) != 0)
>         goto error;

'&err' blurgh.  Why not return an error code and set the error in the
handle, same way that libguestfs works?

>     guestconv_root **roots = guestconv_inspect(h, "rhev-3.1", &err);
>     if (roots == NULL) goto error;
>     if (roots[0] == NULL) {
>         fprintf(stderr, "Didn't find an OS\n");
>         return 1;
>     }

It's interesting that you decided to return each OS as separate HTML.
Does anything useful happen if the guest is multi-boot, or would it be
better to ban that case right now?  If you decide to support dual boot
guests, is it better to return all the operating systems in a single
block of XML given that (a) they may share filesystems (libguestfs
allows this) and (b) they may share a single bootloader so applying
separate convert operations to each OS separately will probably break?

>     if (guestconv_convert(h, roots[0], &err) != 0)
>         goto error;
> 
>     printf("Success\n");
> 
>     return 0;
> 
> error:
>     fprintf(stderr, "%s\n", err->message);
>     return 1;
> }

[...]

<guestconv>
    <info>
        <hostname>guest.example.com</hostname>
        <os>linux</os>
        <distribution>rhel</distribution>
        <version>
            <major>6</major>
            <minor>4</minor>
        </version>
    </info>
    <devices>
        <graphics id='0' driver='qxl-vga'>
            <driver>qxl-vga</driver>
            <driver>cirrus-vga</driver>
        </graphics>
        <network id='eth0' driver='virtio-net-pci'>
            <driver>virtio-net-pci</driver>
            <driver>e1000</driver>
        </network>
        <network id='eth1' driver='virtio-net-pci'>
            <driver>virtio-net-pci</driver>
            <driver>e1000</driver>
        </network>
        <block id='sda' driver='virtio-blk-pci'>
            <driver>virtio-blk-pci</driver>
            <driver>scsi-hd</driver>
        </block>
        <console id='console' driver='isa-serial'>
            <driver>virtserialport</driver>
            <driver>virtconsole</driver>
            <driver>isa-serial</driver>
        </console>
    </devices>
<guestconv>

Should you have an "updatable='1'" flag on those elements which the
caller is allowed to change?  Or they can make arbitrary changes to
anything in /guestconv/devices?  Can they add new devices or device
sections?

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
libguestfs lets you edit virtual machines.  Supports shell scripting,
bindings from many languages.  http://libguestfs.org