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.
  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 complete guest.  Then we mount it on
 104 the host using guestmount (FUSE) and browse around.
 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
 120 "virt-win-reg" lets you read and write Windows Registry
 121 entries.  There is a rather complex example below right.
 122
 123 Now we come round to the "inspection" tools, and these
 124 three tools let you inspect an unknown guest to find out
 125 what operating system it contains, what applications are
 126 installed, what filesystems, how the filesystems are used
 127 and much more.  I cover that in the next section, but if
 128 you look below you'll see an example of running "virt-df".
 129
 130 Finally there are now tools to resize guests, make them
 131 sparse, align them, and check their alignment.  These
 132 last tools are ones that we eventually hope will become
 133 obsolete.
 134
 135 [4 Inspection]
 136
 137 Next I want to look at another aspect of the API which is
 138 called "inspection".
 139
 140 Inspection means taking arbitrary disk images and finding
 141 out what they contain, from just what partitions and filesystems
 142 are in a disk image, to whether and what operating system(s)
 143 it contains, to what applications are installed.
 144
 145 The two main command-line tools are virt-filesystems and
 146 virt-inspector, and you can see the output from these tools.
 147 However this information is also available through the
 148 API.  The example there shows getting operating system
 149 inspection data from a C program.  Programs can also get
 150 inspection information, as you can see in the screenshots
 151 from the latest virt-manager.
 152
 153 [5 Graphical browsers]
 154
 155 I've concentrated a lot on command line tools, but you can
 156 also use libguestfs from graphical programs.  I wrote an
 157 experimental program called guestfs-browser, and there are
 158 screenshots shown.  But many people will simply want to mount
 159 a filesystem on the host using guestmount, and then use
 160 ordinary tools.  At the bottom is a screenshot of GNOME
 161 Nautilus browsing into a guest filesystem.
 162