tests: Put test-tool and comment into own section.
[libguestfs.git] / src / 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  #include <guestfs.h>
10  
11  guestfs_h *g = guestfs_create ();
12  guestfs_add_drive (g, "guest.img");
13  guestfs_launch (g);
14  guestfs_mount (g, "/dev/sda1", "/");
15  guestfs_touch (g, "/hello");
16  guestfs_umount (g, "/");
17  guestfs_close (g);
18
19  cc prog.c -o prog -lguestfs
20 or:
21  cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
22
23 =head1 DESCRIPTION
24
25 Libguestfs is a library for accessing and modifying guest disk images.
26 Amongst the things this is good for: making batch configuration
27 changes to guests, getting disk used/free statistics (see also:
28 virt-df), migrating between virtualization systems (see also:
29 virt-p2v), performing partial backups, performing partial guest
30 clones, cloning guests and changing registry/UUID/hostname info, and
31 much else besides.
32
33 Libguestfs uses Linux kernel and qemu code, and can access any type of
34 guest filesystem that Linux and qemu can, including but not limited
35 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
36 schemes, qcow, qcow2, vmdk.
37
38 Libguestfs provides ways to enumerate guest storage (eg. partitions,
39 LVs, what filesystem is in each LV, etc.).  It can also run commands
40 in the context of the guest.  Also you can access filesystems over
41 FUSE.
42
43 Libguestfs is a library that can be linked with C and C++ management
44 programs (or management programs written in OCaml, Perl, Python, Ruby,
45 Java, PHP, Erlang, Haskell or C#).  You can also use it from shell
46 scripts or the command line.
47
48 You don't need to be root to use libguestfs, although obviously you do
49 need enough permissions to access the disk images.
50
51 Libguestfs is a large API because it can do many things.  For a gentle
52 introduction, please read the L</API OVERVIEW> section next.
53
54 There are also some example programs in the L<guestfs-examples(3)>
55 manual page.
56
57 =head1 API OVERVIEW
58
59 This section provides a gentler overview of the libguestfs API.  We
60 also try to group API calls together, where that may not be obvious
61 from reading about the individual calls in the main section of this
62 manual.
63
64 =head2 HANDLES
65
66 Before you can use libguestfs calls, you have to create a handle.
67 Then you must add at least one disk image to the handle, followed by
68 launching the handle, then performing whatever operations you want,
69 and finally closing the handle.  By convention we use the single
70 letter C<g> for the name of the handle variable, although of course
71 you can use any name you want.
72
73 The general structure of all libguestfs-using programs looks like
74 this:
75
76  guestfs_h *g = guestfs_create ();
77  
78  /* Call guestfs_add_drive additional times if there are
79   * multiple disk images.
80   */
81  guestfs_add_drive (g, "guest.img");
82  
83  /* Most manipulation calls won't work until you've launched
84   * the handle 'g'.  You have to do this _after_ adding drives
85   * and _before_ other commands.
86   */
87  guestfs_launch (g);
88  
89  /* Now you can examine what partitions, LVs etc are available.
90   */
91  char **partitions = guestfs_list_partitions (g);
92  char **logvols = guestfs_lvs (g);
93  
94  /* To access a filesystem in the image, you must mount it.
95   */
96  guestfs_mount (g, "/dev/sda1", "/");
97  
98  /* Now you can perform filesystem actions on the guest
99   * disk image.
100   */
101  guestfs_touch (g, "/hello");
102  
103  /* This is only needed for libguestfs < 1.5.24.  Since then
104   * it is done automatically when you close the handle.  See
105   * discussion of autosync in this page.
106   */
107  guestfs_sync (g);
108  
109  /* Close the handle 'g'. */
110  guestfs_close (g);
111
112 The code above doesn't include any error checking.  In real code you
113 should check return values carefully for errors.  In general all
114 functions that return integers return C<-1> on error, and all
115 functions that return pointers return C<NULL> on error.  See section
116 L</ERROR HANDLING> below for how to handle errors, and consult the
117 documentation for each function call below to see precisely how they
118 return error indications.  See L<guestfs-examples(3)> for fully worked
119 examples.
120
121 =head2 DISK IMAGES
122
123 The image filename (C<"guest.img"> in the example above) could be a
124 disk image from a virtual machine, a L<dd(1)> copy of a physical hard
125 disk, an actual block device, or simply an empty file of zeroes that
126 you have created through L<posix_fallocate(3)>.  Libguestfs lets you
127 do useful things to all of these.
128
129 The call you should use in modern code for adding drives is
130 L</guestfs_add_drive_opts>.  To add a disk image, allowing writes, and
131 specifying that the format is raw, do:
132
133  guestfs_add_drive_opts (g, filename,
134                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
135                          -1);
136
137 You can add a disk read-only using:
138
139  guestfs_add_drive_opts (g, filename,
140                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
141                          GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
142                          -1);
143
144 or by calling the older function L</guestfs_add_drive_ro>.  In either
145 case libguestfs won't modify the file.
146
147 Be extremely cautious if the disk image is in use, eg. if it is being
148 used by a virtual machine.  Adding it read-write will almost certainly
149 cause disk corruption, but adding it read-only is safe.
150
151 You must add at least one disk image, and you may add multiple disk
152 images.  In the API, the disk images are usually referred to as
153 C</dev/sda> (for the first one you added), C</dev/sdb> (for the second
154 one you added), etc.
155
156 Once L</guestfs_launch> has been called you cannot add any more images.
157 You can call L</guestfs_list_devices> to get a list of the device
158 names, in the order that you added them.  See also L</BLOCK DEVICE
159 NAMING> below.
160
161 =head2 MOUNTING
162
163 Before you can read or write files, create directories and so on in a
164 disk image that contains filesystems, you have to mount those
165 filesystems using L</guestfs_mount_options> or L</guestfs_mount_ro>.
166 If you already know that a disk image contains (for example) one
167 partition with a filesystem on that partition, then you can mount it
168 directly:
169
170  guestfs_mount_options (g, "", "/dev/sda1", "/");
171
172 where C</dev/sda1> means literally the first partition (C<1>) of the
173 first disk image that we added (C</dev/sda>).  If the disk contains
174 Linux LVM2 logical volumes you could refer to those instead
175 (eg. C</dev/VG/LV>).  Note that these are libguestfs virtual devices,
176 and are nothing to do with host devices.
177
178 If you are given a disk image and you don't know what it contains then
179 you have to find out.  Libguestfs can do that too: use
180 L</guestfs_list_partitions> and L</guestfs_lvs> to list possible
181 partitions and LVs, and either try mounting each to see what is
182 mountable, or else examine them with L</guestfs_vfs_type> or
183 L</guestfs_file>.  To list just filesystems, use
184 L</guestfs_list_filesystems>.
185
186 Libguestfs also has a set of APIs for inspection of unknown disk
187 images (see L</INSPECTION> below).  But you might find it easier to
188 look at higher level programs built on top of libguestfs, in
189 particular L<virt-inspector(1)>.
190
191 To mount a filesystem read-only, use L</guestfs_mount_ro>.  There are
192 several other variations of the C<guestfs_mount_*> call.
193
194 =head2 FILESYSTEM ACCESS AND MODIFICATION
195
196 The majority of the libguestfs API consists of fairly low-level calls
197 for accessing and modifying the files, directories, symlinks etc on
198 mounted filesystems.  There are over a hundred such calls which you
199 can find listed in detail below in this man page, and we don't even
200 pretend to cover them all in this overview.
201
202 Specify filenames as full paths, starting with C<"/"> and including
203 the mount point.
204
205 For example, if you mounted a filesystem at C<"/"> and you want to
206 read the file called C<"etc/passwd"> then you could do:
207
208  char *data = guestfs_cat (g, "/etc/passwd");
209
210 This would return C<data> as a newly allocated buffer containing the
211 full content of that file (with some conditions: see also
212 L</DOWNLOADING> below), or C<NULL> if there was an error.
213
214 As another example, to create a top-level directory on that filesystem
215 called C<"var"> you would do:
216
217  guestfs_mkdir (g, "/var");
218
219 To create a symlink you could do:
220
221  guestfs_ln_s (g, "/etc/init.d/portmap",
222                "/etc/rc3.d/S30portmap");
223
224 Libguestfs will reject attempts to use relative paths and there is no
225 concept of a current working directory.
226
227 Libguestfs can return errors in many situations: for example if the
228 filesystem isn't writable, or if a file or directory that you
229 requested doesn't exist.  If you are using the C API (documented here)
230 you have to check for those error conditions after each call.  (Other
231 language bindings turn these errors into exceptions).
232
233 File writes are affected by the per-handle umask, set by calling
234 L</guestfs_umask> and defaulting to 022.  See L</UMASK>.
235
236 =head2 PARTITIONING
237
238 Libguestfs contains API calls to read, create and modify partition
239 tables on disk images.
240
241 In the common case where you want to create a single partition
242 covering the whole disk, you should use the L</guestfs_part_disk>
243 call:
244
245  const char *parttype = "mbr";
246  if (disk_is_larger_than_2TB)
247    parttype = "gpt";
248  guestfs_part_disk (g, "/dev/sda", parttype);
249
250 Obviously this effectively wipes anything that was on that disk image
251 before.
252
253 =head2 LVM2
254
255 Libguestfs provides access to a large part of the LVM2 API, such as
256 L</guestfs_lvcreate> and L</guestfs_vgremove>.  It won't make much sense
257 unless you familiarize yourself with the concepts of physical volumes,
258 volume groups and logical volumes.
259
260 This author strongly recommends reading the LVM HOWTO, online at
261 L<http://tldp.org/HOWTO/LVM-HOWTO/>.
262
263 =head2 DOWNLOADING
264
265 Use L</guestfs_cat> to download small, text only files.  This call is
266 limited to files which are less than 2 MB and which cannot contain any
267 ASCII NUL (C<\0>) characters.  However the API is very simple to use.
268
269 L</guestfs_read_file> can be used to read files which contain
270 arbitrary 8 bit data, since it returns a (pointer, size) pair.
271 However it is still limited to "small" files, less than 2 MB.
272
273 L</guestfs_download> can be used to download any file, with no
274 limits on content or size (even files larger than 4 GB).
275
276 To download multiple files, see L</guestfs_tar_out> and
277 L</guestfs_tgz_out>.
278
279 =head2 UPLOADING
280
281 It's often the case that you want to write a file or files to the disk
282 image.
283
284 To write a small file with fixed content, use L</guestfs_write>.  To
285 create a file of all zeroes, use L</guestfs_truncate_size> (sparse) or
286 L</guestfs_fallocate64> (with all disk blocks allocated).  There are a
287 variety of other functions for creating test files, for example
288 L</guestfs_fill> and L</guestfs_fill_pattern>.
289
290 To upload a single file, use L</guestfs_upload>.  This call has no
291 limits on file content or size (even files larger than 4 GB).
292
293 To upload multiple files, see L</guestfs_tar_in> and L</guestfs_tgz_in>.
294
295 However the fastest way to upload I<large numbers of arbitrary files>
296 is to turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and
297 L<mkisofs(8)>), then attach this using L</guestfs_add_drive_ro>.  If
298 you add the drive in a predictable way (eg. adding it last after all
299 other drives) then you can get the device name from
300 L</guestfs_list_devices> and mount it directly using
301 L</guestfs_mount_ro>.  Note that squashfs images are sometimes
302 non-portable between kernel versions, and they don't support labels or
303 UUIDs.  If you want to pre-build an image or you need to mount it
304 using a label or UUID, use an ISO image instead.
305
306 =head2 COPYING
307
308 There are various different commands for copying between files and
309 devices and in and out of the guest filesystem.  These are summarised
310 in the table below.
311
312 =over 4
313
314 =item B<file> to B<file>
315
316 Use L</guestfs_cp> to copy a single file, or L</guestfs_cp_a> to copy
317 directories recursively.
318
319 To copy part of a file (offset and size) use
320 L</guestfs_copy_file_to_file>.
321
322 =item B<file> to B<device>
323
324 =item B<device> to B<file>
325
326 =item B<device> to B<device>
327
328 Use L</guestfs_copy_file_to_device>, L</guestfs_copy_device_to_file>,
329 or L</guestfs_copy_device_to_device>.
330
331 Example: duplicate the contents of an LV:
332
333  guestfs_copy_device_to_device (g,
334          "/dev/VG/Original", "/dev/VG/Copy",
335          /* -1 marks the end of the list of optional parameters */
336          -1);
337
338 The destination (C</dev/VG/Copy>) must be at least as large as the
339 source (C</dev/VG/Original>).  To copy less than the whole source
340 device, use the optional C<size> parameter:
341
342  guestfs_copy_device_to_device (g,
343          "/dev/VG/Original", "/dev/VG/Copy",
344          GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
345          -1);
346
347 =item B<file on the host> to B<file or device>
348
349 Use L</guestfs_upload>.  See L</UPLOADING> above.
350
351 =item B<file or device> to B<file on the host>
352
353 Use L</guestfs_download>.  See L</DOWNLOADING> above.
354
355 =back
356
357 =head2 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
358
359 Calls like L</guestfs_upload>, L</guestfs_download>,
360 L</guestfs_tar_in>, L</guestfs_tar_out> etc appear to only take
361 filenames as arguments, so it appears you can only upload and download
362 to files.  However many Un*x-like hosts let you use the special device
363 files C</dev/stdin>, C</dev/stdout>, C</dev/stderr> and C</dev/fd/N>
364 to read and write from stdin, stdout, stderr, and arbitrary file
365 descriptor N.
366
367 For example, L<virt-cat(1)> writes its output to stdout by
368 doing:
369
370  guestfs_download (g, filename, "/dev/stdout");
371
372 and you can write tar output to a file descriptor C<fd> by doing:
373
374  char devfd[64];
375  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
376  guestfs_tar_out (g, "/", devfd);
377
378 =head2 LISTING FILES
379
380 L</guestfs_ll> is just designed for humans to read (mainly when using
381 the L<guestfish(1)>-equivalent command C<ll>).
382
383 L</guestfs_ls> is a quick way to get a list of files in a directory
384 from programs, as a flat list of strings.
385
386 L</guestfs_readdir> is a programmatic way to get a list of files in a
387 directory, plus additional information about each one.  It is more
388 equivalent to using the L<readdir(3)> call on a local filesystem.
389
390 L</guestfs_find> and L</guestfs_find0> can be used to recursively list
391 files.
392
393 =head2 RUNNING COMMANDS
394
395 Although libguestfs is primarily an API for manipulating files
396 inside guest images, we also provide some limited facilities for
397 running commands inside guests.
398
399 There are many limitations to this:
400
401 =over 4
402
403 =item *
404
405 The kernel version that the command runs under will be different
406 from what it expects.
407
408 =item *
409
410 If the command needs to communicate with daemons, then most likely
411 they won't be running.
412
413 =item *
414
415 The command will be running in limited memory.
416
417 =item *
418
419 The network may not be available unless you enable it
420 (see L</guestfs_set_network>).
421
422 =item *
423
424 Only supports Linux guests (not Windows, BSD, etc).
425
426 =item *
427
428 Architecture limitations (eg. won't work for a PPC guest on
429 an X86 host).
430
431 =item *
432
433 For SELinux guests, you may need to enable SELinux and load policy
434 first.  See L</SELINUX> in this manpage.
435
436 =item *
437
438 I<Security:> It is not safe to run commands from untrusted, possibly
439 malicious guests.  These commands may attempt to exploit your program
440 by sending unexpected output.  They could also try to exploit the
441 Linux kernel or qemu provided by the libguestfs appliance.  They could
442 use the network provided by the libguestfs appliance to bypass
443 ordinary network partitions and firewalls.  They could use the
444 elevated privileges or different SELinux context of your program
445 to their advantage.
446
447 A secure alternative is to use libguestfs to install a "firstboot"
448 script (a script which runs when the guest next boots normally), and
449 to have this script run the commands you want in the normal context of
450 the running guest, network security and so on.  For information about
451 other security issues, see L</SECURITY>.
452
453 =back
454
455 The two main API calls to run commands are L</guestfs_command> and
456 L</guestfs_sh> (there are also variations).
457
458 The difference is that L</guestfs_sh> runs commands using the shell, so
459 any shell globs, redirections, etc will work.
460
461 =head2 CONFIGURATION FILES
462
463 To read and write configuration files in Linux guest filesystems, we
464 strongly recommend using Augeas.  For example, Augeas understands how
465 to read and write, say, a Linux shadow password file or X.org
466 configuration file, and so avoids you having to write that code.
467
468 The main Augeas calls are bound through the C<guestfs_aug_*> APIs.  We
469 don't document Augeas itself here because there is excellent
470 documentation on the L<http://augeas.net/> website.
471
472 If you don't want to use Augeas (you fool!) then try calling
473 L</guestfs_read_lines> to get the file as a list of lines which
474 you can iterate over.
475
476 =head2 SELINUX
477
478 We support SELinux guests.  To ensure that labeling happens correctly
479 in SELinux guests, you need to enable SELinux and load the guest's
480 policy:
481
482 =over 4
483
484 =item 1.
485
486 Before launching, do:
487
488  guestfs_set_selinux (g, 1);
489
490 =item 2.
491
492 After mounting the guest's filesystem(s), load the policy.  This
493 is best done by running the L<load_policy(8)> command in the
494 guest itself:
495
496  guestfs_sh (g, "/usr/sbin/load_policy");
497
498 (Older versions of C<load_policy> require you to specify the
499 name of the policy file).
500
501 =item 3.
502
503 Optionally, set the security context for the API.  The correct
504 security context to use can only be known by inspecting the
505 guest.  As an example:
506
507  guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
508
509 =back
510
511 This will work for running commands and editing existing files.
512
513 When new files are created, you may need to label them explicitly,
514 for example by running the external command
515 C<restorecon pathname>.
516
517 =head2 UMASK
518
519 Certain calls are affected by the current file mode creation mask (the
520 "umask").  In particular ones which create files or directories, such
521 as L</guestfs_touch>, L</guestfs_mknod> or L</guestfs_mkdir>.  This
522 affects either the default mode that the file is created with or
523 modifies the mode that you supply.
524
525 The default umask is C<022>, so files are created with modes such as
526 C<0644> and directories with C<0755>.
527
528 There are two ways to avoid being affected by umask.  Either set umask
529 to 0 (call C<guestfs_umask (g, 0)> early after launching).  Or call
530 L</guestfs_chmod> after creating each file or directory.
531
532 For more information about umask, see L<umask(2)>.
533
534 =head2 ENCRYPTED DISKS
535
536 Libguestfs allows you to access Linux guests which have been
537 encrypted using whole disk encryption that conforms to the
538 Linux Unified Key Setup (LUKS) standard.  This includes
539 nearly all whole disk encryption systems used by modern
540 Linux guests.
541
542 Use L</guestfs_vfs_type> to identify LUKS-encrypted block
543 devices (it returns the string C<crypto_LUKS>).
544
545 Then open these devices by calling L</guestfs_luks_open>.
546 Obviously you will require the passphrase!
547
548 Opening a LUKS device creates a new device mapper device
549 called C</dev/mapper/mapname> (where C<mapname> is the
550 string you supply to L</guestfs_luks_open>).
551 Reads and writes to this mapper device are decrypted from and
552 encrypted to the underlying block device respectively.
553
554 LVM volume groups on the device can be made visible by calling
555 L</guestfs_vgscan> followed by L</guestfs_vg_activate_all>.
556 The logical volume(s) can now be mounted in the usual way.
557
558 Use the reverse process to close a LUKS device.  Unmount
559 any logical volumes on it, deactivate the volume groups
560 by caling C<guestfs_vg_activate (g, 0, ["/dev/VG"])>.
561 Then close the mapper device by calling
562 L</guestfs_luks_close> on the C</dev/mapper/mapname>
563 device (I<not> the underlying encrypted block device).
564
565 =head2 INSPECTION
566
567 Libguestfs has APIs for inspecting an unknown disk image to find out
568 if it contains operating systems, an install CD or a live CD.  (These
569 APIs used to be in a separate Perl-only library called
570 L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most frequently
571 used part of this library has been rewritten in C and moved into the
572 core code).
573
574 Add all disks belonging to the unknown virtual machine and call
575 L</guestfs_launch> in the usual way.
576
577 Then call L</guestfs_inspect_os>.  This function uses other libguestfs
578 calls and certain heuristics, and returns a list of operating systems
579 that were found.  An empty list means none were found.  A single
580 element is the root filesystem of the operating system.  For dual- or
581 multi-boot guests, multiple roots can be returned, each one
582 corresponding to a separate operating system.  (Multi-boot virtual
583 machines are extremely rare in the world of virtualization, but since
584 this scenario can happen, we have built libguestfs to deal with it.)
585
586 For each root, you can then call various C<guestfs_inspect_get_*>
587 functions to get additional details about that operating system.  For
588 example, call L</guestfs_inspect_get_type> to return the string
589 C<windows> or C<linux> for Windows and Linux-based operating systems
590 respectively.
591
592 Un*x-like and Linux-based operating systems usually consist of several
593 filesystems which are mounted at boot time (for example, a separate
594 boot partition mounted on C</boot>).  The inspection rules are able to
595 detect how filesystems correspond to mount points.  Call
596 C<guestfs_inspect_get_mountpoints> to get this mapping.  It might
597 return a hash table like this example:
598
599  /boot => /dev/sda1
600  /     => /dev/vg_guest/lv_root
601  /usr  => /dev/vg_guest/lv_usr
602
603 The caller can then make calls to L</guestfs_mount_options> to
604 mount the filesystems as suggested.
605
606 Be careful to mount filesystems in the right order (eg. C</> before
607 C</usr>).  Sorting the keys of the hash by length, shortest first,
608 should work.
609
610 Inspection currently only works for some common operating systems.
611 Contributors are welcome to send patches for other operating systems
612 that we currently cannot detect.
613
614 Encrypted disks must be opened before inspection.  See
615 L</ENCRYPTED DISKS> for more details.  The L</guestfs_inspect_os>
616 function just ignores any encrypted devices.
617
618 A note on the implementation: The call L</guestfs_inspect_os> performs
619 inspection and caches the results in the guest handle.  Subsequent
620 calls to C<guestfs_inspect_get_*> return this cached information, but
621 I<do not> re-read the disks.  If you change the content of the guest
622 disks, you can redo inspection by calling L</guestfs_inspect_os>
623 again.  (L</guestfs_inspect_list_applications> works a little
624 differently from the other calls and does read the disks.  See
625 documentation for that function for details).
626
627 =head3 INSPECTING INSTALL DISKS
628
629 Libguestfs (since 1.9.4) can detect some install disks, install
630 CDs, live CDs and more.
631
632 Call L</guestfs_inspect_get_format> to return the format of the
633 operating system, which currently can be C<installed> (a regular
634 operating system) or C<installer> (some sort of install disk).
635
636 Further information is available about the operating system that can
637 be installed using the regular inspection APIs like
638 L</guestfs_inspect_get_product_name>,
639 L</guestfs_inspect_get_major_version> etc.
640
641 Some additional information specific to installer disks is also
642 available from the L</guestfs_inspect_is_live>,
643 L</guestfs_inspect_is_netinst> and L</guestfs_inspect_is_multipart>
644 calls.
645
646 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
647
648 Libguestfs can mount NTFS partitions.  It does this using the
649 L<http://www.ntfs-3g.org/> driver.
650
651 =head3 DRIVE LETTERS AND PATHS
652
653 DOS and Windows still use drive letters, and the filesystems are
654 always treated as case insensitive by Windows itself, and therefore
655 you might find a Windows configuration file referring to a path like
656 C<c:\windows\system32>.  When the filesystem is mounted in libguestfs,
657 that directory might be referred to as C</WINDOWS/System32>.
658
659 Drive letter mappings can be found using inspection
660 (see L</INSPECTION> and L</guestfs_inspect_get_drive_mappings>)
661
662 Dealing with separator characters (backslash vs forward slash) is
663 outside the scope of libguestfs, but usually a simple character
664 replacement will work.
665
666 To resolve the case insensitivity of paths, call
667 L</guestfs_case_sensitive_path>.
668
669 =head3 ACCESSING THE WINDOWS REGISTRY
670
671 Libguestfs also provides some help for decoding Windows Registry
672 "hive" files, through the library C<hivex> which is part of the
673 libguestfs project although ships as a separate tarball.  You have to
674 locate and download the hive file(s) yourself, and then pass them to
675 C<hivex> functions.  See also the programs L<hivexml(1)>,
676 L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-reg(1)> for more help
677 on this issue.
678
679 =head3 SYMLINKS ON NTFS-3G FILESYSTEMS
680
681 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links"
682 to provide something which looks like a Linux symlink.  The way it
683 tries to do the rewriting is described here:
684
685 L<http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/>
686
687 The essential problem is that ntfs-3g simply does not have enough
688 information to do a correct job.  NTFS links can contain drive letters
689 and references to external device GUIDs that ntfs-3g has no way of
690 resolving.  It is almost certainly the case that libguestfs callers
691 should ignore what ntfs-3g does (ie. don't use L</guestfs_readlink> on
692 NTFS volumes).
693
694 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
695 L</guestfs_lgetxattr> to read the C<system.ntfs_reparse_data> extended
696 attribute, and read the raw reparse data from that (you can find the
697 format documented in various places around the web).
698
699 =head3 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
700
701 There are other useful extended attributes that can be read from
702 ntfs-3g filesystems (using L</guestfs_getxattr>).  See:
703
704 L<http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/>
705
706 =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
707
708 Although we don't want to discourage you from using the C API, we will
709 mention here that the same API is also available in other languages.
710
711 The API is broadly identical in all supported languages.  This means
712 that the C call C<guestfs_add_drive_ro(g,file)> is
713 C<$g-E<gt>add_drive_ro($file)> in Perl, C<g.add_drive_ro(file)> in Python,
714 and C<g#add_drive_ro file> in OCaml.  In other words, a
715 straightforward, predictable isomorphism between each language.
716
717 Error messages are automatically transformed
718 into exceptions if the language supports it.
719
720 We don't try to "object orientify" parts of the API in OO languages,
721 although contributors are welcome to write higher level APIs above
722 what we provide in their favourite languages if they wish.
723
724 =over 4
725
726 =item B<C++>
727
728 You can use the I<guestfs.h> header file from C++ programs.  The C++
729 API is identical to the C API.  C++ classes and exceptions are not
730 used.
731
732 =item B<C#>
733
734 The C# bindings are highly experimental.  Please read the warnings
735 at the top of C<csharp/Libguestfs.cs>.
736
737 =item B<Erlang>
738
739 See L<guestfs-erlang(3)>.
740
741 =item B<Haskell>
742
743 This is the only language binding that is working but incomplete.
744 Only calls which return simple integers have been bound in Haskell,
745 and we are looking for help to complete this binding.
746
747 =item B<Java>
748
749 Full documentation is contained in the Javadoc which is distributed
750 with libguestfs.  For examples, see L<guestfs-java(3)>.
751
752 =item B<OCaml>
753
754 See L<guestfs-ocaml(3)>.
755
756 =item B<Perl>
757
758 See L<guestfs-perl(3)> and L<Sys::Guestfs(3)>.
759
760 =item B<PHP>
761
762 For documentation see C<README-PHP> supplied with libguestfs
763 sources or in the php-libguestfs package for your distribution.
764
765 The PHP binding only works correctly on 64 bit machines.
766
767 =item B<Python>
768
769 See L<guestfs-python(3)>.
770
771 =item B<Ruby>
772
773 See L<guestfs-ruby(3)>.
774
775 =item B<shell scripts>
776
777 See L<guestfish(1)>.
778
779 =back
780
781 =head2 LIBGUESTFS GOTCHAS
782
783 L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: "A feature of a
784 system [...] that works in the way it is documented but is
785 counterintuitive and almost invites mistakes."
786
787 Since we developed libguestfs and the associated tools, there are
788 several things we would have designed differently, but are now stuck
789 with for backwards compatibility or other reasons.  If there is ever a
790 libguestfs 2.0 release, you can expect these to change.  Beware of
791 them.
792
793 =over 4
794
795 =item Autosync / forgetting to sync.
796
797 I<Update:> Autosync is enabled by default for all API users starting
798 from libguestfs 1.5.24.  This section only applies to older versions.
799
800 When modifying a filesystem from C or another language, you B<must>
801 unmount all filesystems and call L</guestfs_sync> explicitly before
802 you close the libguestfs handle.  You can also call:
803
804  guestfs_set_autosync (g, 1);
805
806 to have the unmount/sync done automatically for you when the handle 'g'
807 is closed.  (This feature is called "autosync", L</guestfs_set_autosync>
808 q.v.)
809
810 If you forget to do this, then it is entirely possible that your
811 changes won't be written out, or will be partially written, or (very
812 rarely) that you'll get disk corruption.
813
814 Note that in L<guestfish(3)> autosync is the default.  So quick and
815 dirty guestfish scripts that forget to sync will work just fine, which
816 can make this very puzzling if you are trying to debug a problem.
817
818 =item Mount option C<-o sync> should not be the default.
819
820 I<Update:> L</guestfs_mount> no longer adds any options starting
821 from libguestfs 1.13.16.  This section only applies to older versions.
822
823 If you use L</guestfs_mount>, then C<-o sync,noatime> are added
824 implicitly.  However C<-o sync> does not add any reliability benefit,
825 but does have a very large performance impact.
826
827 The work around is to use L</guestfs_mount_options> and set the mount
828 options that you actually want to use.
829
830 =item Read-only should be the default.
831
832 In L<guestfish(3)>, I<--ro> should be the default, and you should
833 have to specify I<--rw> if you want to make changes to the image.
834
835 This would reduce the potential to corrupt live VM images.
836
837 Note that many filesystems change the disk when you just mount and
838 unmount, even if you didn't perform any writes.  You need to use
839 L</guestfs_add_drive_ro> to guarantee that the disk is not changed.
840
841 =item guestfish command line is hard to use.
842
843 C<guestfish disk.img> doesn't do what people expect (open C<disk.img>
844 for examination).  It tries to run a guestfish command C<disk.img>
845 which doesn't exist, so it fails.  In earlier versions of guestfish
846 the error message was also unintuitive, but we have corrected this
847 since.  Like the Bourne shell, we should have used C<guestfish -c
848 command> to run commands.
849
850 =item guestfish megabyte modifiers don't work right on all commands
851
852 In recent guestfish you can use C<1M> to mean 1 megabyte (and
853 similarly for other modifiers).  What guestfish actually does is to
854 multiply the number part by the modifier part and pass the result to
855 the C API.  However this doesn't work for a few APIs which aren't
856 expecting bytes, but are already expecting some other unit
857 (eg. megabytes).
858
859 The most common is L</guestfs_lvcreate>.  The guestfish command:
860
861  lvcreate LV VG 100M
862
863 does not do what you might expect.  Instead because
864 L</guestfs_lvcreate> is already expecting megabytes, this tries to
865 create a 100 I<terabyte> (100 megabytes * megabytes) logical volume.
866 The error message you get from this is also a little obscure.
867
868 This could be fixed in the generator by specially marking parameters
869 and return values which take bytes or other units.
870
871 =item Ambiguity between devices and paths
872
873 There is a subtle ambiguity in the API between a device name
874 (eg. C</dev/sdb2>) and a similar pathname.  A file might just happen
875 to be called C<sdb2> in the directory C</dev> (consider some non-Unix
876 VM image).
877
878 In the current API we usually resolve this ambiguity by having two
879 separate calls, for example L</guestfs_checksum> and
880 L</guestfs_checksum_device>.  Some API calls are ambiguous and
881 (incorrectly) resolve the problem by detecting if the path supplied
882 begins with C</dev/>.
883
884 To avoid both the ambiguity and the need to duplicate some calls, we
885 could make paths/devices into structured names.  One way to do this
886 would be to use a notation like grub (C<hd(0,0)>), although nobody
887 really likes this aspect of grub.  Another way would be to use a
888 structured type, equivalent to this OCaml type:
889
890  type path = Path of string | Device of int | Partition of int * int
891
892 which would allow you to pass arguments like:
893
894  Path "/foo/bar"
895  Device 1            (* /dev/sdb, or perhaps /dev/sda *)
896  Partition (1, 2)    (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
897  Path "/dev/sdb2"    (* not a device *)
898
899 As you can see there are still problems to resolve even with this
900 representation.  Also consider how it might work in guestfish.
901
902 =back
903
904 =head2 KEYS AND PASSPHRASES
905
906 Certain libguestfs calls take a parameter that contains sensitive key
907 material, passed in as a C string.
908
909 In the future we would hope to change the libguestfs implementation so
910 that keys are L<mlock(2)>-ed into physical RAM, and thus can never end
911 up in swap.  However this is I<not> done at the moment, because of the
912 complexity of such an implementation.
913
914 Therefore you should be aware that any key parameter you pass to
915 libguestfs might end up being written out to the swap partition.  If
916 this is a concern, scrub the swap partition or don't use libguestfs on
917 encrypted devices.
918
919 =head2 MULTIPLE HANDLES AND MULTIPLE THREADS
920
921 All high-level libguestfs actions are synchronous.  If you want
922 to use libguestfs asynchronously then you must create a thread.
923
924 Only use the handle from a single thread.  Either use the handle
925 exclusively from one thread, or provide your own mutex so that two
926 threads cannot issue calls on the same handle at the same time.
927
928 See the graphical program guestfs-browser for one possible
929 architecture for multithreaded programs using libvirt and libguestfs.
930
931 =head2 PATH
932
933 Libguestfs needs a supermin appliance, which it finds by looking along
934 an internal path.
935
936 By default it looks for these in the directory C<$libdir/guestfs>
937 (eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
938
939 Use L</guestfs_set_path> or set the environment variable
940 L</LIBGUESTFS_PATH> to change the directories that libguestfs will
941 search in.  The value is a colon-separated list of paths.  The current
942 directory is I<not> searched unless the path contains an empty element
943 or C<.>.  For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
944 search the current directory and then C</usr/lib/guestfs>.
945
946 =head2 QEMU WRAPPERS
947
948 If you want to compile your own qemu, run qemu from a non-standard
949 location, or pass extra arguments to qemu, then you can write a
950 shell-script wrapper around qemu.
951
952 There is one important rule to remember: you I<must C<exec qemu>> as
953 the last command in the shell script (so that qemu replaces the shell
954 and becomes the direct child of the libguestfs-using program).  If you
955 don't do this, then the qemu process won't be cleaned up correctly.
956
957 Here is an example of a wrapper, where I have built my own copy of
958 qemu from source:
959
960  #!/bin/sh -
961  qemudir=/home/rjones/d/qemu
962  exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
963
964 Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
965 and then use it by setting the LIBGUESTFS_QEMU environment variable.
966 For example:
967
968  LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
969
970 Note that libguestfs also calls qemu with the -help and -version
971 options in order to determine features.
972
973 Wrappers can also be used to edit the options passed to qemu.  In the
974 following example, the C<-machine ...> option (C<-machine> and the
975 following argument) are removed from the command line and replaced
976 with C<-machine pc,accel=tcg>.  The while loop iterates over the
977 options until it finds the right one to remove, putting the remaining
978 options into the C<args> array.
979
980  #!/bin/bash -
981  
982  i=0
983  while [ $# -gt 0 ]; do
984      case "$1" in
985      -machine)
986          shift 2;;
987      *)
988          args[i]="$1"
989          (( i++ ))
990          shift ;;
991      esac
992  done
993  
994  exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
995
996 =head2 ATTACHING TO RUNNING DAEMONS
997
998 I<Note (1):> This is B<highly experimental> and has a tendency to eat
999 babies.  Use with caution.
1000
1001 I<Note (2):> This section explains how to attach to a running daemon
1002 from a low level perspective.  For most users, simply using virt tools
1003 such as L<guestfish(1)> with the I<--live> option will "just work".
1004
1005 =head3 Using guestfs_set_attach_method
1006
1007 By calling L</guestfs_set_attach_method> you can change how the
1008 library connects to the C<guestfsd> daemon in L</guestfs_launch>
1009 (read L</ARCHITECTURE> for some background).
1010
1011 The normal attach method is C<appliance>, where a small appliance is
1012 created containing the daemon, and then the library connects to this.
1013
1014 Setting attach method to C<unix:I<path>> (where I<path> is the path of
1015 a Unix domain socket) causes L</guestfs_launch> to connect to an
1016 existing daemon over the Unix domain socket.
1017
1018 The normal use for this is to connect to a running virtual machine
1019 that contains a C<guestfsd> daemon, and send commands so you can read
1020 and write files inside the live virtual machine.
1021
1022 =head3 Using guestfs_add_domain with live flag
1023
1024 L</guestfs_add_domain> provides some help for getting the
1025 correct attach method.  If you pass the C<live> option to this
1026 function, then (if the virtual machine is running) it will
1027 examine the libvirt XML looking for a virtio-serial channel
1028 to connect to:
1029
1030  <domain>
1031    ...
1032    <devices>
1033      ...
1034      <channel type='unix'>
1035        <source mode='bind' path='/path/to/socket'/>
1036        <target type='virtio' name='org.libguestfs.channel.0'/>
1037      </channel>
1038      ...
1039    </devices>
1040  </domain>
1041
1042 L</guestfs_add_domain> extracts C</path/to/socket> and sets the attach
1043 method to C<unix:/path/to/socket>.
1044
1045 Some of the libguestfs tools (including guestfish) support a I<--live>
1046 option which is passed through to L</guestfs_add_domain> thus allowing
1047 you to attach to and modify live virtual machines.
1048
1049 The virtual machine needs to have been set up beforehand so that it
1050 has the virtio-serial channel and so that guestfsd is running inside
1051 it.
1052
1053 =head2 ABI GUARANTEE
1054
1055 We guarantee the libguestfs ABI (binary interface), for public,
1056 high-level actions as outlined in this section.  Although we will
1057 deprecate some actions, for example if they get replaced by newer
1058 calls, we will keep the old actions forever.  This allows you the
1059 developer to program in confidence against the libguestfs API.
1060
1061 =head2 BLOCK DEVICE NAMING
1062
1063 In the kernel there is now quite a profusion of schemata for naming
1064 block devices (in this context, by I<block device> I mean a physical
1065 or virtual hard drive).  The original Linux IDE driver used names
1066 starting with C</dev/hd*>.  SCSI devices have historically used a
1067 different naming scheme, C</dev/sd*>.  When the Linux kernel I<libata>
1068 driver became a popular replacement for the old IDE driver
1069 (particularly for SATA devices) those devices also used the
1070 C</dev/sd*> scheme.  Additionally we now have virtual machines with
1071 paravirtualized drivers.  This has created several different naming
1072 systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
1073 PV disks.
1074
1075 As discussed above, libguestfs uses a qemu appliance running an
1076 embedded Linux kernel to access block devices.  We can run a variety
1077 of appliances based on a variety of Linux kernels.
1078
1079 This causes a problem for libguestfs because many API calls use device
1080 or partition names.  Working scripts and the recipe (example) scripts
1081 that we make available over the internet could fail if the naming
1082 scheme changes.
1083
1084 Therefore libguestfs defines C</dev/sd*> as the I<standard naming
1085 scheme>.  Internally C</dev/sd*> names are translated, if necessary,
1086 to other names as required.  For example, under RHEL 5 which uses the
1087 C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
1088 C</dev/hda2> transparently.
1089
1090 Note that this I<only> applies to parameters.  The
1091 L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
1092 return the true names of the devices and partitions as known to the
1093 appliance.
1094
1095 =head3 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
1096
1097 Usually this translation is transparent.  However in some (very rare)
1098 cases you may need to know the exact algorithm.  Such cases include
1099 where you use L</guestfs_config> to add a mixture of virtio and IDE
1100 devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
1101 and C</dev/vd*> devices.
1102
1103 The algorithm is applied only to I<parameters> which are known to be
1104 either device or partition names.  Return values from functions such
1105 as L</guestfs_list_devices> are never changed.
1106
1107 =over 4
1108
1109 =item *
1110
1111 Is the string a parameter which is a device or partition name?
1112
1113 =item *
1114
1115 Does the string begin with C</dev/sd>?
1116
1117 =item *
1118
1119 Does the named device exist?  If so, we use that device.
1120 However if I<not> then we continue with this algorithm.
1121
1122 =item *
1123
1124 Replace initial C</dev/sd> string with C</dev/hd>.
1125
1126 For example, change C</dev/sda2> to C</dev/hda2>.
1127
1128 If that named device exists, use it.  If not, continue.
1129
1130 =item *
1131
1132 Replace initial C</dev/sd> string with C</dev/vd>.
1133
1134 If that named device exists, use it.  If not, return an error.
1135
1136 =back
1137
1138 =head3 PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING
1139
1140 Although the standard naming scheme and automatic translation is
1141 useful for simple programs and guestfish scripts, for larger programs
1142 it is best not to rely on this mechanism.
1143
1144 Where possible for maximum future portability programs using
1145 libguestfs should use these future-proof techniques:
1146
1147 =over 4
1148
1149 =item *
1150
1151 Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list
1152 actual device names, and then use those names directly.
1153
1154 Since those device names exist by definition, they will never be
1155 translated.
1156
1157 =item *
1158
1159 Use higher level ways to identify filesystems, such as LVM names,
1160 UUIDs and filesystem labels.
1161
1162 =back
1163
1164 =head1 SECURITY
1165
1166 This section discusses security implications of using libguestfs,
1167 particularly with untrusted or malicious guests or disk images.
1168
1169 =head2 GENERAL SECURITY CONSIDERATIONS
1170
1171 Be careful with any files or data that you download from a guest (by
1172 "download" we mean not just the L</guestfs_download> command but any
1173 command that reads files, filenames, directories or anything else from
1174 a disk image).  An attacker could manipulate the data to fool your
1175 program into doing the wrong thing.  Consider cases such as:
1176
1177 =over 4
1178
1179 =item *
1180
1181 the data (file etc) not being present
1182
1183 =item *
1184
1185 being present but empty
1186
1187 =item *
1188
1189 being much larger than normal
1190
1191 =item *
1192
1193 containing arbitrary 8 bit data
1194
1195 =item *
1196
1197 being in an unexpected character encoding
1198
1199 =item *
1200
1201 containing homoglyphs.
1202
1203 =back
1204
1205 =head2 SECURITY OF MOUNTING FILESYSTEMS
1206
1207 When you mount a filesystem under Linux, mistakes in the kernel
1208 filesystem (VFS) module can sometimes be escalated into exploits by
1209 deliberately creating a malicious, malformed filesystem.  These
1210 exploits are very severe for two reasons.  Firstly there are very many
1211 filesystem drivers in the kernel, and many of them are infrequently
1212 used and not much developer attention has been paid to the code.
1213 Linux userspace helps potential crackers by detecting the filesystem
1214 type and automatically choosing the right VFS driver, even if that
1215 filesystem type is obscure or unexpected for the administrator.
1216 Secondly, a kernel-level exploit is like a local root exploit (worse
1217 in some ways), giving immediate and total access to the system right
1218 down to the hardware level.
1219
1220 That explains why you should never mount a filesystem from an
1221 untrusted guest on your host kernel.  How about libguestfs?  We run a
1222 Linux kernel inside a qemu virtual machine, usually running as a
1223 non-root user.  The attacker would need to write a filesystem which
1224 first exploited the kernel, and then exploited either qemu
1225 virtualization (eg. a faulty qemu driver) or the libguestfs protocol,
1226 and finally to be as serious as the host kernel exploit it would need
1227 to escalate its privileges to root.  This multi-step escalation,
1228 performed by a static piece of data, is thought to be extremely hard
1229 to do, although we never say 'never' about security issues.
1230
1231 In any case callers can reduce the attack surface by forcing the
1232 filesystem type when mounting (use L</guestfs_mount_vfs>).
1233
1234 =head2 PROTOCOL SECURITY
1235
1236 The protocol is designed to be secure, being based on RFC 4506 (XDR)
1237 with a defined upper message size.  However a program that uses
1238 libguestfs must also take care - for example you can write a program
1239 that downloads a binary from a disk image and executes it locally, and
1240 no amount of protocol security will save you from the consequences.
1241
1242 =head2 INSPECTION SECURITY
1243
1244 Parts of the inspection API (see L</INSPECTION>) return untrusted
1245 strings directly from the guest, and these could contain any 8 bit
1246 data.  Callers should be careful to escape these before printing them
1247 to a structured file (for example, use HTML escaping if creating a web
1248 page).
1249
1250 Guest configuration may be altered in unusual ways by the
1251 administrator of the virtual machine, and may not reflect reality
1252 (particularly for untrusted or actively malicious guests).  For
1253 example we parse the hostname from configuration files like
1254 C</etc/sysconfig/network> that we find in the guest, but the guest
1255 administrator can easily manipulate these files to provide the wrong
1256 hostname.
1257
1258 The inspection API parses guest configuration using two external
1259 libraries: Augeas (Linux configuration) and hivex (Windows Registry).
1260 Both are designed to be robust in the face of malicious data, although
1261 denial of service attacks are still possible, for example with
1262 oversized configuration files.
1263
1264 =head2 RUNNING UNTRUSTED GUEST COMMANDS
1265
1266 Be very cautious about running commands from the guest.  By running a
1267 command in the guest, you are giving CPU time to a binary that you do
1268 not control, under the same user account as the library, albeit
1269 wrapped in qemu virtualization.  More information and alternatives can
1270 be found in the section L</RUNNING COMMANDS>.
1271
1272 =head2 CVE-2010-3851
1273
1274 https://bugzilla.redhat.com/642934
1275
1276 This security bug concerns the automatic disk format detection that
1277 qemu does on disk images.
1278
1279 A raw disk image is just the raw bytes, there is no header.  Other
1280 disk images like qcow2 contain a special header.  Qemu deals with this
1281 by looking for one of the known headers, and if none is found then
1282 assuming the disk image must be raw.
1283
1284 This allows a guest which has been given a raw disk image to write
1285 some other header.  At next boot (or when the disk image is accessed
1286 by libguestfs) qemu would do autodetection and think the disk image
1287 format was, say, qcow2 based on the header written by the guest.
1288
1289 This in itself would not be a problem, but qcow2 offers many features,
1290 one of which is to allow a disk image to refer to another image
1291 (called the "backing disk").  It does this by placing the path to the
1292 backing disk into the qcow2 header.  This path is not validated and
1293 could point to any host file (eg. "/etc/passwd").  The backing disk is
1294 then exposed through "holes" in the qcow2 disk image, which of course
1295 is completely under the control of the attacker.
1296
1297 In libguestfs this is rather hard to exploit except under two
1298 circumstances:
1299
1300 =over 4
1301
1302 =item 1.
1303
1304 You have enabled the network or have opened the disk in write mode.
1305
1306 =item 2.
1307
1308 You are also running untrusted code from the guest (see
1309 L</RUNNING COMMANDS>).
1310
1311 =back
1312
1313 The way to avoid this is to specify the expected disk format when
1314 adding disks (the optional C<format> option to
1315 L</guestfs_add_drive_opts>).  You should always do this if the disk is
1316 raw format, and it's a good idea for other cases too.
1317
1318 For disks added from libvirt using calls like L</guestfs_add_domain>,
1319 the format is fetched from libvirt and passed through.
1320
1321 For libguestfs tools, use the I<--format> command line parameter as
1322 appropriate.
1323
1324 =head1 CONNECTION MANAGEMENT
1325
1326 =head2 guestfs_h *
1327
1328 C<guestfs_h> is the opaque type representing a connection handle.
1329 Create a handle by calling L</guestfs_create>.  Call L</guestfs_close>
1330 to free the handle and release all resources used.
1331
1332 For information on using multiple handles and threads, see the section
1333 L</MULTIPLE HANDLES AND MULTIPLE THREADS> above.
1334
1335 =head2 guestfs_create
1336
1337  guestfs_h *guestfs_create (void);
1338
1339 Create a connection handle.
1340
1341 On success this returns a non-NULL pointer to a handle.  On error it
1342 returns NULL.
1343
1344 You have to "configure" the handle after creating it.  This includes
1345 calling L</guestfs_add_drive_opts> (or one of the equivalent calls) on
1346 the handle at least once.
1347
1348 After configuring the handle, you have to call L</guestfs_launch>.
1349
1350 You may also want to configure error handling for the handle.  See the
1351 L</ERROR HANDLING> section below.
1352
1353 =head2 guestfs_close
1354
1355  void guestfs_close (guestfs_h *g);
1356
1357 This closes the connection handle and frees up all resources used.
1358
1359 If autosync was set on the handle and the handle was launched, then
1360 this implicitly calls various functions to unmount filesystems and
1361 sync the disk.  See L</guestfs_set_autosync> for more details.
1362
1363 If a close callback was set on the handle, then it is called.
1364
1365 =head1 ERROR HANDLING
1366
1367 API functions can return errors.  For example, almost all functions
1368 that return C<int> will return C<-1> to indicate an error.
1369
1370 Additional information is available for errors: an error message
1371 string and optionally an error number (errno) if the thing that failed
1372 was a system call.
1373
1374 You can get at the additional information about the last error on the
1375 handle by calling L</guestfs_last_error>, L</guestfs_last_errno>,
1376 and/or by setting up an error handler with
1377 L</guestfs_set_error_handler>.
1378
1379 When the handle is created, a default error handler is installed which
1380 prints the error message string to C<stderr>.  For small short-running
1381 command line programs it is sufficient to do:
1382
1383  if (guestfs_launch (g) == -1)
1384    exit (EXIT_FAILURE);
1385
1386 since the default error handler will ensure that an error message has
1387 been printed to C<stderr> before the program exits.
1388
1389 For other programs the caller will almost certainly want to install an
1390 alternate error handler or do error handling in-line like this:
1391
1392  /* This disables the default behaviour of printing errors
1393     on stderr. */
1394  guestfs_set_error_handler (g, NULL, NULL);
1395  
1396  if (guestfs_launch (g) == -1) {
1397    /* Examine the error message and print it etc. */
1398    char *msg = guestfs_last_error (g);
1399    int errnum = guestfs_last_errno (g);
1400    fprintf (stderr, "%s", msg);
1401    if (errnum != 0)
1402      fprintf (stderr, ": %s", strerror (errnum));
1403    fprintf (stderr, "\n");
1404    /* ... */
1405  }
1406
1407 Out of memory errors are handled differently.  The default action is
1408 to call L<abort(3)>.  If this is undesirable, then you can set a
1409 handler using L</guestfs_set_out_of_memory_handler>.
1410
1411 L</guestfs_create> returns C<NULL> if the handle cannot be created,
1412 and because there is no handle if this happens there is no way to get
1413 additional error information.  However L</guestfs_create> is supposed
1414 to be a lightweight operation which can only fail because of
1415 insufficient memory (it returns NULL in this case).
1416
1417 =head2 guestfs_last_error
1418
1419  const char *guestfs_last_error (guestfs_h *g);
1420
1421 This returns the last error message that happened on C<g>.  If
1422 there has not been an error since the handle was created, then this
1423 returns C<NULL>.
1424
1425 The lifetime of the returned string is until the next error occurs, or
1426 L</guestfs_close> is called.
1427
1428 =head2 guestfs_last_errno
1429
1430  int guestfs_last_errno (guestfs_h *g);
1431
1432 This returns the last error number (errno) that happened on C<g>.
1433
1434 If successful, an errno integer not equal to zero is returned.
1435
1436 If no error, this returns 0.  This call can return 0 in three
1437 situations:
1438
1439 =over 4
1440
1441 =item 1.
1442
1443 There has not been any error on the handle.
1444
1445 =item 2.
1446
1447 There has been an error but the errno was meaningless.  This
1448 corresponds to the case where the error did not come from a
1449 failed system call, but for some other reason.
1450
1451 =item 3.
1452
1453 There was an error from a failed system call, but for some
1454 reason the errno was not captured and returned.  This usually
1455 indicates a bug in libguestfs.
1456
1457 =back
1458
1459 Libguestfs tries to convert the errno from inside the applicance into
1460 a corresponding errno for the caller (not entirely trivial: the
1461 appliance might be running a completely different operating system
1462 from the library and error numbers are not standardized across
1463 Un*xen).  If this could not be done, then the error is translated to
1464 C<EINVAL>.  In practice this should only happen in very rare
1465 circumstances.
1466
1467 =head2 guestfs_set_error_handler
1468
1469  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1470                                            void *opaque,
1471                                            const char *msg);
1472  void guestfs_set_error_handler (guestfs_h *g,
1473                                  guestfs_error_handler_cb cb,
1474                                  void *opaque);
1475
1476 The callback C<cb> will be called if there is an error.  The
1477 parameters passed to the callback are an opaque data pointer and the
1478 error message string.
1479
1480 C<errno> is not passed to the callback.  To get that the callback must
1481 call L</guestfs_last_errno>.
1482
1483 Note that the message string C<msg> is freed as soon as the callback
1484 function returns, so if you want to stash it somewhere you must make
1485 your own copy.
1486
1487 The default handler prints messages on C<stderr>.
1488
1489 If you set C<cb> to C<NULL> then I<no> handler is called.
1490
1491 =head2 guestfs_get_error_handler
1492
1493  guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1494                                                      void **opaque_rtn);
1495
1496 Returns the current error handler callback.
1497
1498 =head2 guestfs_set_out_of_memory_handler
1499
1500  typedef void (*guestfs_abort_cb) (void);
1501  void guestfs_set_out_of_memory_handler (guestfs_h *g,
1502                                          guestfs_abort_cb);
1503
1504 The callback C<cb> will be called if there is an out of memory
1505 situation.  I<Note this callback must not return>.
1506
1507 The default is to call L<abort(3)>.
1508
1509 You cannot set C<cb> to C<NULL>.  You can't ignore out of memory
1510 situations.
1511
1512 =head2 guestfs_get_out_of_memory_handler
1513
1514  guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1515
1516 This returns the current out of memory handler.
1517
1518 =head1 API CALLS
1519
1520 @ACTIONS@
1521
1522 =head1 STRUCTURES
1523
1524 @STRUCTS@
1525
1526 =head1 AVAILABILITY
1527
1528 =head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
1529
1530 Using L</guestfs_available> you can test availability of
1531 the following groups of functions.  This test queries the
1532 appliance to see if the appliance you are currently using
1533 supports the functionality.
1534
1535 @AVAILABILITY@
1536
1537 =head2 GUESTFISH supported COMMAND
1538
1539 In L<guestfish(3)> there is a handy interactive command
1540 C<supported> which prints out the available groups and
1541 whether they are supported by this build of libguestfs.
1542 Note however that you have to do C<run> first.
1543
1544 =head2 SINGLE CALLS AT COMPILE TIME
1545
1546 Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols
1547 for each C API function, such as:
1548
1549  #define LIBGUESTFS_HAVE_DD 1
1550
1551 if L</guestfs_dd> is available.
1552
1553 Before version 1.5.8, if you needed to test whether a single
1554 libguestfs function is available at compile time, we recommended using
1555 build tools such as autoconf or cmake.  For example in autotools you
1556 could use:
1557
1558  AC_CHECK_LIB([guestfs],[guestfs_create])
1559  AC_CHECK_FUNCS([guestfs_dd])
1560
1561 which would result in C<HAVE_GUESTFS_DD> being either defined
1562 or not defined in your program.
1563
1564 =head2 SINGLE CALLS AT RUN TIME
1565
1566 Testing at compile time doesn't guarantee that a function really
1567 exists in the library.  The reason is that you might be dynamically
1568 linked against a previous I<libguestfs.so> (dynamic library)
1569 which doesn't have the call.  This situation unfortunately results
1570 in a segmentation fault, which is a shortcoming of the C dynamic
1571 linking system itself.
1572
1573 You can use L<dlopen(3)> to test if a function is available
1574 at run time, as in this example program (note that you still
1575 need the compile time check as well):
1576
1577  #include <stdio.h>
1578  #include <stdlib.h>
1579  #include <unistd.h>
1580  #include <dlfcn.h>
1581  #include <guestfs.h>
1582  
1583  main ()
1584  {
1585  #ifdef LIBGUESTFS_HAVE_DD
1586    void *dl;
1587    int has_function;
1588  
1589    /* Test if the function guestfs_dd is really available. */
1590    dl = dlopen (NULL, RTLD_LAZY);
1591    if (!dl) {
1592      fprintf (stderr, "dlopen: %s\n", dlerror ());
1593      exit (EXIT_FAILURE);
1594    }
1595    has_function = dlsym (dl, "guestfs_dd") != NULL;
1596    dlclose (dl);
1597  
1598    if (!has_function)
1599      printf ("this libguestfs.so does NOT have guestfs_dd function\n");
1600    else {
1601      printf ("this libguestfs.so has guestfs_dd function\n");
1602      /* Now it's safe to call
1603      guestfs_dd (g, "foo", "bar");
1604      */
1605    }
1606  #else
1607    printf ("guestfs_dd function was not found at compile time\n");
1608  #endif
1609   }
1610
1611 You may think the above is an awful lot of hassle, and it is.
1612 There are other ways outside of the C linking system to ensure
1613 that this kind of incompatibility never arises, such as using
1614 package versioning:
1615
1616  Requires: libguestfs >= 1.0.80
1617
1618 =head1 CALLS WITH OPTIONAL ARGUMENTS
1619
1620 A recent feature of the API is the introduction of calls which take
1621 optional arguments.  In C these are declared 3 ways.  The main way is
1622 as a call which takes variable arguments (ie. C<...>), as in this
1623 example:
1624
1625  int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
1626
1627 Call this with a list of optional arguments, terminated by C<-1>.
1628 So to call with no optional arguments specified:
1629
1630  guestfs_add_drive_opts (g, filename, -1);
1631
1632 With a single optional argument:
1633
1634  guestfs_add_drive_opts (g, filename,
1635                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
1636                          -1);
1637
1638 With two:
1639
1640  guestfs_add_drive_opts (g, filename,
1641                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
1642                          GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
1643                          -1);
1644
1645 and so forth.  Don't forget the terminating C<-1> otherwise
1646 Bad Things will happen!
1647
1648 =head2 USING va_list FOR OPTIONAL ARGUMENTS
1649
1650 The second variant has the same name with the suffix C<_va>, which
1651 works the same way but takes a C<va_list>.  See the C manual for
1652 details.  For the example function, this is declared:
1653
1654  int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
1655                                 va_list args);
1656
1657 =head2 CONSTRUCTING OPTIONAL ARGUMENTS
1658
1659 The third variant is useful where you need to construct these
1660 calls.  You pass in a structure where you fill in the optional
1661 fields.  The structure has a bitmask as the first element which
1662 you must set to indicate which fields you have filled in.  For
1663 our example function the structure and call are declared:
1664
1665  struct guestfs_add_drive_opts_argv {
1666    uint64_t bitmask;
1667    int readonly;
1668    const char *format;
1669    /* ... */
1670  };
1671  int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
1672               const struct guestfs_add_drive_opts_argv *optargs);
1673
1674 You could call it like this:
1675
1676  struct guestfs_add_drive_opts_argv optargs = {
1677    .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
1678               GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
1679    .readonly = 1,
1680    .format = "qcow2"
1681  };
1682  
1683  guestfs_add_drive_opts_argv (g, filename, &optargs);
1684
1685 Notes:
1686
1687 =over 4
1688
1689 =item *
1690
1691 The C<_BITMASK> suffix on each option name when specifying the
1692 bitmask.
1693
1694 =item *
1695
1696 You do not need to fill in all fields of the structure.
1697
1698 =item *
1699
1700 There must be a one-to-one correspondence between fields of the
1701 structure that are filled in, and bits set in the bitmask.
1702
1703 =back
1704
1705 =head2 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
1706
1707 In other languages, optional arguments are expressed in the
1708 way that is natural for that language.  We refer you to the
1709 language-specific documentation for more details on that.
1710
1711 For guestfish, see L<guestfish(1)/OPTIONAL ARGUMENTS>.
1712
1713 =head2 SETTING CALLBACKS TO HANDLE EVENTS
1714
1715 B<Note:> This section documents the generic event mechanism introduced
1716 in libguestfs 1.10, which you should use in new code if possible.  The
1717 old functions C<guestfs_set_log_message_callback>,
1718 C<guestfs_set_subprocess_quit_callback>,
1719 C<guestfs_set_launch_done_callback>, C<guestfs_set_close_callback> and
1720 C<guestfs_set_progress_callback> are no longer documented in this
1721 manual page.  Because of the ABI guarantee, the old functions continue
1722 to work.
1723
1724 Handles generate events when certain things happen, such as log
1725 messages being generated, progress messages during long-running
1726 operations, or the handle being closed.  The API calls described below
1727 let you register a callback to be called when events happen.  You can
1728 register multiple callbacks (for the same, different or overlapping
1729 sets of events), and individually remove callbacks.  If callbacks are
1730 not removed, then they remain in force until the handle is closed.
1731
1732 In the current implementation, events are only generated
1733 synchronously: that means that events (and hence callbacks) can only
1734 happen while you are in the middle of making another libguestfs call.
1735 The callback is called in the same thread.
1736
1737 Events may contain a payload, usually nothing (void), an array of 64
1738 bit unsigned integers, or a message buffer.  Payloads are discussed
1739 later on.
1740
1741 =head3 CLASSES OF EVENTS
1742
1743 =over 4
1744
1745 =item GUESTFS_EVENT_CLOSE
1746 (payload type: void)
1747
1748 The callback function will be called while the handle is being closed
1749 (synchronously from L</guestfs_close>).
1750
1751 Note that libguestfs installs an L<atexit(3)> handler to try to clean
1752 up handles that are open when the program exits.  This means that this
1753 callback might be called indirectly from L<exit(3)>, which can cause
1754 unexpected problems in higher-level languages (eg. if your HLL
1755 interpreter has already been cleaned up by the time this is called,
1756 and if your callback then jumps into some HLL function).
1757
1758 If no callback is registered: the handle is closed without any
1759 callback being invoked.
1760
1761 =item GUESTFS_EVENT_SUBPROCESS_QUIT
1762 (payload type: void)
1763
1764 The callback function will be called when the child process quits,
1765 either asynchronously or if killed by L</guestfs_kill_subprocess>.
1766 (This corresponds to a transition from any state to the CONFIG state).
1767
1768 If no callback is registered: the event is ignored.
1769
1770 =item GUESTFS_EVENT_LAUNCH_DONE
1771 (payload type: void)
1772
1773 The callback function will be called when the child process becomes
1774 ready first time after it has been launched.  (This corresponds to a
1775 transition from LAUNCHING to the READY state).
1776
1777 If no callback is registered: the event is ignored.
1778
1779 =item GUESTFS_EVENT_PROGRESS
1780 (payload type: array of 4 x uint64_t)
1781
1782 Some long-running operations can generate progress messages.  If
1783 this callback is registered, then it will be called each time a
1784 progress message is generated (usually two seconds after the
1785 operation started, and three times per second thereafter until
1786 it completes, although the frequency may change in future versions).
1787
1788 The callback receives in the payload four unsigned 64 bit numbers
1789 which are (in order): C<proc_nr>, C<serial>, C<position>, C<total>.
1790
1791 The units of C<total> are not defined, although for some
1792 operations C<total> may relate in some way to the amount of
1793 data to be transferred (eg. in bytes or megabytes), and
1794 C<position> may be the portion which has been transferred.
1795
1796 The only defined and stable parts of the API are:
1797
1798 =over 4
1799
1800 =item *
1801
1802 The callback can display to the user some type of progress bar or
1803 indicator which shows the ratio of C<position>:C<total>.
1804
1805 =item *
1806
1807 0 E<lt>= C<position> E<lt>= C<total>
1808
1809 =item *
1810
1811 If any progress notification is sent during a call, then a final
1812 progress notification is always sent when C<position> = C<total>
1813 (I<unless> the call fails with an error).
1814
1815 This is to simplify caller code, so callers can easily set the
1816 progress indicator to "100%" at the end of the operation, without
1817 requiring special code to detect this case.
1818
1819 =item *
1820
1821 For some calls we are unable to estimate the progress of the call, but
1822 we can still generate progress messages to indicate activity.  This is
1823 known as "pulse mode", and is directly supported by certain progress
1824 bar implementations (eg. GtkProgressBar).
1825
1826 For these calls, zero or more progress messages are generated with
1827 C<position = 0> and C<total = 1>, followed by a final message with
1828 C<position = total = 1>.
1829
1830 As noted above, if the call fails with an error then the final message
1831 may not be generated.
1832
1833 =back
1834
1835 The callback also receives the procedure number (C<proc_nr>) and
1836 serial number (C<serial>) of the call.  These are only useful for
1837 debugging protocol issues, and the callback can normally ignore them.
1838 The callback may want to print these numbers in error messages or
1839 debugging messages.
1840
1841 If no callback is registered: progress messages are discarded.
1842
1843 =item GUESTFS_EVENT_APPLIANCE
1844 (payload type: message buffer)
1845
1846 The callback function is called whenever a log message is generated by
1847 qemu, the appliance kernel, guestfsd (daemon), or utility programs.
1848
1849 If the verbose flag (L</guestfs_set_verbose>) is set before launch
1850 (L</guestfs_launch>) then additional debug messages are generated.
1851
1852 If no callback is registered: the messages are discarded unless the
1853 verbose flag is set in which case they are sent to stderr.  You can
1854 override the printing of verbose messages to stderr by setting up a
1855 callback.
1856
1857 =item GUESTFS_EVENT_LIBRARY
1858 (payload type: message buffer)
1859
1860 The callback function is called whenever a log message is generated by
1861 the library part of libguestfs.
1862
1863 If the verbose flag (L</guestfs_set_verbose>) is set then additional
1864 debug messages are generated.
1865
1866 If no callback is registered: the messages are discarded unless the
1867 verbose flag is set in which case they are sent to stderr.  You can
1868 override the printing of verbose messages to stderr by setting up a
1869 callback.
1870
1871 =item GUESTFS_EVENT_TRACE
1872 (payload type: message buffer)
1873
1874 The callback function is called whenever a trace message is generated.
1875 This only applies if the trace flag (L</guestfs_set_trace>) is set.
1876
1877 If no callback is registered: the messages are sent to stderr.  You
1878 can override the printing of trace messages to stderr by setting up a
1879 callback.
1880
1881 =item GUESTFS_EVENT_ENTER
1882 (payload type: function name)
1883
1884 The callback function is called whenever a libguestfs function
1885 is entered.
1886
1887 The payload is a string which contains the name of the function
1888 that we are entering (not including C<guestfs_> prefix).
1889
1890 Note that libguestfs functions can call themselves, so you may
1891 see many events from a single call.  A few libguestfs functions
1892 do not generate this event.
1893
1894 If no callback is registered: the event is ignored.
1895
1896 =back
1897
1898 =head3 guestfs_set_event_callback
1899
1900  int guestfs_set_event_callback (guestfs_h *g,
1901                                  guestfs_event_callback cb,
1902                                  uint64_t event_bitmask,
1903                                  int flags,
1904                                  void *opaque);
1905
1906 This function registers a callback (C<cb>) for all event classes
1907 in the C<event_bitmask>.
1908
1909 For example, to register for all log message events, you could call
1910 this function with the bitmask
1911 C<GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY>.  To register a
1912 single callback for all possible classes of events, use
1913 C<GUESTFS_EVENT_ALL>.
1914
1915 C<flags> should always be passed as 0.
1916
1917 C<opaque> is an opaque pointer which is passed to the callback.  You
1918 can use it for any purpose.
1919
1920 The return value is the event handle (an integer) which you can use to
1921 delete the callback (see below).
1922
1923 If there is an error, this function returns C<-1>, and sets the error
1924 in the handle in the usual way (see L</guestfs_last_error> etc.)
1925
1926 Callbacks remain in effect until they are deleted, or until the handle
1927 is closed.
1928
1929 In the case where multiple callbacks are registered for a particular
1930 event class, all of the callbacks are called.  The order in which
1931 multiple callbacks are called is not defined.
1932
1933 =head3 guestfs_delete_event_callback
1934
1935  void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
1936
1937 Delete a callback that was previously registered.  C<event_handle>
1938 should be the integer that was returned by a previous call to
1939 C<guestfs_set_event_callback> on the same handle.
1940
1941 =head3 guestfs_event_callback
1942
1943  typedef void (*guestfs_event_callback) (
1944                   guestfs_h *g,
1945                   void *opaque,
1946                   uint64_t event,
1947                   int event_handle,
1948                   int flags,
1949                   const char *buf, size_t buf_len,
1950                   const uint64_t *array, size_t array_len);
1951
1952 This is the type of the event callback function that you have to
1953 provide.
1954
1955 The basic parameters are: the handle (C<g>), the opaque user pointer
1956 (C<opaque>), the event class (eg. C<GUESTFS_EVENT_PROGRESS>), the
1957 event handle, and C<flags> which in the current API you should ignore.
1958
1959 The remaining parameters contain the event payload (if any).  Each
1960 event may contain a payload, which usually relates to the event class,
1961 but for future proofing your code should be written to handle any
1962 payload for any event class.
1963
1964 C<buf> and C<buf_len> contain a message buffer (if C<buf_len == 0>,
1965 then there is no message buffer).  Note that this message buffer can
1966 contain arbitrary 8 bit data, including NUL bytes.
1967
1968 C<array> and C<array_len> is an array of 64 bit unsigned integers.  At
1969 the moment this is only used for progress messages.
1970
1971 =head3 EXAMPLE: CAPTURING LOG MESSAGES
1972
1973 One motivation for the generic event API was to allow GUI programs to
1974 capture debug and other messages.  In libguestfs E<le> 1.8 these were
1975 sent unconditionally to C<stderr>.
1976
1977 Events associated with log messages are: C<GUESTFS_EVENT_LIBRARY>,
1978 C<GUESTFS_EVENT_APPLIANCE> and C<GUESTFS_EVENT_TRACE>.  (Note that
1979 error messages are not events; you must capture error messages
1980 separately).
1981
1982 Programs have to set up a callback to capture the classes of events of
1983 interest:
1984
1985  int eh =
1986    guestfs_set_event_callback
1987      (g, message_callback,
1988       GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_APPLIANCE|
1989       GUESTFS_EVENT_TRACE,
1990       0, NULL) == -1)
1991  if (eh == -1) {
1992    // handle error in the usual way
1993  }
1994
1995 The callback can then direct messages to the appropriate place.  In
1996 this example, messages are directed to syslog:
1997
1998  static void
1999  message_callback (
2000          guestfs_h *g,
2001          void *opaque,
2002          uint64_t event,
2003          int event_handle,
2004          int flags,
2005          const char *buf, size_t buf_len,
2006          const uint64_t *array, size_t array_len)
2007  {
2008    const int priority = LOG_USER|LOG_INFO;
2009    if (buf_len > 0)
2010      syslog (priority, "event 0x%lx: %s", event, buf);
2011  }
2012
2013 =head1 CANCELLING LONG TRANSFERS
2014
2015 Some operations can be cancelled by the caller while they are in
2016 progress.  Currently only operations that involve uploading or
2017 downloading data can be cancelled (technically: operations that have
2018 C<FileIn> or C<FileOut> parameters in the generator).
2019
2020 =head2 guestfs_user_cancel
2021
2022  void guestfs_user_cancel (guestfs_h *g);
2023
2024 C<guestfs_user_cancel> cancels the current upload or download
2025 operation.
2026
2027 Unlike most other libguestfs calls, this function is signal safe and
2028 thread safe.  You can call it from a signal handler or from another
2029 thread, without needing to do any locking.
2030
2031 The transfer that was in progress (if there is one) will stop shortly
2032 afterwards, and will return an error.  The errno (see
2033 L</guestfs_last_errno>) is set to C<EINTR>, so you can test for this
2034 to find out if the operation was cancelled or failed because of
2035 another error.
2036
2037 No cleanup is performed: for example, if a file was being uploaded
2038 then after cancellation there may be a partially uploaded file.  It is
2039 the caller's responsibility to clean up if necessary.
2040
2041 There are two common places that you might call C<guestfs_user_cancel>.
2042
2043 In an interactive text-based program, you might call it from a
2044 C<SIGINT> signal handler so that pressing C<^C> cancels the current
2045 operation.  (You also need to call L</guestfs_set_pgroup> so that
2046 child processes don't receive the C<^C> signal).
2047
2048 In a graphical program, when the main thread is displaying a progress
2049 bar with a cancel button, wire up the cancel button to call this
2050 function.
2051
2052 =head1 PRIVATE DATA AREA
2053
2054 You can attach named pieces of private data to the libguestfs handle,
2055 fetch them by name, and walk over them, for the lifetime of the
2056 handle.  This is called the private data area and is only available
2057 from the C API.
2058
2059 To attach a named piece of data, use the following call:
2060
2061  void guestfs_set_private (guestfs_h *g, const char *key, void *data);
2062
2063 C<key> is the name to associate with this data, and C<data> is an
2064 arbitrary pointer (which can be C<NULL>).  Any previous item with the
2065 same key is overwritten.
2066
2067 You can use any C<key> you want, but your key should I<not> start with
2068 an underscore character.  Keys beginning with an underscore character
2069 are reserved for internal libguestfs purposes (eg. for implementing
2070 language bindings).  It is recommended that you prefix the key with
2071 some unique string to avoid collisions with other users.
2072
2073 To retrieve the pointer, use:
2074
2075  void *guestfs_get_private (guestfs_h *g, const char *key);
2076
2077 This function returns C<NULL> if either no data is found associated
2078 with C<key>, or if the user previously set the C<key>'s C<data>
2079 pointer to C<NULL>.
2080
2081 Libguestfs does not try to look at or interpret the C<data> pointer in
2082 any way.  As far as libguestfs is concerned, it need not be a valid
2083 pointer at all.  In particular, libguestfs does I<not> try to free the
2084 data when the handle is closed.  If the data must be freed, then the
2085 caller must either free it before calling L</guestfs_close> or must
2086 set up a close callback to do it (see L</GUESTFS_EVENT_CLOSE>).
2087
2088 To walk over all entries, use these two functions:
2089
2090  void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
2091
2092  void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
2093
2094 C<guestfs_first_private> returns the first key, pointer pair ("first"
2095 does not have any particular meaning -- keys are not returned in any
2096 defined order).  A pointer to the key is returned in C<*key_rtn> and
2097 the corresponding data pointer is returned from the function.  C<NULL>
2098 is returned if there are no keys stored in the handle.
2099
2100 C<guestfs_next_private> returns the next key, pointer pair.  The
2101 return value of this function is also C<NULL> is there are no further
2102 entries to return.
2103
2104 Notes about walking over entries:
2105
2106 =over 4
2107
2108 =item *
2109
2110 You must not call C<guestfs_set_private> while walking over the
2111 entries.
2112
2113 =item *
2114
2115 The handle maintains an internal iterator which is reset when you call
2116 C<guestfs_first_private>.  This internal iterator is invalidated when
2117 you call C<guestfs_set_private>.
2118
2119 =item *
2120
2121 If you have set the data pointer associated with a key to C<NULL>, ie:
2122
2123  guestfs_set_private (g, key, NULL);
2124
2125 then that C<key> is not returned when walking.
2126
2127 =item *
2128
2129 C<*key_rtn> is only valid until the next call to
2130 C<guestfs_first_private>, C<guestfs_next_private> or
2131 C<guestfs_set_private>.
2132
2133 =back
2134
2135 The following example code shows how to print all keys and data
2136 pointers that are associated with the handle C<g>:
2137
2138  const char *key;
2139  void *data = guestfs_first_private (g, &key);
2140  while (data != NULL)
2141    {
2142      printf ("key = %s, data = %p\n", key, data);
2143      data = guestfs_next_private (g, &key);
2144    }
2145
2146 More commonly you are only interested in keys that begin with an
2147 application-specific prefix C<foo_>.  Modify the loop like so:
2148
2149  const char *key;
2150  void *data = guestfs_first_private (g, &key);
2151  while (data != NULL)
2152    {
2153      if (strncmp (key, "foo_", strlen ("foo_")) == 0)
2154        printf ("key = %s, data = %p\n", key, data);
2155      data = guestfs_next_private (g, &key);
2156    }
2157
2158 If you need to modify keys while walking, then you have to jump back
2159 to the beginning of the loop.  For example, to delete all keys
2160 prefixed with C<foo_>:
2161
2162   const char *key;
2163   void *data;
2164  again:
2165   data = guestfs_first_private (g, &key);
2166   while (data != NULL)
2167     {
2168       if (strncmp (key, "foo_", strlen ("foo_")) == 0)
2169         {
2170           guestfs_set_private (g, key, NULL);
2171           /* note that 'key' pointer is now invalid, and so is
2172              the internal iterator */
2173           goto again;
2174         }
2175       data = guestfs_next_private (g, &key);
2176     }
2177
2178 Note that the above loop is guaranteed to terminate because the keys
2179 are being deleted, but other manipulations of keys within the loop
2180 might not terminate unless you also maintain an indication of which
2181 keys have been visited.
2182
2183 =head1 SYSTEMTAP
2184
2185 The libguestfs C library can be probed using systemtap or DTrace.
2186 This is true of any library, not just libguestfs.  However libguestfs
2187 also contains static markers to help in probing internal operations.
2188
2189 You can list all the static markers by doing:
2190
2191  stap -l 'process("/usr/lib*/libguestfs.so.0")
2192               .provider("guestfs").mark("*")'
2193
2194 B<Note:> These static markers are I<not> part of the stable API and
2195 may change in future versions.
2196
2197 =head2 SYSTEMTAP SCRIPT EXAMPLE
2198
2199 This script contains examples of displaying both the static markers
2200 and some ordinary C entry points:
2201
2202  global last;
2203  
2204  function display_time () {
2205        now = gettimeofday_us ();
2206        delta = 0;
2207        if (last > 0)
2208              delta = now - last;
2209        last = now;
2210  
2211        printf ("%d (+%d):", now, delta);
2212  }
2213  
2214  probe begin {
2215        last = 0;
2216        printf ("ready\n");
2217  }
2218  
2219  /* Display all calls to static markers. */
2220  probe process("/usr/lib*/libguestfs.so.0")
2221            .provider("guestfs").mark("*") ? {
2222        display_time();
2223        printf ("\t%s %s\n", $$name, $$parms);
2224  }
2225  
2226  /* Display all calls to guestfs_mkfs* functions. */
2227  probe process("/usr/lib*/libguestfs.so.0")
2228            .function("guestfs_mkfs*") ? {
2229        display_time();
2230        printf ("\t%s %s\n", probefunc(), $$parms);
2231  }
2232
2233 The script above can be saved to C<test.stap> and run using the
2234 L<stap(1)> program.  Note that you either have to be root, or you have
2235 to add yourself to several special stap groups.  Consult the systemtap
2236 documentation for more information.
2237
2238  # stap /tmp/test.stap
2239  ready
2240
2241 In another terminal, run a guestfish command such as this:
2242
2243  guestfish -N fs
2244
2245 In the first terminal, stap trace output similar to this is shown:
2246
2247  1318248056692655 (+0): launch_start
2248  1318248056692850 (+195):       launch_build_appliance_start
2249  1318248056818285 (+125435):    launch_build_appliance_end
2250  1318248056838059 (+19774):     launch_run_qemu
2251  1318248061071167 (+4233108):   launch_end
2252  1318248061280324 (+209157):    guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
2253
2254 =begin html
2255
2256 <!-- old anchor for the next section -->
2257 <a name="state_machine_and_low_level_event_api"/>
2258
2259 =end html
2260
2261 =head1 ARCHITECTURE
2262
2263 Internally, libguestfs is implemented by running an appliance (a
2264 special type of small virtual machine) using L<qemu(1)>.  Qemu runs as
2265 a child process of the main program.
2266
2267   ___________________
2268  /                   \
2269  | main program      |
2270  |                   |
2271  |                   |           child process / appliance
2272  |                   |           __________________________
2273  |                   |          / qemu                     \
2274  +-------------------+   RPC    |      +-----------------+ |
2275  | libguestfs     <--------------------> guestfsd        | |
2276  |                   |          |      +-----------------+ |
2277  \___________________/          |      | Linux kernel    | |
2278                                 |      +--^--------------+ |
2279                                 \_________|________________/
2280                                           |
2281                                    _______v______
2282                                   /              \
2283                                   | Device or    |
2284                                   | disk image   |
2285                                   \______________/
2286
2287 The library, linked to the main program, creates the child process and
2288 hence the appliance in the L</guestfs_launch> function.
2289
2290 Inside the appliance is a Linux kernel and a complete stack of
2291 userspace tools (such as LVM and ext2 programs) and a small
2292 controlling daemon called L</guestfsd>.  The library talks to
2293 L</guestfsd> using remote procedure calls (RPC).  There is a mostly
2294 one-to-one correspondence between libguestfs API calls and RPC calls
2295 to the daemon.  Lastly the disk image(s) are attached to the qemu
2296 process which translates device access by the appliance's Linux kernel
2297 into accesses to the image.
2298
2299 A common misunderstanding is that the appliance "is" the virtual
2300 machine.  Although the disk image you are attached to might also be
2301 used by some virtual machine, libguestfs doesn't know or care about
2302 this.  (But you will care if both libguestfs's qemu process and your
2303 virtual machine are trying to update the disk image at the same time,
2304 since these usually results in massive disk corruption).
2305
2306 =head1 STATE MACHINE
2307
2308 libguestfs uses a state machine to model the child process:
2309
2310                          |
2311                     guestfs_create
2312                          |
2313                          |
2314                      ____V_____
2315                     /          \
2316                     |  CONFIG  |
2317                     \__________/
2318                      ^ ^   ^  \
2319                     /  |    \  \ guestfs_launch
2320                    /   |    _\__V______
2321                   /    |   /           \
2322                  /     |   | LAUNCHING |
2323                 /      |   \___________/
2324                /       |       /
2325               /        |  guestfs_launch
2326              /         |     /
2327     ______  /        __|____V
2328    /      \ ------> /        \
2329    | BUSY |         | READY  |
2330    \______/ <------ \________/
2331
2332 The normal transitions are (1) CONFIG (when the handle is created, but
2333 there is no child process), (2) LAUNCHING (when the child process is
2334 booting up), (3) alternating between READY and BUSY as commands are
2335 issued to, and carried out by, the child process.
2336
2337 The guest may be killed by L</guestfs_kill_subprocess>, or may die
2338 asynchronously at any time (eg. due to some internal error), and that
2339 causes the state to transition back to CONFIG.
2340
2341 Configuration commands for qemu such as L</guestfs_add_drive> can only
2342 be issued when in the CONFIG state.
2343
2344 The API offers one call that goes from CONFIG through LAUNCHING to
2345 READY.  L</guestfs_launch> blocks until the child process is READY to
2346 accept commands (or until some failure or timeout).
2347 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
2348 while it is running.
2349
2350 API actions such as L</guestfs_mount> can only be issued when in the
2351 READY state.  These API calls block waiting for the command to be
2352 carried out (ie. the state to transition to BUSY and then back to
2353 READY).  There are no non-blocking versions, and no way to issue more
2354 than one command per handle at the same time.
2355
2356 Finally, the child process sends asynchronous messages back to the
2357 main program, such as kernel log messages.  You can register a
2358 callback to receive these messages.
2359
2360 =head1 INTERNALS
2361
2362 =head2 APPLIANCE BOOT PROCESS
2363
2364 This process has evolved and continues to evolve.  The description
2365 here corresponds only to the current version of libguestfs and is
2366 provided for information only.
2367
2368 In order to follow the stages involved below, enable libguestfs
2369 debugging (set the environment variable C<LIBGUESTFS_DEBUG=1>).
2370
2371 =over 4
2372
2373 =item Create the appliance
2374
2375 C<febootstrap-supermin-helper> is invoked to create the kernel, a
2376 small initrd and the appliance.
2377
2378 The appliance is cached in C</var/tmp/.guestfs-E<lt>UIDE<gt>> (or in
2379 another directory if C<TMPDIR> is set).
2380
2381 For a complete description of how the appliance is created and cached,
2382 read the L<febootstrap(8)> and L<febootstrap-supermin-helper(8)> man
2383 pages.
2384
2385 =item Start qemu and boot the kernel
2386
2387 qemu is invoked to boot the kernel.
2388
2389 =item Run the initrd
2390
2391 C<febootstrap-supermin-helper> builds a small initrd.  The initrd is
2392 not the appliance.  The purpose of the initrd is to load enough kernel
2393 modules in order that the appliance itself can be mounted and started.
2394
2395 The initrd is a cpio archive called
2396 C</var/tmp/.guestfs-E<lt>UIDE<gt>/initrd>.
2397
2398 When the initrd has started you will see messages showing that kernel
2399 modules are being loaded, similar to this:
2400
2401  febootstrap: ext2 mini initrd starting up
2402  febootstrap: mounting /sys
2403  febootstrap: internal insmod libcrc32c.ko
2404  febootstrap: internal insmod crc32c-intel.ko
2405
2406 =item Find and mount the appliance device
2407
2408 The appliance is a sparse file containing an ext2 filesystem which
2409 contains a familiar (although reduced in size) Linux operating system.
2410 It would normally be called C</var/tmp/.guestfs-E<lt>UIDE<gt>/root>.
2411
2412 The regular disks being inspected by libguestfs are the first
2413 devices exposed by qemu (eg. as C</dev/vda>).
2414
2415 The last disk added to qemu is the appliance itself (eg. C</dev/vdb>
2416 if there was only one regular disk).
2417
2418 Thus the final job of the initrd is to locate the appliance disk,
2419 mount it, and switch root into the appliance, and run C</init> from
2420 the appliance.
2421
2422 If this works successfully you will see messages such as:
2423
2424  febootstrap: picked /sys/block/vdb/dev as root device
2425  febootstrap: creating /dev/root as block special 252:16
2426  febootstrap: mounting new root on /root
2427  febootstrap: chroot
2428  Starting /init script ...
2429
2430 Note that C<Starting /init script ...> indicates that the appliance's
2431 init script is now running.
2432
2433 =item Initialize the appliance
2434
2435 The appliance itself now initializes itself.  This involves starting
2436 certain processes like C<udev>, possibly printing some debug
2437 information, and finally running the daemon (C<guestfsd>).
2438
2439 =item The daemon
2440
2441 Finally the daemon (C<guestfsd>) runs inside the appliance.  If it
2442 runs you should see:
2443
2444  verbose daemon enabled
2445
2446 The daemon expects to see a named virtio-serial port exposed by qemu
2447 and connected on the other end to the library.
2448
2449 The daemon connects to this port (and hence to the library) and sends
2450 a four byte message C<GUESTFS_LAUNCH_FLAG>, which initiates the
2451 communication protocol (see below).
2452
2453 =back
2454
2455 =head2 COMMUNICATION PROTOCOL
2456
2457 Don't rely on using this protocol directly.  This section documents
2458 how it currently works, but it may change at any time.
2459
2460 The protocol used to talk between the library and the daemon running
2461 inside the qemu virtual machine is a simple RPC mechanism built on top
2462 of XDR (RFC 1014, RFC 1832, RFC 4506).
2463
2464 The detailed format of structures is in C<src/guestfs_protocol.x>
2465 (note: this file is automatically generated).
2466
2467 There are two broad cases, ordinary functions that don't have any
2468 C<FileIn> and C<FileOut> parameters, which are handled with very
2469 simple request/reply messages.  Then there are functions that have any
2470 C<FileIn> or C<FileOut> parameters, which use the same request and
2471 reply messages, but they may also be followed by files sent using a
2472 chunked encoding.
2473
2474 =head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)
2475
2476 For ordinary functions, the request message is:
2477
2478  total length (header + arguments,
2479       but not including the length word itself)
2480  struct guestfs_message_header (encoded as XDR)
2481  struct guestfs_<foo>_args (encoded as XDR)
2482
2483 The total length field allows the daemon to allocate a fixed size
2484 buffer into which it slurps the rest of the message.  As a result, the
2485 total length is limited to C<GUESTFS_MESSAGE_MAX> bytes (currently
2486 4MB), which means the effective size of any request is limited to
2487 somewhere under this size.
2488
2489 Note also that many functions don't take any arguments, in which case
2490 the C<guestfs_I<foo>_args> is completely omitted.
2491
2492 The header contains the procedure number (C<guestfs_proc>) which is
2493 how the receiver knows what type of args structure to expect, or none
2494 at all.
2495
2496 For functions that take optional arguments, the optional arguments are
2497 encoded in the C<guestfs_I<foo>_args> structure in the same way as
2498 ordinary arguments.  A bitmask in the header indicates which optional
2499 arguments are meaningful.  The bitmask is also checked to see if it
2500 contains bits set which the daemon does not know about (eg. if more
2501 optional arguments were added in a later version of the library), and
2502 this causes the call to be rejected.
2503
2504 The reply message for ordinary functions is:
2505
2506  total length (header + ret,
2507       but not including the length word itself)
2508  struct guestfs_message_header (encoded as XDR)
2509  struct guestfs_<foo>_ret (encoded as XDR)
2510
2511 As above the C<guestfs_I<foo>_ret> structure may be completely omitted
2512 for functions that return no formal return values.
2513
2514 As above the total length of the reply is limited to
2515 C<GUESTFS_MESSAGE_MAX>.
2516
2517 In the case of an error, a flag is set in the header, and the reply
2518 message is slightly changed:
2519
2520  total length (header + error,
2521       but not including the length word itself)
2522  struct guestfs_message_header (encoded as XDR)
2523  struct guestfs_message_error (encoded as XDR)
2524
2525 The C<guestfs_message_error> structure contains the error message as a
2526 string.
2527
2528 =head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS
2529
2530 A C<FileIn> parameter indicates that we transfer a file I<into> the
2531 guest.  The normal request message is sent (see above).  However this
2532 is followed by a sequence of file chunks.
2533
2534  total length (header + arguments,
2535       but not including the length word itself,
2536       and not including the chunks)
2537  struct guestfs_message_header (encoded as XDR)
2538  struct guestfs_<foo>_args (encoded as XDR)
2539  sequence of chunks for FileIn param #0
2540  sequence of chunks for FileIn param #1 etc.
2541
2542 The "sequence of chunks" is:
2543
2544  length of chunk (not including length word itself)
2545  struct guestfs_chunk (encoded as XDR)
2546  length of chunk
2547  struct guestfs_chunk (encoded as XDR)
2548    ...
2549  length of chunk
2550  struct guestfs_chunk (with data.data_len == 0)
2551
2552 The final chunk has the C<data_len> field set to zero.  Additionally a
2553 flag is set in the final chunk to indicate either successful
2554 completion or early cancellation.
2555
2556 At time of writing there are no functions that have more than one
2557 FileIn parameter.  However this is (theoretically) supported, by
2558 sending the sequence of chunks for each FileIn parameter one after
2559 another (from left to right).
2560
2561 Both the library (sender) I<and> the daemon (receiver) may cancel the
2562 transfer.  The library does this by sending a chunk with a special
2563 flag set to indicate cancellation.  When the daemon sees this, it
2564 cancels the whole RPC, does I<not> send any reply, and goes back to
2565 reading the next request.
2566
2567 The daemon may also cancel.  It does this by writing a special word
2568 C<GUESTFS_CANCEL_FLAG> to the socket.  The library listens for this
2569 during the transfer, and if it gets it, it will cancel the transfer
2570 (it sends a cancel chunk).  The special word is chosen so that even if
2571 cancellation happens right at the end of the transfer (after the
2572 library has finished writing and has started listening for the reply),
2573 the "spurious" cancel flag will not be confused with the reply
2574 message.
2575
2576 This protocol allows the transfer of arbitrary sized files (no 32 bit
2577 limit), and also files where the size is not known in advance
2578 (eg. from pipes or sockets).  However the chunks are rather small
2579 (C<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the
2580 daemon need to keep much in memory.
2581
2582 =head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS
2583
2584 The protocol for FileOut parameters is exactly the same as for FileIn
2585 parameters, but with the roles of daemon and library reversed.
2586
2587  total length (header + ret,
2588       but not including the length word itself,
2589       and not including the chunks)
2590  struct guestfs_message_header (encoded as XDR)
2591  struct guestfs_<foo>_ret (encoded as XDR)
2592  sequence of chunks for FileOut param #0
2593  sequence of chunks for FileOut param #1 etc.
2594
2595 =head3 INITIAL MESSAGE
2596
2597 When the daemon launches it sends an initial word
2598 (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest and daemon is
2599 alive.  This is what L</guestfs_launch> waits for.
2600
2601 =head3 PROGRESS NOTIFICATION MESSAGES
2602
2603 The daemon may send progress notification messages at any time.  These
2604 are distinguished by the normal length word being replaced by
2605 C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message.
2606
2607 The library turns them into progress callbacks (see
2608 L</GUESTFS_EVENT_PROGRESS>) if there is a callback registered, or
2609 discards them if not.
2610
2611 The daemon self-limits the frequency of progress messages it sends
2612 (see C<daemon/proto.c:notify_progress>).  Not all calls generate
2613 progress messages.
2614
2615 =head1 LIBGUESTFS VERSION NUMBERS
2616
2617 Since April 2010, libguestfs has started to make separate development
2618 and stable releases, along with corresponding branches in our git
2619 repository.  These separate releases can be identified by version
2620 number:
2621
2622                  even numbers for stable: 1.2.x, 1.4.x, ...
2623        .-------- odd numbers for development: 1.3.x, 1.5.x, ...
2624        |
2625        v
2626  1  .  3  .  5
2627  ^           ^
2628  |           |
2629  |           `-------- sub-version
2630  |
2631  `------ always '1' because we don't change the ABI
2632
2633 Thus "1.3.5" is the 5th update to the development branch "1.3".
2634
2635 As time passes we cherry pick fixes from the development branch and
2636 backport those into the stable branch, the effect being that the
2637 stable branch should get more stable and less buggy over time.  So the
2638 stable releases are ideal for people who don't need new features but
2639 would just like the software to work.
2640
2641 Our criteria for backporting changes are:
2642
2643 =over 4
2644
2645 =item *
2646
2647 Documentation changes which don't affect any code are
2648 backported unless the documentation refers to a future feature
2649 which is not in stable.
2650
2651 =item *
2652
2653 Bug fixes which are not controversial, fix obvious problems, and
2654 have been well tested are backported.
2655
2656 =item *
2657
2658 Simple rearrangements of code which shouldn't affect how it works get
2659 backported.  This is so that the code in the two branches doesn't get
2660 too far out of step, allowing us to backport future fixes more easily.
2661
2662 =item *
2663
2664 We I<don't> backport new features, new APIs, new tools etc, except in
2665 one exceptional case: the new feature is required in order to
2666 implement an important bug fix.
2667
2668 =back
2669
2670 A new stable branch starts when we think the new features in
2671 development are substantial and compelling enough over the current
2672 stable branch to warrant it.  When that happens we create new stable
2673 and development versions 1.N.0 and 1.(N+1).0 [N is even].  The new
2674 dot-oh release won't necessarily be so stable at this point, but by
2675 backporting fixes from development, that branch will stabilize over
2676 time.
2677
2678 =head1 EXTENDING LIBGUESTFS
2679
2680 =head2 ADDING A NEW API ACTION
2681
2682 Large amounts of boilerplate code in libguestfs (RPC, bindings,
2683 documentation) are generated, and this makes it easy to extend the
2684 libguestfs API.
2685
2686 To add a new API action there are two changes:
2687
2688 =over 4
2689
2690 =item 1.
2691
2692 You need to add a description of the call (name, parameters, return
2693 type, tests, documentation) to C<generator/generator_actions.ml>.
2694
2695 There are two sorts of API action, depending on whether the call goes
2696 through to the daemon in the appliance, or is serviced entirely by the
2697 library (see L</ARCHITECTURE> above).  L</guestfs_sync> is an example
2698 of the former, since the sync is done in the appliance.
2699 L</guestfs_set_trace> is an example of the latter, since a trace flag
2700 is maintained in the handle and all tracing is done on the library
2701 side.
2702
2703 Most new actions are of the first type, and get added to the
2704 C<daemon_functions> list.  Each function has a unique procedure number
2705 used in the RPC protocol which is assigned to that action when we
2706 publish libguestfs and cannot be reused.  Take the latest procedure
2707 number and increment it.
2708
2709 For library-only actions of the second type, add to the
2710 C<non_daemon_functions> list.  Since these functions are serviced by
2711 the library and do not travel over the RPC mechanism to the daemon,
2712 these functions do not need a procedure number, and so the procedure
2713 number is set to C<-1>.
2714
2715 =item 2.
2716
2717 Implement the action (in C):
2718
2719 For daemon actions, implement the function C<do_E<lt>nameE<gt>> in the
2720 C<daemon/> directory.
2721
2722 For library actions, implement the function C<guestfs__E<lt>nameE<gt>>
2723 (note: double underscore) in the C<src/> directory.
2724
2725 In either case, use another function as an example of what to do.
2726
2727 =back
2728
2729 After making these changes, use C<make> to compile.
2730
2731 Note that you don't need to implement the RPC, language bindings,
2732 manual pages or anything else.  It's all automatically generated from
2733 the OCaml description.
2734
2735 =head2 ADDING TESTS FOR AN API ACTION
2736
2737 You can supply zero or as many tests as you want per API call.  The
2738 tests can either be added as part of the API description
2739 (C<generator/generator_actions.ml>), or in some rarer cases you may
2740 want to drop a script into C<tests/*/>.  Note that adding
2741 a script to C<tests/*/> is slower, so if possible use the
2742 first method.
2743
2744 The following describes the test environment used when you add an API
2745 test in C<generator_actions.ml>.
2746
2747 The test environment has 4 block devices:
2748
2749 =over 4
2750
2751 =item C</dev/sda> 500MB
2752
2753 General block device for testing.
2754
2755 =item C</dev/sdb> 50MB
2756
2757 C</dev/sdb1> is an ext2 filesystem used for testing
2758 filesystem write operations.
2759
2760 =item C</dev/sdc> 10MB
2761
2762 Used in a few tests where two block devices are needed.
2763
2764 =item C</dev/sdd>
2765
2766 ISO with fixed content (see C<images/test.iso>).
2767
2768 =back
2769
2770 To be able to run the tests in a reasonable amount of time, the
2771 libguestfs appliance and block devices are reused between tests.  So
2772 don't try testing L</guestfs_kill_subprocess> :-x
2773
2774 Each test starts with an initial scenario, selected using one of the
2775 C<Init*> expressions, described in C<generator/generator_types.ml>.
2776 These initialize the disks mentioned above in a particular way as
2777 documented in C<generator_types.ml>.  You should not assume anything
2778 about the previous contents of other disks that are not initialized.
2779
2780 You can add a prerequisite clause to any individual test.  This is a
2781 run-time check, which, if it fails, causes the test to be skipped.
2782 Useful if testing a command which might not work on all variations of
2783 libguestfs builds.  A test that has prerequisite of C<Always> means to
2784 run unconditionally.
2785
2786 In addition, packagers can skip individual tests by setting
2787 environment variables before running C<make check>.
2788
2789  SKIP_TEST_<CMD>_<NUM>=1
2790
2791 eg: C<SKIP_TEST_COMMAND_3=1> skips test #3 of L</guestfs_command>.
2792
2793 or:
2794
2795  SKIP_TEST_<CMD>=1
2796
2797 eg: C<SKIP_TEST_ZEROFREE=1> skips all L</guestfs_zerofree> tests.
2798
2799 Packagers can run only certain tests by setting for example:
2800
2801  TEST_ONLY="vfs_type zerofree"
2802
2803 See C<tests/c-api/tests.c> for more details of how these environment
2804 variables work.
2805
2806 =head2 DEBUGGING NEW API ACTIONS
2807
2808 Test new actions work before submitting them.
2809
2810 You can use guestfish to try out new commands.
2811
2812 Debugging the daemon is a problem because it runs inside a minimal
2813 environment.  However you can fprintf messages in the daemon to
2814 stderr, and they will show up if you use C<guestfish -v>.
2815
2816 =head2 FORMATTING CODE AND OTHER CONVENTIONS
2817
2818 Our C source code generally adheres to some basic code-formatting
2819 conventions.  The existing code base is not totally consistent on this
2820 front, but we do prefer that contributed code be formatted similarly.
2821 In short, use spaces-not-TABs for indentation, use 2 spaces for each
2822 indentation level, and other than that, follow the K&R style.
2823
2824 If you use Emacs, add the following to one of one of your start-up files
2825 (e.g., ~/.emacs), to help ensure that you get indentation right:
2826
2827  ;;; In libguestfs, indent with spaces everywhere (not TABs).
2828  ;;; Exceptions: Makefile and ChangeLog modes.
2829  (add-hook 'find-file-hook
2830      '(lambda () (if (and buffer-file-name
2831                           (string-match "/libguestfs\\>"
2832                               (buffer-file-name))
2833                           (not (string-equal mode-name "Change Log"))
2834                           (not (string-equal mode-name "Makefile")))
2835                      (setq indent-tabs-mode nil))))
2836  
2837  ;;; When editing C sources in libguestfs, use this style.
2838  (defun libguestfs-c-mode ()
2839    "C mode with adjusted defaults for use with libguestfs."
2840    (interactive)
2841    (c-set-style "K&R")
2842    (setq c-indent-level 2)
2843    (setq c-basic-offset 2))
2844  (add-hook 'c-mode-hook
2845            '(lambda () (if (string-match "/libguestfs\\>"
2846                                (buffer-file-name))
2847                            (libguestfs-c-mode))))
2848
2849 Enable warnings when compiling (and fix any problems this
2850 finds):
2851
2852  ./configure --enable-gcc-warnings
2853
2854 Useful targets are:
2855
2856  make syntax-check  # checks the syntax of the C code
2857  make check         # runs the test suite
2858
2859 =head2 DAEMON CUSTOM PRINTF FORMATTERS
2860
2861 In the daemon code we have created custom printf formatters C<%Q> and
2862 C<%R>, which are used to do shell quoting.
2863
2864 =over 4
2865
2866 =item %Q
2867
2868 Simple shell quoted string.  Any spaces or other shell characters are
2869 escaped for you.
2870
2871 =item %R
2872
2873 Same as C<%Q> except the string is treated as a path which is prefixed
2874 by the sysroot.
2875
2876 =back
2877
2878 For example:
2879
2880  asprintf (&cmd, "cat %R", path);
2881
2882 would produce C<cat /sysroot/some\ path\ with\ spaces>
2883
2884 I<Note:> Do I<not> use these when you are passing parameters to the
2885 C<command{,r,v,rv}()> functions.  These parameters do NOT need to be
2886 quoted because they are not passed via the shell (instead, straight to
2887 exec).  You probably want to use the C<sysroot_path()> function
2888 however.
2889
2890 =head2 SUBMITTING YOUR NEW API ACTIONS
2891
2892 Submit patches to the mailing list:
2893 L<http://www.redhat.com/mailman/listinfo/libguestfs>
2894 and CC to L<rjones@redhat.com>.
2895
2896 =head2 INTERNATIONALIZATION (I18N) SUPPORT
2897
2898 We support i18n (gettext anyhow) in the library.
2899
2900 However many messages come from the daemon, and we don't translate
2901 those at the moment.  One reason is that the appliance generally has
2902 all locale files removed from it, because they take up a lot of space.
2903 So we'd have to readd some of those, as well as copying our PO files
2904 into the appliance.
2905
2906 Debugging messages are never translated, since they are intended for
2907 the programmers.
2908
2909 =head2 SOURCE CODE SUBDIRECTORIES
2910
2911 =over 4
2912
2913 =item C<align>
2914
2915 L<virt-alignment-scan(1)> command and documentation.
2916
2917 =item C<appliance>
2918
2919 The libguestfs appliance, build scripts and so on.
2920
2921 =item C<cat>
2922
2923 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
2924 and documentation.
2925
2926 =item C<clone>
2927
2928 Tools for cloning virtual machines.  Currently contains
2929 L<virt-sysprep(1)> command and documentation.
2930
2931 =item C<contrib>
2932
2933 Outside contributions, experimental parts.
2934
2935 =item C<daemon>
2936
2937 The daemon that runs inside the libguestfs appliance and carries out
2938 actions.
2939
2940 =item C<df>
2941
2942 L<virt-df(1)> command and documentation.
2943
2944 =item C<edit>
2945
2946 L<virt-edit(1)> command and documentation.
2947
2948 =item C<examples>
2949
2950 C API example code.
2951
2952 =item C<fish>
2953
2954 L<guestfish(1)>, the command-line shell, and various shell scripts
2955 built on top such as L<virt-copy-in(1)>, L<virt-copy-out(1)>,
2956 L<virt-tar-in(1)>, L<virt-tar-out(1)>.
2957
2958 =item C<fuse>
2959
2960 L<guestmount(1)>, FUSE (userspace filesystem) built on top of libguestfs.
2961
2962 =item C<generator>
2963
2964 The crucially important generator, used to automatically generate
2965 large amounts of boilerplate C code for things like RPC and bindings.
2966
2967 =item C<inspector>
2968
2969 L<virt-inspector(1)>, the virtual machine image inspector.
2970
2971 =item C<logo>
2972
2973 Logo used on the website.  The fish is called Arthur by the way.
2974
2975 =item C<m4>
2976
2977 M4 macros used by autoconf.
2978
2979 =item C<po>
2980
2981 Translations of simple gettext strings.
2982
2983 =item C<po-docs>
2984
2985 The build infrastructure and PO files for translations of manpages and
2986 POD files.  Eventually this will be combined with the C<po> directory,
2987 but that is rather complicated.
2988
2989 =item C<rescue>
2990
2991 L<virt-rescue(1)> command and documentation.
2992
2993 =item C<resize>
2994
2995 L<virt-resize(1)> command and documentation.
2996
2997 =item C<sparsify>
2998
2999 L<virt-sparsify(1)> command and documentation.
3000
3001 =item C<src>
3002
3003 Source code to the C library.
3004
3005 =item C<test-tool>
3006
3007 Test tool for end users to test if their qemu/kernel combination
3008 will work with libguestfs.
3009
3010 =item C<tests>
3011
3012 Tests.
3013
3014 =item C<tools>
3015
3016 Command line tools written in Perl (L<virt-win-reg(1)> and many others).
3017
3018 =item C<csharp>
3019
3020 =item C<erlang>
3021
3022 =item C<haskell>
3023
3024 =item C<java>
3025
3026 =item C<ocaml>
3027
3028 =item C<php>
3029
3030 =item C<perl>
3031
3032 =item C<python>
3033
3034 =item C<ruby>
3035
3036 Language bindings.
3037
3038 =back
3039
3040 =head2 MAKING A STABLE RELEASE
3041
3042 When we make a stable release, there are several steps documented
3043 here.  See L</LIBGUESTFS VERSION NUMBERS> for general information
3044 about the stable branch policy.
3045
3046 =over 4
3047
3048 =item *
3049
3050 Check C<make && make check> works on at least Fedora, Debian and
3051 Ubuntu.
3052
3053 =item *
3054
3055 Finalize RELEASE-NOTES.
3056
3057 =item *
3058
3059 Update ROADMAP.
3060
3061 =item *
3062
3063 Run C<src/api-support/update-from-tarballs.sh>.
3064
3065 =item *
3066
3067 Push and pull from Transifex.
3068
3069 Run:
3070
3071  tx push -s
3072
3073 to push the latest POT files to Transifex.  Then run:
3074
3075  ./tx-pull.sh
3076
3077 which is a wrapper to pull the latest translated C<*.po> files.
3078
3079 =item *
3080
3081 Create new stable and development directories under
3082 L<http://libguestfs.org/download>.
3083
3084 =item *
3085
3086 Create the branch in git:
3087
3088  git tag -a 1.XX.0 -m "Version 1.XX.0 (stable)"
3089  git tag -a 1.YY.0 -m "Version 1.YY.0 (development)"
3090  git branch stable-1.XX
3091  git push origin tag 1.XX.0 1.YY.0 stable-1.XX
3092
3093 =back
3094
3095 =head1 LIMITS
3096
3097 =head2 PROTOCOL LIMITS
3098
3099 Internally libguestfs uses a message-based protocol to pass API calls
3100 and their responses to and from a small "appliance" (see L</INTERNALS>
3101 for plenty more detail about this).  The maximum message size used by
3102 the protocol is slightly less than 4 MB.  For some API calls you may
3103 need to be aware of this limit.  The API calls which may be affected
3104 are individually documented, with a link back to this section of the
3105 documentation.
3106
3107 A simple call such as L</guestfs_cat> returns its result (the file
3108 data) in a simple string.  Because this string is at some point
3109 internally encoded as a message, the maximum size that it can return
3110 is slightly under 4 MB.  If the requested file is larger than this
3111 then you will get an error.
3112
3113 In order to transfer large files into and out of the guest filesystem,
3114 you need to use particular calls that support this.  The sections
3115 L</UPLOADING> and L</DOWNLOADING> document how to do this.
3116
3117 You might also consider mounting the disk image using our FUSE
3118 filesystem support (L<guestmount(1)>).
3119
3120 =head2 MAXIMUM NUMBER OF DISKS
3121
3122 When using virtio disks (the default) the current limit is B<25>
3123 disks.
3124
3125 Virtio itself consumes 1 virtual PCI slot per disk, and PCI is limited
3126 to 31 slots.  However febootstrap only understands disks with names
3127 C</dev/vda> through C</dev/vdz> (26 letters) and it reserves one disk
3128 for its own purposes.
3129
3130 We are working to substantially raise this limit in future versions
3131 but it requires complex changes to qemu.
3132
3133 In future versions of libguestfs it should also be possible to "hot
3134 plug" disks (add and remove disks after calling L</guestfs_launch>).
3135 This also requires changes to qemu.
3136
3137 =head2 MAXIMUM NUMBER OF PARTITIONS PER DISK
3138
3139 Virtio limits the maximum number of partitions per disk to B<15>.
3140
3141 This is because it reserves 4 bits for the minor device number (thus
3142 C</dev/vda>, and C</dev/vda1> through C</dev/vda15>).
3143
3144 If you attach a disk with more than 15 partitions, the extra
3145 partitions are ignored by libguestfs.
3146
3147 =head2 MAXIMUM SIZE OF A DISK
3148
3149 Probably the limit is between 2**63-1 and 2**64-1 bytes.
3150
3151 We have tested block devices up to 1 exabyte (2**60 or
3152 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
3153 host filesystem.
3154
3155 Although libguestfs probably does not impose any limit, the underlying
3156 host storage will.  If you store disk images on a host ext4
3157 filesystem, then the maximum size will be limited by the maximum ext4
3158 file size (currently 16 TB).  If you store disk images as host logical
3159 volumes then you are limited by the maximum size of an LV.
3160
3161 For the hugest disk image files, we recommend using XFS on the host
3162 for storage.
3163
3164 =head2 MAXIMUM SIZE OF A PARTITION
3165
3166 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
3167 numbers.  Assuming a 512 byte sector size, this means that MBR cannot
3168 address a partition located beyond 2 TB on the disk.
3169
3170 It is recommended that you use GPT partitions on disks which are
3171 larger than this size.  GPT uses 64 bit sector numbers and so can
3172 address partitions which are theoretically larger than the largest
3173 disk we could support.
3174
3175 =head2 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
3176
3177 This depends on the filesystem type.  libguestfs itself does not
3178 impose any known limit.  Consult Wikipedia or the filesystem
3179 documentation to find out what these limits are.
3180
3181 =head2 MAXIMUM UPLOAD AND DOWNLOAD
3182
3183 The API functions L</guestfs_upload>, L</guestfs_download>,
3184 L</guestfs_tar_in>, L</guestfs_tar_out> and the like allow unlimited
3185 sized uploads and downloads.
3186
3187 =head2 INSPECTION LIMITS
3188
3189 The inspection code has several arbitrary limits on things like the
3190 size of Windows Registry hive it will read, and the length of product
3191 name.  These are intended to stop a malicious guest from consuming
3192 arbitrary amounts of memory and disk space on the host, and should not
3193 be reached in practice.  See the source code for more information.
3194
3195 =head1 ENVIRONMENT VARIABLES
3196
3197 =over 4
3198
3199 =item FEBOOTSTRAP_KERNEL
3200
3201 =item FEBOOTSTRAP_MODULES
3202
3203 These two environment variables allow the kernel that libguestfs uses
3204 in the appliance to be selected.  If C<$FEBOOTSTRAP_KERNEL> is not
3205 set, then the most recent host kernel is chosen.  For more information
3206 about kernel selection, see L<febootstrap-supermin-helper(8)>.  This
3207 feature is only available in febootstrap E<ge> 3.8.
3208
3209 =item LIBGUESTFS_APPEND
3210
3211 Pass additional options to the guest kernel.
3212
3213 =item LIBGUESTFS_DEBUG
3214
3215 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This
3216 has the same effect as calling C<guestfs_set_verbose (g, 1)>.
3217
3218 =item LIBGUESTFS_MEMSIZE
3219
3220 Set the memory allocated to the qemu process, in megabytes.  For
3221 example:
3222
3223  LIBGUESTFS_MEMSIZE=700
3224
3225 =item LIBGUESTFS_PATH
3226
3227 Set the path that libguestfs uses to search for a supermin appliance.
3228 See the discussion of paths in section L</PATH> above.
3229
3230 =item LIBGUESTFS_QEMU
3231
3232 Set the default qemu binary that libguestfs uses.  If not set, then
3233 the qemu which was found at compile time by the configure script is
3234 used.
3235
3236 See also L</QEMU WRAPPERS> above.
3237
3238 =item LIBGUESTFS_TRACE
3239
3240 Set C<LIBGUESTFS_TRACE=1> to enable command traces.  This
3241 has the same effect as calling C<guestfs_set_trace (g, 1)>.
3242
3243 =item TMPDIR
3244
3245 Location of temporary directory, defaults to C</tmp> except for the
3246 cached supermin appliance which defaults to C</var/tmp>.
3247
3248 If libguestfs was compiled to use the supermin appliance then the
3249 real appliance is cached in this directory, shared between all
3250 handles belonging to the same EUID.  You can use C<$TMPDIR> to
3251 configure another directory to use in case C</var/tmp> is not large
3252 enough.
3253
3254 =back
3255
3256 =head1 SEE ALSO
3257
3258 L<guestfs-examples(3)>,
3259 L<guestfs-erlang(3)>,
3260 L<guestfs-java(3)>,
3261 L<guestfs-ocaml(3)>,
3262 L<guestfs-perl(3)>,
3263 L<guestfs-python(3)>,
3264 L<guestfs-ruby(3)>,
3265 L<guestfish(1)>,
3266 L<guestmount(1)>,
3267 L<virt-alignment-scan(1)>,
3268 L<virt-cat(1)>,
3269 L<virt-copy-in(1)>,
3270 L<virt-copy-out(1)>,
3271 L<virt-df(1)>,
3272 L<virt-edit(1)>,
3273 L<virt-filesystems(1)>,
3274 L<virt-inspector(1)>,
3275 L<virt-list-filesystems(1)>,
3276 L<virt-list-partitions(1)>,
3277 L<virt-ls(1)>,
3278 L<virt-make-fs(1)>,
3279 L<virt-rescue(1)>,
3280 L<virt-resize(1)>,
3281 L<virt-sparsify(1)>,
3282 L<virt-sysprep(1)>,
3283 L<virt-tar(1)>,
3284 L<virt-tar-in(1)>,
3285 L<virt-tar-out(1)>,
3286 L<virt-win-reg(1)>,
3287 L<guestfs-testing(1)>,
3288 L<qemu(1)>,
3289 L<febootstrap(1)>,
3290 L<febootstrap-supermin-helper(8)>,
3291 L<hivex(3)>,
3292 L<stap(1)>,
3293 L<http://libguestfs.org/>.
3294
3295 Tools with a similar purpose:
3296 L<fdisk(8)>,
3297 L<parted(8)>,
3298 L<kpartx(8)>,
3299 L<lvm(8)>,
3300 L<disktype(1)>.
3301
3302 =head1 BUGS
3303
3304 To get a list of bugs against libguestfs use this link:
3305
3306 L<https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools>
3307
3308 To report a new bug against libguestfs use this link:
3309
3310 L<https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools>
3311
3312 When reporting a bug, please check:
3313
3314 =over 4
3315
3316 =item *
3317
3318 That the bug hasn't been reported already.
3319
3320 =item *
3321
3322 That you are testing a recent version.
3323
3324 =item *
3325
3326 Describe the bug accurately, and give a way to reproduce it.
3327
3328 =item *
3329
3330 Run libguestfs-test-tool and paste the B<complete, unedited>
3331 output into the bug report.
3332
3333 =back
3334
3335 =head1 AUTHORS
3336
3337 Richard W.M. Jones (C<rjones at redhat dot com>)
3338
3339 =head1 COPYRIGHT
3340
3341 Copyright (C) 2009-2011 Red Hat Inc.
3342 L<http://libguestfs.org/>
3343
3344 This library is free software; you can redistribute it and/or
3345 modify it under the terms of the GNU Lesser General Public
3346 License as published by the Free Software Foundation; either
3347 version 2 of the License, or (at your option) any later version.
3348
3349 This library is distributed in the hope that it will be useful,
3350 but WITHOUT ANY WARRANTY; without even the implied warranty of
3351 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
3352 Lesser General Public License for more details.
3353
3354 You should have received a copy of the GNU Lesser General Public
3355 License along with this library; if not, write to the Free Software
3356 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA