todo: Add notes on inspecting ISO images.
[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, Haskell or C#).  You can also use it from shell scripts or the
46 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
317 L</guestfs_cp_a> to copy directories recursively.
318
319 =item B<file or device> to B<file or device>
320
321 Use L</guestfs_dd> which efficiently uses L<dd(1)>
322 to copy between files and devices in the guest.
323
324 Example: duplicate the contents of an LV:
325
326  guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy");
327
328 The destination (C</dev/VG/Copy>) must be at least as large as the
329 source (C</dev/VG/Original>).  To copy less than the whole
330 source device, use L</guestfs_copy_size>.
331
332 =item B<file on the host> to B<file or device>
333
334 Use L</guestfs_upload>.  See L</UPLOADING> above.
335
336 =item B<file or device> to B<file on the host>
337
338 Use L</guestfs_download>.  See L</DOWNLOADING> above.
339
340 =back
341
342 =head2 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
343
344 Calls like L</guestfs_upload>, L</guestfs_download>,
345 L</guestfs_tar_in>, L</guestfs_tar_out> etc appear to only take
346 filenames as arguments, so it appears you can only upload and download
347 to files.  However many Un*x-like hosts let you use the special device
348 files C</dev/stdin>, C</dev/stdout>, C</dev/stderr> and C</dev/fd/N>
349 to read and write from stdin, stdout, stderr, and arbitrary file
350 descriptor N.
351
352 For example, L<virt-cat(1)> writes its output to stdout by
353 doing:
354
355  guestfs_download (g, filename, "/dev/stdout");
356
357 and you can write tar output to a pipe C<fd> by doing:
358
359  char devfd[64];
360  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
361  guestfs_tar_out (g, "/", devfd);
362
363 =head2 LISTING FILES
364
365 L</guestfs_ll> is just designed for humans to read (mainly when using
366 the L<guestfish(1)>-equivalent command C<ll>).
367
368 L</guestfs_ls> is a quick way to get a list of files in a directory
369 from programs, as a flat list of strings.
370
371 L</guestfs_readdir> is a programmatic way to get a list of files in a
372 directory, plus additional information about each one.  It is more
373 equivalent to using the L<readdir(3)> call on a local filesystem.
374
375 L</guestfs_find> and L</guestfs_find0> can be used to recursively list
376 files.
377
378 =head2 RUNNING COMMANDS
379
380 Although libguestfs is primarily an API for manipulating files
381 inside guest images, we also provide some limited facilities for
382 running commands inside guests.
383
384 There are many limitations to this:
385
386 =over 4
387
388 =item *
389
390 The kernel version that the command runs under will be different
391 from what it expects.
392
393 =item *
394
395 If the command needs to communicate with daemons, then most likely
396 they won't be running.
397
398 =item *
399
400 The command will be running in limited memory.
401
402 =item *
403
404 The network may not be available unless you enable it
405 (see L</guestfs_set_network>).
406
407 =item *
408
409 Only supports Linux guests (not Windows, BSD, etc).
410
411 =item *
412
413 Architecture limitations (eg. won't work for a PPC guest on
414 an X86 host).
415
416 =item *
417
418 For SELinux guests, you may need to enable SELinux and load policy
419 first.  See L</SELINUX> in this manpage.
420
421 =item *
422
423 I<Security:> It is not safe to run commands from untrusted, possibly
424 malicious guests.  These commands may attempt to exploit your program
425 by sending unexpected output.  They could also try to exploit the
426 Linux kernel or qemu provided by the libguestfs appliance.  They could
427 use the network provided by the libguestfs appliance to bypass
428 ordinary network partitions and firewalls.  They could use the
429 elevated privileges or different SELinux context of your program
430 to their advantage.
431
432 A secure alternative is to use libguestfs to install a "firstboot"
433 script (a script which runs when the guest next boots normally), and
434 to have this script run the commands you want in the normal context of
435 the running guest, network security and so on.  For information about
436 other security issues, see L</SECURITY>.
437
438 =back
439
440 The two main API calls to run commands are L</guestfs_command> and
441 L</guestfs_sh> (there are also variations).
442
443 The difference is that L</guestfs_sh> runs commands using the shell, so
444 any shell globs, redirections, etc will work.
445
446 =head2 CONFIGURATION FILES
447
448 To read and write configuration files in Linux guest filesystems, we
449 strongly recommend using Augeas.  For example, Augeas understands how
450 to read and write, say, a Linux shadow password file or X.org
451 configuration file, and so avoids you having to write that code.
452
453 The main Augeas calls are bound through the C<guestfs_aug_*> APIs.  We
454 don't document Augeas itself here because there is excellent
455 documentation on the L<http://augeas.net/> website.
456
457 If you don't want to use Augeas (you fool!) then try calling
458 L</guestfs_read_lines> to get the file as a list of lines which
459 you can iterate over.
460
461 =head2 SELINUX
462
463 We support SELinux guests.  To ensure that labeling happens correctly
464 in SELinux guests, you need to enable SELinux and load the guest's
465 policy:
466
467 =over 4
468
469 =item 1.
470
471 Before launching, do:
472
473  guestfs_set_selinux (g, 1);
474
475 =item 2.
476
477 After mounting the guest's filesystem(s), load the policy.  This
478 is best done by running the L<load_policy(8)> command in the
479 guest itself:
480
481  guestfs_sh (g, "/usr/sbin/load_policy");
482
483 (Older versions of C<load_policy> require you to specify the
484 name of the policy file).
485
486 =item 3.
487
488 Optionally, set the security context for the API.  The correct
489 security context to use can only be known by inspecting the
490 guest.  As an example:
491
492  guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
493
494 =back
495
496 This will work for running commands and editing existing files.
497
498 When new files are created, you may need to label them explicitly,
499 for example by running the external command
500 C<restorecon pathname>.
501
502 =head2 UMASK
503
504 Certain calls are affected by the current file mode creation mask (the
505 "umask").  In particular ones which create files or directories, such
506 as L</guestfs_touch>, L</guestfs_mknod> or L</guestfs_mkdir>.  This
507 affects either the default mode that the file is created with or
508 modifies the mode that you supply.
509
510 The default umask is C<022>, so files are created with modes such as
511 C<0644> and directories with C<0755>.
512
513 There are two ways to avoid being affected by umask.  Either set umask
514 to 0 (call C<guestfs_umask (g, 0)> early after launching).  Or call
515 L</guestfs_chmod> after creating each file or directory.
516
517 For more information about umask, see L<umask(2)>.
518
519 =head2 ENCRYPTED DISKS
520
521 Libguestfs allows you to access Linux guests which have been
522 encrypted using whole disk encryption that conforms to the
523 Linux Unified Key Setup (LUKS) standard.  This includes
524 nearly all whole disk encryption systems used by modern
525 Linux guests.
526
527 Use L</guestfs_vfs_type> to identify LUKS-encrypted block
528 devices (it returns the string C<crypto_LUKS>).
529
530 Then open these devices by calling L</guestfs_luks_open>.
531 Obviously you will require the passphrase!
532
533 Opening a LUKS device creates a new device mapper device
534 called C</dev/mapper/mapname> (where C<mapname> is the
535 string you supply to L</guestfs_luks_open>).
536 Reads and writes to this mapper device are decrypted from and
537 encrypted to the underlying block device respectively.
538
539 LVM volume groups on the device can be made visible by calling
540 L</guestfs_vgscan> followed by L</guestfs_vg_activate_all>.
541 The logical volume(s) can now be mounted in the usual way.
542
543 Use the reverse process to close a LUKS device.  Unmount
544 any logical volumes on it, deactivate the volume groups
545 by caling C<guestfs_vg_activate (g, 0, ["/dev/VG"])>.
546 Then close the mapper device by calling
547 L</guestfs_luks_close> on the C</dev/mapper/mapname>
548 device (I<not> the underlying encrypted block device).
549
550 =head2 INSPECTION
551
552 Libguestfs has APIs for inspecting an unknown disk image to find out
553 if it contains operating systems.  (These APIs used to be in a
554 separate Perl-only library called L<Sys::Guestfs::Lib(3)> but since
555 version 1.5.3 the most frequently used part of this library has been
556 rewritten in C and moved into the core code).
557
558 Add all disks belonging to the unknown virtual machine and call
559 L</guestfs_launch> in the usual way.
560
561 Then call L</guestfs_inspect_os>.  This function uses other libguestfs
562 calls and certain heuristics, and returns a list of operating systems
563 that were found.  An empty list means none were found.  A single
564 element is the root filesystem of the operating system.  For dual- or
565 multi-boot guests, multiple roots can be returned, each one
566 corresponding to a separate operating system.  (Multi-boot virtual
567 machines are extremely rare in the world of virtualization, but since
568 this scenario can happen, we have built libguestfs to deal with it.)
569
570 For each root, you can then call various C<guestfs_inspect_get_*>
571 functions to get additional details about that operating system.  For
572 example, call L</guestfs_inspect_get_type> to return the string
573 C<windows> or C<linux> for Windows and Linux-based operating systems
574 respectively.
575
576 Un*x-like and Linux-based operating systems usually consist of several
577 filesystems which are mounted at boot time (for example, a separate
578 boot partition mounted on C</boot>).  The inspection rules are able to
579 detect how filesystems correspond to mount points.  Call
580 C<guestfs_inspect_get_mountpoints> to get this mapping.  It might
581 return a hash table like this example:
582
583  /boot => /dev/sda1
584  /     => /dev/vg_guest/lv_root
585  /usr  => /dev/vg_guest/lv_usr
586
587 The caller can then make calls to L</guestfs_mount_options> to
588 mount the filesystems as suggested.
589
590 Be careful to mount filesystems in the right order (eg. C</> before
591 C</usr>).  Sorting the keys of the hash by length, shortest first,
592 should work.
593
594 Inspection currently only works for some common operating systems.
595 Contributors are welcome to send patches for other operating systems
596 that we currently cannot detect.
597
598 Encrypted disks must be opened before inspection.  See
599 L</ENCRYPTED DISKS> for more details.  The L</guestfs_inspect_os>
600 function just ignores any encrypted devices.
601
602 A note on the implementation: The call L</guestfs_inspect_os> performs
603 inspection and caches the results in the guest handle.  Subsequent
604 calls to C<guestfs_inspect_get_*> return this cached information, but
605 I<do not> re-read the disks.  If you change the content of the guest
606 disks, you can redo inspection by calling L</guestfs_inspect_os>
607 again.  (L</guestfs_inspect_list_applications> works a little
608 differently from the other calls and does read the disks.  See
609 documentation for that function for details).
610
611 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
612
613 Libguestfs can mount NTFS partitions.  It does this using the
614 L<http://www.ntfs-3g.org/> driver.
615
616 =head3 DRIVE LETTERS AND PATHS
617
618 DOS and Windows still use drive letters, and the filesystems are
619 always treated as case insensitive by Windows itself, and therefore
620 you might find a Windows configuration file referring to a path like
621 C<c:\windows\system32>.  When the filesystem is mounted in libguestfs,
622 that directory might be referred to as C</WINDOWS/System32>.
623
624 Drive letter mappings are outside the scope of libguestfs.  You have
625 to use libguestfs to read the appropriate Windows Registry and
626 configuration files, to determine yourself how drives are mapped (see
627 also L<hivex(3)> and L<virt-inspector(1)>).
628
629 Replacing backslash characters with forward slash characters is also
630 outside the scope of libguestfs, but something that you can easily do.
631
632 Where we can help is in resolving the case insensitivity of paths.
633 For this, call L</guestfs_case_sensitive_path>.
634
635 =head3 ACCESSING THE WINDOWS REGISTRY
636
637 Libguestfs also provides some help for decoding Windows Registry
638 "hive" files, through the library C<hivex> which is part of the
639 libguestfs project although ships as a separate tarball.  You have to
640 locate and download the hive file(s) yourself, and then pass them to
641 C<hivex> functions.  See also the programs L<hivexml(1)>,
642 L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-reg(1)> for more help
643 on this issue.
644
645 =head3 SYMLINKS ON NTFS-3G FILESYSTEMS
646
647 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links"
648 to provide something which looks like a Linux symlink.  The way it
649 tries to do the rewriting is described here:
650
651 L<http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/>
652
653 The essential problem is that ntfs-3g simply does not have enough
654 information to do a correct job.  NTFS links can contain drive letters
655 and references to external device GUIDs that ntfs-3g has no way of
656 resolving.  It is almost certainly the case that libguestfs callers
657 should ignore what ntfs-3g does (ie. don't use L</guestfs_readlink> on
658 NTFS volumes).
659
660 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
661 L</guestfs_lgetxattr> to read the C<system.ntfs_reparse_data> extended
662 attribute, and read the raw reparse data from that (you can find the
663 format documented in various places around the web).
664
665 =head3 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
666
667 There are other useful extended attributes that can be read from
668 ntfs-3g filesystems (using L</guestfs_getxattr>).  See:
669
670 L<http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/>
671
672 =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
673
674 Although we don't want to discourage you from using the C API, we will
675 mention here that the same API is also available in other languages.
676
677 The API is broadly identical in all supported languages.  This means
678 that the C call C<guestfs_add_drive_ro(g,file)> is
679 C<$g-E<gt>add_drive_ro($file)> in Perl, C<g.add_drive_ro(file)> in Python,
680 and C<g#add_drive_ro file> in OCaml.  In other words, a
681 straightforward, predictable isomorphism between each language.
682
683 Error messages are automatically transformed
684 into exceptions if the language supports it.
685
686 We don't try to "object orientify" parts of the API in OO languages,
687 although contributors are welcome to write higher level APIs above
688 what we provide in their favourite languages if they wish.
689
690 =over 4
691
692 =item B<C++>
693
694 You can use the I<guestfs.h> header file from C++ programs.  The C++
695 API is identical to the C API.  C++ classes and exceptions are not
696 used.
697
698 =item B<C#>
699
700 The C# bindings are highly experimental.  Please read the warnings
701 at the top of C<csharp/Libguestfs.cs>.
702
703 =item B<Haskell>
704
705 This is the only language binding that is working but incomplete.
706 Only calls which return simple integers have been bound in Haskell,
707 and we are looking for help to complete this binding.
708
709 =item B<Java>
710
711 Full documentation is contained in the Javadoc which is distributed
712 with libguestfs.
713
714 =item B<OCaml>
715
716 See L<guestfs-ocaml(3)>.
717
718 =item B<Perl>
719
720 See L<Sys::Guestfs(3)>.
721
722 =item B<PHP>
723
724 For documentation see C<README-PHP> supplied with libguestfs
725 sources or in the php-libguestfs package for your distribution.
726
727 The PHP binding only works correctly on 64 bit machines.
728
729 =item B<Python>
730
731 See L<guestfs-python(3)>.
732
733 =item B<Ruby>
734
735 See L<guestfs-ruby(3)>.
736
737 =item B<shell scripts>
738
739 See L<guestfish(1)>.
740
741 =back
742
743 =head2 LIBGUESTFS GOTCHAS
744
745 L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: "A feature of a
746 system [...] that works in the way it is documented but is
747 counterintuitive and almost invites mistakes."
748
749 Since we developed libguestfs and the associated tools, there are
750 several things we would have designed differently, but are now stuck
751 with for backwards compatibility or other reasons.  If there is ever a
752 libguestfs 2.0 release, you can expect these to change.  Beware of
753 them.
754
755 =over 4
756
757 =item Autosync / forgetting to sync.
758
759 When modifying a filesystem from C or another language, you B<must>
760 unmount all filesystems and call L</guestfs_sync> explicitly before
761 you close the libguestfs handle.  You can also call:
762
763  guestfs_set_autosync (g, 1);
764
765 to have the unmount/sync done automatically for you when the handle 'g'
766 is closed.  (This feature is called "autosync", L</guestfs_set_autosync>
767 q.v.)
768
769 If you forget to do this, then it is entirely possible that your
770 changes won't be written out, or will be partially written, or (very
771 rarely) that you'll get disk corruption.
772
773 Note that in L<guestfish(3)> autosync is the default.  So quick and
774 dirty guestfish scripts that forget to sync will work just fine, which
775 can make this very puzzling if you are trying to debug a problem.
776
777 Update: Autosync is enabled by default for all API users starting from
778 libguestfs 1.5.24.
779
780 =item Mount option C<-o sync> should not be the default.
781
782 If you use L</guestfs_mount>, then C<-o sync,noatime> are added
783 implicitly.  However C<-o sync> does not add any reliability benefit,
784 but does have a very large performance impact.
785
786 The work around is to use L</guestfs_mount_options> and set the mount
787 options that you actually want to use.
788
789 =item Read-only should be the default.
790
791 In L<guestfish(3)>, I<--ro> should be the default, and you should
792 have to specify I<--rw> if you want to make changes to the image.
793
794 This would reduce the potential to corrupt live VM images.
795
796 Note that many filesystems change the disk when you just mount and
797 unmount, even if you didn't perform any writes.  You need to use
798 L</guestfs_add_drive_ro> to guarantee that the disk is not changed.
799
800 =item guestfish command line is hard to use.
801
802 C<guestfish disk.img> doesn't do what people expect (open C<disk.img>
803 for examination).  It tries to run a guestfish command C<disk.img>
804 which doesn't exist, so it fails.  In earlier versions of guestfish
805 the error message was also unintuitive, but we have corrected this
806 since.  Like the Bourne shell, we should have used C<guestfish -c
807 command> to run commands.
808
809 =item guestfish megabyte modifiers don't work right on all commands
810
811 In recent guestfish you can use C<1M> to mean 1 megabyte (and
812 similarly for other modifiers).  What guestfish actually does is to
813 multiply the number part by the modifier part and pass the result to
814 the C API.  However this doesn't work for a few APIs which aren't
815 expecting bytes, but are already expecting some other unit
816 (eg. megabytes).
817
818 The most common is L</guestfs_lvcreate>.  The guestfish command:
819
820  lvcreate LV VG 100M
821
822 does not do what you might expect.  Instead because
823 L</guestfs_lvcreate> is already expecting megabytes, this tries to
824 create a 100 I<terabyte> (100 megabytes * megabytes) logical volume.
825 The error message you get from this is also a little obscure.
826
827 This could be fixed in the generator by specially marking parameters
828 and return values which take bytes or other units.
829
830 =item Ambiguity between devices and paths
831
832 There is a subtle ambiguity in the API between a device name
833 (eg. C</dev/sdb2>) and a similar pathname.  A file might just happen
834 to be called C<sdb2> in the directory C</dev> (consider some non-Unix
835 VM image).
836
837 In the current API we usually resolve this ambiguity by having two
838 separate calls, for example L</guestfs_checksum> and
839 L</guestfs_checksum_device>.  Some API calls are ambiguous and
840 (incorrectly) resolve the problem by detecting if the path supplied
841 begins with C</dev/>.
842
843 To avoid both the ambiguity and the need to duplicate some calls, we
844 could make paths/devices into structured names.  One way to do this
845 would be to use a notation like grub (C<hd(0,0)>), although nobody
846 really likes this aspect of grub.  Another way would be to use a
847 structured type, equivalent to this OCaml type:
848
849  type path = Path of string | Device of int | Partition of int * int
850
851 which would allow you to pass arguments like:
852
853  Path "/foo/bar"
854  Device 1            (* /dev/sdb, or perhaps /dev/sda *)
855  Partition (1, 2)    (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
856  Path "/dev/sdb2"    (* not a device *)
857
858 As you can see there are still problems to resolve even with this
859 representation.  Also consider how it might work in guestfish.
860
861 =back
862
863 =head2 PROTOCOL LIMITS
864
865 Internally libguestfs uses a message-based protocol to pass API calls
866 and their responses to and from a small "appliance" (see L</INTERNALS>
867 for plenty more detail about this).  The maximum message size used by
868 the protocol is slightly less than 4 MB.  For some API calls you may
869 need to be aware of this limit.  The API calls which may be affected
870 are individually documented, with a link back to this section of the
871 documentation.
872
873 A simple call such as L</guestfs_cat> returns its result (the file
874 data) in a simple string.  Because this string is at some point
875 internally encoded as a message, the maximum size that it can return
876 is slightly under 4 MB.  If the requested file is larger than this
877 then you will get an error.
878
879 In order to transfer large files into and out of the guest filesystem,
880 you need to use particular calls that support this.  The sections
881 L</UPLOADING> and L</DOWNLOADING> document how to do this.
882
883 You might also consider mounting the disk image using our FUSE
884 filesystem support (L<guestmount(1)>).
885
886 =head2 KEYS AND PASSPHRASES
887
888 Certain libguestfs calls take a parameter that contains sensitive key
889 material, passed in as a C string.
890
891 In the future we would hope to change the libguestfs implementation so
892 that keys are L<mlock(2)>-ed into physical RAM, and thus can never end
893 up in swap.  However this is I<not> done at the moment, because of the
894 complexity of such an implementation.
895
896 Therefore you should be aware that any key parameter you pass to
897 libguestfs might end up being written out to the swap partition.  If
898 this is a concern, scrub the swap partition or don't use libguestfs on
899 encrypted devices.
900
901 =head2 MULTIPLE HANDLES AND MULTIPLE THREADS
902
903 All high-level libguestfs actions are synchronous.  If you want
904 to use libguestfs asynchronously then you must create a thread.
905
906 Only use the handle from a single thread.  Either use the handle
907 exclusively from one thread, or provide your own mutex so that two
908 threads cannot issue calls on the same handle at the same time.
909
910 See the graphical program guestfs-browser for one possible
911 architecture for multithreaded programs using libvirt and libguestfs.
912
913 =head2 PATH
914
915 Libguestfs needs a kernel and initrd.img, which it finds by looking
916 along an internal path.
917
918 By default it looks for these in the directory C<$libdir/guestfs>
919 (eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
920
921 Use L</guestfs_set_path> or set the environment variable
922 L</LIBGUESTFS_PATH> to change the directories that libguestfs will
923 search in.  The value is a colon-separated list of paths.  The current
924 directory is I<not> searched unless the path contains an empty element
925 or C<.>.  For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
926 search the current directory and then C</usr/lib/guestfs>.
927
928 =head2 QEMU WRAPPERS
929
930 If you want to compile your own qemu, run qemu from a non-standard
931 location, or pass extra arguments to qemu, then you can write a
932 shell-script wrapper around qemu.
933
934 There is one important rule to remember: you I<must C<exec qemu>> as
935 the last command in the shell script (so that qemu replaces the shell
936 and becomes the direct child of the libguestfs-using program).  If you
937 don't do this, then the qemu process won't be cleaned up correctly.
938
939 Here is an example of a wrapper, where I have built my own copy of
940 qemu from source:
941
942  #!/bin/sh -
943  qemudir=/home/rjones/d/qemu
944  exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
945
946 Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
947 and then use it by setting the LIBGUESTFS_QEMU environment variable.
948 For example:
949
950  LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
951
952 Note that libguestfs also calls qemu with the -help and -version
953 options in order to determine features.
954
955 =head2 ABI GUARANTEE
956
957 We guarantee the libguestfs ABI (binary interface), for public,
958 high-level actions as outlined in this section.  Although we will
959 deprecate some actions, for example if they get replaced by newer
960 calls, we will keep the old actions forever.  This allows you the
961 developer to program in confidence against the libguestfs API.
962
963 =head2 BLOCK DEVICE NAMING
964
965 In the kernel there is now quite a profusion of schemata for naming
966 block devices (in this context, by I<block device> I mean a physical
967 or virtual hard drive).  The original Linux IDE driver used names
968 starting with C</dev/hd*>.  SCSI devices have historically used a
969 different naming scheme, C</dev/sd*>.  When the Linux kernel I<libata>
970 driver became a popular replacement for the old IDE driver
971 (particularly for SATA devices) those devices also used the
972 C</dev/sd*> scheme.  Additionally we now have virtual machines with
973 paravirtualized drivers.  This has created several different naming
974 systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
975 PV disks.
976
977 As discussed above, libguestfs uses a qemu appliance running an
978 embedded Linux kernel to access block devices.  We can run a variety
979 of appliances based on a variety of Linux kernels.
980
981 This causes a problem for libguestfs because many API calls use device
982 or partition names.  Working scripts and the recipe (example) scripts
983 that we make available over the internet could fail if the naming
984 scheme changes.
985
986 Therefore libguestfs defines C</dev/sd*> as the I<standard naming
987 scheme>.  Internally C</dev/sd*> names are translated, if necessary,
988 to other names as required.  For example, under RHEL 5 which uses the
989 C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
990 C</dev/hda2> transparently.
991
992 Note that this I<only> applies to parameters.  The
993 L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
994 return the true names of the devices and partitions as known to the
995 appliance.
996
997 =head3 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
998
999 Usually this translation is transparent.  However in some (very rare)
1000 cases you may need to know the exact algorithm.  Such cases include
1001 where you use L</guestfs_config> to add a mixture of virtio and IDE
1002 devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
1003 and C</dev/vd*> devices.
1004
1005 The algorithm is applied only to I<parameters> which are known to be
1006 either device or partition names.  Return values from functions such
1007 as L</guestfs_list_devices> are never changed.
1008
1009 =over 4
1010
1011 =item *
1012
1013 Is the string a parameter which is a device or partition name?
1014
1015 =item *
1016
1017 Does the string begin with C</dev/sd>?
1018
1019 =item *
1020
1021 Does the named device exist?  If so, we use that device.
1022 However if I<not> then we continue with this algorithm.
1023
1024 =item *
1025
1026 Replace initial C</dev/sd> string with C</dev/hd>.
1027
1028 For example, change C</dev/sda2> to C</dev/hda2>.
1029
1030 If that named device exists, use it.  If not, continue.
1031
1032 =item *
1033
1034 Replace initial C</dev/sd> string with C</dev/vd>.
1035
1036 If that named device exists, use it.  If not, return an error.
1037
1038 =back
1039
1040 =head3 PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING
1041
1042 Although the standard naming scheme and automatic translation is
1043 useful for simple programs and guestfish scripts, for larger programs
1044 it is best not to rely on this mechanism.
1045
1046 Where possible for maximum future portability programs using
1047 libguestfs should use these future-proof techniques:
1048
1049 =over 4
1050
1051 =item *
1052
1053 Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list
1054 actual device names, and then use those names directly.
1055
1056 Since those device names exist by definition, they will never be
1057 translated.
1058
1059 =item *
1060
1061 Use higher level ways to identify filesystems, such as LVM names,
1062 UUIDs and filesystem labels.
1063
1064 =back
1065
1066 =head1 SECURITY
1067
1068 This section discusses security implications of using libguestfs,
1069 particularly with untrusted or malicious guests or disk images.
1070
1071 =head2 GENERAL SECURITY CONSIDERATIONS
1072
1073 Be careful with any files or data that you download from a guest (by
1074 "download" we mean not just the L</guestfs_download> command but any
1075 command that reads files, filenames, directories or anything else from
1076 a disk image).  An attacker could manipulate the data to fool your
1077 program into doing the wrong thing.  Consider cases such as:
1078
1079 =over 4
1080
1081 =item *
1082
1083 the data (file etc) not being present
1084
1085 =item *
1086
1087 being present but empty
1088
1089 =item *
1090
1091 being much larger than normal
1092
1093 =item *
1094
1095 containing arbitrary 8 bit data
1096
1097 =item *
1098
1099 being in an unexpected character encoding
1100
1101 =item *
1102
1103 containing homoglyphs.
1104
1105 =back
1106
1107 =head2 SECURITY OF MOUNTING FILESYSTEMS
1108
1109 When you mount a filesystem under Linux, mistakes in the kernel
1110 filesystem (VFS) module can sometimes be escalated into exploits by
1111 deliberately creating a malicious, malformed filesystem.  These
1112 exploits are very severe for two reasons.  Firstly there are very many
1113 filesystem drivers in the kernel, and many of them are infrequently
1114 used and not much developer attention has been paid to the code.
1115 Linux userspace helps potential crackers by detecting the filesystem
1116 type and automatically choosing the right VFS driver, even if that
1117 filesystem type is obscure or unexpected for the administrator.
1118 Secondly, a kernel-level exploit is like a local root exploit (worse
1119 in some ways), giving immediate and total access to the system right
1120 down to the hardware level.
1121
1122 That explains why you should never mount a filesystem from an
1123 untrusted guest on your host kernel.  How about libguestfs?  We run a
1124 Linux kernel inside a qemu virtual machine, usually running as a
1125 non-root user.  The attacker would need to write a filesystem which
1126 first exploited the kernel, and then exploited either qemu
1127 virtualization (eg. a faulty qemu driver) or the libguestfs protocol,
1128 and finally to be as serious as the host kernel exploit it would need
1129 to escalate its privileges to root.  This multi-step escalation,
1130 performed by a static piece of data, is thought to be extremely hard
1131 to do, although we never say 'never' about security issues.
1132
1133 In any case callers can reduce the attack surface by forcing the
1134 filesystem type when mounting (use L</guestfs_mount_vfs>).
1135
1136 =head2 PROTOCOL SECURITY
1137
1138 The protocol is designed to be secure, being based on RFC 4506 (XDR)
1139 with a defined upper message size.  However a program that uses
1140 libguestfs must also take care - for example you can write a program
1141 that downloads a binary from a disk image and executes it locally, and
1142 no amount of protocol security will save you from the consequences.
1143
1144 =head2 INSPECTION SECURITY
1145
1146 Parts of the inspection API (see L</INSPECTION>) return untrusted
1147 strings directly from the guest, and these could contain any 8 bit
1148 data.  Callers should be careful to escape these before printing them
1149 to a structured file (for example, use HTML escaping if creating a web
1150 page).
1151
1152 Guest configuration may be altered in unusual ways by the
1153 administrator of the virtual machine, and may not reflect reality
1154 (particularly for untrusted or actively malicious guests).  For
1155 example we parse the hostname from configuration files like
1156 C</etc/sysconfig/network> that we find in the guest, but the guest
1157 administrator can easily manipulate these files to provide the wrong
1158 hostname.
1159
1160 The inspection API parses guest configuration using two external
1161 libraries: Augeas (Linux configuration) and hivex (Windows Registry).
1162 Both are designed to be robust in the face of malicious data, although
1163 denial of service attacks are still possible, for example with
1164 oversized configuration files.
1165
1166 =head2 RUNNING UNTRUSTED GUEST COMMANDS
1167
1168 Be very cautious about running commands from the guest.  By running a
1169 command in the guest, you are giving CPU time to a binary that you do
1170 not control, under the same user account as the library, albeit
1171 wrapped in qemu virtualization.  More information and alternatives can
1172 be found in the section L</RUNNING COMMANDS>.
1173
1174 =head2 CVE-2010-3851
1175
1176 https://bugzilla.redhat.com/642934
1177
1178 This security bug concerns the automatic disk format detection that
1179 qemu does on disk images.
1180
1181 A raw disk image is just the raw bytes, there is no header.  Other
1182 disk images like qcow2 contain a special header.  Qemu deals with this
1183 by looking for one of the known headers, and if none is found then
1184 assuming the disk image must be raw.
1185
1186 This allows a guest which has been given a raw disk image to write
1187 some other header.  At next boot (or when the disk image is accessed
1188 by libguestfs) qemu would do autodetection and think the disk image
1189 format was, say, qcow2 based on the header written by the guest.
1190
1191 This in itself would not be a problem, but qcow2 offers many features,
1192 one of which is to allow a disk image to refer to another image
1193 (called the "backing disk").  It does this by placing the path to the
1194 backing disk into the qcow2 header.  This path is not validated and
1195 could point to any host file (eg. "/etc/passwd").  The backing disk is
1196 then exposed through "holes" in the qcow2 disk image, which of course
1197 is completely under the control of the attacker.
1198
1199 In libguestfs this is rather hard to exploit except under two
1200 circumstances:
1201
1202 =over 4
1203
1204 =item 1.
1205
1206 You have enabled the network or have opened the disk in write mode.
1207
1208 =item 2.
1209
1210 You are also running untrusted code from the guest (see
1211 L</RUNNING COMMANDS>).
1212
1213 =back
1214
1215 The way to avoid this is to specify the expected disk format when
1216 adding disks (the optional C<format> option to
1217 L</guestfs_add_drive_opts>).  You should always do this if the disk is
1218 raw format, and it's a good idea for other cases too.
1219
1220 For disks added from libvirt using calls like L</guestfs_add_domain>,
1221 the format is fetched from libvirt and passed through.
1222
1223 For libguestfs tools, use the I<--format> command line parameter as
1224 appropriate.
1225
1226 =head1 CONNECTION MANAGEMENT
1227
1228 =head2 guestfs_h *
1229
1230 C<guestfs_h> is the opaque type representing a connection handle.
1231 Create a handle by calling L</guestfs_create>.  Call L</guestfs_close>
1232 to free the handle and release all resources used.
1233
1234 For information on using multiple handles and threads, see the section
1235 L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
1236
1237 =head2 guestfs_create
1238
1239  guestfs_h *guestfs_create (void);
1240
1241 Create a connection handle.
1242
1243 You have to call L</guestfs_add_drive_opts> (or one of the equivalent
1244 calls) on the handle at least once.
1245
1246 This function returns a non-NULL pointer to a handle on success or
1247 NULL on error.
1248
1249 After configuring the handle, you have to call L</guestfs_launch>.
1250
1251 You may also want to configure error handling for the handle.  See
1252 L</ERROR HANDLING> section below.
1253
1254 =head2 guestfs_close
1255
1256  void guestfs_close (guestfs_h *g);
1257
1258 This closes the connection handle and frees up all resources used.
1259
1260 =head1 ERROR HANDLING
1261
1262 API functions can return errors.  For example, almost all functions
1263 that return C<int> will return C<-1> to indicate an error.
1264
1265 Additional information is available for errors: an error message
1266 string and optionally an error number (errno) if the thing that failed
1267 was a system call.
1268
1269 You can get at the additional information about the last error on the
1270 handle by calling L</guestfs_last_error>, L</guestfs_last_errno>,
1271 and/or by setting up an error handler with
1272 L</guestfs_set_error_handler>.
1273
1274 When the handle is created, a default error handler is installed which
1275 prints the error message string to C<stderr>.  For small short-running
1276 command line programs it is sufficient to do:
1277
1278  if (guestfs_launch (g) == -1)
1279    exit (EXIT_FAILURE);
1280
1281 since the default error handler will ensure that an error message has
1282 been printed to C<stderr> before the program exits.
1283
1284 For other programs the caller will almost certainly want to install an
1285 alternate error handler or do error handling in-line like this:
1286
1287  g = guestfs_create ();
1288  
1289  /* This disables the default behaviour of printing errors
1290     on stderr. */
1291  guestfs_set_error_handler (g, NULL, NULL);
1292  
1293  if (guestfs_launch (g) == -1) {
1294    /* Examine the error message and print it etc. */
1295    char *msg = guestfs_last_error (g);
1296    int errnum = guestfs_last_errno (g);
1297    fprintf (stderr, "%s\n", msg);
1298    /* ... */
1299   }
1300
1301 Out of memory errors are handled differently.  The default action is
1302 to call L<abort(3)>.  If this is undesirable, then you can set a
1303 handler using L</guestfs_set_out_of_memory_handler>.
1304
1305 L</guestfs_create> returns C<NULL> if the handle cannot be created,
1306 and because there is no handle if this happens there is no way to get
1307 additional error information.  However L</guestfs_create> is supposed
1308 to be a lightweight operation which can only fail because of
1309 insufficient memory (it returns NULL in this case).
1310
1311 =head2 guestfs_last_error
1312
1313  const char *guestfs_last_error (guestfs_h *g);
1314
1315 This returns the last error message that happened on C<g>.  If
1316 there has not been an error since the handle was created, then this
1317 returns C<NULL>.
1318
1319 The lifetime of the returned string is until the next error occurs, or
1320 L</guestfs_close> is called.
1321
1322 =head2 guestfs_last_errno
1323
1324  int guestfs_last_errno (guestfs_h *g);
1325
1326 This returns the last error number (errno) that happened on C<g>.
1327
1328 If successful, an errno integer not equal to zero is returned.
1329
1330 If no error, this returns 0.  This call can return 0 in three
1331 situations:
1332
1333 =over 4
1334
1335 =item 1.
1336
1337 There has not been any error on the handle.
1338
1339 =item 2.
1340
1341 There has been an error but the errno was meaningless.  This
1342 corresponds to the case where the error did not come from a
1343 failed system call, but for some other reason.
1344
1345 =item 3.
1346
1347 There was an error from a failed system call, but for some
1348 reason the errno was not captured and returned.  This usually
1349 indicates a bug in libguestfs.
1350
1351 =back
1352
1353 Libguestfs tries to convert the errno from inside the applicance into
1354 a corresponding errno for the caller (not entirely trivial: the
1355 appliance might be running a completely different operating system
1356 from the library and error numbers are not standardized across
1357 Un*xen).  If this could not be done, then the error is translated to
1358 C<EINVAL>.  In practice this should only happen in very rare
1359 circumstances.
1360
1361 =head2 guestfs_set_error_handler
1362
1363  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1364                                            void *opaque,
1365                                            const char *msg);
1366  void guestfs_set_error_handler (guestfs_h *g,
1367                                  guestfs_error_handler_cb cb,
1368                                  void *opaque);
1369
1370 The callback C<cb> will be called if there is an error.  The
1371 parameters passed to the callback are an opaque data pointer and the
1372 error message string.
1373
1374 C<errno> is not passed to the callback.  To get that the callback must
1375 call L</guestfs_last_errno>.
1376
1377 Note that the message string C<msg> is freed as soon as the callback
1378 function returns, so if you want to stash it somewhere you must make
1379 your own copy.
1380
1381 The default handler prints messages on C<stderr>.
1382
1383 If you set C<cb> to C<NULL> then I<no> handler is called.
1384
1385 =head2 guestfs_get_error_handler
1386
1387  guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1388                                                      void **opaque_rtn);
1389
1390 Returns the current error handler callback.
1391
1392 =head2 guestfs_set_out_of_memory_handler
1393
1394  typedef void (*guestfs_abort_cb) (void);
1395  int guestfs_set_out_of_memory_handler (guestfs_h *g,
1396                                         guestfs_abort_cb);
1397
1398 The callback C<cb> will be called if there is an out of memory
1399 situation.  I<Note this callback must not return>.
1400
1401 The default is to call L<abort(3)>.
1402
1403 You cannot set C<cb> to C<NULL>.  You can't ignore out of memory
1404 situations.
1405
1406 =head2 guestfs_get_out_of_memory_handler
1407
1408  guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1409
1410 This returns the current out of memory handler.
1411
1412 =head1 API CALLS
1413
1414 @ACTIONS@
1415
1416 =head1 STRUCTURES
1417
1418 @STRUCTS@
1419
1420 =head1 AVAILABILITY
1421
1422 =head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
1423
1424 Using L</guestfs_available> you can test availability of
1425 the following groups of functions.  This test queries the
1426 appliance to see if the appliance you are currently using
1427 supports the functionality.
1428
1429 @AVAILABILITY@
1430
1431 =head2 GUESTFISH supported COMMAND
1432
1433 In L<guestfish(3)> there is a handy interactive command
1434 C<supported> which prints out the available groups and
1435 whether they are supported by this build of libguestfs.
1436 Note however that you have to do C<run> first.
1437
1438 =head2 SINGLE CALLS AT COMPILE TIME
1439
1440 Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols
1441 for each C API function, such as:
1442
1443  #define LIBGUESTFS_HAVE_DD 1
1444
1445 if L</guestfs_dd> is available.
1446
1447 Before version 1.5.8, if you needed to test whether a single
1448 libguestfs function is available at compile time, we recommended using
1449 build tools such as autoconf or cmake.  For example in autotools you
1450 could use:
1451
1452  AC_CHECK_LIB([guestfs],[guestfs_create])
1453  AC_CHECK_FUNCS([guestfs_dd])
1454
1455 which would result in C<HAVE_GUESTFS_DD> being either defined
1456 or not defined in your program.
1457
1458 =head2 SINGLE CALLS AT RUN TIME
1459
1460 Testing at compile time doesn't guarantee that a function really
1461 exists in the library.  The reason is that you might be dynamically
1462 linked against a previous I<libguestfs.so> (dynamic library)
1463 which doesn't have the call.  This situation unfortunately results
1464 in a segmentation fault, which is a shortcoming of the C dynamic
1465 linking system itself.
1466
1467 You can use L<dlopen(3)> to test if a function is available
1468 at run time, as in this example program (note that you still
1469 need the compile time check as well):
1470
1471  #include <stdio.h>
1472  #include <stdlib.h>
1473  #include <unistd.h>
1474  #include <dlfcn.h>
1475  #include <guestfs.h>
1476  
1477  main ()
1478  {
1479  #ifdef LIBGUESTFS_HAVE_DD
1480    void *dl;
1481    int has_function;
1482  
1483    /* Test if the function guestfs_dd is really available. */
1484    dl = dlopen (NULL, RTLD_LAZY);
1485    if (!dl) {
1486      fprintf (stderr, "dlopen: %s\n", dlerror ());
1487      exit (EXIT_FAILURE);
1488    }
1489    has_function = dlsym (dl, "guestfs_dd") != NULL;
1490    dlclose (dl);
1491  
1492    if (!has_function)
1493      printf ("this libguestfs.so does NOT have guestfs_dd function\n");
1494    else {
1495      printf ("this libguestfs.so has guestfs_dd function\n");
1496      /* Now it's safe to call
1497      guestfs_dd (g, "foo", "bar");
1498      */
1499    }
1500  #else
1501    printf ("guestfs_dd function was not found at compile time\n");
1502  #endif
1503   }
1504
1505 You may think the above is an awful lot of hassle, and it is.
1506 There are other ways outside of the C linking system to ensure
1507 that this kind of incompatibility never arises, such as using
1508 package versioning:
1509
1510  Requires: libguestfs >= 1.0.80
1511
1512 =head1 CALLS WITH OPTIONAL ARGUMENTS
1513
1514 A recent feature of the API is the introduction of calls which take
1515 optional arguments.  In C these are declared 3 ways.  The main way is
1516 as a call which takes variable arguments (ie. C<...>), as in this
1517 example:
1518
1519  int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
1520
1521 Call this with a list of optional arguments, terminated by C<-1>.
1522 So to call with no optional arguments specified:
1523
1524  guestfs_add_drive_opts (g, filename, -1);
1525
1526 With a single optional argument:
1527
1528  guestfs_add_drive_opts (g, filename,
1529                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
1530                          -1);
1531
1532 With two:
1533
1534  guestfs_add_drive_opts (g, filename,
1535                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
1536                          GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
1537                          -1);
1538
1539 and so forth.  Don't forget the terminating C<-1> otherwise
1540 Bad Things will happen!
1541
1542 =head2 USING va_list FOR OPTIONAL ARGUMENTS
1543
1544 The second variant has the same name with the suffix C<_va>, which
1545 works the same way but takes a C<va_list>.  See the C manual for
1546 details.  For the example function, this is declared:
1547
1548  int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
1549                                 va_list args);
1550
1551 =head2 CONSTRUCTING OPTIONAL ARGUMENTS
1552
1553 The third variant is useful where you need to construct these
1554 calls.  You pass in a structure where you fill in the optional
1555 fields.  The structure has a bitmask as the first element which
1556 you must set to indicate which fields you have filled in.  For
1557 our example function the structure and call are declared:
1558
1559  struct guestfs_add_drive_opts_argv {
1560    uint64_t bitmask;
1561    int readonly;
1562    const char *format;
1563    /* ... */
1564  };
1565  int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
1566               const struct guestfs_add_drive_opts_argv *optargs);
1567
1568 You could call it like this:
1569
1570  struct guestfs_add_drive_opts_argv optargs = {
1571    .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
1572               GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
1573    .readonly = 1,
1574    .format = "qcow2"
1575  };
1576  
1577  guestfs_add_drive_opts_argv (g, filename, &optargs);
1578
1579 Notes:
1580
1581 =over 4
1582
1583 =item *
1584
1585 The C<_BITMASK> suffix on each option name when specifying the
1586 bitmask.
1587
1588 =item *
1589
1590 You do not need to fill in all fields of the structure.
1591
1592 =item *
1593
1594 There must be a one-to-one correspondence between fields of the
1595 structure that are filled in, and bits set in the bitmask.
1596
1597 =back
1598
1599 =head2 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
1600
1601 In other languages, optional arguments are expressed in the
1602 way that is natural for that language.  We refer you to the
1603 language-specific documentation for more details on that.
1604
1605 For guestfish, see L<guestfish(1)/OPTIONAL ARGUMENTS>.
1606
1607 =head2 SETTING CALLBACKS TO HANDLE EVENTS
1608
1609 The child process generates events in some situations.  Current events
1610 include: receiving a log message, the child process exits.
1611
1612 Use the C<guestfs_set_*_callback> functions to set a callback for
1613 different types of events.
1614
1615 Only I<one callback of each type> can be registered for each handle.
1616 Calling C<guestfs_set_*_callback> again overwrites the previous
1617 callback of that type.  Cancel all callbacks of this type by calling
1618 this function with C<cb> set to C<NULL>.
1619
1620 =head2 guestfs_set_log_message_callback
1621
1622  typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
1623                                          char *buf, int len);
1624  void guestfs_set_log_message_callback (guestfs_h *g,
1625                                         guestfs_log_message_cb cb,
1626                                         void *opaque);
1627
1628 The callback function C<cb> will be called whenever qemu or the guest
1629 writes anything to the console.
1630
1631 Use this function to capture kernel messages and similar.
1632
1633 Normally there is no log message handler, and log messages are just
1634 discarded.
1635
1636 =head2 guestfs_set_subprocess_quit_callback
1637
1638  typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);
1639  void guestfs_set_subprocess_quit_callback (guestfs_h *g,
1640                                             guestfs_subprocess_quit_cb cb,
1641                                             void *opaque);
1642
1643 The callback function C<cb> will be called when the child process
1644 quits, either asynchronously or if killed by
1645 L</guestfs_kill_subprocess>.  (This corresponds to a transition from
1646 any state to the CONFIG state).
1647
1648 =head2 guestfs_set_launch_done_callback
1649
1650  typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
1651  void guestfs_set_launch_done_callback (guestfs_h *g,
1652                                         guestfs_launch_done_cb cb,
1653                                         void *opaque);
1654
1655 The callback function C<cb> will be called when the child process
1656 becomes ready first time after it has been launched.  (This
1657 corresponds to a transition from LAUNCHING to the READY state).
1658
1659 =head2 guestfs_set_close_callback
1660
1661  typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);
1662  void guestfs_set_close_callback (guestfs_h *g,
1663                                   guestfs_close_cb cb,
1664                                   void *opaque);
1665
1666 The callback function C<cb> will be called while the handle
1667 is being closed (synchronously from L</guestfs_close>).
1668
1669 Note that libguestfs installs an L<atexit(3)> handler to try to
1670 clean up handles that are open when the program exits.  This
1671 means that this callback might be called indirectly from
1672 L<exit(3)>, which can cause unexpected problems in higher-level
1673 languages (eg. if your HLL interpreter has already been cleaned
1674 up by the time this is called, and if your callback then jumps
1675 into some HLL function).
1676
1677 =head2 guestfs_set_progress_callback
1678
1679  typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque,
1680                                       int proc_nr, int serial,
1681                                       uint64_t position, uint64_t total);
1682  void guestfs_set_progress_callback (guestfs_h *g,
1683                                      guestfs_progress_cb cb,
1684                                      void *opaque);
1685
1686 Some long-running operations can generate progress messages.  If
1687 this callback is registered, then it will be called each time a
1688 progress message is generated (usually two seconds after the
1689 operation started, and three times per second thereafter until
1690 it completes, although the frequency may change in future versions).
1691
1692 The callback receives two numbers: C<position> and C<total>.
1693 The units of C<total> are not defined, although for some
1694 operations C<total> may relate in some way to the amount of
1695 data to be transferred (eg. in bytes or megabytes), and
1696 C<position> may be the portion which has been transferred.
1697
1698 The only defined and stable parts of the API are:
1699
1700 =over 4
1701
1702 =item *
1703
1704 The callback can display to the user some type of progress bar or
1705 indicator which shows the ratio of C<position>:C<total>.
1706
1707 =item *
1708
1709 0 E<lt>= C<position> E<lt>= C<total>
1710
1711 =item *
1712
1713 If any progress notification is sent during a call, then a final
1714 progress notification is always sent when C<position> = C<total>.
1715
1716 This is to simplify caller code, so callers can easily set the
1717 progress indicator to "100%" at the end of the operation, without
1718 requiring special code to detect this case.
1719
1720 =back
1721
1722 The callback also receives the procedure number and serial number of
1723 the call.  These are only useful for debugging protocol issues, and
1724 the callback can normally ignore them.  The callback may want to
1725 print these numbers in error messages or debugging messages.
1726
1727 =head1 PRIVATE DATA AREA
1728
1729 You can attach named pieces of private data to the libguestfs handle,
1730 and fetch them by name for the lifetime of the handle.  This is called
1731 the private data area and is only available from the C API.
1732
1733 To attach a named piece of data, use the following call:
1734
1735  void guestfs_set_private (guestfs_h *g, const char *key, void *data);
1736
1737 C<key> is the name to associate with this data, and C<data> is an
1738 arbitrary pointer (which can be C<NULL>).  Any previous item with the
1739 same name is overwritten.
1740
1741 You can use any C<key> you want, but names beginning with an
1742 underscore character are reserved for internal libguestfs purposes
1743 (for implementing language bindings).  It is recommended to prefix the
1744 name with some unique string to avoid collisions with other users.
1745
1746 To retrieve the pointer, use:
1747
1748  void *guestfs_get_private (guestfs_h *g, const char *key);
1749
1750 This function returns C<NULL> if either no data is found associated
1751 with C<key>, or if the user previously set the C<key>'s C<data>
1752 pointer to C<NULL>.
1753
1754 Libguestfs does not try to look at or interpret the C<data> pointer in
1755 any way.  As far as libguestfs is concerned, it need not be a valid
1756 pointer at all.  In particular, libguestfs does I<not> try to free the
1757 data when the handle is closed.  If the data must be freed, then the
1758 caller must either free it before calling L</guestfs_close> or must
1759 set up a close callback to do it (see L</guestfs_set_close_callback>,
1760 and note that only one callback can be registered for a handle).
1761
1762 The private data area is implemented using a hash table, and should be
1763 reasonably efficient for moderate numbers of keys.
1764
1765 =begin html
1766
1767 <!-- old anchor for the next section -->
1768 <a name="state_machine_and_low_level_event_api"/>
1769
1770 =end html
1771
1772 =head1 ARCHITECTURE
1773
1774 Internally, libguestfs is implemented by running an appliance (a
1775 special type of small virtual machine) using L<qemu(1)>.  Qemu runs as
1776 a child process of the main program.
1777
1778   ___________________
1779  /                   \
1780  | main program      |
1781  |                   |
1782  |                   |           child process / appliance
1783  |                   |           __________________________
1784  |                   |          / qemu                     \
1785  +-------------------+   RPC    |      +-----------------+ |
1786  | libguestfs     <--------------------> guestfsd        | |
1787  |                   |          |      +-----------------+ |
1788  \___________________/          |      | Linux kernel    | |
1789                                 |      +--^--------------+ |
1790                                 \_________|________________/
1791                                           |
1792                                    _______v______
1793                                   /              \
1794                                   | Device or    |
1795                                   | disk image   |
1796                                   \______________/
1797
1798 The library, linked to the main program, creates the child process and
1799 hence the appliance in the L</guestfs_launch> function.
1800
1801 Inside the appliance is a Linux kernel and a complete stack of
1802 userspace tools (such as LVM and ext2 programs) and a small
1803 controlling daemon called L</guestfsd>.  The library talks to
1804 L</guestfsd> using remote procedure calls (RPC).  There is a mostly
1805 one-to-one correspondence between libguestfs API calls and RPC calls
1806 to the daemon.  Lastly the disk image(s) are attached to the qemu
1807 process which translates device access by the appliance's Linux kernel
1808 into accesses to the image.
1809
1810 A common misunderstanding is that the appliance "is" the virtual
1811 machine.  Although the disk image you are attached to might also be
1812 used by some virtual machine, libguestfs doesn't know or care about
1813 this.  (But you will care if both libguestfs's qemu process and your
1814 virtual machine are trying to update the disk image at the same time,
1815 since these usually results in massive disk corruption).
1816
1817 =head1 STATE MACHINE
1818
1819 libguestfs uses a state machine to model the child process:
1820
1821                          |
1822                     guestfs_create
1823                          |
1824                          |
1825                      ____V_____
1826                     /          \
1827                     |  CONFIG  |
1828                     \__________/
1829                      ^ ^   ^  \
1830                     /  |    \  \ guestfs_launch
1831                    /   |    _\__V______
1832                   /    |   /           \
1833                  /     |   | LAUNCHING |
1834                 /      |   \___________/
1835                /       |       /
1836               /        |  guestfs_launch
1837              /         |     /
1838     ______  /        __|____V
1839    /      \ ------> /        \
1840    | BUSY |         | READY  |
1841    \______/ <------ \________/
1842
1843 The normal transitions are (1) CONFIG (when the handle is created, but
1844 there is no child process), (2) LAUNCHING (when the child process is
1845 booting up), (3) alternating between READY and BUSY as commands are
1846 issued to, and carried out by, the child process.
1847
1848 The guest may be killed by L</guestfs_kill_subprocess>, or may die
1849 asynchronously at any time (eg. due to some internal error), and that
1850 causes the state to transition back to CONFIG.
1851
1852 Configuration commands for qemu such as L</guestfs_add_drive> can only
1853 be issued when in the CONFIG state.
1854
1855 The API offers one call that goes from CONFIG through LAUNCHING to
1856 READY.  L</guestfs_launch> blocks until the child process is READY to
1857 accept commands (or until some failure or timeout).
1858 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
1859 while it is running.
1860
1861 API actions such as L</guestfs_mount> can only be issued when in the
1862 READY state.  These API calls block waiting for the command to be
1863 carried out (ie. the state to transition to BUSY and then back to
1864 READY).  There are no non-blocking versions, and no way to issue more
1865 than one command per handle at the same time.
1866
1867 Finally, the child process sends asynchronous messages back to the
1868 main program, such as kernel log messages.  You can register a
1869 callback to receive these messages.
1870
1871 =head1 INTERNALS
1872
1873 =head2 COMMUNICATION PROTOCOL
1874
1875 Don't rely on using this protocol directly.  This section documents
1876 how it currently works, but it may change at any time.
1877
1878 The protocol used to talk between the library and the daemon running
1879 inside the qemu virtual machine is a simple RPC mechanism built on top
1880 of XDR (RFC 1014, RFC 1832, RFC 4506).
1881
1882 The detailed format of structures is in C<src/guestfs_protocol.x>
1883 (note: this file is automatically generated).
1884
1885 There are two broad cases, ordinary functions that don't have any
1886 C<FileIn> and C<FileOut> parameters, which are handled with very
1887 simple request/reply messages.  Then there are functions that have any
1888 C<FileIn> or C<FileOut> parameters, which use the same request and
1889 reply messages, but they may also be followed by files sent using a
1890 chunked encoding.
1891
1892 =head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)
1893
1894 For ordinary functions, the request message is:
1895
1896  total length (header + arguments,
1897       but not including the length word itself)
1898  struct guestfs_message_header (encoded as XDR)
1899  struct guestfs_<foo>_args (encoded as XDR)
1900
1901 The total length field allows the daemon to allocate a fixed size
1902 buffer into which it slurps the rest of the message.  As a result, the
1903 total length is limited to C<GUESTFS_MESSAGE_MAX> bytes (currently
1904 4MB), which means the effective size of any request is limited to
1905 somewhere under this size.
1906
1907 Note also that many functions don't take any arguments, in which case
1908 the C<guestfs_I<foo>_args> is completely omitted.
1909
1910 The header contains the procedure number (C<guestfs_proc>) which is
1911 how the receiver knows what type of args structure to expect, or none
1912 at all.
1913
1914 For functions that take optional arguments, the optional arguments are
1915 encoded in the C<guestfs_I<foo>_args> structure in the same way as
1916 ordinary arguments.  A bitmask in the header indicates which optional
1917 arguments are meaningful.  The bitmask is also checked to see if it
1918 contains bits set which the daemon does not know about (eg. if more
1919 optional arguments were added in a later version of the library), and
1920 this causes the call to be rejected.
1921
1922 The reply message for ordinary functions is:
1923
1924  total length (header + ret,
1925       but not including the length word itself)
1926  struct guestfs_message_header (encoded as XDR)
1927  struct guestfs_<foo>_ret (encoded as XDR)
1928
1929 As above the C<guestfs_I<foo>_ret> structure may be completely omitted
1930 for functions that return no formal return values.
1931
1932 As above the total length of the reply is limited to
1933 C<GUESTFS_MESSAGE_MAX>.
1934
1935 In the case of an error, a flag is set in the header, and the reply
1936 message is slightly changed:
1937
1938  total length (header + error,
1939       but not including the length word itself)
1940  struct guestfs_message_header (encoded as XDR)
1941  struct guestfs_message_error (encoded as XDR)
1942
1943 The C<guestfs_message_error> structure contains the error message as a
1944 string.
1945
1946 =head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS
1947
1948 A C<FileIn> parameter indicates that we transfer a file I<into> the
1949 guest.  The normal request message is sent (see above).  However this
1950 is followed by a sequence of file chunks.
1951
1952  total length (header + arguments,
1953       but not including the length word itself,
1954       and not including the chunks)
1955  struct guestfs_message_header (encoded as XDR)
1956  struct guestfs_<foo>_args (encoded as XDR)
1957  sequence of chunks for FileIn param #0
1958  sequence of chunks for FileIn param #1 etc.
1959
1960 The "sequence of chunks" is:
1961
1962  length of chunk (not including length word itself)
1963  struct guestfs_chunk (encoded as XDR)
1964  length of chunk
1965  struct guestfs_chunk (encoded as XDR)
1966    ...
1967  length of chunk
1968  struct guestfs_chunk (with data.data_len == 0)
1969
1970 The final chunk has the C<data_len> field set to zero.  Additionally a
1971 flag is set in the final chunk to indicate either successful
1972 completion or early cancellation.
1973
1974 At time of writing there are no functions that have more than one
1975 FileIn parameter.  However this is (theoretically) supported, by
1976 sending the sequence of chunks for each FileIn parameter one after
1977 another (from left to right).
1978
1979 Both the library (sender) I<and> the daemon (receiver) may cancel the
1980 transfer.  The library does this by sending a chunk with a special
1981 flag set to indicate cancellation.  When the daemon sees this, it
1982 cancels the whole RPC, does I<not> send any reply, and goes back to
1983 reading the next request.
1984
1985 The daemon may also cancel.  It does this by writing a special word
1986 C<GUESTFS_CANCEL_FLAG> to the socket.  The library listens for this
1987 during the transfer, and if it gets it, it will cancel the transfer
1988 (it sends a cancel chunk).  The special word is chosen so that even if
1989 cancellation happens right at the end of the transfer (after the
1990 library has finished writing and has started listening for the reply),
1991 the "spurious" cancel flag will not be confused with the reply
1992 message.
1993
1994 This protocol allows the transfer of arbitrary sized files (no 32 bit
1995 limit), and also files where the size is not known in advance
1996 (eg. from pipes or sockets).  However the chunks are rather small
1997 (C<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the
1998 daemon need to keep much in memory.
1999
2000 =head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS
2001
2002 The protocol for FileOut parameters is exactly the same as for FileIn
2003 parameters, but with the roles of daemon and library reversed.
2004
2005  total length (header + ret,
2006       but not including the length word itself,
2007       and not including the chunks)
2008  struct guestfs_message_header (encoded as XDR)
2009  struct guestfs_<foo>_ret (encoded as XDR)
2010  sequence of chunks for FileOut param #0
2011  sequence of chunks for FileOut param #1 etc.
2012
2013 =head3 INITIAL MESSAGE
2014
2015 When the daemon launches it sends an initial word
2016 (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest and daemon is
2017 alive.  This is what L</guestfs_launch> waits for.
2018
2019 =head3 PROGRESS NOTIFICATION MESSAGES
2020
2021 The daemon may send progress notification messages at any time.  These
2022 are distinguished by the normal length word being replaced by
2023 C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message.
2024
2025 The library turns them into progress callbacks (see
2026 C<guestfs_set_progress_callback>) if there is a callback registered,
2027 or discards them if not.
2028
2029 The daemon self-limits the frequency of progress messages it sends
2030 (see C<daemon/proto.c:notify_progress>).  Not all calls generate
2031 progress messages.
2032
2033 =head1 LIBGUESTFS VERSION NUMBERS
2034
2035 Since April 2010, libguestfs has started to make separate development
2036 and stable releases, along with corresponding branches in our git
2037 repository.  These separate releases can be identified by version
2038 number:
2039
2040                  even numbers for stable: 1.2.x, 1.4.x, ...
2041        .-------- odd numbers for development: 1.3.x, 1.5.x, ...
2042        |
2043        v
2044  1  .  3  .  5
2045  ^           ^
2046  |           |
2047  |           `-------- sub-version
2048  |
2049  `------ always '1' because we don't change the ABI
2050
2051 Thus "1.3.5" is the 5th update to the development branch "1.3".
2052
2053 As time passes we cherry pick fixes from the development branch and
2054 backport those into the stable branch, the effect being that the
2055 stable branch should get more stable and less buggy over time.  So the
2056 stable releases are ideal for people who don't need new features but
2057 would just like the software to work.
2058
2059 Our criteria for backporting changes are:
2060
2061 =over 4
2062
2063 =item *
2064
2065 Documentation changes which don't affect any code are
2066 backported unless the documentation refers to a future feature
2067 which is not in stable.
2068
2069 =item *
2070
2071 Bug fixes which are not controversial, fix obvious problems, and
2072 have been well tested are backported.
2073
2074 =item *
2075
2076 Simple rearrangements of code which shouldn't affect how it works get
2077 backported.  This is so that the code in the two branches doesn't get
2078 too far out of step, allowing us to backport future fixes more easily.
2079
2080 =item *
2081
2082 We I<don't> backport new features, new APIs, new tools etc, except in
2083 one exceptional case: the new feature is required in order to
2084 implement an important bug fix.
2085
2086 =back
2087
2088 A new stable branch starts when we think the new features in
2089 development are substantial and compelling enough over the current
2090 stable branch to warrant it.  When that happens we create new stable
2091 and development versions 1.N.0 and 1.(N+1).0 [N is even].  The new
2092 dot-oh release won't necessarily be so stable at this point, but by
2093 backporting fixes from development, that branch will stabilize over
2094 time.
2095
2096 =head1 EXTENDING LIBGUESTFS
2097
2098 =head2 ADDING A NEW API ACTION
2099
2100 Large amounts of boilerplate code in libguestfs (RPC, bindings,
2101 documentation) are generated, and this makes it easy to extend the
2102 libguestfs API.
2103
2104 To add a new API action there are two changes:
2105
2106 =over 4
2107
2108 =item 1.
2109
2110 You need to add a description of the call (name, parameters, return
2111 type, tests, documentation) to C<generator/generator_actions.ml>.
2112
2113 There are two sorts of API action, depending on whether the call goes
2114 through to the daemon in the appliance, or is serviced entirely by the
2115 library (see L</ARCHITECTURE> above).  L</guestfs_sync> is an example
2116 of the former, since the sync is done in the appliance.
2117 L</guestfs_set_trace> is an example of the latter, since a trace flag
2118 is maintained in the handle and all tracing is done on the library
2119 side.
2120
2121 Most new actions are of the first type, and get added to the
2122 C<daemon_functions> list.  Each function has a unique procedure number
2123 used in the RPC protocol which is assigned to that action when we
2124 publish libguestfs and cannot be reused.  Take the latest procedure
2125 number and increment it.
2126
2127 For library-only actions of the second type, add to the
2128 C<non_daemon_functions> list.  Since these functions are serviced by
2129 the library and do not travel over the RPC mechanism to the daemon,
2130 these functions do not need a procedure number, and so the procedure
2131 number is set to C<-1>.
2132
2133 =item 2.
2134
2135 Implement the action (in C):
2136
2137 For daemon actions, implement the function C<do_E<lt>nameE<gt>> in the
2138 C<daemon/> directory.
2139
2140 For library actions, implement the function C<guestfs__E<lt>nameE<gt>>
2141 (note: double underscore) in the C<src/> directory.
2142
2143 In either case, use another function as an example of what to do.
2144
2145 =back
2146
2147 After making these changes, use C<make> to compile.
2148
2149 Note that you don't need to implement the RPC, language bindings,
2150 manual pages or anything else.  It's all automatically generated from
2151 the OCaml description.
2152
2153 =head2 ADDING TESTS FOR AN API ACTION
2154
2155 You can supply zero or as many tests as you want per API call.  The
2156 tests can either be added as part of the API description
2157 (C<generator/generator_actions.ml>), or in some rarer cases you may
2158 want to drop a script into C<regressions/>.  Note that adding a script
2159 to C<regressions/> is slower, so if possible use the first method.
2160
2161 The following describes the test environment used when you add an API
2162 test in C<generator_actions.ml>.
2163
2164 The test environment has 4 block devices:
2165
2166 =over 4
2167
2168 =item C</dev/sda> 500MB
2169
2170 General block device for testing.
2171
2172 =item C</dev/sdb> 50MB
2173
2174 C</dev/sdb1> is an ext2 filesystem used for testing
2175 filesystem write operations.
2176
2177 =item C</dev/sdc> 10MB
2178
2179 Used in a few tests where two block devices are needed.
2180
2181 =item C</dev/sdd>
2182
2183 ISO with fixed content (see C<images/test.iso>).
2184
2185 =back
2186
2187 To be able to run the tests in a reasonable amount of time, the
2188 libguestfs appliance and block devices are reused between tests.  So
2189 don't try testing L</guestfs_kill_subprocess> :-x
2190
2191 Each test starts with an initial scenario, selected using one of the
2192 C<Init*> expressions, described in C<generator/generator_types.ml>.
2193 These initialize the disks mentioned above in a particular way as
2194 documented in C<generator_types.ml>.  You should not assume anything
2195 about the previous contents of other disks that are not initialized.
2196
2197 You can add a prerequisite clause to any individual test.  This is a
2198 run-time check, which, if it fails, causes the test to be skipped.
2199 Useful if testing a command which might not work on all variations of
2200 libguestfs builds.  A test that has prerequisite of C<Always> means to
2201 run unconditionally.
2202
2203 In addition, packagers can skip individual tests by setting
2204 environment variables before running C<make check>.
2205
2206  SKIP_TEST_<CMD>_<NUM>=1
2207
2208 eg: C<SKIP_TEST_COMMAND_3=1> skips test #3 of L</guestfs_command>.
2209
2210 or:
2211
2212  SKIP_TEST_<CMD>=1
2213
2214 eg: C<SKIP_TEST_ZEROFREE=1> skips all L</guestfs_zerofree> tests.
2215
2216 Packagers can run only certain tests by setting for example:
2217
2218  TEST_ONLY="vfs_type zerofree"
2219
2220 See C<capitests/tests.c> for more details of how these environment
2221 variables work.
2222
2223 =head2 DEBUGGING NEW API ACTIONS
2224
2225 Test new actions work before submitting them.
2226
2227 You can use guestfish to try out new commands.
2228
2229 Debugging the daemon is a problem because it runs inside a minimal
2230 environment.  However you can fprintf messages in the daemon to
2231 stderr, and they will show up if you use C<guestfish -v>.
2232
2233 =head2 FORMATTING CODE AND OTHER CONVENTIONS
2234
2235 Our C source code generally adheres to some basic code-formatting
2236 conventions.  The existing code base is not totally consistent on this
2237 front, but we do prefer that contributed code be formatted similarly.
2238 In short, use spaces-not-TABs for indentation, use 2 spaces for each
2239 indentation level, and other than that, follow the K&R style.
2240
2241 If you use Emacs, add the following to one of one of your start-up files
2242 (e.g., ~/.emacs), to help ensure that you get indentation right:
2243
2244  ;;; In libguestfs, indent with spaces everywhere (not TABs).
2245  ;;; Exceptions: Makefile and ChangeLog modes.
2246  (add-hook 'find-file-hook
2247      '(lambda () (if (and buffer-file-name
2248                           (string-match "/libguestfs\\>"
2249                               (buffer-file-name))
2250                           (not (string-equal mode-name "Change Log"))
2251                           (not (string-equal mode-name "Makefile")))
2252                      (setq indent-tabs-mode nil))))
2253  
2254  ;;; When editing C sources in libguestfs, use this style.
2255  (defun libguestfs-c-mode ()
2256    "C mode with adjusted defaults for use with libguestfs."
2257    (interactive)
2258    (c-set-style "K&R")
2259    (setq c-indent-level 2)
2260    (setq c-basic-offset 2))
2261  (add-hook 'c-mode-hook
2262            '(lambda () (if (string-match "/libguestfs\\>"
2263                                (buffer-file-name))
2264                            (libguestfs-c-mode))))
2265
2266 Enable warnings when compiling (and fix any problems this
2267 finds):
2268
2269  ./configure --enable-gcc-warnings
2270
2271 Useful targets are:
2272
2273  make syntax-check  # checks the syntax of the C code
2274  make check         # runs the test suite
2275
2276 =head2 DAEMON CUSTOM PRINTF FORMATTERS
2277
2278 In the daemon code we have created custom printf formatters C<%Q> and
2279 C<%R>, which are used to do shell quoting.
2280
2281 =over 4
2282
2283 =item %Q
2284
2285 Simple shell quoted string.  Any spaces or other shell characters are
2286 escaped for you.
2287
2288 =item %R
2289
2290 Same as C<%Q> except the string is treated as a path which is prefixed
2291 by the sysroot.
2292
2293 =back
2294
2295 For example:
2296
2297  asprintf (&cmd, "cat %R", path);
2298
2299 would produce C<cat /sysroot/some\ path\ with\ spaces>
2300
2301 I<Note:> Do I<not> use these when you are passing parameters to the
2302 C<command{,r,v,rv}()> functions.  These parameters do NOT need to be
2303 quoted because they are not passed via the shell (instead, straight to
2304 exec).  You probably want to use the C<sysroot_path()> function
2305 however.
2306
2307 =head2 SUBMITTING YOUR NEW API ACTIONS
2308
2309 Submit patches to the mailing list:
2310 L<http://www.redhat.com/mailman/listinfo/libguestfs>
2311 and CC to L<rjones@redhat.com>.
2312
2313 =head2 INTERNATIONALIZATION (I18N) SUPPORT
2314
2315 We support i18n (gettext anyhow) in the library.
2316
2317 However many messages come from the daemon, and we don't translate
2318 those at the moment.  One reason is that the appliance generally has
2319 all locale files removed from it, because they take up a lot of space.
2320 So we'd have to readd some of those, as well as copying our PO files
2321 into the appliance.
2322
2323 Debugging messages are never translated, since they are intended for
2324 the programmers.
2325
2326 =head2 SOURCE CODE SUBDIRECTORIES
2327
2328 =over 4
2329
2330 =item C<appliance>
2331
2332 The libguestfs appliance, build scripts and so on.
2333
2334 =item C<capitests>
2335
2336 Automated tests of the C API.
2337
2338 =item C<cat>
2339
2340 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
2341 and documentation.
2342
2343 =item C<contrib>
2344
2345 Outside contributions, experimental parts.
2346
2347 =item C<daemon>
2348
2349 The daemon that runs inside the libguestfs appliance and carries out
2350 actions.
2351
2352 =item C<df>
2353
2354 L<virt-df(1)> command and documentation.
2355
2356 =item C<examples>
2357
2358 C API example code.
2359
2360 =item C<fish>
2361
2362 L<guestfish(1)>, the command-line shell, and various shell scripts
2363 built on top such as L<virt-copy-in(1)>, L<virt-copy-out(1)>,
2364 L<virt-tar-in(1)>, L<virt-tar-out(1)>.
2365
2366 =item C<fuse>
2367
2368 L<guestmount(1)>, FUSE (userspace filesystem) built on top of libguestfs.
2369
2370 =item C<generator>
2371
2372 The crucially important generator, used to automatically generate
2373 large amounts of boilerplate C code for things like RPC and bindings.
2374
2375 =item C<images>
2376
2377 Files used by the test suite.
2378
2379 Some "phony" guest images which we test against.
2380
2381 =item C<inspector>
2382
2383 L<virt-inspector(1)>, the virtual machine image inspector.
2384
2385 =item C<m4>
2386
2387 M4 macros used by autoconf.
2388
2389 =item C<po>
2390
2391 Translations of simple gettext strings.
2392
2393 =item C<po-docs>
2394
2395 The build infrastructure and PO files for translations of manpages and
2396 POD files.  Eventually this will be combined with the C<po> directory,
2397 but that is rather complicated.
2398
2399 =item C<regressions>
2400
2401 Regression tests.
2402
2403 =item C<rescue>
2404
2405 L<virt-rescue(1)> command and documentation.
2406
2407 =item C<src>
2408
2409 Source code to the C library.
2410
2411 =item C<tools>
2412
2413 Command line tools written in Perl (L<virt-resize(1)> and many others).
2414
2415 =item C<test-tool>
2416
2417 Test tool for end users to test if their qemu/kernel combination
2418 will work with libguestfs.
2419
2420 =item C<csharp>
2421
2422 =item C<haskell>
2423
2424 =item C<java>
2425
2426 =item C<ocaml>
2427
2428 =item C<php>
2429
2430 =item C<perl>
2431
2432 =item C<python>
2433
2434 =item C<ruby>
2435
2436 Language bindings.
2437
2438 =back
2439
2440 =head1 ENVIRONMENT VARIABLES
2441
2442 =over 4
2443
2444 =item LIBGUESTFS_APPEND
2445
2446 Pass additional options to the guest kernel.
2447
2448 =item LIBGUESTFS_DEBUG
2449
2450 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This
2451 has the same effect as calling C<guestfs_set_verbose (g, 1)>.
2452
2453 =item LIBGUESTFS_MEMSIZE
2454
2455 Set the memory allocated to the qemu process, in megabytes.  For
2456 example:
2457
2458  LIBGUESTFS_MEMSIZE=700
2459
2460 =item LIBGUESTFS_PATH
2461
2462 Set the path that libguestfs uses to search for kernel and initrd.img.
2463 See the discussion of paths in section PATH above.
2464
2465 =item LIBGUESTFS_QEMU
2466
2467 Set the default qemu binary that libguestfs uses.  If not set, then
2468 the qemu which was found at compile time by the configure script is
2469 used.
2470
2471 See also L</QEMU WRAPPERS> above.
2472
2473 =item LIBGUESTFS_TRACE
2474
2475 Set C<LIBGUESTFS_TRACE=1> to enable command traces.  This
2476 has the same effect as calling C<guestfs_set_trace (g, 1)>.
2477
2478 =item TMPDIR
2479
2480 Location of temporary directory, defaults to C</tmp>.
2481
2482 If libguestfs was compiled to use the supermin appliance then the
2483 real appliance is cached in this directory, shared between all
2484 handles belonging to the same EUID.  You can use C<$TMPDIR> to
2485 configure another directory to use in case C</tmp> is not large
2486 enough.
2487
2488 =back
2489
2490 =head1 SEE ALSO
2491
2492 L<guestfs-examples(3)>,
2493 L<guestfs-ocaml(3)>,
2494 L<guestfs-python(3)>,
2495 L<guestfs-ruby(3)>,
2496 L<guestfish(1)>,
2497 L<guestmount(1)>,
2498 L<virt-cat(1)>,
2499 L<virt-copy-in(1)>,
2500 L<virt-copy-out(1)>,
2501 L<virt-df(1)>,
2502 L<virt-edit(1)>,
2503 L<virt-filesystems(1)>,
2504 L<virt-inspector(1)>,
2505 L<virt-list-filesystems(1)>,
2506 L<virt-list-partitions(1)>,
2507 L<virt-ls(1)>,
2508 L<virt-make-fs(1)>,
2509 L<virt-rescue(1)>,
2510 L<virt-tar(1)>,
2511 L<virt-tar-in(1)>,
2512 L<virt-tar-out(1)>,
2513 L<virt-win-reg(1)>,
2514 L<qemu(1)>,
2515 L<febootstrap(1)>,
2516 L<hivex(3)>,
2517 L<http://libguestfs.org/>.
2518
2519 Tools with a similar purpose:
2520 L<fdisk(8)>,
2521 L<parted(8)>,
2522 L<kpartx(8)>,
2523 L<lvm(8)>,
2524 L<disktype(1)>.
2525
2526 =head1 BUGS
2527
2528 To get a list of bugs against libguestfs use this link:
2529
2530 L<https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools>
2531
2532 To report a new bug against libguestfs use this link:
2533
2534 L<https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools>
2535
2536 When reporting a bug, please check:
2537
2538 =over 4
2539
2540 =item *
2541
2542 That the bug hasn't been reported already.
2543
2544 =item *
2545
2546 That you are testing a recent version.
2547
2548 =item *
2549
2550 Describe the bug accurately, and give a way to reproduce it.
2551
2552 =item *
2553
2554 Run libguestfs-test-tool and paste the B<complete, unedited>
2555 output into the bug report.
2556
2557 =back
2558
2559 =head1 AUTHORS
2560
2561 Richard W.M. Jones (C<rjones at redhat dot com>)
2562
2563 =head1 COPYRIGHT
2564
2565 Copyright (C) 2009-2010 Red Hat Inc.
2566 L<http://libguestfs.org/>
2567
2568 This library is free software; you can redistribute it and/or
2569 modify it under the terms of the GNU Lesser General Public
2570 License as published by the Free Software Foundation; either
2571 version 2 of the License, or (at your option) any later version.
2572
2573 This library is distributed in the hope that it will be useful,
2574 but WITHOUT ANY WARRANTY; without even the implied warranty of
2575 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
2576 Lesser General Public License for more details.
2577
2578 You should have received a copy of the GNU Lesser General Public
2579 License along with this library; if not, write to the Free Software
2580 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA