=head1 SYNOPSIS
#include <guestfs.h>
-
+
guestfs_h *handle = guestfs_create ();
guestfs_add_drive (handle, "guest.img");
guestfs_launch (handle);
functions in the following order:
guestfs_h *handle = guestfs_create ();
-
+
guestfs_add_drive (handle, "guest.img");
/* call guestfs_add_drive additional times if the guest has
* multiple disks
*/
-
+
guestfs_launch (handle);
guestfs_wait_ready (handle);
/* now you can examine what partitions, LVs etc are available
* you have to mount / at least
- */
+ */
guestfs_mount (handle, "/dev/sda1", "/");
/* now you can perform actions on the guest disk image */
guestfs_touch (handle, "/hello");
-
+
/* you only need to call guestfs_sync if you have made
* changes to the guest image
*/
guestfs_sync (handle);
-
+
guestfs_close (handle);
C<guestfs_wait_ready> and all of the actions including C<guestfs_sync>
non-blocking operations instead.
All functions that return integers, return C<-1> on error. See
-section ERROR HANDLING below for how to handle errors.
+section L</ERROR HANDLING> below for how to handle errors.
=head2 guestfs_h *
to free the handle and release all resources used.
For information on using multiple handles and threads, see the section
-MULTIPLE HANDLES AND MULTIPLE THREADS below.
+L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
=head2 guestfs_create
C<guestfs_wait_ready>.
You may also want to configure error handling for the handle. See
-ERROR HANDLING section below.
+L</ERROR HANDLING> section below.
=head2 guestfs_close
Returns the current error handler callback.
-=head2 guestfs_set_out_of_memory_handler
+=head2 guestfs_set_out_of_memory_handler
typedef void (*guestfs_abort_cb) (void);
int guestfs_set_out_of_memory_handler (guestfs_h *handle,
or C<.>. For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
search the current directory and then C</usr/lib/guestfs>.
+=head1 API OVERVIEW
+
+This section provides additional documentation for groups of API
+calls, which may not be obvious from reading about the individual
+calls below.
+
+=head2 LVM2
+
+Libguestfs provides access to a large part of the LVM2 API. It won't
+make much sense unless you familiarize yourself with the concepts of
+physical volumes, volume groups and logical volumes.
+
+This author strongly recommends reading the LVM HOWTO, online at
+L<http://tldp.org/HOWTO/LVM-HOWTO/>.
+
+=head2 PARTITIONING
+
+To create MBR-style (ie. normal PC) partitions use one of the
+C<guestfs_sfdisk*> variants. These calls use the external
+L<sfdisk(8)> command.
+
+The simplest call is:
+
+ char *lines[] = { ",", NULL };
+ guestfs_sfdiskM (g, "/dev/sda", lines);
+
+This will create a single partition on C</dev/sda> called
+C</dev/sda1> covering the whole disk.
+
+In general MBR partitions are both unnecessarily complicated and
+depend on archaic details, namely the Cylinder-Head-Sector (CHS)
+geometry of the disk. C<guestfs_sfdiskM> allows you to specify sizes
+in megabytes instead of cylinders, which is a small win.
+C<guestfs_sfdiskM> will choose the nearest cylinder to approximate the
+requested size. There's a lot of crazy stuff to do with IDE and
+virtio disks having different, incompatible CHS geometries, that you
+probably don't want to know about. My advice: make a single partition
+to cover the whole disk, then use LVM on top.
+
+In future we aim to provide access to libparted.
+
+=head2 UPLOADING
+
+For small, single files, use C<guestfs_write_file>. In some versions
+of libguestfs there was a bug which limited this call to text files
+(not containing ASCII NUL characters).
+
+To upload a single file, use C<guestfs_upload>. This call has no
+limits on file content or size (even files larger than 4 GB).
+
+To upload multiple files, see C<guestfs_tar_in> and C<guestfs_tgz_in>.
+
+However the fastest way to upload I<large numbers of arbitrary files>
+is to turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and
+L<mkisofs(8)>), then attach this using C<guestfs_add_drive_ro>. If
+you add the drive in a predictable way (eg. adding it last after all
+other drives) then you can get the device name from
+C<guestfs_list_devices> and mount it directly using
+C<guestfs_mount_ro>. Note that squashfs images are sometimes
+non-portable between kernel versions, and they don't support labels or
+UUIDs. If you want to pre-build an image or you need to mount it
+using a label or UUID, use an ISO image instead.
+
+=head2 DOWNLOADING
+
+Use C<guestfs_cat> to download small, text only files. This call
+is limited to files which are less than 2 MB and which cannot contain
+any ASCII NUL (C<\0>) characters. However it has a very simple
+to use API.
+
+C<guestfs_read_file> can be used to read files which contain
+arbitrary 8 bit data, since it returns a (pointer, size) pair.
+However it is still limited to "small" files, less than 2 MB.
+
+C<guestfs_download> can be used to download any file, with no
+limits on content or size (even files larger than 4 GB).
+
+To download multiple files, see C<guestfs_tar_out> and
+C<guestfs_tgz_out>.
+
+=head2 RUNNING COMMANDS
+
+Although libguestfs is a primarily an API for manipulating files
+inside guest images, we also provide some limited facilities for
+running commands inside guests.
+
+There are many limitations to this:
+
+=over 4
+
+=item *
+
+The kernel version that the command runs under will be different
+from what it expects.
+
+=item *
+
+If the command needs to communicate with daemons, then most likely
+they won't be running.
+
+=item *
+
+The command will be running in limited memory.
+
+=item *
+
+Only supports Linux guests (not Windows, BSD, etc).
+
+=item *
+
+Architecture limitations (eg. won't work for a PPC guest on
+an X86 host).
+
+=item *
+
+For SELinux guests, you may need to enable SELinux and load policy
+first. See L</SELINUX> in this manpage.
+
+=back
+
+The two main API calls to run commands are C<guestfs_command> and
+C<guestfs_sh> (there are also variations).
+
+The difference is that C<guestfs_sh> runs commands using the shell, so
+any shell globs, redirections, etc will work.
+
+=head2 LISTING FILES
+
+C<guestfs_ll> is just designed for humans to read (mainly when using
+the L<guestfish(1)>-equivalent command C<ll>).
+
+C<guestfs_ls> is a quick way to get a list of files in a directory
+from programs.
+
+C<guestfs_readdir> is a programmatic way to get a list of files in a
+directory, plus additional information about each one.
+
+C<guestfs_find> can be used to recursively list files.
+
+=head2 SELINUX
+
+We support SELinux guests. To ensure that labeling happens correctly
+in SELinux guests, you need to enable SELinux and load the guest's
+policy:
+
+=over 4
+
+=item 1.
+
+Before launching, do:
+
+ guestfs_set_selinux (g, 1);
+
+=item 2.
+
+After mounting the guest's filesystem(s), load the policy. This
+is best done by running the L<load_policy(8)> command in the
+guest itself:
+
+ guestfs_sh (g, "/usr/sbin/load_policy");
+
+(Older versions of C<load_policy> require you to specify the
+name of the policy file).
+
+=item 3.
+
+Optionally, set the security context for the API. The correct
+security context to use can only be known by inspecting the
+guest. As an example:
+
+ guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0");
+
+=back
+
+This will work for running commands and editing existing files.
+
+When new files are created, you may need to label them explicitly,
+for example by running the external command
+C<restorecon pathname>.
+
=head1 HIGH-LEVEL API ACTIONS
+=head2 ABI GUARANTEE
+
+We guarantee the libguestfs ABI (binary interface), for public,
+high-level actions as outlined in this section. Although we will
+deprecate some actions, for example if they get replaced by newer
+calls, we will keep the old actions forever. This allows you the
+developer to program in confidence against libguestfs.
+
@ACTIONS@
=head1 STRUCTURES
LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
+Note that libguestfs also calls qemu with the -help and -version
+options in order to determine features.
+
=head1 ENVIRONMENT VARIABLES
=over 4
+=item LIBGUESTFS_APPEND
+
+Pass additional options to the guest kernel.
+
=item LIBGUESTFS_DEBUG
Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This
has the same effect as calling C<guestfs_set_verbose (handle, 1)>.
+=item LIBGUESTFS_MEMSIZE
+
+Set the memory allocated to the qemu process, in megabytes. For
+example:
+
+ LIBGUESTFS_MEMSIZE=700
+
=item LIBGUESTFS_PATH
Set the path that libguestfs uses to search for kernel and initrd.img.
the qemu which was found at compile time by the configure script is
used.
-See also L<QEMU WRAPPERS> above.
+See also L</QEMU WRAPPERS> above.
-=item LIBGUESTFS_APPEND
+=item LIBGUESTFS_TRACE
-Pass additional options to the guest kernel.
+Set C<LIBGUESTFS_TRACE=1> to enable command traces. This
+has the same effect as calling C<guestfs_set_trace (handle, 1)>.
+
+=item TMPDIR
+
+Location of temporary directory, defaults to C</tmp>.
+
+If libguestfs was compiled to use the supermin appliance then each
+handle will require rather a large amount of space in this directory
+for short periods of time (~ 80 MB). You can use C<$TMPDIR> to
+configure another directory to use in case C</tmp> is not large
+enough.
=back
L<febootstrap(1)>,
L<http://libguestfs.org/>.
+Tools with a similar purpose:
+L<fdisk(8)>,
+L<parted(8)>,
+L<kpartx(8)>,
+L<lvm(8)>,
+L<disktype(1)>.
+
=head1 BUGS
To get a list of bugs against libguestfs use this link:
Describe the bug accurately, and give a way to reproduce it.
+=item *
+
+Run libguestfs-test-tool and paste the B<complete, unedited>
+output into the bug report.
+
=back
=head1 AUTHORS
git.annexia.org / libguestfs.git / blobdiff