contrib/intro/talk.txt

   1 This is a short (10-15 min) talk that I give to introduce the main
   2 features of libguestfs.  The "slides" are in the form of a complete
   3 self-contained HTML page with a handful images that can be easily
   4 distributed before the talk.
   5
   6 ----------------------------------------------------------------------
   7
   8 [1 The Idea]
   9
  10 The "big idea" behind libguestfs is to read and write disk
  11 images by reusing all the qemu, Linux kernel and userspace
  12 code.
  13
  14 This gives us tremendous power in a relatively small
  15 library: we can handle all Linux filesystems, all Windows
  16 filesystems, LVM, BSD, containers like raw and qcow, CD ISOs,
  17 USB keys, regular hard disks, and lots more.
  18
  19 If you give us a btrfs filesystem in a BSD partition wrapped
  20 in a qcow2 file -- that is something we can handle.
  21
  22 libguestfs -- as the name suggests -- is a plain, ordinary
  23 shared library written in C that you can link to C programs.
  24 You're all very smart people and you will have guessed
  25 already that we don't in fact run qemu as a library inside
  26 libguestfs as this diagram suggests.  Instead we fork
  27 qemu or KVM, running a small "appliance" which has
  28 the usual kernel, a small Linux distribution with tools
  29 like mkfs, lvcreate and parted, and a libguestfs daemon.
  30 The library and the daemon talk to each other over a
  31 virtio-serial connection.
  32
  33 The qemu instance is connected to the disks we are
  34 examining using the ordinary qemu -drive option.
  35
  36 [2 The Stable API]
  37
  38 Consider how you might send commands to the daemon.
  39 Example: Create a filesystem (mkfs).
  40
  41 One thing you might do is to send shell commands over
  42 the virtio-serial connection.  It would send "mkfs -t ..."
  43
  44 This is something that is possible using the libguestfs
  45 API, but we don't encourage it.  There are three reasons
  46 why we don't encourage and support this: one is that
  47 because we're calling this from a C program, it's hard
  48 to construct shell commands and deal with quoting issues.
  49 Secondly it's hard to parse the result from commands
  50 (think about parted or lvs which are two commands that
  51 produce quite complex output that is hard to parse).
  52 Thirdly the command line isn't very long-term stable,
  53 with some commands appearing and changing over time.
  54
  55 I'd emphasize again that we do let you send shell
  56 commands over to the daemon if that's what you want to do.
  57
  58 What we support, though, is a long-term stable API and ABI.
  59 It's slightly (but not very much) higher level than shell
  60 commands.
  61
  62 I've got an example on the page.  This is the guestfs_vfs_type
  63 API which returns the name of the filesystem on a device.
  64
  65 Like libvirt, we are serious about the long term stability
  66 of the API and ABI, and if you write your program against
  67 this API, you'll never have to change the program or even
  68 recompile it.
  69
  70 Because there are 100s of commands that you might want to
  71 run, we made it exceptionally simple to add new APIs.
  72 Shown below is the actual code used to implement "vfs-type".
  73
  74 On the right is the code fragment that runs in the daemon.
  75 This is a short C function which handles constructing the
  76 command line and parsing out the result.  Although there
  77 is parsing code here, the good thing is that it only exists
  78 in one place, and we can update it from time to time if
  79 the underlying shell commands change.
  80
  81 On the left is the metadata for this API function.  It
  82 has a description of the parameters and return value,
  83 some tests (not shown), and a fragment of documentation.
  84
  85 That's ALL you have to write.  From that, we generate
  86 header files, bindings in all the different languages,
  87 RPC for the virtio-serial connection, documentation, etc.
  88 Currently we generate about a quarter of a million lines
  89 of code and documentation.
  90
  91 [3 Tools written around the API]
  92
  93 Around this stable API, myself and the libguestfs team
  94 have written a number of tools.  There are also people
  95 in the community writing other tools.
  96
  97 A few of them are shown on this diagram, in fact there
  98 are many more than are shown here.
  99
 100 Starting at the top, "guestfish" is a shell for the API,
 101 letting you write simple shell scripts.  If you look at
 102 the code examples below, you can see a small guestfish
 103 script that creates a new raw format partitioned filesystem
 104 with some content.
 105
 106 Going round clockwise:
 107
 108 The libguestfs API is a mix of high-level calls like
 109 mkfs, lvremove, vfs-type; and also low level POSIX calls
 110 like mkdir and writing to files.
 111 "guestmount" lets you mount an existing filesystem from
 112 a guest and access it as a regular mountpoint on the host.
 113 guestmount intelligently caches and prefetches data so it's
 114 quite usable and fast from the command line or graphical
 115 programs like the GNOME Nautilus file browser.
 116
 117 "virt-rescue" lets you use the appliance directly, and
 118 it's a useful way to rescue guests by hand.
 119 You just want to hammer out some shell commands manually.
 120
 121 "virt-win-reg" lets you read and write Windows Registry
 122 entries.  There is a rather complex example below right.
 123
 124 Now we come round to the "inspection" tools, and these
 125 three tools let you inspect an unknown guest to find out
 126 what operating system it contains, what applications are
 127 installed, what filesystems, how the filesystems are used
 128 and much more.  I cover that in the next section, but if
 129 you look below you'll see an example of running "virt-df".
 130
 131 Finally there are now tools to resize guests, make them
 132 sparse, align them, and check their alignment.  These
 133 last tools are ones that we eventually hope will become
 134 obsolete.
 135
 136 [4 Inspection]
 137