libguestfs/contrib/intro/talk.txt

This is a short (10-15 min) talk that I give to introduce the main
features of libguestfs.  The "slides" are in the form of a complete
self-contained HTML page with a handful images that can be easily
distributed before the talk.

----------------------------------------------------------------------

[1 The Idea]

The "big idea" behind libguestfs is to read and write disk
images by reusing all the qemu, Linux kernel and userspace
code.

This gives us tremendous power in a relatively small
library: we can handle all Linux filesystems, all Windows
filesystems, LVM, BSD, containers like raw and qcow, CD ISOs,
USB keys, regular hard disks, and lots more.

If you give us a btrfs filesystem in a BSD partition wrapped
in a qcow2 file -- that is something we can handle.

libguestfs -- as the name suggests -- is a plain, ordinary
shared library written in C that you can link to C programs.
You're all very smart people and you will have guessed
already that we don't in fact run qemu as a library inside
libguestfs as this diagram suggests.  Instead we fork
qemu or KVM, running a small "appliance" which has
the usual kernel, a small Linux distribution with tools
like mkfs, lvcreate and parted, and a libguestfs daemon.
The library and the daemon talk to each other over a
virtio-serial connection.

The qemu instance is connected to the disks we are
examining using the ordinary qemu -drive option.

[2 The Stable API]

Consider how you might send commands to the daemon.
Example: Create a filesystem (mkfs).

One thing you might do is to send shell commands over
the virtio-serial connection.  It would send "mkfs -t ..."

This is something that is possible using the libguestfs
API, but we don't encourage it.  There are three reasons
why we don't encourage and support this: one is that
because we're calling this from a C program, it's hard
to construct shell commands.
Secondly it's hard to parse the result from commands
(think about parted or lvs which are two commands that
produce quite complex output that is hard to parse).
Thirdly the command line isn't very long-term stable,
with some commands appearing and changing over time.

I'd emphasize again that we do let you send shell
commands over to the daemon if that's what you want to do.

What we support, though, is a long-term stable API and ABI.
It's slightly (but not very much) higher level than shell
commands.

I've got an example on the page.  This is the guestfs_vfs_type
API which returns the name of the filesystem on a device.

Like libvirt, we are serious about the long term stability
of the API and ABI, and if you write your program against
this API, you'll never have to change the program or even
recompile it.

Because there are 100s of commands that you might want to
run, we made it exceptionally simple to add new APIs.
Shown below is the actual code used to implement "vfs-type".

On the right is the code fragment that runs in the daemon.
This is a short C function which handles constructing the
command line and parsing out the result.  Although there
is parsing code here, the good thing is that it only exists
in one place, and we can update it from time to time if
the underlying shell commands change.

On the left is the metadata for this API function.  It
has a description of the parameters and return value,
some tests (not shown), and a fragment of documentation.

That's ALL you have to write.  From that, we generate
header files, bindings in all the different languages,
RPC for the virtio-serial connection, documentation, etc.
Currently we generate about a quarter of a million lines
of code and documentation.

[3 Tools written around the API]

Around this stable API, myself and the libguestfs team
have written a number of tools.  There are also people
in the community writing other tools.

A few of them are shown on this diagram, in fact there
are many more than are shown here.

Starting at the top, "guestfish" is a shell for the API,
letting you write simple shell scripts.  If you look at
the code examples below, you can see a small guestfish
script that creates a complete guest.  Then we mount it on
the host using guestmount (FUSE) and browse around.

Going round clockwise:

The libguestfs API is a mix of high-level calls like
mkfs, lvremove, vfs-type; and also low level POSIX calls
like mkdir and writing to files.
"guestmount" lets you mount an existing filesystem from
a guest and access it as a regular mountpoint on the host.
guestmount intelligently caches and prefetches data so it's
quite usable and fast from the command line or graphical
programs like the GNOME Nautilus file browser.

"virt-rescue" lets you use the appliance directly, and
it's a useful way to rescue guests by hand.

"virt-win-reg" lets you read and write Windows Registry
entries.  There is a rather complex example below right.

Now we come round to the "inspection" tools, and these
three tools let you inspect an unknown guest to find out
what operating system it contains, what applications are
installed, what filesystems, how the filesystems are used
and much more.  I cover that in the next section, but if
you look below you'll see an example of running "virt-df".

Finally there are now tools to resize guests, make them
sparse, align them, and check their alignment.  These
last tools are ones that we eventually hope will become
obsolete.

[4 Inspection]

Next I want to look at another aspect of the API which is
called "inspection".

Inspection means taking arbitrary disk images and finding
out what they contain, from just what partitions and filesystems
are in a disk image, to whether and what operating system(s)
it contains, to what applications are installed.

The two main command-line tools are virt-filesystems and
virt-inspector, and you can see the output from these tools.
However this information is also available through the
API.  The example there shows getting operating system
inspection data from a C program.  Programs can also get
inspection information, as you can see in the screenshots
from the latest virt-manager.

[5 Graphical browsers]

I've concentrated a lot on command line tools, but you can
also use libguestfs from graphical programs.  I wrote an
experimental program called guestfs-browser, and there are
screenshots shown.  But many people will simply want to mount
a filesystem on the host using guestmount, and then use
ordinary tools.  At the bottom is a screenshot of GNOME
Nautilus browsing into a guest filesystem.