lib: Make pcre, libmagic and hivex libraries optional.
[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_sync (g);
18  guestfs_close (g);
19
20  cc prog.c -o prog -lguestfs
21 or:
22  cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
23
24 =head1 DESCRIPTION
25
26 Libguestfs is a library for accessing and modifying guest disk images.
27 Amongst the things this is good for: making batch configuration
28 changes to guests, getting disk used/free statistics (see also:
29 virt-df), migrating between virtualization systems (see also:
30 virt-p2v), performing partial backups, performing partial guest
31 clones, cloning guests and changing registry/UUID/hostname info, and
32 much else besides.
33
34 Libguestfs uses Linux kernel and qemu code, and can access any type of
35 guest filesystem that Linux and qemu can, including but not limited
36 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
37 schemes, qcow, qcow2, vmdk.
38
39 Libguestfs provides ways to enumerate guest storage (eg. partitions,
40 LVs, what filesystem is in each LV, etc.).  It can also run commands
41 in the context of the guest.  Also you can access filesystems over
42 FUSE.
43
44 Libguestfs is a library that can be linked with C and C++ management
45 programs (or management programs written in OCaml, Perl, Python, Ruby,
46 Java, PHP, Haskell or C#).  You can also use it from shell scripts or the
47 command line.
48
49 You don't need to be root to use libguestfs, although obviously you do
50 need enough permissions to access the disk images.
51
52 Libguestfs is a large API because it can do many things.  For a gentle
53 introduction, please read the L</API OVERVIEW> section next.
54
55 =head1 API OVERVIEW
56
57 This section provides a gentler overview of the libguestfs API.  We
58 also try to group API calls together, where that may not be obvious
59 from reading about the individual calls in the main section of this
60 manual.
61
62 =head2 HANDLES
63
64 Before you can use libguestfs calls, you have to create a handle.
65 Then you must add at least one disk image to the handle, followed by
66 launching the handle, then performing whatever operations you want,
67 and finally closing the handle.  By convention we use the single
68 letter C<g> for the name of the handle variable, although of course
69 you can use any name you want.
70
71 The general structure of all libguestfs-using programs looks like
72 this:
73
74  guestfs_h *g = guestfs_create ();
75  
76  /* Call guestfs_add_drive additional times if there are
77   * multiple disk images.
78   */
79  guestfs_add_drive (g, "guest.img");
80  
81  /* Most manipulation calls won't work until you've launched
82   * the handle 'g'.  You have to do this _after_ adding drives
83   * and _before_ other commands.
84   */
85  guestfs_launch (g);
86  
87  /* Now you can examine what partitions, LVs etc are available.
88   */
89  char **partitions = guestfs_list_partitions (g);
90  char **logvols = guestfs_lvs (g);
91  
92  /* To access a filesystem in the image, you must mount it.
93   */
94  guestfs_mount (g, "/dev/sda1", "/");
95  
96  /* Now you can perform filesystem actions on the guest
97   * disk image.
98   */
99  guestfs_touch (g, "/hello");
100  
101  /* You only need to call guestfs_sync if you have made
102   * changes to the guest image.  (But if you've made changes
103   * then you *must* sync).  See also: guestfs_umount and
104   * guestfs_umount_all calls.
105   */
106  guestfs_sync (g);
107  
108  /* Close the handle 'g'. */
109  guestfs_close (g);
110
111 The code above doesn't include any error checking.  In real code you
112 should check return values carefully for errors.  In general all
113 functions that return integers return C<-1> on error, and all
114 functions that return pointers return C<NULL> on error.  See section
115 L</ERROR HANDLING> below for how to handle errors, and consult the
116 documentation for each function call below to see precisely how they
117 return error indications.
118
119 =head2 DISK IMAGES
120
121 The image filename (C<"guest.img"> in the example above) could be a
122 disk image from a virtual machine, a L<dd(1)> copy of a physical hard
123 disk, an actual block device, or simply an empty file of zeroes that
124 you have created through L<posix_fallocate(3)>.  Libguestfs lets you
125 do useful things to all of these.
126
127 The call you should use in modern code for adding drives is
128 L</guestfs_add_drive_opts>.  To add a disk image, allowing writes, and
129 specifying that the format is raw, do:
130
131  guestfs_add_drive_opts (g, filename,
132                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
133                          -1);
134
135 You can add a disk read-only using:
136
137  guestfs_add_drive_opts (g, filename,
138                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
139                          GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
140                          -1);
141
142 or by calling the older function L</guestfs_add_drive_ro>.  In either
143 case libguestfs won't modify the file.
144
145 Be extremely cautious if the disk image is in use, eg. if it is being
146 used by a virtual machine.  Adding it read-write will almost certainly
147 cause disk corruption, but adding it read-only is safe.
148
149 You must add at least one disk image, and you may add multiple disk
150 images.  In the API, the disk images are usually referred to as
151 C</dev/sda> (for the first one you added), C</dev/sdb> (for the second
152 one you added), etc.
153
154 Once L</guestfs_launch> has been called you cannot add any more images.
155 You can call L</guestfs_list_devices> to get a list of the device
156 names, in the order that you added them.  See also L</BLOCK DEVICE
157 NAMING> below.
158
159 =head2 MOUNTING
160
161 Before you can read or write files, create directories and so on in a
162 disk image that contains filesystems, you have to mount those
163 filesystems using L</guestfs_mount>.  If you already know that a disk
164 image contains (for example) one partition with a filesystem on that
165 partition, then you can mount it directly:
166
167  guestfs_mount (g, "/dev/sda1", "/");
168
169 where C</dev/sda1> means literally the first partition (C<1>) of the
170 first disk image that we added (C</dev/sda>).  If the disk contains
171 Linux LVM2 logical volumes you could refer to those instead (eg. C</dev/VG/LV>).
172
173 If you are given a disk image and you don't know what it contains then
174 you have to find out.  Libguestfs can do that too: use
175 L</guestfs_list_partitions> and L</guestfs_lvs> to list possible
176 partitions and LVs, and either try mounting each to see what is
177 mountable, or else examine them with L</guestfs_vfs_type> or
178 L</guestfs_file>.  Libguestfs also has a set of APIs for inspection of
179 disk images (see L</INSPECTION> below).  But you might find it easier
180 to look at higher level programs built on top of libguestfs, in
181 particular L<virt-inspector(1)>.
182
183 To mount a disk image read-only, use L</guestfs_mount_ro>.  There are
184 several other variations of the C<guestfs_mount_*> call.
185
186 =head2 FILESYSTEM ACCESS AND MODIFICATION
187
188 The majority of the libguestfs API consists of fairly low-level calls
189 for accessing and modifying the files, directories, symlinks etc on
190 mounted filesystems.  There are over a hundred such calls which you
191 can find listed in detail below in this man page, and we don't even
192 pretend to cover them all in this overview.
193
194 Specify filenames as full paths, starting with C<"/"> and including
195 the mount point.
196
197 For example, if you mounted a filesystem at C<"/"> and you want to
198 read the file called C<"etc/passwd"> then you could do:
199
200  char *data = guestfs_cat (g, "/etc/passwd");
201
202 This would return C<data> as a newly allocated buffer containing the
203 full content of that file (with some conditions: see also
204 L</DOWNLOADING> below), or C<NULL> if there was an error.
205
206 As another example, to create a top-level directory on that filesystem
207 called C<"var"> you would do:
208
209  guestfs_mkdir (g, "/var");
210
211 To create a symlink you could do:
212
213  guestfs_ln_s (g, "/etc/init.d/portmap",
214                "/etc/rc3.d/S30portmap");
215
216 Libguestfs will reject attempts to use relative paths and there is no
217 concept of a current working directory.
218
219 Libguestfs can return errors in many situations: for example if the
220 filesystem isn't writable, or if a file or directory that you
221 requested doesn't exist.  If you are using the C API (documented here)
222 you have to check for those error conditions after each call.  (Other
223 language bindings turn these errors into exceptions).
224
225 File writes are affected by the per-handle umask, set by calling
226 L</guestfs_umask> and defaulting to 022.  See L</UMASK>.
227
228 =head2 PARTITIONING
229
230 Libguestfs contains API calls to read, create and modify partition
231 tables on disk images.
232
233 In the common case where you want to create a single partition
234 covering the whole disk, you should use the L</guestfs_part_disk>
235 call:
236
237  const char *parttype = "mbr";
238  if (disk_is_larger_than_2TB)
239    parttype = "gpt";
240  guestfs_part_disk (g, "/dev/sda", parttype);
241
242 Obviously this effectively wipes anything that was on that disk image
243 before.
244
245 =head2 LVM2
246
247 Libguestfs provides access to a large part of the LVM2 API, such as
248 L</guestfs_lvcreate> and L</guestfs_vgremove>.  It won't make much sense
249 unless you familiarize yourself with the concepts of physical volumes,
250 volume groups and logical volumes.
251
252 This author strongly recommends reading the LVM HOWTO, online at
253 L<http://tldp.org/HOWTO/LVM-HOWTO/>.
254
255 =head2 DOWNLOADING
256
257 Use L</guestfs_cat> to download small, text only files.  This call
258 is limited to files which are less than 2 MB and which cannot contain
259 any ASCII NUL (C<\0>) characters.  However it has a very simple
260 to use API.
261
262 L</guestfs_read_file> can be used to read files which contain
263 arbitrary 8 bit data, since it returns a (pointer, size) pair.
264 However it is still limited to "small" files, less than 2 MB.
265
266 L</guestfs_download> can be used to download any file, with no
267 limits on content or size (even files larger than 4 GB).
268
269 To download multiple files, see L</guestfs_tar_out> and
270 L</guestfs_tgz_out>.
271
272 =head2 UPLOADING
273
274 It's often the case that you want to write a file or files to the disk
275 image.
276
277 To write a small file with fixed content, use L</guestfs_write>.  To
278 create a file of all zeroes, use L</guestfs_truncate_size> (sparse) or
279 L</guestfs_fallocate64> (with all disk blocks allocated).  There are a
280 variety of other functions for creating test files, for example
281 L</guestfs_fill> and L</guestfs_fill_pattern>.
282
283 To upload a single file, use L</guestfs_upload>.  This call has no
284 limits on file content or size (even files larger than 4 GB).
285
286 To upload multiple files, see L</guestfs_tar_in> and L</guestfs_tgz_in>.
287
288 However the fastest way to upload I<large numbers of arbitrary files>
289 is to turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and
290 L<mkisofs(8)>), then attach this using L</guestfs_add_drive_ro>.  If
291 you add the drive in a predictable way (eg. adding it last after all
292 other drives) then you can get the device name from
293 L</guestfs_list_devices> and mount it directly using
294 L</guestfs_mount_ro>.  Note that squashfs images are sometimes
295 non-portable between kernel versions, and they don't support labels or
296 UUIDs.  If you want to pre-build an image or you need to mount it
297 using a label or UUID, use an ISO image instead.
298
299 =head2 COPYING
300
301 There are various different commands for copying between files and
302 devices and in and out of the guest filesystem.  These are summarised
303 in the table below.
304
305 =over 4
306
307 =item B<file> to B<file>
308
309 Use L</guestfs_cp> to copy a single file, or
310 L</guestfs_cp_a> to copy directories recursively.
311
312 =item B<file or device> to B<file or device>
313
314 Use L</guestfs_dd> which efficiently uses L<dd(1)>
315 to copy between files and devices in the guest.
316
317 Example: duplicate the contents of an LV:
318
319  guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy");
320
321 The destination (C</dev/VG/Copy>) must be at least as large as the
322 source (C</dev/VG/Original>).  To copy less than the whole
323 source device, use L</guestfs_copy_size>.
324
325 =item B<file on the host> to B<file or device>
326
327 Use L</guestfs_upload>.  See L</UPLOADING> above.
328
329 =item B<file or device> to B<file on the host>
330
331 Use L</guestfs_download>.  See L</DOWNLOADING> above.
332
333 =back
334
335 =head2 LISTING FILES
336
337 L</guestfs_ll> is just designed for humans to read (mainly when using
338 the L<guestfish(1)>-equivalent command C<ll>).
339
340 L</guestfs_ls> is a quick way to get a list of files in a directory
341 from programs, as a flat list of strings.
342
343 L</guestfs_readdir> is a programmatic way to get a list of files in a
344 directory, plus additional information about each one.  It is more
345 equivalent to using the L<readdir(3)> call on a local filesystem.
346
347 L</guestfs_find> and L</guestfs_find0> can be used to recursively list
348 files.
349
350 =head2 RUNNING COMMANDS
351
352 Although libguestfs is primarily an API for manipulating files
353 inside guest images, we also provide some limited facilities for
354 running commands inside guests.
355
356 There are many limitations to this:
357
358 =over 4
359
360 =item *
361
362 The kernel version that the command runs under will be different
363 from what it expects.
364
365 =item *
366
367 If the command needs to communicate with daemons, then most likely
368 they won't be running.
369
370 =item *
371
372 The command will be running in limited memory.
373
374 =item *
375
376 The network may not be available unless you enable it
377 (see L</guestfs_set_network>).
378
379 =item *
380
381 Only supports Linux guests (not Windows, BSD, etc).
382
383 =item *
384
385 Architecture limitations (eg. won't work for a PPC guest on
386 an X86 host).
387
388 =item *
389
390 For SELinux guests, you may need to enable SELinux and load policy
391 first.  See L</SELINUX> in this manpage.
392
393 =item *
394
395 I<Security:> It is not safe to run commands from untrusted, possibly
396 malicious guests.  These commands may attempt to exploit your program
397 by sending unexpected output.  They could also try to exploit the
398 Linux kernel or qemu provided by the libguestfs appliance.  They could
399 use the network provided by the libguestfs appliance to bypass
400 ordinary network partitions and firewalls.  They could use the
401 elevated privileges or different SELinux context of your program
402 to their advantage.
403
404 A secure alternative is to use libguestfs to install a "firstboot"
405 script (a script which runs when the guest next boots normally), and
406 to have this script run the commands you want in the normal context of
407 the running guest, network security and so on.
408
409 =back
410
411 The two main API calls to run commands are L</guestfs_command> and
412 L</guestfs_sh> (there are also variations).
413
414 The difference is that L</guestfs_sh> runs commands using the shell, so
415 any shell globs, redirections, etc will work.
416
417 =head2 CONFIGURATION FILES
418
419 To read and write configuration files in Linux guest filesystems, we
420 strongly recommend using Augeas.  For example, Augeas understands how
421 to read and write, say, a Linux shadow password file or X.org
422 configuration file, and so avoids you having to write that code.
423
424 The main Augeas calls are bound through the C<guestfs_aug_*> APIs.  We
425 don't document Augeas itself here because there is excellent
426 documentation on the L<http://augeas.net/> website.
427
428 If you don't want to use Augeas (you fool!) then try calling
429 L</guestfs_read_lines> to get the file as a list of lines which
430 you can iterate over.
431
432 =head2 SELINUX
433
434 We support SELinux guests.  To ensure that labeling happens correctly
435 in SELinux guests, you need to enable SELinux and load the guest's
436 policy:
437
438 =over 4
439
440 =item 1.
441
442 Before launching, do:
443
444  guestfs_set_selinux (g, 1);
445
446 =item 2.
447
448 After mounting the guest's filesystem(s), load the policy.  This
449 is best done by running the L<load_policy(8)> command in the
450 guest itself:
451
452  guestfs_sh (g, "/usr/sbin/load_policy");
453
454 (Older versions of C<load_policy> require you to specify the
455 name of the policy file).
456
457 =item 3.
458
459 Optionally, set the security context for the API.  The correct
460 security context to use can only be known by inspecting the
461 guest.  As an example:
462
463  guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
464
465 =back
466
467 This will work for running commands and editing existing files.
468
469 When new files are created, you may need to label them explicitly,
470 for example by running the external command
471 C<restorecon pathname>.
472
473 =head2 UMASK
474
475 Certain calls are affected by the current file mode creation mask (the
476 "umask").  In particular ones which create files or directories, such
477 as L</guestfs_touch>, L</guestfs_mknod> or L</guestfs_mkdir>.  This
478 affects either the default mode that the file is created with or
479 modifies the mode that you supply.
480
481 The default umask is C<022>, so files are created with modes such as
482 C<0644> and directories with C<0755>.
483
484 There are two ways to avoid being affected by umask.  Either set umask
485 to 0 (call C<guestfs_umask (g, 0)> early after launching).  Or call
486 L</guestfs_chmod> after creating each file or directory.
487
488 For more information about umask, see L<umask(2)>.
489
490 =head2 ENCRYPTED DISKS
491
492 Libguestfs allows you to access Linux guests which have been
493 encrypted using whole disk encryption that conforms to the
494 Linux Unified Key Setup (LUKS) standard.  This includes
495 nearly all whole disk encryption systems used by modern
496 Linux guests.
497
498 Use L</guestfs_vfs_type> to identify LUKS-encrypted block
499 devices (it returns the string C<crypto_LUKS>).
500
501 Then open these devices by calling L</guestfs_luks_open>.
502 Obviously you will require the passphrase!
503
504 Opening a LUKS device creates a new device mapper device
505 called C</dev/mapper/mapname> (where C<mapname> is the
506 string you supply to L</guestfs_luks_open>).
507 Reads and writes to this mapper device are decrypted from and
508 encrypted to the underlying block device respectively.
509
510 LVM volume groups on the device can be made visible by calling
511 L</guestfs_vgscan> followed by L</guestfs_vg_activate_all>.
512 The logical volume(s) can now be mounted in the usual way.
513
514 Use the reverse process to close a LUKS device.  Unmount
515 any logical volumes on it, deactivate the volume groups
516 by caling C<guestfs_vg_activate (g, 0, ["/dev/VG"])>.
517 Then close the mapper device by calling
518 L</guestfs_luks_close> on the C</dev/mapper/mapname>
519 device (I<not> the underlying encrypted block device).
520
521 =head2 INSPECTION
522
523 Libguestfs has APIs for inspecting an unknown disk image to find out
524 if it contains operating systems.  (These APIs used to be in a
525 separate Perl-only library called L<Sys::Guestfs::Lib(3)> but since
526 version 1.5.3 the most frequently used part of this library has been
527 rewritten in C and moved into the core code).
528
529 Add all disks belonging to the unknown virtual machine and call
530 L</guestfs_launch> in the usual way.
531
532 Then call L</guestfs_inspect_os>.  This function uses other libguestfs
533 calls and certain heuristics, and returns a list of operating systems
534 that were found.  An empty list means none were found.  A single
535 element is the root filesystem of the operating system.  For dual- or
536 multi-boot guests, multiple roots can be returned, each one
537 corresponding to a separate operating system.  (Multi-boot virtual
538 machines are extremely rare in the world of virtualization, but since
539 this scenario can happen, we have built libguestfs to deal with it.)
540
541 For each root, you can then call various C<guestfs_inspect_get_*>
542 functions to get additional details about that operating system.  For
543 example, call L</guestfs_inspect_get_type> to return the string
544 C<windows> or C<linux> for Windows and Linux-based operating systems
545 respectively.
546
547 Un*x-like and Linux-based operating systems usually consist of several
548 filesystems which are mounted at boot time (for example, a separate
549 boot partition mounted on C</boot>).  The inspection rules are able to
550 detect how filesystems correspond to mount points.  Call
551 C<guestfs_inspect_get_mountpoints> to get this mapping.  It might
552 return a hash table like this example:
553
554  /boot => /dev/sda1
555  /     => /dev/vg_guest/lv_root
556  /usr  => /dev/vg_guest/lv_usr
557
558 The caller can then make calls to L</guestfs_mount_options> to
559 mount the filesystems as suggested.
560
561 Be careful to mount filesystems in the right order (eg. C</> before
562 C</usr>).  Sorting the keys of the hash by length, shortest first,
563 should work.
564
565 Inspection currently only works for some common operating systems.
566 Contributors are welcome to send patches for other operating systems
567 that we currently cannot detect.
568
569 Encrypted disks must be opened before inspection.  See
570 L</ENCRYPTED DISKS> for more details.  The L</guestfs_inspect_os>
571 function just ignores any encrypted devices.
572
573 A note on the implementation: The call L</guestfs_inspect_os> performs
574 inspection and caches the results in the guest handle.  Subsequent
575 calls to C<guestfs_inspect_get_*> return this cached information, but
576 I<do not> re-read the disks.  If you change the content of the guest
577 disks, you can redo inspection by calling L</guestfs_inspect_os>
578 again.
579
580 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
581
582 Libguestfs can mount NTFS partitions.  It does this using the
583 L<http://www.ntfs-3g.org/> driver.
584
585 DOS and Windows still use drive letters, and the filesystems are
586 always treated as case insensitive by Windows itself, and therefore
587 you might find a Windows configuration file referring to a path like
588 C<c:\windows\system32>.  When the filesystem is mounted in libguestfs,
589 that directory might be referred to as C</WINDOWS/System32>.
590
591 Drive letter mappings are outside the scope of libguestfs.  You have
592 to use libguestfs to read the appropriate Windows Registry and
593 configuration files, to determine yourself how drives are mapped (see
594 also L<hivex(3)> and L<virt-inspector(1)>).
595
596 Replacing backslash characters with forward slash characters is also
597 outside the scope of libguestfs, but something that you can easily do.
598
599 Where we can help is in resolving the case insensitivity of paths.
600 For this, call L</guestfs_case_sensitive_path>.
601
602 Libguestfs also provides some help for decoding Windows Registry
603 "hive" files, through the library C<hivex> which is part of the
604 libguestfs project although ships as a separate tarball.  You have to
605 locate and download the hive file(s) yourself, and then pass them to
606 C<hivex> functions.  See also the programs L<hivexml(1)>,
607 L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-reg(1)> for more help
608 on this issue.
609
610 =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
611
612 Although we don't want to discourage you from using the C API, we will
613 mention here that the same API is also available in other languages.
614
615 The API is broadly identical in all supported languages.  This means
616 that the C call C<guestfs_mount(g,path)> is
617 C<$g-E<gt>mount($path)> in Perl, C<g.mount(path)> in Python,
618 and C<Guestfs.mount g path> in OCaml.  In other words, a
619 straightforward, predictable isomorphism between each language.
620
621 Error messages are automatically transformed
622 into exceptions if the language supports it.
623
624 We don't try to "object orientify" parts of the API in OO languages,
625 although contributors are welcome to write higher level APIs above
626 what we provide in their favourite languages if they wish.
627
628 =over 4
629
630 =item B<C++>
631
632 You can use the I<guestfs.h> header file from C++ programs.  The C++
633 API is identical to the C API.  C++ classes and exceptions are not
634 used.
635
636 =item B<C#>
637
638 The C# bindings are highly experimental.  Please read the warnings
639 at the top of C<csharp/Libguestfs.cs>.
640
641 =item B<Haskell>
642
643 This is the only language binding that is working but incomplete.
644 Only calls which return simple integers have been bound in Haskell,
645 and we are looking for help to complete this binding.
646
647 =item B<Java>
648
649 Full documentation is contained in the Javadoc which is distributed
650 with libguestfs.
651
652 =item B<OCaml>
653
654 For documentation see the file C<guestfs.mli>.
655
656 =item B<Perl>
657
658 For documentation see L<Sys::Guestfs(3)>.
659
660 =item B<PHP>
661
662 For documentation see C<README-PHP> supplied with libguestfs
663 sources or in the php-libguestfs package for your distribution.
664
665 The PHP binding only works correctly on 64 bit machines.
666
667 =item B<Python>
668
669 For documentation do:
670
671  $ python
672  >>> import guestfs
673  >>> help (guestfs)
674
675 =item B<Ruby>
676
677 Use the Guestfs module.  There is no Ruby-specific documentation, but
678 you can find examples written in Ruby in the libguestfs source.
679
680 =item B<shell scripts>
681
682 For documentation see L<guestfish(1)>.
683
684 =back
685
686 =head2 LIBGUESTFS GOTCHAS
687
688 L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: "A feature of a
689 system [...] that works in the way it is documented but is
690 counterintuitive and almost invites mistakes."
691
692 Since we developed libguestfs and the associated tools, there are
693 several things we would have designed differently, but are now stuck
694 with for backwards compatibility or other reasons.  If there is ever a
695 libguestfs 2.0 release, you can expect these to change.  Beware of
696 them.
697
698 =over 4
699
700 =item Autosync / forgetting to sync.
701
702 When modifying a filesystem from C or another language, you B<must>
703 unmount all filesystems and call L</guestfs_sync> explicitly before
704 you close the libguestfs handle.  You can also call:
705
706  guestfs_set_autosync (g, 1);
707
708 to have the unmount/sync done automatically for you when the handle 'g'
709 is closed.  (This feature is called "autosync", L</guestfs_set_autosync>
710 q.v.)
711
712 If you forget to do this, then it is entirely possible that your
713 changes won't be written out, or will be partially written, or (very
714 rarely) that you'll get disk corruption.
715
716 Note that in L<guestfish(3)> autosync is the default.  So quick and
717 dirty guestfish scripts that forget to sync will work just fine, which
718 can make this very puzzling if you are trying to debug a problem.
719
720 Update: Autosync is enabled by default for all API users starting from
721 libguestfs 1.5.24.
722
723 =item Mount option C<-o sync> should not be the default.
724
725 If you use L</guestfs_mount>, then C<-o sync,noatime> are added
726 implicitly.  However C<-o sync> does not add any reliability benefit,
727 but does have a very large performance impact.
728
729 The work around is to use L</guestfs_mount_options> and set the mount
730 options that you actually want to use.
731
732 =item Read-only should be the default.
733
734 In L<guestfish(3)>, I<--ro> should be the default, and you should
735 have to specify I<--rw> if you want to make changes to the image.
736
737 This would reduce the potential to corrupt live VM images.
738
739 Note that many filesystems change the disk when you just mount and
740 unmount, even if you didn't perform any writes.  You need to use
741 L</guestfs_add_drive_ro> to guarantee that the disk is not changed.
742
743 =item guestfish command line is hard to use.
744
745 C<guestfish disk.img> doesn't do what people expect (open C<disk.img>
746 for examination).  It tries to run a guestfish command C<disk.img>
747 which doesn't exist, so it fails.  In earlier versions of guestfish
748 the error message was also unintuitive, but we have corrected this
749 since.  Like the Bourne shell, we should have used C<guestfish -c
750 command> to run commands.
751
752 =item guestfish megabyte modifiers don't work right on all commands
753
754 In recent guestfish you can use C<1M> to mean 1 megabyte (and
755 similarly for other modifiers).  What guestfish actually does is to
756 multiply the number part by the modifier part and pass the result to
757 the C API.  However this doesn't work for a few APIs which aren't
758 expecting bytes, but are already expecting some other unit
759 (eg. megabytes).
760
761 The most common is L</guestfs_lvcreate>.  The guestfish command:
762
763  lvcreate LV VG 100M
764
765 does not do what you might expect.  Instead because
766 L</guestfs_lvcreate> is already expecting megabytes, this tries to
767 create a 100 I<terabyte> (100 megabytes * megabytes) logical volume.
768 The error message you get from this is also a little obscure.
769
770 This could be fixed in the generator by specially marking parameters
771 and return values which take bytes or other units.
772
773 =item Ambiguity between devices and paths
774
775 There is a subtle ambiguity in the API between a device name
776 (eg. C</dev/sdb2>) and a similar pathname.  A file might just happen
777 to be called C<sdb2> in the directory C</dev> (consider some non-Unix
778 VM image).
779
780 In the current API we usually resolve this ambiguity by having two
781 separate calls, for example L</guestfs_checksum> and
782 L</guestfs_checksum_device>.  Some API calls are ambiguous and
783 (incorrectly) resolve the problem by detecting if the path supplied
784 begins with C</dev/>.
785
786 To avoid both the ambiguity and the need to duplicate some calls, we
787 could make paths/devices into structured names.  One way to do this
788 would be to use a notation like grub (C<hd(0,0)>), although nobody
789 really likes this aspect of grub.  Another way would be to use a
790 structured type, equivalent to this OCaml type:
791
792  type path = Path of string | Device of int | Partition of int * int
793
794 which would allow you to pass arguments like:
795
796  Path "/foo/bar"
797  Device 1            (* /dev/sdb, or perhaps /dev/sda *)
798  Partition (1, 2)    (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
799  Path "/dev/sdb2"    (* not a device *)
800
801 As you can see there are still problems to resolve even with this
802 representation.  Also consider how it might work in guestfish.
803
804 =back
805
806 =head2 PROTOCOL LIMITS
807
808 Internally libguestfs uses a message-based protocol to pass API calls
809 and their responses to and from a small "appliance" (see L</INTERNALS>
810 for plenty more detail about this).  The maximum message size used by
811 the protocol is slightly less than 4 MB.  For some API calls you may
812 need to be aware of this limit.  The API calls which may be affected
813 are individually documented, with a link back to this section of the
814 documentation.
815
816 A simple call such as L</guestfs_cat> returns its result (the file
817 data) in a simple string.  Because this string is at some point
818 internally encoded as a message, the maximum size that it can return
819 is slightly under 4 MB.  If the requested file is larger than this
820 then you will get an error.
821
822 In order to transfer large files into and out of the guest filesystem,
823 you need to use particular calls that support this.  The sections
824 L</UPLOADING> and L</DOWNLOADING> document how to do this.
825
826 You might also consider mounting the disk image using our FUSE
827 filesystem support (L<guestmount(1)>).
828
829 =head2 KEYS AND PASSPHRASES
830
831 Certain libguestfs calls take a parameter that contains sensitive key
832 material, passed in as a C string.
833
834 In the future we would hope to change the libguestfs implementation so
835 that keys are L<mlock(2)>-ed into physical RAM, and thus can never end
836 up in swap.  However this is I<not> done at the moment, because of the
837 complexity of such an implementation.
838
839 Therefore you should be aware that any key parameter you pass to
840 libguestfs might end up being written out to the swap partition.  If
841 this is a concern, scrub the swap partition or don't use libguestfs on
842 encrypted devices.
843
844 =head1 CONNECTION MANAGEMENT
845
846 =head2 guestfs_h *
847
848 C<guestfs_h> is the opaque type representing a connection handle.
849 Create a handle by calling L</guestfs_create>.  Call L</guestfs_close>
850 to free the handle and release all resources used.
851
852 For information on using multiple handles and threads, see the section
853 L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
854
855 =head2 guestfs_create
856
857  guestfs_h *guestfs_create (void);
858
859 Create a connection handle.
860
861 You have to call L</guestfs_add_drive_opts> (or one of the equivalent
862 calls) on the handle at least once.
863
864 This function returns a non-NULL pointer to a handle on success or
865 NULL on error.
866
867 After configuring the handle, you have to call L</guestfs_launch>.
868
869 You may also want to configure error handling for the handle.  See
870 L</ERROR HANDLING> section below.
871
872 =head2 guestfs_close
873
874  void guestfs_close (guestfs_h *g);
875
876 This closes the connection handle and frees up all resources used.
877
878 =head1 ERROR HANDLING
879
880 API functions can return errors.  For example, almost all functions
881 that return C<int> will return C<-1> to indicate an error.
882
883 Additional information is available for errors: an error message
884 string and optionally an error number (errno) if the thing that failed
885 was a system call.
886
887 You can get at the additional information about the last error on the
888 handle by calling L</guestfs_last_error>, L</guestfs_last_errno>,
889 and/or by setting up an error handler with
890 L</guestfs_set_error_handler>.
891
892 When the handle is created, a default error handler is installed which
893 prints the error message string to C<stderr>.  For small short-running
894 command line programs it is sufficient to do:
895
896  if (guestfs_launch (g) == -1)
897    exit (EXIT_FAILURE);
898
899 since the default error handler will ensure that an error message has
900 been printed to C<stderr> before the program exits.
901
902 For other programs the caller will almost certainly want to install an
903 alternate error handler or do error handling in-line like this:
904
905  g = guestfs_create ();
906  
907  /* This disables the default behaviour of printing errors
908     on stderr. */
909  guestfs_set_error_handler (g, NULL, NULL);
910  
911  if (guestfs_launch (g) == -1) {
912    /* Examine the error message and print it etc. */
913    char *msg = guestfs_last_error (g);
914    int errnum = guestfs_last_errno (g);
915    fprintf (stderr, "%s\n", msg);
916    /* ... */
917   }
918
919 Out of memory errors are handled differently.  The default action is
920 to call L<abort(3)>.  If this is undesirable, then you can set a
921 handler using L</guestfs_set_out_of_memory_handler>.
922
923 L</guestfs_create> returns C<NULL> if the handle cannot be created,
924 and because there is no handle if this happens there is no way to get
925 additional error information.  However L</guestfs_create> is supposed
926 to be a lightweight operation which can only fail because of
927 insufficient memory (it returns NULL in this case).
928
929 =head2 guestfs_last_error
930
931  const char *guestfs_last_error (guestfs_h *g);
932
933 This returns the last error message that happened on C<g>.  If
934 there has not been an error since the handle was created, then this
935 returns C<NULL>.
936
937 The lifetime of the returned string is until the next error occurs, or
938 L</guestfs_close> is called.
939
940 =head2 guestfs_last_errno
941
942  int guestfs_last_errno (guestfs_h *g);
943
944 This returns the last error number (errno) that happened on C<g>.
945
946 If successful, an errno integer not equal to zero is returned.
947
948 If no error, this returns 0.  This call can return 0 in three
949 situations:
950
951 =over 4
952
953 =item 1.
954
955 There has not been any error on the handle.
956
957 =item 2.
958
959 There has been an error but the errno was meaningless.  This
960 corresponds to the case where the error did not come from a
961 failed system call, but for some other reason.
962
963 =item 3.
964
965 There was an error from a failed system call, but for some
966 reason the errno was not captured and returned.  This usually
967 indicates a bug in libguestfs.
968
969 =back
970
971 Libguestfs tries to convert the errno from inside the applicance into
972 a corresponding errno for the caller (not entirely trivial: the
973 appliance might be running a completely different operating system
974 from the library and error numbers are not standardized across
975 Un*xen).  If this could not be done, then the error is translated to
976 C<EINVAL>.  In practice this should only happen in very rare
977 circumstances.
978
979 =head2 guestfs_set_error_handler
980
981  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
982                                            void *opaque,
983                                            const char *msg);
984  void guestfs_set_error_handler (guestfs_h *g,
985                                  guestfs_error_handler_cb cb,
986                                  void *opaque);
987
988 The callback C<cb> will be called if there is an error.  The
989 parameters passed to the callback are an opaque data pointer and the
990 error message string.
991
992 C<errno> is not passed to the callback.  To get that the callback must
993 call L</guestfs_last_errno>.
994
995 Note that the message string C<msg> is freed as soon as the callback
996 function returns, so if you want to stash it somewhere you must make
997 your own copy.
998
999 The default handler prints messages on C<stderr>.
1000
1001 If you set C<cb> to C<NULL> then I<no> handler is called.
1002
1003 =head2 guestfs_get_error_handler
1004
1005  guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1006                                                      void **opaque_rtn);
1007
1008 Returns the current error handler callback.
1009
1010 =head2 guestfs_set_out_of_memory_handler
1011
1012  typedef void (*guestfs_abort_cb) (void);
1013  int guestfs_set_out_of_memory_handler (guestfs_h *g,
1014                                         guestfs_abort_cb);
1015
1016 The callback C<cb> will be called if there is an out of memory
1017 situation.  I<Note this callback must not return>.
1018
1019 The default is to call L<abort(3)>.
1020
1021 You cannot set C<cb> to C<NULL>.  You can't ignore out of memory
1022 situations.
1023
1024 =head2 guestfs_get_out_of_memory_handler
1025
1026  guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1027
1028 This returns the current out of memory handler.
1029
1030 =head1 PATH
1031
1032 Libguestfs needs a kernel and initrd.img, which it finds by looking
1033 along an internal path.
1034
1035 By default it looks for these in the directory C<$libdir/guestfs>
1036 (eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
1037
1038 Use L</guestfs_set_path> or set the environment variable
1039 L</LIBGUESTFS_PATH> to change the directories that libguestfs will
1040 search in.  The value is a colon-separated list of paths.  The current
1041 directory is I<not> searched unless the path contains an empty element
1042 or C<.>.  For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
1043 search the current directory and then C</usr/lib/guestfs>.
1044
1045 =head1 HIGH-LEVEL API ACTIONS
1046
1047 =head2 ABI GUARANTEE
1048
1049 We guarantee the libguestfs ABI (binary interface), for public,
1050 high-level actions as outlined in this section.  Although we will
1051 deprecate some actions, for example if they get replaced by newer
1052 calls, we will keep the old actions forever.  This allows you the
1053 developer to program in confidence against the libguestfs API.
1054
1055 @ACTIONS@
1056
1057 =head1 STRUCTURES
1058
1059 @STRUCTS@
1060
1061 =head1 AVAILABILITY
1062
1063 =head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
1064
1065 Using L</guestfs_available> you can test availability of
1066 the following groups of functions.  This test queries the
1067 appliance to see if the appliance you are currently using
1068 supports the functionality.
1069
1070 @AVAILABILITY@
1071
1072 =head2 GUESTFISH supported COMMAND
1073
1074 In L<guestfish(3)> there is a handy interactive command
1075 C<supported> which prints out the available groups and
1076 whether they are supported by this build of libguestfs.
1077 Note however that you have to do C<run> first.
1078
1079 =head2 SINGLE CALLS AT COMPILE TIME
1080
1081 Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols
1082 for each C API function, such as:
1083
1084  #define LIBGUESTFS_HAVE_DD 1
1085
1086 if L</guestfs_dd> is available.
1087
1088 Before version 1.5.8, if you needed to test whether a single
1089 libguestfs function is available at compile time, we recommended using
1090 build tools such as autoconf or cmake.  For example in autotools you
1091 could use:
1092
1093  AC_CHECK_LIB([guestfs],[guestfs_create])
1094  AC_CHECK_FUNCS([guestfs_dd])
1095
1096 which would result in C<HAVE_GUESTFS_DD> being either defined
1097 or not defined in your program.
1098
1099 =head2 SINGLE CALLS AT RUN TIME
1100
1101 Testing at compile time doesn't guarantee that a function really
1102 exists in the library.  The reason is that you might be dynamically
1103 linked against a previous I<libguestfs.so> (dynamic library)
1104 which doesn't have the call.  This situation unfortunately results
1105 in a segmentation fault, which is a shortcoming of the C dynamic
1106 linking system itself.
1107
1108 You can use L<dlopen(3)> to test if a function is available
1109 at run time, as in this example program (note that you still
1110 need the compile time check as well):
1111
1112  #include <stdio.h>
1113  #include <stdlib.h>
1114  #include <unistd.h>
1115  #include <dlfcn.h>
1116  #include <guestfs.h>
1117  
1118  main ()
1119  {
1120  #ifdef LIBGUESTFS_HAVE_DD
1121    void *dl;
1122    int has_function;
1123  
1124    /* Test if the function guestfs_dd is really available. */
1125    dl = dlopen (NULL, RTLD_LAZY);
1126    if (!dl) {
1127      fprintf (stderr, "dlopen: %s\n", dlerror ());
1128      exit (EXIT_FAILURE);
1129    }
1130    has_function = dlsym (dl, "guestfs_dd") != NULL;
1131    dlclose (dl);
1132  
1133    if (!has_function)
1134      printf ("this libguestfs.so does NOT have guestfs_dd function\n");
1135    else {
1136      printf ("this libguestfs.so has guestfs_dd function\n");
1137      /* Now it's safe to call
1138      guestfs_dd (g, "foo", "bar");
1139      */
1140    }
1141  #else
1142    printf ("guestfs_dd function was not found at compile time\n");
1143  #endif
1144   }
1145
1146 You may think the above is an awful lot of hassle, and it is.
1147 There are other ways outside of the C linking system to ensure
1148 that this kind of incompatibility never arises, such as using
1149 package versioning:
1150
1151  Requires: libguestfs >= 1.0.80
1152
1153 =head1 CALLS WITH OPTIONAL ARGUMENTS
1154
1155 A recent feature of the API is the introduction of calls which take
1156 optional arguments.  In C these are declared 3 ways.  The main way is
1157 as a call which takes variable arguments (ie. C<...>), as in this
1158 example:
1159
1160  int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
1161
1162 Call this with a list of optional arguments, terminated by C<-1>.
1163 So to call with no optional arguments specified:
1164
1165  guestfs_add_drive_opts (g, filename, -1);
1166
1167 With a single optional argument:
1168
1169  guestfs_add_drive_opts (g, filename,
1170                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
1171                          -1);
1172
1173 With two:
1174
1175  guestfs_add_drive_opts (g, filename,
1176                          GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
1177                          GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
1178                          -1);
1179
1180 and so forth.  Don't forget the terminating C<-1> otherwise
1181 Bad Things will happen!
1182
1183 =head2 USING va_list FOR OPTIONAL ARGUMENTS
1184
1185 The second variant has the same name with the suffix C<_va>, which
1186 works the same way but takes a C<va_list>.  See the C manual for
1187 details.  For the example function, this is declared:
1188
1189  int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
1190                                 va_list args);
1191
1192 =head2 CONSTRUCTING OPTIONAL ARGUMENTS
1193
1194 The third variant is useful where you need to construct these
1195 calls.  You pass in a structure where you fill in the optional
1196 fields.  The structure has a bitmask as the first element which
1197 you must set to indicate which fields you have filled in.  For
1198 our example function the structure and call are declared:
1199
1200  struct guestfs_add_drive_opts_argv {
1201    uint64_t bitmask;
1202    int readonly;
1203    const char *format;
1204    /* ... */
1205  };
1206  int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
1207               const struct guestfs_add_drive_opts_argv *optargs);
1208
1209 You could call it like this:
1210
1211  struct guestfs_add_drive_opts_argv optargs = {
1212    .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
1213               GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
1214    .readonly = 1,
1215    .format = "qcow2"
1216  };
1217  
1218  guestfs_add_drive_opts_argv (g, filename, &optargs);
1219
1220 Notes:
1221
1222 =over 4
1223
1224 =item *
1225
1226 The C<_BITMASK> suffix on each option name when specifying the
1227 bitmask.
1228
1229 =item *
1230
1231 You do not need to fill in all fields of the structure.
1232
1233 =item *
1234
1235 There must be a one-to-one correspondence between fields of the
1236 structure that are filled in, and bits set in the bitmask.
1237
1238 =back
1239
1240 =head2 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
1241
1242 In other languages, optional arguments are expressed in the
1243 way that is natural for that language.  We refer you to the
1244 language-specific documentation for more details on that.
1245
1246 For guestfish, see L<guestfish(1)/OPTIONAL ARGUMENTS>.
1247
1248 =begin html
1249
1250 <!-- old anchor for the next section -->
1251 <a name="state_machine_and_low_level_event_api"/>
1252
1253 =end html
1254
1255 =head1 ARCHITECTURE
1256
1257 Internally, libguestfs is implemented by running an appliance (a
1258 special type of small virtual machine) using L<qemu(1)>.  Qemu runs as
1259 a child process of the main program.
1260
1261   ___________________
1262  /                   \
1263  | main program      |
1264  |                   |
1265  |                   |           child process / appliance
1266  |                   |           __________________________
1267  |                   |          / qemu                     \
1268  +-------------------+   RPC    |      +-----------------+ |
1269  | libguestfs     <--------------------> guestfsd        | |
1270  |                   |          |      +-----------------+ |
1271  \___________________/          |      | Linux kernel    | |
1272                                 |      +--^--------------+ |
1273                                 \_________|________________/
1274                                           |
1275                                    _______v______
1276                                   /              \
1277                                   | Device or    |
1278                                   | disk image   |
1279                                   \______________/
1280
1281 The library, linked to the main program, creates the child process and
1282 hence the appliance in the L</guestfs_launch> function.
1283
1284 Inside the appliance is a Linux kernel and a complete stack of
1285 userspace tools (such as LVM and ext2 programs) and a small
1286 controlling daemon called L</guestfsd>.  The library talks to
1287 L</guestfsd> using remote procedure calls (RPC).  There is a mostly
1288 one-to-one correspondence between libguestfs API calls and RPC calls
1289 to the daemon.  Lastly the disk image(s) are attached to the qemu
1290 process which translates device access by the appliance's Linux kernel
1291 into accesses to the image.
1292
1293 A common misunderstanding is that the appliance "is" the virtual
1294 machine.  Although the disk image you are attached to might also be
1295 used by some virtual machine, libguestfs doesn't know or care about
1296 this.  (But you will care if both libguestfs's qemu process and your
1297 virtual machine are trying to update the disk image at the same time,
1298 since these usually results in massive disk corruption).
1299
1300 =head1 STATE MACHINE
1301
1302 libguestfs uses a state machine to model the child process:
1303
1304                          |
1305                     guestfs_create
1306                          |
1307                          |
1308                      ____V_____
1309                     /          \
1310                     |  CONFIG  |
1311                     \__________/
1312                      ^ ^   ^  \
1313                     /  |    \  \ guestfs_launch
1314                    /   |    _\__V______
1315                   /    |   /           \
1316                  /     |   | LAUNCHING |
1317                 /      |   \___________/
1318                /       |       /
1319               /        |  guestfs_launch
1320              /         |     /
1321     ______  /        __|____V
1322    /      \ ------> /        \
1323    | BUSY |         | READY  |
1324    \______/ <------ \________/
1325
1326 The normal transitions are (1) CONFIG (when the handle is created, but
1327 there is no child process), (2) LAUNCHING (when the child process is
1328 booting up), (3) alternating between READY and BUSY as commands are
1329 issued to, and carried out by, the child process.
1330
1331 The guest may be killed by L</guestfs_kill_subprocess>, or may die
1332 asynchronously at any time (eg. due to some internal error), and that
1333 causes the state to transition back to CONFIG.
1334
1335 Configuration commands for qemu such as L</guestfs_add_drive> can only
1336 be issued when in the CONFIG state.
1337
1338 The API offers one call that goes from CONFIG through LAUNCHING to
1339 READY.  L</guestfs_launch> blocks until the child process is READY to
1340 accept commands (or until some failure or timeout).
1341 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
1342 while it is running.
1343
1344 API actions such as L</guestfs_mount> can only be issued when in the
1345 READY state.  These API calls block waiting for the command to be
1346 carried out (ie. the state to transition to BUSY and then back to
1347 READY).  There are no non-blocking versions, and no way to issue more
1348 than one command per handle at the same time.
1349
1350 Finally, the child process sends asynchronous messages back to the
1351 main program, such as kernel log messages.  You can register a
1352 callback to receive these messages.
1353
1354 =head2 SETTING CALLBACKS TO HANDLE EVENTS
1355
1356 The child process generates events in some situations.  Current events
1357 include: receiving a log message, the child process exits.
1358
1359 Use the C<guestfs_set_*_callback> functions to set a callback for
1360 different types of events.
1361
1362 Only I<one callback of each type> can be registered for each handle.
1363 Calling C<guestfs_set_*_callback> again overwrites the previous
1364 callback of that type.  Cancel all callbacks of this type by calling
1365 this function with C<cb> set to C<NULL>.
1366
1367 =head2 guestfs_set_log_message_callback
1368
1369  typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
1370                                          char *buf, int len);
1371  void guestfs_set_log_message_callback (guestfs_h *g,
1372                                         guestfs_log_message_cb cb,
1373                                         void *opaque);
1374
1375 The callback function C<cb> will be called whenever qemu or the guest
1376 writes anything to the console.
1377
1378 Use this function to capture kernel messages and similar.
1379
1380 Normally there is no log message handler, and log messages are just
1381 discarded.
1382
1383 =head2 guestfs_set_subprocess_quit_callback
1384
1385  typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);
1386  void guestfs_set_subprocess_quit_callback (guestfs_h *g,
1387                                             guestfs_subprocess_quit_cb cb,
1388                                             void *opaque);
1389
1390 The callback function C<cb> will be called when the child process
1391 quits, either asynchronously or if killed by
1392 L</guestfs_kill_subprocess>.  (This corresponds to a transition from
1393 any state to the CONFIG state).
1394
1395 =head2 guestfs_set_launch_done_callback
1396
1397  typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
1398  void guestfs_set_launch_done_callback (guestfs_h *g,
1399                                         guestfs_launch_done_cb cb,
1400                                         void *opaque);
1401
1402 The callback function C<cb> will be called when the child process
1403 becomes ready first time after it has been launched.  (This
1404 corresponds to a transition from LAUNCHING to the READY state).
1405
1406 =head2 guestfs_set_close_callback
1407
1408  typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);
1409  void guestfs_set_close_callback (guestfs_h *g,
1410                                   guestfs_close_cb cb,
1411                                   void *opaque);
1412
1413 The callback function C<cb> will be called while the handle
1414 is being closed (synchronously from L</guestfs_close>).
1415
1416 Note that libguestfs installs an L<atexit(3)> handler to try to
1417 clean up handles that are open when the program exits.  This
1418 means that this callback might be called indirectly from
1419 L<exit(3)>, which can cause unexpected problems in higher-level
1420 languages (eg. if your HLL interpreter has already been cleaned
1421 up by the time this is called, and if your callback then jumps
1422 into some HLL function).
1423
1424 =head2 guestfs_set_progress_callback
1425
1426  typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque,
1427                                       int proc_nr, int serial,
1428                                       uint64_t position, uint64_t total);
1429  void guestfs_set_progress_callback (guestfs_h *g,
1430                                      guestfs_progress_cb cb,
1431                                      void *opaque);
1432
1433 Some long-running operations can generate progress messages.  If
1434 this callback is registered, then it will be called each time a
1435 progress message is generated (usually two seconds after the
1436 operation started, and three times per second thereafter until
1437 it completes, although the frequency may change in future versions).
1438
1439 The callback receives two numbers: C<position> and C<total>.
1440 The units of C<total> are not defined, although for some
1441 operations C<total> may relate in some way to the amount of
1442 data to be transferred (eg. in bytes or megabytes), and
1443 C<position> may be the portion which has been transferred.
1444
1445 The only defined and stable parts of the API are:
1446
1447 =over 4
1448
1449 =item *
1450
1451 The callback can display to the user some type of progress bar or
1452 indicator which shows the ratio of C<position>:C<total>.
1453
1454 =item *
1455
1456 0 E<lt>= C<position> E<lt>= C<total>
1457
1458 =item *
1459
1460 If any progress notification is sent during a call, then a final
1461 progress notification is always sent when C<position> = C<total>.
1462
1463 This is to simplify caller code, so callers can easily set the
1464 progress indicator to "100%" at the end of the operation, without
1465 requiring special code to detect this case.
1466
1467 =back
1468
1469 The callback also receives the procedure number and serial number of
1470 the call.  These are only useful for debugging protocol issues, and
1471 the callback can normally ignore them.  The callback may want to
1472 print these numbers in error messages or debugging messages.
1473
1474 =head1 PRIVATE DATA AREA
1475
1476 You can attach named pieces of private data to the libguestfs handle,
1477 and fetch them by name for the lifetime of the handle.  This is called
1478 the private data area and is only available from the C API.
1479
1480 To attach a named piece of data, use the following call:
1481
1482  void guestfs_set_private (guestfs_h *g, const char *key, void *data);
1483
1484 C<key> is the name to associate with this data, and C<data> is an
1485 arbitrary pointer (which can be C<NULL>).  Any previous item with the
1486 same name is overwritten.
1487
1488 You can use any C<key> you want, but names beginning with an
1489 underscore character are reserved for internal libguestfs purposes
1490 (for implementing language bindings).  It is recommended to prefix the
1491 name with some unique string to avoid collisions with other users.
1492
1493 To retrieve the pointer, use:
1494
1495  void *guestfs_get_private (guestfs_h *g, const char *key);
1496
1497 This function returns C<NULL> if either no data is found associated
1498 with C<key>, or if the user previously set the C<key>'s C<data>
1499 pointer to C<NULL>.
1500
1501 Libguestfs does not try to look at or interpret the C<data> pointer in
1502 any way.  As far as libguestfs is concerned, it need not be a valid
1503 pointer at all.  In particular, libguestfs does I<not> try to free the
1504 data when the handle is closed.  If the data must be freed, then the
1505 caller must either free it before calling L</guestfs_close> or must
1506 set up a close callback to do it (see L</guestfs_set_close_callback>,
1507 and note that only one callback can be registered for a handle).
1508
1509 The private data area is implemented using a hash table, and should be
1510 reasonably efficient for moderate numbers of keys.
1511
1512 =head1 BLOCK DEVICE NAMING
1513
1514 In the kernel there is now quite a profusion of schemata for naming
1515 block devices (in this context, by I<block device> I mean a physical
1516 or virtual hard drive).  The original Linux IDE driver used names
1517 starting with C</dev/hd*>.  SCSI devices have historically used a
1518 different naming scheme, C</dev/sd*>.  When the Linux kernel I<libata>
1519 driver became a popular replacement for the old IDE driver
1520 (particularly for SATA devices) those devices also used the
1521 C</dev/sd*> scheme.  Additionally we now have virtual machines with
1522 paravirtualized drivers.  This has created several different naming
1523 systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
1524 PV disks.
1525
1526 As discussed above, libguestfs uses a qemu appliance running an
1527 embedded Linux kernel to access block devices.  We can run a variety
1528 of appliances based on a variety of Linux kernels.
1529
1530 This causes a problem for libguestfs because many API calls use device
1531 or partition names.  Working scripts and the recipe (example) scripts
1532 that we make available over the internet could fail if the naming
1533 scheme changes.
1534
1535 Therefore libguestfs defines C</dev/sd*> as the I<standard naming
1536 scheme>.  Internally C</dev/sd*> names are translated, if necessary,
1537 to other names as required.  For example, under RHEL 5 which uses the
1538 C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
1539 C</dev/hda2> transparently.
1540
1541 Note that this I<only> applies to parameters.  The
1542 L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
1543 return the true names of the devices and partitions as known to the
1544 appliance.
1545
1546 =head2 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
1547
1548 Usually this translation is transparent.  However in some (very rare)
1549 cases you may need to know the exact algorithm.  Such cases include
1550 where you use L</guestfs_config> to add a mixture of virtio and IDE
1551 devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
1552 and C</dev/vd*> devices.
1553
1554 The algorithm is applied only to I<parameters> which are known to be
1555 either device or partition names.  Return values from functions such
1556 as L</guestfs_list_devices> are never changed.
1557
1558 =over 4
1559
1560 =item *
1561
1562 Is the string a parameter which is a device or partition name?
1563
1564 =item *
1565
1566 Does the string begin with C</dev/sd>?
1567
1568 =item *
1569
1570 Does the named device exist?  If so, we use that device.
1571 However if I<not> then we continue with this algorithm.
1572
1573 =item *
1574
1575 Replace initial C</dev/sd> string with C</dev/hd>.
1576
1577 For example, change C</dev/sda2> to C</dev/hda2>.
1578
1579 If that named device exists, use it.  If not, continue.
1580
1581 =item *
1582
1583 Replace initial C</dev/sd> string with C</dev/vd>.
1584
1585 If that named device exists, use it.  If not, return an error.
1586
1587 =back
1588
1589 =head2 PORTABILITY CONCERNS
1590
1591 Although the standard naming scheme and automatic translation is
1592 useful for simple programs and guestfish scripts, for larger programs
1593 it is best not to rely on this mechanism.
1594
1595 Where possible for maximum future portability programs using
1596 libguestfs should use these future-proof techniques:
1597
1598 =over 4
1599
1600 =item *
1601
1602 Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list
1603 actual device names, and then use those names directly.
1604
1605 Since those device names exist by definition, they will never be
1606 translated.
1607
1608 =item *
1609
1610 Use higher level ways to identify filesystems, such as LVM names,
1611 UUIDs and filesystem labels.
1612
1613 =back
1614
1615 =head1 INTERNALS
1616
1617 =head2 COMMUNICATION PROTOCOL
1618
1619 Don't rely on using this protocol directly.  This section documents
1620 how it currently works, but it may change at any time.
1621
1622 The protocol used to talk between the library and the daemon running
1623 inside the qemu virtual machine is a simple RPC mechanism built on top
1624 of XDR (RFC 1014, RFC 1832, RFC 4506).
1625
1626 The detailed format of structures is in C<src/guestfs_protocol.x>
1627 (note: this file is automatically generated).
1628
1629 There are two broad cases, ordinary functions that don't have any
1630 C<FileIn> and C<FileOut> parameters, which are handled with very
1631 simple request/reply messages.  Then there are functions that have any
1632 C<FileIn> or C<FileOut> parameters, which use the same request and
1633 reply messages, but they may also be followed by files sent using a
1634 chunked encoding.
1635
1636 =head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)
1637
1638 For ordinary functions, the request message is:
1639
1640  total length (header + arguments,
1641       but not including the length word itself)
1642  struct guestfs_message_header (encoded as XDR)
1643  struct guestfs_<foo>_args (encoded as XDR)
1644
1645 The total length field allows the daemon to allocate a fixed size
1646 buffer into which it slurps the rest of the message.  As a result, the
1647 total length is limited to C<GUESTFS_MESSAGE_MAX> bytes (currently
1648 4MB), which means the effective size of any request is limited to
1649 somewhere under this size.
1650
1651 Note also that many functions don't take any arguments, in which case
1652 the C<guestfs_I<foo>_args> is completely omitted.
1653
1654 The header contains the procedure number (C<guestfs_proc>) which is
1655 how the receiver knows what type of args structure to expect, or none
1656 at all.
1657
1658 The reply message for ordinary functions is:
1659
1660  total length (header + ret,
1661       but not including the length word itself)
1662  struct guestfs_message_header (encoded as XDR)
1663  struct guestfs_<foo>_ret (encoded as XDR)
1664
1665 As above the C<guestfs_I<foo>_ret> structure may be completely omitted
1666 for functions that return no formal return values.
1667
1668 As above the total length of the reply is limited to
1669 C<GUESTFS_MESSAGE_MAX>.
1670
1671 In the case of an error, a flag is set in the header, and the reply
1672 message is slightly changed:
1673
1674  total length (header + error,
1675       but not including the length word itself)
1676  struct guestfs_message_header (encoded as XDR)
1677  struct guestfs_message_error (encoded as XDR)
1678
1679 The C<guestfs_message_error> structure contains the error message as a
1680 string.
1681
1682 =head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS
1683
1684 A C<FileIn> parameter indicates that we transfer a file I<into> the
1685 guest.  The normal request message is sent (see above).  However this
1686 is followed by a sequence of file chunks.
1687
1688  total length (header + arguments,
1689       but not including the length word itself,
1690       and not including the chunks)
1691  struct guestfs_message_header (encoded as XDR)
1692  struct guestfs_<foo>_args (encoded as XDR)
1693  sequence of chunks for FileIn param #0
1694  sequence of chunks for FileIn param #1 etc.
1695
1696 The "sequence of chunks" is:
1697
1698  length of chunk (not including length word itself)
1699  struct guestfs_chunk (encoded as XDR)
1700  length of chunk
1701  struct guestfs_chunk (encoded as XDR)
1702    ...
1703  length of chunk
1704  struct guestfs_chunk (with data.data_len == 0)
1705
1706 The final chunk has the C<data_len> field set to zero.  Additionally a
1707 flag is set in the final chunk to indicate either successful
1708 completion or early cancellation.
1709
1710 At time of writing there are no functions that have more than one
1711 FileIn parameter.  However this is (theoretically) supported, by
1712 sending the sequence of chunks for each FileIn parameter one after
1713 another (from left to right).
1714
1715 Both the library (sender) I<and> the daemon (receiver) may cancel the
1716 transfer.  The library does this by sending a chunk with a special
1717 flag set to indicate cancellation.  When the daemon sees this, it
1718 cancels the whole RPC, does I<not> send any reply, and goes back to
1719 reading the next request.
1720
1721 The daemon may also cancel.  It does this by writing a special word
1722 C<GUESTFS_CANCEL_FLAG> to the socket.  The library listens for this
1723 during the transfer, and if it gets it, it will cancel the transfer
1724 (it sends a cancel chunk).  The special word is chosen so that even if
1725 cancellation happens right at the end of the transfer (after the
1726 library has finished writing and has started listening for the reply),
1727 the "spurious" cancel flag will not be confused with the reply
1728 message.
1729
1730 This protocol allows the transfer of arbitrary sized files (no 32 bit
1731 limit), and also files where the size is not known in advance
1732 (eg. from pipes or sockets).  However the chunks are rather small
1733 (C<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the
1734 daemon need to keep much in memory.
1735
1736 =head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS
1737
1738 The protocol for FileOut parameters is exactly the same as for FileIn
1739 parameters, but with the roles of daemon and library reversed.
1740
1741  total length (header + ret,
1742       but not including the length word itself,
1743       and not including the chunks)
1744  struct guestfs_message_header (encoded as XDR)
1745  struct guestfs_<foo>_ret (encoded as XDR)
1746  sequence of chunks for FileOut param #0
1747  sequence of chunks for FileOut param #1 etc.
1748
1749 =head3 INITIAL MESSAGE
1750
1751 When the daemon launches it sends an initial word
1752 (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest and daemon is
1753 alive.  This is what L</guestfs_launch> waits for.
1754
1755 =head3 PROGRESS NOTIFICATION MESSAGES
1756
1757 The daemon may send progress notification messages at any time.  These
1758 are distinguished by the normal length word being replaced by
1759 C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message.
1760
1761 The library turns them into progress callbacks (see
1762 C<guestfs_set_progress_callback>) if there is a callback registered,
1763 or discards them if not.
1764
1765 The daemon self-limits the frequency of progress messages it sends
1766 (see C<daemon/proto.c:notify_progress>).  Not all calls generate
1767 progress messages.
1768
1769 =head1 MULTIPLE HANDLES AND MULTIPLE THREADS
1770
1771 All high-level libguestfs actions are synchronous.  If you want
1772 to use libguestfs asynchronously then you must create a thread.
1773
1774 Only use the handle from a single thread.  Either use the handle
1775 exclusively from one thread, or provide your own mutex so that two
1776 threads cannot issue calls on the same handle at the same time.
1777
1778 See the graphical program guestfs-browser for one possible
1779 architecture for multithreaded programs using libvirt and libguestfs.
1780
1781 =head1 QEMU WRAPPERS
1782
1783 If you want to compile your own qemu, run qemu from a non-standard
1784 location, or pass extra arguments to qemu, then you can write a
1785 shell-script wrapper around qemu.
1786
1787 There is one important rule to remember: you I<must C<exec qemu>> as
1788 the last command in the shell script (so that qemu replaces the shell
1789 and becomes the direct child of the libguestfs-using program).  If you
1790 don't do this, then the qemu process won't be cleaned up correctly.
1791
1792 Here is an example of a wrapper, where I have built my own copy of
1793 qemu from source:
1794
1795  #!/bin/sh -
1796  qemudir=/home/rjones/d/qemu
1797  exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1798
1799 Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
1800 and then use it by setting the LIBGUESTFS_QEMU environment variable.
1801 For example:
1802
1803  LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
1804
1805 Note that libguestfs also calls qemu with the -help and -version
1806 options in order to determine features.
1807
1808 =head1 LIBGUESTFS VERSION NUMBERS
1809
1810 Since April 2010, libguestfs has started to make separate development
1811 and stable releases, along with corresponding branches in our git
1812 repository.  These separate releases can be identified by version
1813 number:
1814
1815                  even numbers for stable: 1.2.x, 1.4.x, ...
1816        .-------- odd numbers for development: 1.3.x, 1.5.x, ...
1817        |
1818        v
1819  1  .  3  .  5
1820  ^           ^
1821  |           |
1822  |           `-------- sub-version
1823  |
1824  `------ always '1' because we don't change the ABI
1825
1826 Thus "1.3.5" is the 5th update to the development branch "1.3".
1827
1828 As time passes we cherry pick fixes from the development branch and
1829 backport those into the stable branch, the effect being that the
1830 stable branch should get more stable and less buggy over time.  So the
1831 stable releases are ideal for people who don't need new features but
1832 would just like the software to work.
1833
1834 Our criteria for backporting changes are:
1835
1836 =over 4
1837
1838 =item *
1839
1840 Documentation changes which don't affect any code are
1841 backported unless the documentation refers to a future feature
1842 which is not in stable.
1843
1844 =item *
1845
1846 Bug fixes which are not controversial, fix obvious problems, and
1847 have been well tested are backported.
1848
1849 =item *
1850
1851 Simple rearrangements of code which shouldn't affect how it works get
1852 backported.  This is so that the code in the two branches doesn't get
1853 too far out of step, allowing us to backport future fixes more easily.
1854
1855 =item *
1856
1857 We I<don't> backport new features, new APIs, new tools etc, except in
1858 one exceptional case: the new feature is required in order to
1859 implement an important bug fix.
1860
1861 =back
1862
1863 A new stable branch starts when we think the new features in
1864 development are substantial and compelling enough over the current
1865 stable branch to warrant it.  When that happens we create new stable
1866 and development versions 1.N.0 and 1.(N+1).0 [N is even].  The new
1867 dot-oh release won't necessarily be so stable at this point, but by
1868 backporting fixes from development, that branch will stabilize over
1869 time.
1870
1871 =head1 ENVIRONMENT VARIABLES
1872
1873 =over 4
1874
1875 =item LIBGUESTFS_APPEND
1876
1877 Pass additional options to the guest kernel.
1878
1879 =item LIBGUESTFS_DEBUG
1880
1881 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This
1882 has the same effect as calling C<guestfs_set_verbose (g, 1)>.
1883
1884 =item LIBGUESTFS_MEMSIZE
1885
1886 Set the memory allocated to the qemu process, in megabytes.  For
1887 example:
1888
1889  LIBGUESTFS_MEMSIZE=700
1890
1891 =item LIBGUESTFS_PATH
1892
1893 Set the path that libguestfs uses to search for kernel and initrd.img.
1894 See the discussion of paths in section PATH above.
1895
1896 =item LIBGUESTFS_QEMU
1897
1898 Set the default qemu binary that libguestfs uses.  If not set, then
1899 the qemu which was found at compile time by the configure script is
1900 used.
1901
1902 See also L</QEMU WRAPPERS> above.
1903
1904 =item LIBGUESTFS_TRACE
1905
1906 Set C<LIBGUESTFS_TRACE=1> to enable command traces.  This
1907 has the same effect as calling C<guestfs_set_trace (g, 1)>.
1908
1909 =item TMPDIR
1910
1911 Location of temporary directory, defaults to C</tmp>.
1912
1913 If libguestfs was compiled to use the supermin appliance then the
1914 real appliance is cached in this directory, shared between all
1915 handles belonging to the same EUID.  You can use C<$TMPDIR> to
1916 configure another directory to use in case C</tmp> is not large
1917 enough.
1918
1919 =back
1920
1921 =head1 SEE ALSO
1922
1923 L<guestfish(1)>,
1924 L<guestmount(1)>,
1925 L<virt-cat(1)>,
1926 L<virt-df(1)>,
1927 L<virt-edit(1)>,
1928 L<virt-inspector(1)>,
1929 L<virt-list-filesystems(1)>,
1930 L<virt-list-partitions(1)>,
1931 L<virt-ls(1)>,
1932 L<virt-make-fs(1)>,
1933 L<virt-rescue(1)>,
1934 L<virt-tar(1)>,
1935 L<virt-win-reg(1)>,
1936 L<qemu(1)>,
1937 L<febootstrap(1)>,
1938 L<hivex(3)>,
1939 L<http://libguestfs.org/>.
1940
1941 Tools with a similar purpose:
1942 L<fdisk(8)>,
1943 L<parted(8)>,
1944 L<kpartx(8)>,
1945 L<lvm(8)>,
1946 L<disktype(1)>.
1947
1948 =head1 BUGS
1949
1950 To get a list of bugs against libguestfs use this link:
1951
1952 L<https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools>
1953
1954 To report a new bug against libguestfs use this link:
1955
1956 L<https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools>
1957
1958 When reporting a bug, please check:
1959
1960 =over 4
1961
1962 =item *
1963
1964 That the bug hasn't been reported already.
1965
1966 =item *
1967
1968 That you are testing a recent version.
1969
1970 =item *
1971
1972 Describe the bug accurately, and give a way to reproduce it.
1973
1974 =item *
1975
1976 Run libguestfs-test-tool and paste the B<complete, unedited>
1977 output into the bug report.
1978
1979 =back
1980
1981 =head1 AUTHORS
1982
1983 Richard W.M. Jones (C<rjones at redhat dot com>)
1984
1985 =head1 COPYRIGHT
1986
1987 Copyright (C) 2009-2010 Red Hat Inc.
1988 L<http://libguestfs.org/>
1989
1990 This library is free software; you can redistribute it and/or
1991 modify it under the terms of the GNU Lesser General Public
1992 License as published by the Free Software Foundation; either
1993 version 2 of the License, or (at your option) any later version.
1994
1995 This library is distributed in the hope that it will be useful,
1996 but WITHOUT ANY WARRANTY; without even the implied warranty of
1997 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1998 Lesser General Public License for more details.
1999
2000 You should have received a copy of the GNU Lesser General Public
2001 License along with this library; if not, write to the Free Software
2002 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA