guestfs.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 guestfs - Library for accessing and modifying virtual machine images
   6
   7 =head1 SYNOPSIS
   8
   9  guestfs_h handle = guestfs_create ();
  10  guestfs_add_drive (handle, "guest.img");
  11  guestfs_launch (handle);
  12  guestfs_wait_ready (handle);
  13  guestfs_mount (handle, "/dev/sda1", "/");
  14  guestfs_touch_file (handle, "/hello");
  15  guestfs_sync (handle);
  16  guestfs_close (handle);
  17
  18 =head1 DESCRIPTION
  19
  20 Libguestfs is a library for accessing and modifying guest disk images.
  21 Amongst the things this is good for: making batch configuration
  22 changes to guests, getting disk used/free statistics (see also:
  23 virt-df), migrating between virtualization systems (see also:
  24 virt-p2v), performing partial backups, performing partial guest
  25 clones, cloning guests and changing registry/UUID/hostname info, and
  26 much else besides.
  27
  28 Libguestfs uses Linux kernel and qemu code, and can access any type of
  29 guest filesystem that Linux and qemu can, including but not limited
  30 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
  31 schemes, qcow, qcow2, vmdk.
  32
  33 Libguestfs provides ways to enumerate guest storage (eg. partitions,
  34 LVs, what filesystem is in each LV, etc.).  It can also run commands
  35 in the context of the guest.  Also you can mount guest filesystems on
  36 the host (requires root privs and NFS).
  37
  38 Libguestfs is a library that can be linked with C and C++ management
  39 programs (or management programs written in other languages, if people
  40 contribute the language bindings).  You can also use it from shell
  41 scripts or the command line.
  42
  43 =head1 CONNECTION MANAGEMENT
  44
  45
  46
  47
  48
  49
  50 =head1 CONFIGURATION MANAGEMENT
  51
  52
  53
  54
  55
  56
  57 =head1 HIGH-LEVEL API
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67 =head1 ERROR HANDLING
  68
  69
  70
  71
  72
  73
  74 =head1 STATE MACHINE AND LOW-LEVEL EVENT API
  75
  76 Internally, libguestfs is implemented by running a virtual machine
  77 using L<qemu(1)>.  QEmu runs as a child process of the main program,
  78 and most of this discussion won't make sense unless you understand
  79 that the complexity is dealing with the (asynchronous) actions of the
  80 child process.
  81
  82 =head2 STATE MACHINE
  83
  84 libguestfs uses a state machine to model the child process:
  85
  86                          |
  87                     guestfs_create
  88                          |
  89                          |
  90                      ____V_____
  91                     /          \
  92                     |  CONFIG  |
  93                     \__________/
  94                      ^ ^   ^  \
  95                     /  |    \  \ guestfs_launch
  96                    /   |    _\__V______
  97                   /    |   /           \
  98                  /     |   | LAUNCHING |
  99                 /      |   \___________/
 100                /       |       /
 101               /        |  guestfs_wait_ready
 102              /         |     /
 103     ______  /        __|____V
 104    /      \ ------> /        \
 105    | BUSY |         | READY  |
 106    \______/ <------ \________/
 107
 108 The normal transitions are (1) CONFIG (when the handle is created, but
 109 there is no child process), (2) LAUNCHING (when the child process is
 110 booting up), (3) alternating between READY and BUSY as commands are
 111 issued to, and carried out by, the child process.
 112
 113 The guest may be killed by C<guestfs_kill_subprocess>, or may die
 114 asynchronously at any time (eg. due to some internal error), and that
 115 causes the state to transition back to CONFIG.
 116
 117 Configuration commands for qemu such as C<guestfs_add_drive> can only
 118 be issued when in the CONFIG state.
 119
 120 The high-level API offers two calls that go from CONFIG through
 121 LAUNCHING to READY.  C<guestfs_launch> is a non-blocking call that
 122 starts up the child process, immediately moving from CONFIG to
 123 LAUNCHING.  C<guestfs_wait_ready> blocks until the child process is
 124 READY to accept commands (or until some failure or timeout).  The
 125 low-level event API described below provides a non-blocking way to
 126 replace C<guestfs_wait_ready>.
 127
 128 High-level API actions such as C<guestfs_mount> can only be issued
 129 when in the READY state.  These high-level API calls block waiting for
 130 the command to be carried out (ie. the state to transition to BUSY and
 131 then back to READY).  But using the low-level event API, you get
 132 non-blocking versions.  (But you can still only carry out one
 133 operation per handle at a time - that is a limitation of the
 134 communications protocol we use).
 135
 136 Finally, the child process sends asynchronous messages back to the
 137 main program, such as kernel log messages.  Mostly these are ignored
 138 by the high-level API, but using the low-level event API you can
 139 register to receive these messages.
 140
 141 =head2 SETTING CALLBACKS TO HANDLE EVENTS
 142
 143 The child process generates events in some situations.  Current events
 144 include: receiving a reply message after some action, receiving a log
 145 message, the child process exits, &c.
 146
 147 Use the C<guestfs_set_*_callback> functions to set a callback for
 148 different types of events.
 149
 150 Only I<one callback of each type> can be registered for each handle.
 151 Calling C<guestfs_set_*_callback> again overwrites the previous
 152 callback of that type.  Cancel all callbacks of this type by calling
 153 this function with C<cb> set to C<NULL>.
 154
 155 =head2 NON-BLOCKING ACTIONS
 156
 157 C<guestfs_set_reply_callback> is the most interesting callback to
 158 play with, since it allows you to perform actions without blocking.
 159
 160 For example:
 161
 162  do_it ()
 163  {
 164    start_call ();
 165    guestfs_main_loop_run (); /* --> blocks, then calls my_cb */
 166  }
 167
 168  start_call ()
 169  {
 170    guestfs_set_reply_callback (handle, my_cb, data);
 171    guestfs_nb_[action] (handle, [other parameters ...]);
 172    /* returns immediately */
 173  }
 174
 175  my_cb (guestfs_h handle, void *data)
 176  {
 177    retval = guestfs_nb_[action]_r (handle);
 178    /* ... */
 179  }
 180
 181 There are C<guestfs_nb_*> and C<guestfs_nb_*_r> functions
 182 corresponding to (very nearly) every C<guestfs_*> action in the
 183 high-level API.
 184
 185 =head2 guestfs_set_reply_callback
 186
 187  void guestfs_set_reply_callback (guestfs_handle h,
 188                                   guestfs_reply_cb cb,
 189                                   void *opaque);
 190
 191 The callback function C<cb> will be called whenever a reply is
 192 received from the child process.  (This corresponds to a transition
 193 from the BUSY state to the READY state).
 194
 195 Note (I<important!>) that high-level API calls overwrite this
 196 callback.
 197
 198 =head2 guestfs_set_log_message_callback
 199
 200  void guestfs_set_log_message_callback (guestfs_handle h,
 201                                         guestfs_log_message_cb cb,
 202                                         void *opaque);
 203
 204 The callback function C<cb> will be called whenever qemu or the guest
 205 writes anything to the console.
 206
 207 Use this function to capture kernel messages and similar.
 208
 209 Normally there is no log message handler, and log messages are just
 210 discarded.
 211
 212 =head2 guestfs_set_subprocess_quit_callback
 213
 214  void guestfs_set_subprocess_quit_callback (guestfs_handle h,
 215                                             guestfs_subprocess_quit_cb cb,
 216                                             void *opaque);
 217
 218 The callback function C<cb> will be called when the child process
 219 quits, either asynchronously or if killed by
 220 C<guestfs_kill_subprocess>.  (This corresponds to a transition from
 221 any state to the CONFIG state).
 222
 223 =head2 guestfs_set_ready_callback
 224
 225  void guestfs_set_ready_callback (guestfs_handle h,
 226                                   guestfs_ready_cb cb,
 227                                   void *opaque);
 228
 229 The callback function C<cb> will be called when the child process
 230 becomes ready.  (This corresponds to a transition from I<either>
 231 LAUNCHING I<or> BUSY to the READY state).
 232
 233 You can use this instead of C<guestfs_wait_ready> to implement a
 234 non-blocking wait for the child process to finish booting up.
 235
 236 =head2 EVENT MAIN LOOP
 237
 238 To use the low-level event API, you have to provide an event "main
 239 loop".  You can write your own, but if you don't want to write one,
 240 two are provided for you:
 241
 242 =over 4
 243
 244 =item libguestfs-poll
 245
 246 A simple main loop that is implemented using L<poll(2)>.
 247
 248 This is the default main loop unless you call C<guestfs_set_main_loop>
 249 or C<guestfs_glib_set_main_loop>.
 250
 251 =item libguestfs-glib
 252
 253 An implementation which can be used with GLib and GTK+ programs.  You
 254 can use this to write graphical (GTK+) programs which use libguestfs
 255 without hanging during long or slow operations.
 256
 257 =back
 258
 259 =head2 guestfs_set_main_loop
 260
 261  void guestfs_set_main_loop (guestfs_main_loop *);
 262
 263 This call sets the current main loop to the list of callbacks
 264 contained in the C<guestfs_main_loop> structure.
 265
 266 Only one main loop implementation can be used by libguestfs, so
 267 calling this replaces the previous one.  (So this is something that
 268 has to be done by the main program, but only the main program "knows"
 269 that it is a GTK+ program or whatever).
 270
 271 You should call this early in the main program, certainly before
 272 calling C<guestfs_create>.
 273
 274 =head2 guestfs_glib_set_main_loop
 275
 276  void guestfs_glib_set_main_loop (GMainLoop *);
 277
 278 This helper calls C<guestfs_set_main_loop> with the correct callbacks
 279 for integrating with the GLib main loop.
 280
 281 The libguestfs-glib main loop is contained in a separate library, so
 282 that libguestfs doesn't depend on the whole of GLib:
 283
 284  #include <glib.h>
 285  #include <guestfs-glib.h>
 286
 287  main ()
 288  {
 289    GMainLoop *loop =
 290      g_main_loop_new (g_main_context_default (), 1);
 291    ...
 292    guestfs_glib_set_main_loop (loop);
 293    ...
 294    g_main_loop_run (loop);
 295  }
 296
 297 To use this main loop you must link with C<-lguestfs-glib>.  (See also
 298 the GLib and GTK+ documentation).
 299
 300 =head2 guestfs_main_loop_run
 301
 302  void guestfs_main_loop_run (void);
 303
 304 This calls the main loop.
 305
 306 For some types of main loop you may want or prefer to call another
 307 function, eg. C<g_main_loop_run>, or the main loop may already be
 308 invoked by another part of your program.  In those cases, ignore this
 309 call.
 310
 311 =head2 guestfs_main_loop_quit
 312
 313  void guestfs_main_loop_quit (void);
 314
 315 This instructs the main loop to quit.  In other words,
 316 C<guestfs_main_loop_run> will return.
 317
 318 For some types of main loop you may want or prefer to call another
 319 function, eg. C<g_main_loop_quit>.  In those cases, ignore this call.
 320
 321 =head2 WRITING A CUSTOM MAIN LOOP
 322
 323 This isn't documented.  Please see the libguestfs-poll and libguestfs-glib
 324 implementations.
 325
 326 =head1 SEE ALSO
 327
 328 L<qemu(1)>
 329
 330
 331
 332
 333
 334 =head1 AUTHORS
 335
 336 Richard W.M. Jones (C<rjones at redhat dot com>)
 337
 338 =head1 COPYRIGHT
 339
 340 Copyright (C) 2009 Red Hat Inc.
 341 L<http://et.redhat.com/~rjones/libguestfs>
 342
 343 This library is free software; you can redistribute it and/or
 344 modify it under the terms of the GNU Lesser General Public
 345 License as published by the Free Software Foundation; either
 346 version 2 of the License, or (at your option) any later version.
 347
 348 This library is distributed in the hope that it will be useful,
 349 but WITHOUT ANY WARRANTY; without even the implied warranty of
 350 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 351 Lesser General Public License for more details.
 352
 353 You should have received a copy of the GNU Lesser General Public
 354 License along with this library; if not, write to the Free Software
 355 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA