mkfs-b: Check that blocksize parameter is > 0 and a power of 2.
[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, 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 You can add a disk read-only using L</guestfs_add_drive_ro>, in which
128 case libguestfs won't modify the file.
129
130 Be extremely cautious if the disk image is in use, eg. if it is being
131 used by a virtual machine.  Adding it read-write will almost certainly
132 cause disk corruption, but adding it read-only is safe.
133
134 You must add at least one disk image, and you may add multiple disk
135 images.  In the API, the disk images are usually referred to as
136 C</dev/sda> (for the first one you added), C</dev/sdb> (for the second
137 one you added), etc.
138
139 Once L</guestfs_launch> has been called you cannot add any more images.
140 You can call L</guestfs_list_devices> to get a list of the device
141 names, in the order that you added them.  See also L</BLOCK DEVICE
142 NAMING> below.
143
144 =head2 MOUNTING
145
146 Before you can read or write files, create directories and so on in a
147 disk image that contains filesystems, you have to mount those
148 filesystems using L</guestfs_mount>.  If you already know that a disk
149 image contains (for example) one partition with a filesystem on that
150 partition, then you can mount it directly:
151
152  guestfs_mount (g, "/dev/sda1", "/");
153
154 where C</dev/sda1> means literally the first partition (C<1>) of the
155 first disk image that we added (C</dev/sda>).  If the disk contains
156 Linux LVM2 logical volumes you could refer to those instead (eg. C</dev/VG/LV>).
157
158 If you are given a disk image and you don't know what it contains then
159 you have to find out.  Libguestfs can do that too: use
160 L</guestfs_list_partitions> and L</guestfs_lvs> to list possible
161 partitions and LVs, and either try mounting each to see what is
162 mountable, or else examine them with L</guestfs_vfs_type> or
163 L</guestfs_file>.  But you might find it easier to look at higher level
164 programs built on top of libguestfs, in particular
165 L<virt-inspector(1)>.
166
167 To mount a disk image read-only, use L</guestfs_mount_ro>.  There are
168 several other variations of the C<guestfs_mount_*> call.
169
170 =head2 FILESYSTEM ACCESS AND MODIFICATION
171
172 The majority of the libguestfs API consists of fairly low-level calls
173 for accessing and modifying the files, directories, symlinks etc on
174 mounted filesystems.  There are over a hundred such calls which you
175 can find listed in detail below in this man page, and we don't even
176 pretend to cover them all in this overview.
177
178 Specify filenames as full paths, starting with C<"/"> and including
179 the mount point.
180
181 For example, if you mounted a filesystem at C<"/"> and you want to
182 read the file called C<"etc/passwd"> then you could do:
183
184  char *data = guestfs_cat (g, "/etc/passwd");
185
186 This would return C<data> as a newly allocated buffer containing the
187 full content of that file (with some conditions: see also
188 L</DOWNLOADING> below), or C<NULL> if there was an error.
189
190 As another example, to create a top-level directory on that filesystem
191 called C<"var"> you would do:
192
193  guestfs_mkdir (g, "/var");
194
195 To create a symlink you could do:
196
197  guestfs_ln_s (g, "/etc/init.d/portmap",
198                "/etc/rc3.d/S30portmap");
199
200 Libguestfs will reject attempts to use relative paths and there is no
201 concept of a current working directory.
202
203 Libguestfs can return errors in many situations: for example if the
204 filesystem isn't writable, or if a file or directory that you
205 requested doesn't exist.  If you are using the C API (documented here)
206 you have to check for those error conditions after each call.  (Other
207 language bindings turn these errors into exceptions).
208
209 File writes are affected by the per-handle umask, set by calling
210 L</guestfs_umask> and defaulting to 022.  See L</UMASK>.
211
212 =head2 PARTITIONING
213
214 Libguestfs contains API calls to read, create and modify partition
215 tables on disk images.
216
217 In the common case where you want to create a single partition
218 covering the whole disk, you should use the L</guestfs_part_disk>
219 call:
220
221  const char *parttype = "mbr";
222  if (disk_is_larger_than_2TB)
223    parttype = "gpt";
224  guestfs_part_disk (g, "/dev/sda", parttype);
225
226 Obviously this effectively wipes anything that was on that disk image
227 before.
228
229 =head2 LVM2
230
231 Libguestfs provides access to a large part of the LVM2 API, such as
232 L</guestfs_lvcreate> and L</guestfs_vgremove>.  It won't make much sense
233 unless you familiarize yourself with the concepts of physical volumes,
234 volume groups and logical volumes.
235
236 This author strongly recommends reading the LVM HOWTO, online at
237 L<http://tldp.org/HOWTO/LVM-HOWTO/>.
238
239 =head2 DOWNLOADING
240
241 Use L</guestfs_cat> to download small, text only files.  This call
242 is limited to files which are less than 2 MB and which cannot contain
243 any ASCII NUL (C<\0>) characters.  However it has a very simple
244 to use API.
245
246 L</guestfs_read_file> can be used to read files which contain
247 arbitrary 8 bit data, since it returns a (pointer, size) pair.
248 However it is still limited to "small" files, less than 2 MB.
249
250 L</guestfs_download> can be used to download any file, with no
251 limits on content or size (even files larger than 4 GB).
252
253 To download multiple files, see L</guestfs_tar_out> and
254 L</guestfs_tgz_out>.
255
256 =head2 UPLOADING
257
258 It's often the case that you want to write a file or files to the disk
259 image.
260
261 To write a small file with fixed content, use L</guestfs_write>.  To
262 create a file of all zeroes, use L</guestfs_truncate_size> (sparse) or
263 L</guestfs_fallocate64> (with all disk blocks allocated).  There are a
264 variety of other functions for creating test files, for example
265 L</guestfs_fill> and L</guestfs_fill_pattern>.
266
267 To upload a single file, use L</guestfs_upload>.  This call has no
268 limits on file content or size (even files larger than 4 GB).
269
270 To upload multiple files, see L</guestfs_tar_in> and L</guestfs_tgz_in>.
271
272 However the fastest way to upload I<large numbers of arbitrary files>
273 is to turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and
274 L<mkisofs(8)>), then attach this using L</guestfs_add_drive_ro>.  If
275 you add the drive in a predictable way (eg. adding it last after all
276 other drives) then you can get the device name from
277 L</guestfs_list_devices> and mount it directly using
278 L</guestfs_mount_ro>.  Note that squashfs images are sometimes
279 non-portable between kernel versions, and they don't support labels or
280 UUIDs.  If you want to pre-build an image or you need to mount it
281 using a label or UUID, use an ISO image instead.
282
283 =head2 COPYING
284
285 There are various different commands for copying between files and
286 devices and in and out of the guest filesystem.  These are summarised
287 in the table below.
288
289 =over 4
290
291 =item B<file> to B<file>
292
293 Use L</guestfs_cp> to copy a single file, or
294 L</guestfs_cp_a> to copy directories recursively.
295
296 =item B<file or device> to B<file or device>
297
298 Use L</guestfs_dd> which efficiently uses L<dd(1)>
299 to copy between files and devices in the guest.
300
301 Example: duplicate the contents of an LV:
302
303  guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy");
304
305 The destination (C</dev/VG/Copy>) must be at least as large as the
306 source (C</dev/VG/Original>).  To copy less than the whole
307 source device, use L</guestfs_copy_size>.
308
309 =item B<file on the host> to B<file or device>
310
311 Use L</guestfs_upload>.  See L</UPLOADING> above.
312
313 =item B<file or device> to B<file on the host>
314
315 Use L</guestfs_download>.  See L</DOWNLOADING> above.
316
317 =back
318
319 =head2 LISTING FILES
320
321 L</guestfs_ll> is just designed for humans to read (mainly when using
322 the L<guestfish(1)>-equivalent command C<ll>).
323
324 L</guestfs_ls> is a quick way to get a list of files in a directory
325 from programs, as a flat list of strings.
326
327 L</guestfs_readdir> is a programmatic way to get a list of files in a
328 directory, plus additional information about each one.  It is more
329 equivalent to using the L<readdir(3)> call on a local filesystem.
330
331 L</guestfs_find> and L</guestfs_find0> can be used to recursively list
332 files.
333
334 =head2 RUNNING COMMANDS
335
336 Although libguestfs is a primarily an API for manipulating files
337 inside guest images, we also provide some limited facilities for
338 running commands inside guests.
339
340 There are many limitations to this:
341
342 =over 4
343
344 =item *
345
346 The kernel version that the command runs under will be different
347 from what it expects.
348
349 =item *
350
351 If the command needs to communicate with daemons, then most likely
352 they won't be running.
353
354 =item *
355
356 The command will be running in limited memory.
357
358 =item *
359
360 Only supports Linux guests (not Windows, BSD, etc).
361
362 =item *
363
364 Architecture limitations (eg. won't work for a PPC guest on
365 an X86 host).
366
367 =item *
368
369 For SELinux guests, you may need to enable SELinux and load policy
370 first.  See L</SELINUX> in this manpage.
371
372 =back
373
374 The two main API calls to run commands are L</guestfs_command> and
375 L</guestfs_sh> (there are also variations).
376
377 The difference is that L</guestfs_sh> runs commands using the shell, so
378 any shell globs, redirections, etc will work.
379
380 =head2 CONFIGURATION FILES
381
382 To read and write configuration files in Linux guest filesystems, we
383 strongly recommend using Augeas.  For example, Augeas understands how
384 to read and write, say, a Linux shadow password file or X.org
385 configuration file, and so avoids you having to write that code.
386
387 The main Augeas calls are bound through the C<guestfs_aug_*> APIs.  We
388 don't document Augeas itself here because there is excellent
389 documentation on the L<http://augeas.net/> website.
390
391 If you don't want to use Augeas (you fool!) then try calling
392 L</guestfs_read_lines> to get the file as a list of lines which
393 you can iterate over.
394
395 =head2 SELINUX
396
397 We support SELinux guests.  To ensure that labeling happens correctly
398 in SELinux guests, you need to enable SELinux and load the guest's
399 policy:
400
401 =over 4
402
403 =item 1.
404
405 Before launching, do:
406
407  guestfs_set_selinux (g, 1);
408
409 =item 2.
410
411 After mounting the guest's filesystem(s), load the policy.  This
412 is best done by running the L<load_policy(8)> command in the
413 guest itself:
414
415  guestfs_sh (g, "/usr/sbin/load_policy");
416
417 (Older versions of C<load_policy> require you to specify the
418 name of the policy file).
419
420 =item 3.
421
422 Optionally, set the security context for the API.  The correct
423 security context to use can only be known by inspecting the
424 guest.  As an example:
425
426  guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
427
428 =back
429
430 This will work for running commands and editing existing files.
431
432 When new files are created, you may need to label them explicitly,
433 for example by running the external command
434 C<restorecon pathname>.
435
436 =head2 UMASK
437
438 Certain calls are affected by the current file mode creation mask (the
439 "umask").  In particular ones which create files or directories, such
440 as L</guestfs_touch>, L</guestfs_mknod> or L</guestfs_mkdir>.  This
441 affects either the default mode that the file is created with or
442 modifies the mode that you supply.
443
444 The default umask is C<022>, so files are created with modes such as
445 C<0644> and directories with C<0755>.
446
447 There are two ways to avoid being affected by umask.  Either set umask
448 to 0 (call C<guestfs_umask (g, 0)> early after launching).  Or call
449 L</guestfs_chmod> after creating each file or directory.
450
451 For more information about umask, see L<umask(2)>.
452
453 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
454
455 Libguestfs can mount NTFS partitions.  It does this using the
456 L<http://www.ntfs-3g.org/> driver.
457
458 DOS and Windows still use drive letters, and the filesystems are
459 always treated as case insensitive by Windows itself, and therefore
460 you might find a Windows configuration file referring to a path like
461 C<c:\windows\system32>.  When the filesystem is mounted in libguestfs,
462 that directory might be referred to as C</WINDOWS/System32>.
463
464 Drive letter mappings are outside the scope of libguestfs.  You have
465 to use libguestfs to read the appropriate Windows Registry and
466 configuration files, to determine yourself how drives are mapped (see
467 also L<virt-inspector(1)>).
468
469 Replacing backslash characters with forward slash characters is also
470 outside the scope of libguestfs, but something that you can easily do.
471
472 Where we can help is in resolving the case insensitivity of paths.
473 For this, call L</guestfs_case_sensitive_path>.
474
475 Libguestfs also provides some help for decoding Windows Registry
476 "hive" files, through the library C<hivex> which is part of the
477 libguestfs project although ships as a separate tarball.  You have to
478 locate and download the hive file(s) yourself, and then pass them to
479 C<hivex> functions.  See also the programs L<hivexml(1)>,
480 L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-reg(1)> for more help
481 on this issue.
482
483 =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
484
485 Although we don't want to discourage you from using the C API, we will
486 mention here that the same API is also available in other languages.
487
488 The API is broadly identical in all supported languages.  This means
489 that the C call C<guestfs_mount(g,path)> is
490 C<$g-E<gt>mount($path)> in Perl, C<g.mount(path)> in Python,
491 and C<Guestfs.mount g path> in OCaml.  In other words, a
492 straightforward, predictable isomorphism between each language.
493
494 Error messages are automatically transformed
495 into exceptions if the language supports it.
496
497 We don't try to "object orientify" parts of the API in OO languages,
498 although contributors are welcome to write higher level APIs above
499 what we provide in their favourite languages if they wish.
500
501 =over 4
502
503 =item B<C++>
504
505 You can use the I<guestfs.h> header file from C++ programs.  The C++
506 API is identical to the C API.  C++ classes and exceptions are not
507 used.
508
509 =item B<C#>
510
511 The C# bindings are highly experimental.  Please read the warnings
512 at the top of C<csharp/Libguestfs.cs>.
513
514 =item B<Haskell>
515
516 This is the only language binding that is working but incomplete.
517 Only calls which return simple integers have been bound in Haskell,
518 and we are looking for help to complete this binding.
519
520 =item B<Java>
521
522 Full documentation is contained in the Javadoc which is distributed
523 with libguestfs.
524
525 =item B<OCaml>
526
527 For documentation see the file C<guestfs.mli>.
528
529 =item B<Perl>
530
531 For documentation see L<Sys::Guestfs(3)>.
532
533 =item B<Python>
534
535 For documentation do:
536
537  $ python
538  >>> import guestfs
539  >>> help (guestfs)
540
541 =item B<Ruby>
542
543 Use the Guestfs module.  There is no Ruby-specific documentation, but
544 you can find examples written in Ruby in the libguestfs source.
545
546 =item B<shell scripts>
547
548 For documentation see L<guestfish(1)>.
549
550 =back
551
552 =head2 LIBGUESTFS GOTCHAS
553
554 L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: "A feature of a
555 system [...] that works in the way it is documented but is
556 counterintuitive and almost invites mistakes."
557
558 Since we developed libguestfs and the associated tools, there are
559 several things we would have designed differently, but are now stuck
560 with for backwards compatibility or other reasons.  If there is ever a
561 libguestfs 2.0 release, you can expect these to change.  Beware of
562 them.
563
564 =over 4
565
566 =item Autosync / forgetting to sync.
567
568 When modifying a filesystem from C or another language, you B<must>
569 unmount all filesystems and call L</guestfs_sync> explicitly before
570 you close the libguestfs handle.  You can also call:
571
572  guestfs_set_autosync (g, 1);
573
574 to have the unmount/sync done automatically for you when the handle 'g'
575 is closed.  (This feature is called "autosync", L</guestfs_set_autosync>
576 q.v.)
577
578 If you forget to do this, then it is entirely possible that your
579 changes won't be written out, or will be partially written, or (very
580 rarely) that you'll get disk corruption.
581
582 Note that in L<guestfish(3)> autosync is the default.  So quick and
583 dirty guestfish scripts that forget to sync will work just fine, which
584 can make this very puzzling if you are trying to debug a problem.
585
586 =item Mount option C<-o sync> should not be the default.
587
588 If you use L</guestfs_mount>, then C<-o sync,noatime> are added
589 implicitly.  However C<-o sync> does not add any reliability benefit,
590 but does have a very large performance impact.
591
592 The work around is to use L</guestfs_mount_options> and set the mount
593 options that you actually want to use.
594
595 =item Read-only should be the default.
596
597 In L<guestfish(3)>, I<--ro> should be the default, and you should
598 have to specify I<--rw> if you want to make changes to the image.
599
600 This would reduce the potential to corrupt live VM images.
601
602 Note that many filesystems change the disk when you just mount and
603 unmount, even if you didn't perform any writes.  You need to use
604 L</guestfs_add_drive_ro> to guarantee that the disk is not changed.
605
606 =item guestfish command line is hard to use.
607
608 C<guestfish disk.img> doesn't do what people expect (open C<disk.img>
609 for examination).  It tries to run a guestfish command C<disk.img>
610 which doesn't exist, so it fails.  In earlier versions of guestfish
611 the error message was also unintuitive, but we have corrected this
612 since.  Like the Bourne shell, we should have used C<guestfish -c
613 command> to run commands.
614
615 =item Protocol limit of 256 characters for error messages
616
617 This limit is both rather small and quite unnecessary.  We should be
618 able to return error messages up to the length of the protocol message
619 (2-4 MB).
620
621 Note that we cannot change the protocol without some breakage, because
622 there are distributions that repackage the Fedora appliance.
623
624 =item Protocol should return errno with error messages.
625
626 It would be a nice-to-have to be able to get the original value of
627 'errno' from inside the appliance along error paths (where set).
628 Currently L<guestmount(1)> goes through hoops to try to reverse the
629 error message string into an errno, see the function error() in
630 fuse/guestmount.c.
631
632 =back
633
634 =head2 PROTOCOL LIMITS
635
636 Internally libguestfs uses a message-based protocol to pass API calls
637 and their responses to and from a small "appliance" (see L</INTERNALS>
638 for plenty more detail about this).  The maximum message size used by
639 the protocol is slightly less than 4 MB.  For some API calls you may
640 need to be aware of this limit.  The API calls which may be affected
641 are individually documented, with a link back to this section of the
642 documentation.
643
644 A simple call such as L</guestfs_cat> returns its result (the file
645 data) in a simple string.  Because this string is at some point
646 internally encoded as a message, the maximum size that it can return
647 is slightly under 4 MB.  If the requested file is larger than this
648 then you will get an error.
649
650 In order to transfer large files into and out of the guest filesystem,
651 you need to use particular calls that support this.  The sections
652 L</UPLOADING> and L</DOWNLOADING> document how to do this.
653
654 You might also consider mounting the disk image using our FUSE
655 filesystem support (L<guestmount(1)>).
656
657 =head1 CONNECTION MANAGEMENT
658
659 =head2 guestfs_h *
660
661 C<guestfs_h> is the opaque type representing a connection handle.
662 Create a handle by calling L</guestfs_create>.  Call L</guestfs_close>
663 to free the handle and release all resources used.
664
665 For information on using multiple handles and threads, see the section
666 L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
667
668 =head2 guestfs_create
669
670  guestfs_h *guestfs_create (void);
671
672 Create a connection handle.
673
674 You have to call L</guestfs_add_drive> on the handle at least once.
675
676 This function returns a non-NULL pointer to a handle on success or
677 NULL on error.
678
679 After configuring the handle, you have to call L</guestfs_launch>.
680
681 You may also want to configure error handling for the handle.  See
682 L</ERROR HANDLING> section below.
683
684 =head2 guestfs_close
685
686  void guestfs_close (guestfs_h *g);
687
688 This closes the connection handle and frees up all resources used.
689
690 =head1 ERROR HANDLING
691
692 The convention in all functions that return C<int> is that they return
693 C<-1> to indicate an error.  You can get additional information on
694 errors by calling L</guestfs_last_error> and/or by setting up an error
695 handler with L</guestfs_set_error_handler>.
696
697 The default error handler prints the information string to C<stderr>.
698
699 Out of memory errors are handled differently.  The default action is
700 to call L<abort(3)>.  If this is undesirable, then you can set a
701 handler using L</guestfs_set_out_of_memory_handler>.
702
703 =head2 guestfs_last_error
704
705  const char *guestfs_last_error (guestfs_h *g);
706
707 This returns the last error message that happened on C<g>.  If
708 there has not been an error since the handle was created, then this
709 returns C<NULL>.
710
711 The lifetime of the returned string is until the next error occurs, or
712 L</guestfs_close> is called.
713
714 The error string is not localized (ie. is always in English), because
715 this makes searching for error messages in search engines give the
716 largest number of results.
717
718 =head2 guestfs_set_error_handler
719
720  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
721                                            void *data,
722                                            const char *msg);
723  void guestfs_set_error_handler (guestfs_h *g,
724                                  guestfs_error_handler_cb cb,
725                                  void *data);
726
727 The callback C<cb> will be called if there is an error.  The
728 parameters passed to the callback are an opaque data pointer and the
729 error message string.
730
731 Note that the message string C<msg> is freed as soon as the callback
732 function returns, so if you want to stash it somewhere you must make
733 your own copy.
734
735 The default handler prints messages on C<stderr>.
736
737 If you set C<cb> to C<NULL> then I<no> handler is called.
738
739 =head2 guestfs_get_error_handler
740
741  guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
742                                                      void **data_rtn);
743
744 Returns the current error handler callback.
745
746 =head2 guestfs_set_out_of_memory_handler
747
748  typedef void (*guestfs_abort_cb) (void);
749  int guestfs_set_out_of_memory_handler (guestfs_h *g,
750                                         guestfs_abort_cb);
751
752 The callback C<cb> will be called if there is an out of memory
753 situation.  I<Note this callback must not return>.
754
755 The default is to call L<abort(3)>.
756
757 You cannot set C<cb> to C<NULL>.  You can't ignore out of memory
758 situations.
759
760 =head2 guestfs_get_out_of_memory_handler
761
762  guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
763
764 This returns the current out of memory handler.
765
766 =head1 PATH
767
768 Libguestfs needs a kernel and initrd.img, which it finds by looking
769 along an internal path.
770
771 By default it looks for these in the directory C<$libdir/guestfs>
772 (eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
773
774 Use L</guestfs_set_path> or set the environment variable
775 L</LIBGUESTFS_PATH> to change the directories that libguestfs will
776 search in.  The value is a colon-separated list of paths.  The current
777 directory is I<not> searched unless the path contains an empty element
778 or C<.>.  For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
779 search the current directory and then C</usr/lib/guestfs>.
780
781 =head1 HIGH-LEVEL API ACTIONS
782
783 =head2 ABI GUARANTEE
784
785 We guarantee the libguestfs ABI (binary interface), for public,
786 high-level actions as outlined in this section.  Although we will
787 deprecate some actions, for example if they get replaced by newer
788 calls, we will keep the old actions forever.  This allows you the
789 developer to program in confidence against the libguestfs API.
790
791 @ACTIONS@
792
793 =head1 STRUCTURES
794
795 @STRUCTS@
796
797 =head1 AVAILABILITY
798
799 =head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
800
801 Using L</guestfs_available> you can test availability of
802 the following groups of functions.  This test queries the
803 appliance to see if the appliance you are currently using
804 supports the functionality.
805
806 @AVAILABILITY@
807
808 =head2 GUESTFISH supported COMMAND
809
810 In L<guestfish(3)> there is a handy interactive command
811 C<supported> which prints out the available groups and
812 whether they are supported by this build of libguestfs.
813 Note however that you have to do C<run> first.
814
815 =head2 SINGLE CALLS AT COMPILE TIME
816
817 If you need to test whether a single libguestfs function is
818 available at compile time, we recommend using build tools
819 such as autoconf or cmake.  For example in autotools you could
820 use:
821
822  AC_CHECK_LIB([guestfs],[guestfs_create])
823  AC_CHECK_FUNCS([guestfs_dd])
824
825 which would result in C<HAVE_GUESTFS_DD> being either defined
826 or not defined in your program.
827
828 =head2 SINGLE CALLS AT RUN TIME
829
830 Testing at compile time doesn't guarantee that a function really
831 exists in the library.  The reason is that you might be dynamically
832 linked against a previous I<libguestfs.so> (dynamic library)
833 which doesn't have the call.  This situation unfortunately results
834 in a segmentation fault, which is a shortcoming of the C dynamic
835 linking system itself.
836
837 You can use L<dlopen(3)> to test if a function is available
838 at run time, as in this example program (note that you still
839 need the compile time check as well):
840
841  #include <config.h>
842  
843  #include <stdio.h>
844  #include <stdlib.h>
845  #include <unistd.h>
846  #include <dlfcn.h>
847  #include <guestfs.h>
848  
849  main ()
850  {
851  #ifdef HAVE_GUESTFS_DD
852    void *dl;
853    int has_function;
854  
855    /* Test if the function guestfs_dd is really available. */
856    dl = dlopen (NULL, RTLD_LAZY);
857    if (!dl) {
858      fprintf (stderr, "dlopen: %s\n", dlerror ());
859      exit (EXIT_FAILURE);
860    }
861    has_function = dlsym (dl, "guestfs_dd") != NULL;
862    dlclose (dl);
863  
864    if (!has_function)
865      printf ("this libguestfs.so does NOT have guestfs_dd function\n");
866    else {
867      printf ("this libguestfs.so has guestfs_dd function\n");
868      /* Now it's safe to call
869      guestfs_dd (g, "foo", "bar");
870      */
871    }
872  #else
873    printf ("guestfs_dd function was not found at compile time\n");
874  #endif
875   }
876
877 You may think the above is an awful lot of hassle, and it is.
878 There are other ways outside of the C linking system to ensure
879 that this kind of incompatibility never arises, such as using
880 package versioning:
881
882  Requires: libguestfs >= 1.0.80
883
884 =begin html
885
886 <!-- old anchor for the next section -->
887 <a name="state_machine_and_low_level_event_api"/>
888
889 =end html
890
891 =head1 ARCHITECTURE
892
893 Internally, libguestfs is implemented by running an appliance (a
894 special type of small virtual machine) using L<qemu(1)>.  Qemu runs as
895 a child process of the main program.
896
897   ___________________
898  /                   \
899  | main program      |
900  |                   |
901  |                   |           child process / appliance
902  |                   |           __________________________
903  |                   |          / qemu                     \
904  +-------------------+   RPC    |      +-----------------+ |
905  | libguestfs     <--------------------> guestfsd        | |
906  |                   |          |      +-----------------+ |
907  \___________________/          |      | Linux kernel    | |
908                                 |      +--^--------------+ |
909                                 \_________|________________/
910                                           |
911                                    _______v______
912                                   /              \
913                                   | Device or    |
914                                   | disk image   |
915                                   \______________/
916
917 The library, linked to the main program, creates the child process and
918 hence the appliance in the L</guestfs_launch> function.
919
920 Inside the appliance is a Linux kernel and a complete stack of
921 userspace tools (such as LVM and ext2 programs) and a small
922 controlling daemon called L</guestfsd>.  The library talks to
923 L</guestfsd> using remote procedure calls (RPC).  There is a mostly
924 one-to-one correspondence between libguestfs API calls and RPC calls
925 to the daemon.  Lastly the disk image(s) are attached to the qemu
926 process which translates device access by the appliance's Linux kernel
927 into accesses to the image.
928
929 A common misunderstanding is that the appliance "is" the virtual
930 machine.  Although the disk image you are attached to might also be
931 used by some virtual machine, libguestfs doesn't know or care about
932 this.  (But you will care if both libguestfs's qemu process and your
933 virtual machine are trying to update the disk image at the same time,
934 since these usually results in massive disk corruption).
935
936 =head1 STATE MACHINE
937
938 libguestfs uses a state machine to model the child process:
939
940                          |
941                     guestfs_create
942                          |
943                          |
944                      ____V_____
945                     /          \
946                     |  CONFIG  |
947                     \__________/
948                      ^ ^   ^  \
949                     /  |    \  \ guestfs_launch
950                    /   |    _\__V______
951                   /    |   /           \
952                  /     |   | LAUNCHING |
953                 /      |   \___________/
954                /       |       /
955               /        |  guestfs_launch
956              /         |     /
957     ______  /        __|____V
958    /      \ ------> /        \
959    | BUSY |         | READY  |
960    \______/ <------ \________/
961
962 The normal transitions are (1) CONFIG (when the handle is created, but
963 there is no child process), (2) LAUNCHING (when the child process is
964 booting up), (3) alternating between READY and BUSY as commands are
965 issued to, and carried out by, the child process.
966
967 The guest may be killed by L</guestfs_kill_subprocess>, or may die
968 asynchronously at any time (eg. due to some internal error), and that
969 causes the state to transition back to CONFIG.
970
971 Configuration commands for qemu such as L</guestfs_add_drive> can only
972 be issued when in the CONFIG state.
973
974 The high-level API offers two calls that go from CONFIG through
975 LAUNCHING to READY.  L</guestfs_launch> blocks until the child process
976 is READY to accept commands (or until some failure or timeout).
977 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
978 while it is running.
979
980 High-level API actions such as L</guestfs_mount> can only be issued
981 when in the READY state.  These high-level API calls block waiting for
982 the command to be carried out (ie. the state to transition to BUSY and
983 then back to READY).  But using the low-level event API, you get
984 non-blocking versions.  (But you can still only carry out one
985 operation per handle at a time - that is a limitation of the
986 communications protocol we use).
987
988 Finally, the child process sends asynchronous messages back to the
989 main program, such as kernel log messages.  Mostly these are ignored
990 by the high-level API, but using the low-level event API you can
991 register to receive these messages.
992
993 =head2 SETTING CALLBACKS TO HANDLE EVENTS
994
995 The child process generates events in some situations.  Current events
996 include: receiving a log message, the child process exits.
997
998 Use the C<guestfs_set_*_callback> functions to set a callback for
999 different types of events.
1000
1001 Only I<one callback of each type> can be registered for each handle.
1002 Calling C<guestfs_set_*_callback> again overwrites the previous
1003 callback of that type.  Cancel all callbacks of this type by calling
1004 this function with C<cb> set to C<NULL>.
1005
1006 =head2 guestfs_set_log_message_callback
1007
1008  typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
1009                                          char *buf, int len);
1010  void guestfs_set_log_message_callback (guestfs_h *g,
1011                                         guestfs_log_message_cb cb,
1012                                         void *opaque);
1013
1014 The callback function C<cb> will be called whenever qemu or the guest
1015 writes anything to the console.
1016
1017 Use this function to capture kernel messages and similar.
1018
1019 Normally there is no log message handler, and log messages are just
1020 discarded.
1021
1022 =head2 guestfs_set_subprocess_quit_callback
1023
1024  typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);
1025  void guestfs_set_subprocess_quit_callback (guestfs_h *g,
1026                                             guestfs_subprocess_quit_cb cb,
1027                                             void *opaque);
1028
1029 The callback function C<cb> will be called when the child process
1030 quits, either asynchronously or if killed by
1031 L</guestfs_kill_subprocess>.  (This corresponds to a transition from
1032 any state to the CONFIG state).
1033
1034 =head2 guestfs_set_launch_done_callback
1035
1036  typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
1037  void guestfs_set_launch_done_callback (guestfs_h *g,
1038                                         guestfs_ready_cb cb,
1039                                         void *opaque);
1040
1041 The callback function C<cb> will be called when the child process
1042 becomes ready first time after it has been launched.  (This
1043 corresponds to a transition from LAUNCHING to the READY state).
1044
1045 =head1 BLOCK DEVICE NAMING
1046
1047 In the kernel there is now quite a profusion of schemata for naming
1048 block devices (in this context, by I<block device> I mean a physical
1049 or virtual hard drive).  The original Linux IDE driver used names
1050 starting with C</dev/hd*>.  SCSI devices have historically used a
1051 different naming scheme, C</dev/sd*>.  When the Linux kernel I<libata>
1052 driver became a popular replacement for the old IDE driver
1053 (particularly for SATA devices) those devices also used the
1054 C</dev/sd*> scheme.  Additionally we now have virtual machines with
1055 paravirtualized drivers.  This has created several different naming
1056 systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
1057 PV disks.
1058
1059 As discussed above, libguestfs uses a qemu appliance running an
1060 embedded Linux kernel to access block devices.  We can run a variety
1061 of appliances based on a variety of Linux kernels.
1062
1063 This causes a problem for libguestfs because many API calls use device
1064 or partition names.  Working scripts and the recipe (example) scripts
1065 that we make available over the internet could fail if the naming
1066 scheme changes.
1067
1068 Therefore libguestfs defines C</dev/sd*> as the I<standard naming
1069 scheme>.  Internally C</dev/sd*> names are translated, if necessary,
1070 to other names as required.  For example, under RHEL 5 which uses the
1071 C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
1072 C</dev/hda2> transparently.
1073
1074 Note that this I<only> applies to parameters.  The
1075 L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
1076 return the true names of the devices and partitions as known to the
1077 appliance.
1078
1079 =head2 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
1080
1081 Usually this translation is transparent.  However in some (very rare)
1082 cases you may need to know the exact algorithm.  Such cases include
1083 where you use L</guestfs_config> to add a mixture of virtio and IDE
1084 devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
1085 and C</dev/vd*> devices.
1086
1087 The algorithm is applied only to I<parameters> which are known to be
1088 either device or partition names.  Return values from functions such
1089 as L</guestfs_list_devices> are never changed.
1090
1091 =over 4
1092
1093 =item *
1094
1095 Is the string a parameter which is a device or partition name?
1096
1097 =item *
1098
1099 Does the string begin with C</dev/sd>?
1100
1101 =item *
1102
1103 Does the named device exist?  If so, we use that device.
1104 However if I<not> then we continue with this algorithm.
1105
1106 =item *
1107
1108 Replace initial C</dev/sd> string with C</dev/hd>.
1109
1110 For example, change C</dev/sda2> to C</dev/hda2>.
1111
1112 If that named device exists, use it.  If not, continue.
1113
1114 =item *
1115
1116 Replace initial C</dev/sd> string with C</dev/vd>.
1117
1118 If that named device exists, use it.  If not, return an error.
1119
1120 =back
1121
1122 =head2 PORTABILITY CONCERNS
1123
1124 Although the standard naming scheme and automatic translation is
1125 useful for simple programs and guestfish scripts, for larger programs
1126 it is best not to rely on this mechanism.
1127
1128 Where possible for maximum future portability programs using
1129 libguestfs should use these future-proof techniques:
1130
1131 =over 4
1132
1133 =item *
1134
1135 Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list
1136 actual device names, and then use those names directly.
1137
1138 Since those device names exist by definition, they will never be
1139 translated.
1140
1141 =item *
1142
1143 Use higher level ways to identify filesystems, such as LVM names,
1144 UUIDs and filesystem labels.
1145
1146 =back
1147
1148 =head1 INTERNALS
1149
1150 =head2 COMMUNICATION PROTOCOL
1151
1152 Don't rely on using this protocol directly.  This section documents
1153 how it currently works, but it may change at any time.
1154
1155 The protocol used to talk between the library and the daemon running
1156 inside the qemu virtual machine is a simple RPC mechanism built on top
1157 of XDR (RFC 1014, RFC 1832, RFC 4506).
1158
1159 The detailed format of structures is in C<src/guestfs_protocol.x>
1160 (note: this file is automatically generated).
1161
1162 There are two broad cases, ordinary functions that don't have any
1163 C<FileIn> and C<FileOut> parameters, which are handled with very
1164 simple request/reply messages.  Then there are functions that have any
1165 C<FileIn> or C<FileOut> parameters, which use the same request and
1166 reply messages, but they may also be followed by files sent using a
1167 chunked encoding.
1168
1169 =head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)
1170
1171 For ordinary functions, the request message is:
1172
1173  total length (header + arguments,
1174       but not including the length word itself)
1175  struct guestfs_message_header (encoded as XDR)
1176  struct guestfs_<foo>_args (encoded as XDR)
1177
1178 The total length field allows the daemon to allocate a fixed size
1179 buffer into which it slurps the rest of the message.  As a result, the
1180 total length is limited to C<GUESTFS_MESSAGE_MAX> bytes (currently
1181 4MB), which means the effective size of any request is limited to
1182 somewhere under this size.
1183
1184 Note also that many functions don't take any arguments, in which case
1185 the C<guestfs_I<foo>_args> is completely omitted.
1186
1187 The header contains the procedure number (C<guestfs_proc>) which is
1188 how the receiver knows what type of args structure to expect, or none
1189 at all.
1190
1191 The reply message for ordinary functions is:
1192
1193  total length (header + ret,
1194       but not including the length word itself)
1195  struct guestfs_message_header (encoded as XDR)
1196  struct guestfs_<foo>_ret (encoded as XDR)
1197
1198 As above the C<guestfs_I<foo>_ret> structure may be completely omitted
1199 for functions that return no formal return values.
1200
1201 As above the total length of the reply is limited to
1202 C<GUESTFS_MESSAGE_MAX>.
1203
1204 In the case of an error, a flag is set in the header, and the reply
1205 message is slightly changed:
1206
1207  total length (header + error,
1208       but not including the length word itself)
1209  struct guestfs_message_header (encoded as XDR)
1210  struct guestfs_message_error (encoded as XDR)
1211
1212 The C<guestfs_message_error> structure contains the error message as a
1213 string.
1214
1215 =head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS
1216
1217 A C<FileIn> parameter indicates that we transfer a file I<into> the
1218 guest.  The normal request message is sent (see above).  However this
1219 is followed by a sequence of file chunks.
1220
1221  total length (header + arguments,
1222       but not including the length word itself,
1223       and not including the chunks)
1224  struct guestfs_message_header (encoded as XDR)
1225  struct guestfs_<foo>_args (encoded as XDR)
1226  sequence of chunks for FileIn param #0
1227  sequence of chunks for FileIn param #1 etc.
1228
1229 The "sequence of chunks" is:
1230
1231  length of chunk (not including length word itself)
1232  struct guestfs_chunk (encoded as XDR)
1233  length of chunk
1234  struct guestfs_chunk (encoded as XDR)
1235    ...
1236  length of chunk
1237  struct guestfs_chunk (with data.data_len == 0)
1238
1239 The final chunk has the C<data_len> field set to zero.  Additionally a
1240 flag is set in the final chunk to indicate either successful
1241 completion or early cancellation.
1242
1243 At time of writing there are no functions that have more than one
1244 FileIn parameter.  However this is (theoretically) supported, by
1245 sending the sequence of chunks for each FileIn parameter one after
1246 another (from left to right).
1247
1248 Both the library (sender) I<and> the daemon (receiver) may cancel the
1249 transfer.  The library does this by sending a chunk with a special
1250 flag set to indicate cancellation.  When the daemon sees this, it
1251 cancels the whole RPC, does I<not> send any reply, and goes back to
1252 reading the next request.
1253
1254 The daemon may also cancel.  It does this by writing a special word
1255 C<GUESTFS_CANCEL_FLAG> to the socket.  The library listens for this
1256 during the transfer, and if it gets it, it will cancel the transfer
1257 (it sends a cancel chunk).  The special word is chosen so that even if
1258 cancellation happens right at the end of the transfer (after the
1259 library has finished writing and has started listening for the reply),
1260 the "spurious" cancel flag will not be confused with the reply
1261 message.
1262
1263 This protocol allows the transfer of arbitrary sized files (no 32 bit
1264 limit), and also files where the size is not known in advance
1265 (eg. from pipes or sockets).  However the chunks are rather small
1266 (C<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the
1267 daemon need to keep much in memory.
1268
1269 =head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS
1270
1271 The protocol for FileOut parameters is exactly the same as for FileIn
1272 parameters, but with the roles of daemon and library reversed.
1273
1274  total length (header + ret,
1275       but not including the length word itself,
1276       and not including the chunks)
1277  struct guestfs_message_header (encoded as XDR)
1278  struct guestfs_<foo>_ret (encoded as XDR)
1279  sequence of chunks for FileOut param #0
1280  sequence of chunks for FileOut param #1 etc.
1281
1282 =head3 INITIAL MESSAGE
1283
1284 Because the underlying channel (QEmu -net channel) doesn't have any
1285 sort of connection control, when the daemon launches it sends an
1286 initial word (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest
1287 and daemon is alive.  This is what L</guestfs_launch> waits for.
1288
1289 =head1 MULTIPLE HANDLES AND MULTIPLE THREADS
1290
1291 All high-level libguestfs actions are synchronous.  If you want
1292 to use libguestfs asynchronously then you must create a thread.
1293
1294 Only use the handle from a single thread.  Either use the handle
1295 exclusively from one thread, or provide your own mutex so that two
1296 threads cannot issue calls on the same handle at the same time.
1297
1298 =head1 QEMU WRAPPERS
1299
1300 If you want to compile your own qemu, run qemu from a non-standard
1301 location, or pass extra arguments to qemu, then you can write a
1302 shell-script wrapper around qemu.
1303
1304 There is one important rule to remember: you I<must C<exec qemu>> as
1305 the last command in the shell script (so that qemu replaces the shell
1306 and becomes the direct child of the libguestfs-using program).  If you
1307 don't do this, then the qemu process won't be cleaned up correctly.
1308
1309 Here is an example of a wrapper, where I have built my own copy of
1310 qemu from source:
1311
1312  #!/bin/sh -
1313  qemudir=/home/rjones/d/qemu
1314  exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1315
1316 Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
1317 and then use it by setting the LIBGUESTFS_QEMU environment variable.
1318 For example:
1319
1320  LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
1321
1322 Note that libguestfs also calls qemu with the -help and -version
1323 options in order to determine features.
1324
1325 =head1 LIBGUESTFS VERSION NUMBERS
1326
1327 Since April 2010, libguestfs has started to make separate development
1328 and stable releases, along with corresponding branches in our git
1329 repository.  These separate releases can be identified by version
1330 number:
1331
1332                  even numbers for stable: 1.2.x, 1.4.x, ...
1333        .-------- odd numbers for development: 1.3.x, 1.5.x, ...
1334        |
1335        v
1336  1  .  3  .  5
1337  ^           ^
1338  |           |
1339  |           `-------- sub-version
1340  |
1341  `------ always '1' because we don't change the ABI
1342
1343 Thus "1.3.5" is the 5th update to the development branch "1.3".
1344
1345 As time passes we cherry pick fixes from the development branch and
1346 backport those into the stable branch, the effect being that the
1347 stable branch should get more stable and less buggy over time.  So the
1348 stable releases are ideal for people who don't need new features but
1349 would just like the software to work.
1350
1351 Our criteria for backporting changes are:
1352
1353 =over 4
1354
1355 =item *
1356
1357 Documentation changes which don't affect any code are
1358 backported unless the documentation refers to a future feature
1359 which is not in stable.
1360
1361 =item *
1362
1363 Bug fixes which are not controversial, fix obvious problems, and
1364 have been well tested are backported.
1365
1366 =item *
1367
1368 Simple rearrangements of code which shouldn't affect how it works get
1369 backported.  This is so that the code in the two branches doesn't get
1370 too far out of step, allowing us to backport future fixes more easily.
1371
1372 =item *
1373
1374 We I<don't> backport new features, new APIs, new tools etc, except in
1375 one exceptional case: the new feature is required in order to
1376 implement an important bug fix.
1377
1378 =back
1379
1380 A new stable branch starts when we think the new features in
1381 development are substantial and compelling enough over the current
1382 stable branch to warrant it.  When that happens we create new stable
1383 and development versions 1.N.0 and 1.(N+1).0 [N is even].  The new
1384 dot-oh release won't necessarily be so stable at this point, but by
1385 backporting fixes from development, that branch will stabilize over
1386 time.
1387
1388 =head1 ENVIRONMENT VARIABLES
1389
1390 =over 4
1391
1392 =item LIBGUESTFS_APPEND
1393
1394 Pass additional options to the guest kernel.
1395
1396 =item LIBGUESTFS_DEBUG
1397
1398 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This
1399 has the same effect as calling C<guestfs_set_verbose (g, 1)>.
1400
1401 =item LIBGUESTFS_MEMSIZE
1402
1403 Set the memory allocated to the qemu process, in megabytes.  For
1404 example:
1405
1406  LIBGUESTFS_MEMSIZE=700
1407
1408 =item LIBGUESTFS_PATH
1409
1410 Set the path that libguestfs uses to search for kernel and initrd.img.
1411 See the discussion of paths in section PATH above.
1412
1413 =item LIBGUESTFS_QEMU
1414
1415 Set the default qemu binary that libguestfs uses.  If not set, then
1416 the qemu which was found at compile time by the configure script is
1417 used.
1418
1419 See also L</QEMU WRAPPERS> above.
1420
1421 =item LIBGUESTFS_TRACE
1422
1423 Set C<LIBGUESTFS_TRACE=1> to enable command traces.  This
1424 has the same effect as calling C<guestfs_set_trace (g, 1)>.
1425
1426 =item TMPDIR
1427
1428 Location of temporary directory, defaults to C</tmp>.
1429
1430 If libguestfs was compiled to use the supermin appliance then each
1431 handle will require rather a large amount of space in this directory
1432 for short periods of time (~ 80 MB).  You can use C<$TMPDIR> to
1433 configure another directory to use in case C</tmp> is not large
1434 enough.
1435
1436 =back
1437
1438 =head1 SEE ALSO
1439
1440 L<guestfish(1)>,
1441 L<guestmount(1)>,
1442 L<virt-cat(1)>,
1443 L<virt-df(1)>,
1444 L<virt-edit(1)>,
1445 L<virt-inspector(1)>,
1446 L<virt-list-filesystems(1)>,
1447 L<virt-list-partitions(1)>,
1448 L<virt-ls(1)>,
1449 L<virt-make-fs(1)>,
1450 L<virt-rescue(1)>,
1451 L<virt-tar(1)>,
1452 L<virt-win-reg(1)>,
1453 L<qemu(1)>,
1454 L<febootstrap(1)>,
1455 L<hivex(3)>,
1456 L<http://libguestfs.org/>.
1457
1458 Tools with a similar purpose:
1459 L<fdisk(8)>,
1460 L<parted(8)>,
1461 L<kpartx(8)>,
1462 L<lvm(8)>,
1463 L<disktype(1)>.
1464
1465 =head1 BUGS
1466
1467 To get a list of bugs against libguestfs use this link:
1468
1469 L<https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools>
1470
1471 To report a new bug against libguestfs use this link:
1472
1473 L<https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools>
1474
1475 When reporting a bug, please check:
1476
1477 =over 4
1478
1479 =item *
1480
1481 That the bug hasn't been reported already.
1482
1483 =item *
1484
1485 That you are testing a recent version.
1486
1487 =item *
1488
1489 Describe the bug accurately, and give a way to reproduce it.
1490
1491 =item *
1492
1493 Run libguestfs-test-tool and paste the B<complete, unedited>
1494 output into the bug report.
1495
1496 =back
1497
1498 =head1 AUTHORS
1499
1500 Richard W.M. Jones (C<rjones at redhat dot com>)
1501
1502 =head1 COPYRIGHT
1503
1504 Copyright (C) 2009-2010 Red Hat Inc.
1505 L<http://libguestfs.org/>
1506
1507 This library is free software; you can redistribute it and/or
1508 modify it under the terms of the GNU Lesser General Public
1509 License as published by the Free Software Foundation; either
1510 version 2 of the License, or (at your option) any later version.
1511
1512 This library is distributed in the hope that it will be useful,
1513 but WITHOUT ANY WARRANTY; without even the implied warranty of
1514 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1515 Lesser General Public License for more details.
1516
1517 You should have received a copy of the GNU Lesser General Public
1518 License along with this library; if not, write to the Free Software
1519 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA