X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=9e0d4d3188c1d64ab2d440b459e21eee98d9428f;hp=06cc2b3a457198c9c6f519a6c5307c444425d116;hb=34d2df41626f1ee4172a6d40b06d72d6ed9d6348;hpb=d43dac69483e8ec62e8356d93f761684ce2f5cc8 diff --git a/guestfs.pod b/guestfs.pod index 06cc2b3..9e0d4d3 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -7,7 +7,7 @@ guestfs - Library for accessing and modifying virtual machine images =head1 SYNOPSIS #include - + guestfs_h *handle = guestfs_create (); guestfs_add_drive (handle, "guest.img"); guestfs_launch (handle); @@ -49,28 +49,28 @@ If you are using the high-level API, then you should call the 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 and all of the actions including C @@ -168,7 +168,7 @@ If you set C to C then I handler is called. 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, @@ -203,8 +203,150 @@ directory is I searched unless the path contains an empty element or C<.>. For example C would search the current directory and then C. +=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. + +=head2 PARTITIONING + +To create MBR-style (ie. normal PC) partitions use one of the +C variants. These calls use the external +L command. + +The simplest call is: + + char *lines[] = { ",", NULL }; + guestfs_sfdiskM (g, "/dev/sda", lines); + +This will create a single partition on C called +C 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 allows you to specify sizes +in megabytes instead of cylinders, which is a small win. +C 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. 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. This call has no +limits on file content or size (even files larger than 4 GB). + +To upload multiple files, see C and C. + +However the fastest way to upload I +is to turn them into a squashfs or CD ISO (see L and +L), then attach this using C. 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 and mount it directly using +C. 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 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 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 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 and +C. + +=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). + +=back + +The two main API calls to run commands are C and +C (there are also variations). + +The difference is that C runs commands using the shell, so +any shell globs, redirections, etc will work. + +=head2 LISTING FILES + +C is just designed for humans to read (mainly when using +the L-equivalent command C). + +C is a quick way to get a list of files in a directory +from programs. + +C is a programmatic way to get a list of files in a +directory, plus additional information about each one. + +C can be used to recursively list files. + =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 @@ -491,6 +633,109 @@ C. This isn't documented. Please see the libguestfs-select and libguestfs-glib implementations. +=head1 BLOCK DEVICE NAMING + +In the kernel there is now quite a profusion of schemata for naming +block devices (in this context, by I I mean a physical +or virtual hard drive). The original Linux IDE driver used names +starting with C. SCSI devices have historically used a +different naming scheme, C. When the Linux kernel I +driver became a popular replacement for the old IDE driver +(particularly for SATA devices) those devices also used the +C scheme. Additionally we now have virtual machines with +paravirtualized drivers. This has created several different naming +systems, such as C for virtio disks and C for Xen +PV disks. + +As discussed above, libguestfs uses a qemu appliance running an +embedded Linux kernel to access block devices. We can run a variety +of appliances based on a variety of Linux kernels. + +This causes a problem for libguestfs because many API calls use device +or partition names. Working scripts and the recipe (example) scripts +that we make available over the internet could fail if the naming +scheme changes. + +Therefore libguestfs defines C as the I. Internally C names are translated, if necessary, +to other names as required. For example, under RHEL 5 which uses the +C scheme, any device parameter C is translated to +C transparently. + +Note that this I applies to parameters. The +C, C and similar calls +return the true names of the devices and partitions as known to the +appliance. + +=head2 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION + +Usually this translation is transparent. However in some (very rare) +cases you may need to know the exact algorithm. Such cases include +where you use C to add a mixture of virtio and IDE +devices to the qemu-based appliance, so have a mixture of C +and C devices. + +The algorithm is applied only to I which are known to be +either device or partition names. Return values from functions such +as C are never changed. + +=over 4 + +=item * + +Is the string a parameter which is a device or partition name? + +=item * + +Does the string begin with C? + +=item * + +Does the named device exist? If so, we use that device. +However if I then we continue with this algorithm. + +=item * + +Replace initial C string with C. + +For example, change C to C. + +If that named device exists, use it. If not, continue. + +=item * + +Replace initial C string with C. + +If that named device exists, use it. If not, return an error. + +=back + +=head2 PORTABILITY CONCERNS + +Although the standard naming scheme and automatic translation is +useful for simple programs and guestfish scripts, for larger programs +it is best not to rely on this mechanism. + +Where possible for maximum future portability programs using +libguestfs should use these future-proof techniques: + +=over 4 + +=item * + +Use C or C to list +actual device names, and then use those names directly. + +Since those device names exist by definition, they will never be +translated. + +=item * + +Use higher level ways to identify filesystems, such as LVM names, +UUIDs and filesystem labels. + +=back + =head1 INTERNALS =head2 COMMUNICATION PROTOCOL @@ -656,15 +901,33 @@ For example: 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 to enable verbose messages. This has the same effect as calling C. +=item LIBGUESTFS_KERNEL + +Override the ordinary selection of appliance kernel. + +=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. @@ -678,6 +941,16 @@ used. See also L above. +=item TMPDIR + +Location of temporary directory, defaults to C. + +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 is not large +enough. + =back =head1 SEE ALSO @@ -685,7 +958,35 @@ See also L above. L, L, L, -L. +L. + +=head1 BUGS + +To get a list of bugs against libguestfs use this link: + +L + +To report a new bug against libguestfs use this link: + +L + +When reporting a bug, please check: + +=over 4 + +=item * + +That the bug hasn't been reported already. + +=item * + +That you are testing a recent version. + +=item * + +Describe the bug accurately, and give a way to reproduce it. + +=back =head1 AUTHORS @@ -694,7 +995,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT Copyright (C) 2009 Red Hat Inc. -L +L This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public