5 guestfs - Library for accessing and modifying virtual machine images
11 guestfs_h *handle = guestfs_create ();
12 guestfs_add_drive (handle, "guest.img");
13 guestfs_launch (handle);
14 guestfs_mount (handle, "/dev/sda1", "/");
15 guestfs_touch (handle, "/hello");
16 guestfs_sync (handle);
17 guestfs_close (handle);
21 Libguestfs is a library for accessing and modifying guest disk images.
22 Amongst the things this is good for: making batch configuration
23 changes to guests, getting disk used/free statistics (see also:
24 virt-df), migrating between virtualization systems (see also:
25 virt-p2v), performing partial backups, performing partial guest
26 clones, cloning guests and changing registry/UUID/hostname info, and
29 Libguestfs uses Linux kernel and qemu code, and can access any type of
30 guest filesystem that Linux and qemu can, including but not limited
31 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
32 schemes, qcow, qcow2, vmdk.
34 Libguestfs provides ways to enumerate guest storage (eg. partitions,
35 LVs, what filesystem is in each LV, etc.). It can also run commands
36 in the context of the guest. Also you can access filesystems over FTP.
38 Libguestfs is a library that can be linked with C and C++ management
39 programs (or management programs written in OCaml, Perl, Python, Ruby, Java
40 or Haskell). You can also use it from shell scripts or the command line.
42 You don't need to be root to use libguestfs, although obviously you do
43 need enough permissions to access the disk images.
45 =head1 CONNECTION MANAGEMENT
47 If you are using the high-level API, then you should call the
48 functions in the following order:
50 guestfs_h *handle = guestfs_create ();
52 guestfs_add_drive (handle, "guest.img");
53 /* call guestfs_add_drive additional times if the guest has
57 guestfs_launch (handle);
59 /* now you can examine what partitions, LVs etc are available
60 * you have to mount / at least
62 guestfs_mount (handle, "/dev/sda1", "/");
64 /* now you can perform actions on the guest disk image */
65 guestfs_touch (handle, "/hello");
67 /* you only need to call guestfs_sync if you have made
68 * changes to the guest image
70 guestfs_sync (handle);
72 guestfs_close (handle);
74 C<guestfs_launch> and all of the actions including C<guestfs_sync>
75 are blocking calls. You can use the low-level event API to do
76 non-blocking operations instead.
78 All functions that return integers, return C<-1> on error. See
79 section L</ERROR HANDLING> below for how to handle errors.
83 C<guestfs_h> is the opaque type representing a connection handle.
84 Create a handle by calling C<guestfs_create>. Call C<guestfs_close>
85 to free the handle and release all resources used.
87 For information on using multiple handles and threads, see the section
88 L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
92 guestfs_h *guestfs_create (void);
94 Create a connection handle.
96 You have to call C<guestfs_add_drive> on the handle at least once.
98 This function returns a non-NULL pointer to a handle on success or
101 After configuring the handle, you have to call C<guestfs_launch>.
103 You may also want to configure error handling for the handle. See
104 L</ERROR HANDLING> section below.
108 void guestfs_close (guestfs_h *handle);
110 This closes the connection handle and frees up all resources used.
112 =head1 ERROR HANDLING
114 The convention in all functions that return C<int> is that they return
115 C<-1> to indicate an error. You can get additional information on
116 errors by calling C<guestfs_last_error> and/or by setting up an error
117 handler with C<guestfs_set_error_handler>.
119 The default error handler prints the information string to C<stderr>.
121 Out of memory errors are handled differently. The default action is
122 to call L<abort(3)>. If this is undesirable, then you can set a
123 handler using C<guestfs_set_out_of_memory_handler>.
125 =head2 guestfs_last_error
127 const char *guestfs_last_error (guestfs_h *handle);
129 This returns the last error message that happened on C<handle>. If
130 there has not been an error since the handle was created, then this
133 The lifetime of the returned string is until the next error occurs, or
134 C<guestfs_close> is called.
136 The error string is not localized (ie. is always in English), because
137 this makes searching for error messages in search engines give the
138 largest number of results.
140 =head2 guestfs_set_error_handler
142 typedef void (*guestfs_error_handler_cb) (guestfs_h *handle,
145 void guestfs_set_error_handler (guestfs_h *handle,
146 guestfs_error_handler_cb cb,
149 The callback C<cb> will be called if there is an error. The
150 parameters passed to the callback are an opaque data pointer and the
151 error message string.
153 Note that the message string C<msg> is freed as soon as the callback
154 function returns, so if you want to stash it somewhere you must make
157 The default handler prints messages on C<stderr>.
159 If you set C<cb> to C<NULL> then I<no> handler is called.
161 =head2 guestfs_get_error_handler
163 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle,
166 Returns the current error handler callback.
168 =head2 guestfs_set_out_of_memory_handler
170 typedef void (*guestfs_abort_cb) (void);
171 int guestfs_set_out_of_memory_handler (guestfs_h *handle,
174 The callback C<cb> will be called if there is an out of memory
175 situation. I<Note this callback must not return>.
177 The default is to call L<abort(3)>.
179 You cannot set C<cb> to C<NULL>. You can't ignore out of memory
182 =head2 guestfs_get_out_of_memory_handler
184 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle);
186 This returns the current out of memory handler.
190 Libguestfs needs a kernel and initrd.img, which it finds by looking
191 along an internal path.
193 By default it looks for these in the directory C<$libdir/guestfs>
194 (eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
196 Use C<guestfs_set_path> or set the environment variable
197 C<LIBGUESTFS_PATH> to change the directories that libguestfs will
198 search in. The value is a colon-separated list of paths. The current
199 directory is I<not> searched unless the path contains an empty element
200 or C<.>. For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
201 search the current directory and then C</usr/lib/guestfs>.
205 This section provides additional documentation for groups of API
206 calls, which may not be obvious from reading about the individual
211 Libguestfs provides access to a large part of the LVM2 API. It won't
212 make much sense unless you familiarize yourself with the concepts of
213 physical volumes, volume groups and logical volumes.
215 This author strongly recommends reading the LVM HOWTO, online at
216 L<http://tldp.org/HOWTO/LVM-HOWTO/>.
220 In the common case where you want to create a single partition
221 covering the whole disk, you should use the C<guestfs_part_disk>
224 const char *parttype = "mbr";
225 if (disk_is_larger_than_2TB)
227 guestfs_part_disk (g, "/dev/sda", parttype);
229 In general MBR partitions are both unnecessarily complicated and
230 depend on archaic details, namely the Cylinder-Head-Sector (CHS)
231 geometry of the disk. C<guestfs_sfdiskM> can be used to
232 create more complex arrangements where the relative sizes are
233 expressed in megabytes instead of cylinders, which is a small win.
234 C<guestfs_sfdiskM> will choose the nearest cylinder to approximate the
235 requested size. There's a lot of crazy stuff to do with IDE and
236 virtio disks having different, incompatible CHS geometries, that you
237 probably don't want to know about.
239 My advice: make a single partition to cover the whole disk, then use
244 For small, single files, use C<guestfs_write_file>. In some versions
245 of libguestfs there was a bug which limited this call to text files
246 (not containing ASCII NUL characters).
248 To upload a single file, use C<guestfs_upload>. This call has no
249 limits on file content or size (even files larger than 4 GB).
251 To upload multiple files, see C<guestfs_tar_in> and C<guestfs_tgz_in>.
253 However the fastest way to upload I<large numbers of arbitrary files>
254 is to turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and
255 L<mkisofs(8)>), then attach this using C<guestfs_add_drive_ro>. If
256 you add the drive in a predictable way (eg. adding it last after all
257 other drives) then you can get the device name from
258 C<guestfs_list_devices> and mount it directly using
259 C<guestfs_mount_ro>. Note that squashfs images are sometimes
260 non-portable between kernel versions, and they don't support labels or
261 UUIDs. If you want to pre-build an image or you need to mount it
262 using a label or UUID, use an ISO image instead.
266 Use C<guestfs_cat> to download small, text only files. This call
267 is limited to files which are less than 2 MB and which cannot contain
268 any ASCII NUL (C<\0>) characters. However it has a very simple
271 C<guestfs_read_file> can be used to read files which contain
272 arbitrary 8 bit data, since it returns a (pointer, size) pair.
273 However it is still limited to "small" files, less than 2 MB.
275 C<guestfs_download> can be used to download any file, with no
276 limits on content or size (even files larger than 4 GB).
278 To download multiple files, see C<guestfs_tar_out> and
281 =head2 RUNNING COMMANDS
283 Although libguestfs is a primarily an API for manipulating files
284 inside guest images, we also provide some limited facilities for
285 running commands inside guests.
287 There are many limitations to this:
293 The kernel version that the command runs under will be different
294 from what it expects.
298 If the command needs to communicate with daemons, then most likely
299 they won't be running.
303 The command will be running in limited memory.
307 Only supports Linux guests (not Windows, BSD, etc).
311 Architecture limitations (eg. won't work for a PPC guest on
316 For SELinux guests, you may need to enable SELinux and load policy
317 first. See L</SELINUX> in this manpage.
321 The two main API calls to run commands are C<guestfs_command> and
322 C<guestfs_sh> (there are also variations).
324 The difference is that C<guestfs_sh> runs commands using the shell, so
325 any shell globs, redirections, etc will work.
329 C<guestfs_ll> is just designed for humans to read (mainly when using
330 the L<guestfish(1)>-equivalent command C<ll>).
332 C<guestfs_ls> is a quick way to get a list of files in a directory
335 C<guestfs_readdir> is a programmatic way to get a list of files in a
336 directory, plus additional information about each one.
338 C<guestfs_find> can be used to recursively list files.
342 We support SELinux guests. To ensure that labeling happens correctly
343 in SELinux guests, you need to enable SELinux and load the guest's
350 Before launching, do:
352 guestfs_set_selinux (g, 1);
356 After mounting the guest's filesystem(s), load the policy. This
357 is best done by running the L<load_policy(8)> command in the
360 guestfs_sh (g, "/usr/sbin/load_policy");
362 (Older versions of C<load_policy> require you to specify the
363 name of the policy file).
367 Optionally, set the security context for the API. The correct
368 security context to use can only be known by inspecting the
369 guest. As an example:
371 guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
375 This will work for running commands and editing existing files.
377 When new files are created, you may need to label them explicitly,
378 for example by running the external command
379 C<restorecon pathname>.
381 =head1 HIGH-LEVEL API ACTIONS
385 We guarantee the libguestfs ABI (binary interface), for public,
386 high-level actions as outlined in this section. Although we will
387 deprecate some actions, for example if they get replaced by newer
388 calls, we will keep the old actions forever. This allows you the
389 developer to program in confidence against libguestfs.
397 =head1 STATE MACHINE AND LOW-LEVEL EVENT API
399 Internally, libguestfs is implemented by running a virtual machine
400 using L<qemu(1)>. QEmu runs as a child process of the main program,
401 and most of this discussion won't make sense unless you understand
402 that the complexity is dealing with the (asynchronous) actions of the
406 ___________________ _________________________
408 | main program | | qemu +-----------------+|
409 | | | | Linux kernel ||
410 +-------------------+ | +-----------------+|
411 | libguestfs <-------------->| guestfsd ||
412 | | | +-----------------+|
413 \___________________/ \_________________________/
415 The diagram above shows libguestfs communicating with the guestfsd
416 daemon running inside the qemu child process. There are several
417 points of failure here: qemu can fail to start, the virtual machine
418 inside qemu can fail to boot, guestfsd can fail to start or not
419 establish communication, any component can start successfully but fail
420 asynchronously later, and so on.
424 libguestfs uses a state machine to model the child process:
435 / | \ \ guestfs_launch
446 \______/ <------ \________/
448 The normal transitions are (1) CONFIG (when the handle is created, but
449 there is no child process), (2) LAUNCHING (when the child process is
450 booting up), (3) alternating between READY and BUSY as commands are
451 issued to, and carried out by, the child process.
453 The guest may be killed by C<guestfs_kill_subprocess>, or may die
454 asynchronously at any time (eg. due to some internal error), and that
455 causes the state to transition back to CONFIG.
457 Configuration commands for qemu such as C<guestfs_add_drive> can only
458 be issued when in the CONFIG state.
460 The high-level API offers two calls that go from CONFIG through
461 LAUNCHING to READY. C<guestfs_launch> blocks until the child process
462 is READY to accept commands (or until some failure or timeout).
463 C<guestfs_launch> internally moves the state from CONFIG to LAUNCHING
466 High-level API actions such as C<guestfs_mount> can only be issued
467 when in the READY state. These high-level API calls block waiting for
468 the command to be carried out (ie. the state to transition to BUSY and
469 then back to READY). But using the low-level event API, you get
470 non-blocking versions. (But you can still only carry out one
471 operation per handle at a time - that is a limitation of the
472 communications protocol we use).
474 Finally, the child process sends asynchronous messages back to the
475 main program, such as kernel log messages. Mostly these are ignored
476 by the high-level API, but using the low-level event API you can
477 register to receive these messages.
479 =head2 SETTING CALLBACKS TO HANDLE EVENTS
481 The child process generates events in some situations. Current events
482 include: receiving a log message, the child process exits.
484 Use the C<guestfs_set_*_callback> functions to set a callback for
485 different types of events.
487 Only I<one callback of each type> can be registered for each handle.
488 Calling C<guestfs_set_*_callback> again overwrites the previous
489 callback of that type. Cancel all callbacks of this type by calling
490 this function with C<cb> set to C<NULL>.
492 =head2 guestfs_set_log_message_callback
494 typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
496 void guestfs_set_log_message_callback (guestfs_h *handle,
497 guestfs_log_message_cb cb,
500 The callback function C<cb> will be called whenever qemu or the guest
501 writes anything to the console.
503 Use this function to capture kernel messages and similar.
505 Normally there is no log message handler, and log messages are just
508 =head2 guestfs_set_subprocess_quit_callback
510 typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);
511 void guestfs_set_subprocess_quit_callback (guestfs_h *handle,
512 guestfs_subprocess_quit_cb cb,
515 The callback function C<cb> will be called when the child process
516 quits, either asynchronously or if killed by
517 C<guestfs_kill_subprocess>. (This corresponds to a transition from
518 any state to the CONFIG state).
520 =head2 guestfs_set_launch_done_callback
522 typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
523 void guestfs_set_launch_done_callback (guestfs_h *handle,
527 The callback function C<cb> will be called when the child process
528 becomes ready first time after it has been launched. (This
529 corresponds to a transition from LAUNCHING to the READY state).
531 =head1 BLOCK DEVICE NAMING
533 In the kernel there is now quite a profusion of schemata for naming
534 block devices (in this context, by I<block device> I mean a physical
535 or virtual hard drive). The original Linux IDE driver used names
536 starting with C</dev/hd*>. SCSI devices have historically used a
537 different naming scheme, C</dev/sd*>. When the Linux kernel I<libata>
538 driver became a popular replacement for the old IDE driver
539 (particularly for SATA devices) those devices also used the
540 C</dev/sd*> scheme. Additionally we now have virtual machines with
541 paravirtualized drivers. This has created several different naming
542 systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
545 As discussed above, libguestfs uses a qemu appliance running an
546 embedded Linux kernel to access block devices. We can run a variety
547 of appliances based on a variety of Linux kernels.
549 This causes a problem for libguestfs because many API calls use device
550 or partition names. Working scripts and the recipe (example) scripts
551 that we make available over the internet could fail if the naming
554 Therefore libguestfs defines C</dev/sd*> as the I<standard naming
555 scheme>. Internally C</dev/sd*> names are translated, if necessary,
556 to other names as required. For example, under RHEL 5 which uses the
557 C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
558 C</dev/hda2> transparently.
560 Note that this I<only> applies to parameters. The
561 C<guestfs_list_devices>, C<guestfs_list_partitions> and similar calls
562 return the true names of the devices and partitions as known to the
565 =head2 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
567 Usually this translation is transparent. However in some (very rare)
568 cases you may need to know the exact algorithm. Such cases include
569 where you use C<guestfs_config> to add a mixture of virtio and IDE
570 devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
571 and C</dev/vd*> devices.
573 The algorithm is applied only to I<parameters> which are known to be
574 either device or partition names. Return values from functions such
575 as C<guestfs_list_devices> are never changed.
581 Is the string a parameter which is a device or partition name?
585 Does the string begin with C</dev/sd>?
589 Does the named device exist? If so, we use that device.
590 However if I<not> then we continue with this algorithm.
594 Replace initial C</dev/sd> string with C</dev/hd>.
596 For example, change C</dev/sda2> to C</dev/hda2>.
598 If that named device exists, use it. If not, continue.
602 Replace initial C</dev/sd> string with C</dev/vd>.
604 If that named device exists, use it. If not, return an error.
608 =head2 PORTABILITY CONCERNS
610 Although the standard naming scheme and automatic translation is
611 useful for simple programs and guestfish scripts, for larger programs
612 it is best not to rely on this mechanism.
614 Where possible for maximum future portability programs using
615 libguestfs should use these future-proof techniques:
621 Use C<guestfs_list_devices> or C<guestfs_list_partitions> to list
622 actual device names, and then use those names directly.
624 Since those device names exist by definition, they will never be
629 Use higher level ways to identify filesystems, such as LVM names,
630 UUIDs and filesystem labels.
636 =head2 COMMUNICATION PROTOCOL
638 Don't rely on using this protocol directly. This section documents
639 how it currently works, but it may change at any time.
641 The protocol used to talk between the library and the daemon running
642 inside the qemu virtual machine is a simple RPC mechanism built on top
643 of XDR (RFC 1014, RFC 1832, RFC 4506).
645 The detailed format of structures is in C<src/guestfs_protocol.x>
646 (note: this file is automatically generated).
648 There are two broad cases, ordinary functions that don't have any
649 C<FileIn> and C<FileOut> parameters, which are handled with very
650 simple request/reply messages. Then there are functions that have any
651 C<FileIn> or C<FileOut> parameters, which use the same request and
652 reply messages, but they may also be followed by files sent using a
655 =head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS)
657 For ordinary functions, the request message is:
659 total length (header + arguments,
660 but not including the length word itself)
661 struct guestfs_message_header (encoded as XDR)
662 struct guestfs_<foo>_args (encoded as XDR)
664 The total length field allows the daemon to allocate a fixed size
665 buffer into which it slurps the rest of the message. As a result, the
666 total length is limited to C<GUESTFS_MESSAGE_MAX> bytes (currently
667 4MB), which means the effective size of any request is limited to
668 somewhere under this size.
670 Note also that many functions don't take any arguments, in which case
671 the C<guestfs_I<foo>_args> is completely omitted.
673 The header contains the procedure number (C<guestfs_proc>) which is
674 how the receiver knows what type of args structure to expect, or none
677 The reply message for ordinary functions is:
679 total length (header + ret,
680 but not including the length word itself)
681 struct guestfs_message_header (encoded as XDR)
682 struct guestfs_<foo>_ret (encoded as XDR)
684 As above the C<guestfs_I<foo>_ret> structure may be completely omitted
685 for functions that return no formal return values.
687 As above the total length of the reply is limited to
688 C<GUESTFS_MESSAGE_MAX>.
690 In the case of an error, a flag is set in the header, and the reply
691 message is slightly changed:
693 total length (header + error,
694 but not including the length word itself)
695 struct guestfs_message_header (encoded as XDR)
696 struct guestfs_message_error (encoded as XDR)
698 The C<guestfs_message_error> structure contains the error message as a
701 =head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS
703 A C<FileIn> parameter indicates that we transfer a file I<into> the
704 guest. The normal request message is sent (see above). However this
705 is followed by a sequence of file chunks.
707 total length (header + arguments,
708 but not including the length word itself,
709 and not including the chunks)
710 struct guestfs_message_header (encoded as XDR)
711 struct guestfs_<foo>_args (encoded as XDR)
712 sequence of chunks for FileIn param #0
713 sequence of chunks for FileIn param #1 etc.
715 The "sequence of chunks" is:
717 length of chunk (not including length word itself)
718 struct guestfs_chunk (encoded as XDR)
720 struct guestfs_chunk (encoded as XDR)
723 struct guestfs_chunk (with data.data_len == 0)
725 The final chunk has the C<data_len> field set to zero. Additionally a
726 flag is set in the final chunk to indicate either successful
727 completion or early cancellation.
729 At time of writing there are no functions that have more than one
730 FileIn parameter. However this is (theoretically) supported, by
731 sending the sequence of chunks for each FileIn parameter one after
732 another (from left to right).
734 Both the library (sender) I<and> the daemon (receiver) may cancel the
735 transfer. The library does this by sending a chunk with a special
736 flag set to indicate cancellation. When the daemon sees this, it
737 cancels the whole RPC, does I<not> send any reply, and goes back to
738 reading the next request.
740 The daemon may also cancel. It does this by writing a special word
741 C<GUESTFS_CANCEL_FLAG> to the socket. The library listens for this
742 during the transfer, and if it gets it, it will cancel the transfer
743 (it sends a cancel chunk). The special word is chosen so that even if
744 cancellation happens right at the end of the transfer (after the
745 library has finished writing and has started listening for the reply),
746 the "spurious" cancel flag will not be confused with the reply
749 This protocol allows the transfer of arbitrary sized files (no 32 bit
750 limit), and also files where the size is not known in advance
751 (eg. from pipes or sockets). However the chunks are rather small
752 (C<GUESTFS_MAX_CHUNK_SIZE>), so that neither the library nor the
753 daemon need to keep much in memory.
755 =head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS
757 The protocol for FileOut parameters is exactly the same as for FileIn
758 parameters, but with the roles of daemon and library reversed.
760 total length (header + ret,
761 but not including the length word itself,
762 and not including the chunks)
763 struct guestfs_message_header (encoded as XDR)
764 struct guestfs_<foo>_ret (encoded as XDR)
765 sequence of chunks for FileOut param #0
766 sequence of chunks for FileOut param #1 etc.
768 =head3 INITIAL MESSAGE
770 Because the underlying channel (QEmu -net channel) doesn't have any
771 sort of connection control, when the daemon launches it sends an
772 initial word (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest
773 and daemon is alive. This is what C<guestfs_launch> waits for.
777 If you want to compile your own qemu, run qemu from a non-standard
778 location, or pass extra arguments to qemu, then you can write a
779 shell-script wrapper around qemu.
781 There is one important rule to remember: you I<must C<exec qemu>> as
782 the last command in the shell script (so that qemu replaces the shell
783 and becomes the direct child of the libguestfs-using program). If you
784 don't do this, then the qemu process won't be cleaned up correctly.
786 Here is an example of a wrapper, where I have built my own copy of
790 qemudir=/home/rjones/d/qemu
791 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
793 Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
794 and then use it by setting the LIBGUESTFS_QEMU environment variable.
797 LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
799 Note that libguestfs also calls qemu with the -help and -version
800 options in order to determine features.
802 =head1 ENVIRONMENT VARIABLES
806 =item LIBGUESTFS_APPEND
808 Pass additional options to the guest kernel.
810 =item LIBGUESTFS_DEBUG
812 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This
813 has the same effect as calling C<guestfs_set_verbose (handle, 1)>.
815 =item LIBGUESTFS_MEMSIZE
817 Set the memory allocated to the qemu process, in megabytes. For
820 LIBGUESTFS_MEMSIZE=700
822 =item LIBGUESTFS_PATH
824 Set the path that libguestfs uses to search for kernel and initrd.img.
825 See the discussion of paths in section PATH above.
827 =item LIBGUESTFS_QEMU
829 Set the default qemu binary that libguestfs uses. If not set, then
830 the qemu which was found at compile time by the configure script is
833 See also L</QEMU WRAPPERS> above.
835 =item LIBGUESTFS_TRACE
837 Set C<LIBGUESTFS_TRACE=1> to enable command traces. This
838 has the same effect as calling C<guestfs_set_trace (handle, 1)>.
842 Location of temporary directory, defaults to C</tmp>.
844 If libguestfs was compiled to use the supermin appliance then each
845 handle will require rather a large amount of space in this directory
846 for short periods of time (~ 80 MB). You can use C<$TMPDIR> to
847 configure another directory to use in case C</tmp> is not large
857 L<http://libguestfs.org/>.
859 Tools with a similar purpose:
868 To get a list of bugs against libguestfs use this link:
870 L<https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools>
872 To report a new bug against libguestfs use this link:
874 L<https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools>
876 When reporting a bug, please check:
882 That the bug hasn't been reported already.
886 That you are testing a recent version.
890 Describe the bug accurately, and give a way to reproduce it.
894 Run libguestfs-test-tool and paste the B<complete, unedited>
895 output into the bug report.
901 Richard W.M. Jones (C<rjones at redhat dot com>)
905 Copyright (C) 2009 Red Hat Inc.
906 L<http://libguestfs.org/>
908 This library is free software; you can redistribute it and/or
909 modify it under the terms of the GNU Lesser General Public
910 License as published by the Free Software Foundation; either
911 version 2 of the License, or (at your option) any later version.
913 This library is distributed in the hope that it will be useful,
914 but WITHOUT ANY WARRANTY; without even the implied warranty of
915 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
916 Lesser General Public License for more details.
918 You should have received a copy of the GNU Lesser General Public
919 License along with this library; if not, write to the Free Software
920 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA