Add caution subdirectory containing safety and liveness tests.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index c22ad51..842b0e4 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -354,7 +354,7 @@ doing:
 
  guestfs_download (g, filename, "/dev/stdout");
 
 
  guestfs_download (g, filename, "/dev/stdout");
 

-and you can write tar output to a pipe C<fd> by doing:
+and you can write tar output to a file descriptor C<fd> by doing:

 
  char devfd[64];
  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
 
  char devfd[64];
  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);


@@ -775,6 +775,9 @@ them.
 
 =item Autosync / forgetting to sync.
 
 
 =item Autosync / forgetting to sync.
 

+I<Update:> Autosync is enabled by default for all API users starting
+from libguestfs 1.5.24.  This section only applies to older versions.
+

 When modifying a filesystem from C or another language, you B<must>
 unmount all filesystems and call L</guestfs_sync> explicitly before
 you close the libguestfs handle.  You can also call:
 When modifying a filesystem from C or another language, you B<must>
 unmount all filesystems and call L</guestfs_sync> explicitly before
 you close the libguestfs handle.  You can also call:


@@ -793,9 +796,6 @@ Note that in L<guestfish(3)> autosync is the default.  So quick and
 dirty guestfish scripts that forget to sync will work just fine, which
 can make this very puzzling if you are trying to debug a problem.
 
 dirty guestfish scripts that forget to sync will work just fine, which
 can make this very puzzling if you are trying to debug a problem.
 

-Update: Autosync is enabled by default for all API users starting from
-libguestfs 1.5.24.
-

 =item Mount option C<-o sync> should not be the default.
 
 If you use L</guestfs_mount>, then C<-o sync,noatime> are added
 =item Mount option C<-o sync> should not be the default.
 
 If you use L</guestfs_mount>, then C<-o sync,noatime> are added


@@ -879,29 +879,6 @@ representation.  Also consider how it might work in guestfish.
 
 =back
 
 
 =back
 

-=head2 PROTOCOL LIMITS
-
-Internally libguestfs uses a message-based protocol to pass API calls
-and their responses to and from a small "appliance" (see L</INTERNALS>
-for plenty more detail about this).  The maximum message size used by
-the protocol is slightly less than 4 MB.  For some API calls you may
-need to be aware of this limit.  The API calls which may be affected
-are individually documented, with a link back to this section of the
-documentation.
-
-A simple call such as L</guestfs_cat> returns its result (the file
-data) in a simple string.  Because this string is at some point
-internally encoded as a message, the maximum size that it can return
-is slightly under 4 MB.  If the requested file is larger than this
-then you will get an error.
-
-In order to transfer large files into and out of the guest filesystem,
-you need to use particular calls that support this.  The sections
-L</UPLOADING> and L</DOWNLOADING> document how to do this.
-
-You might also consider mounting the disk image using our FUSE
-filesystem support (L<guestmount(1)>).
-

 =head2 KEYS AND PASSPHRASES
 
 Certain libguestfs calls take a parameter that contains sensitive key
 =head2 KEYS AND PASSPHRASES
 
 Certain libguestfs calls take a parameter that contains sensitive key


@@ -1308,7 +1285,7 @@ Create a handle by calling L</guestfs_create>.  Call L</guestfs_close>
 to free the handle and release all resources used.
 
 For information on using multiple handles and threads, see the section
 to free the handle and release all resources used.
 
 For information on using multiple handles and threads, see the section

-L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
+L</MULTIPLE HANDLES AND MULTIPLE THREADS> above.

 
 =head2 guestfs_create
 
 
 =head2 guestfs_create
 


@@ -1316,15 +1293,16 @@ L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
 
 Create a connection handle.
 
 
 Create a connection handle.
 

-You have to call L</guestfs_add_drive_opts> (or one of the equivalent
-calls) on the handle at least once.
+On success this returns a non-NULL pointer to a handle.  On error it
+returns NULL.

 
 

-This function returns a non-NULL pointer to a handle on success or
-NULL on error.
+You have to "configure" the handle after creating it.  This includes
+calling L</guestfs_add_drive_opts> (or one of the equivalent calls) on
+the handle at least once.

 
 After configuring the handle, you have to call L</guestfs_launch>.
 
 
 After configuring the handle, you have to call L</guestfs_launch>.
 

-You may also want to configure error handling for the handle.  See
+You may also want to configure error handling for the handle.  See the

 L</ERROR HANDLING> section below.
 
 =head2 guestfs_close
 L</ERROR HANDLING> section below.
 
 =head2 guestfs_close


@@ -1333,6 +1311,12 @@ L</ERROR HANDLING> section below.
 
 This closes the connection handle and frees up all resources used.
 
 
 This closes the connection handle and frees up all resources used.
 

+If autosync was set on the handle and the handle was launched, then
+this implicitly calls various functions to unmount filesystems and
+sync the disk.  See L</guestfs_set_autosync> for more details.
+
+If a close callback was set on the handle, then it is called.
+

 =head1 ERROR HANDLING
 
 API functions can return errors.  For example, almost all functions
 =head1 ERROR HANDLING
 
 API functions can return errors.  For example, almost all functions


@@ -1688,7 +1672,8 @@ old functions C<guestfs_set_log_message_callback>,
 C<guestfs_set_subprocess_quit_callback>,
 C<guestfs_set_launch_done_callback>, C<guestfs_set_close_callback> and
 C<guestfs_set_progress_callback> are no longer documented in this
 C<guestfs_set_subprocess_quit_callback>,
 C<guestfs_set_launch_done_callback>, C<guestfs_set_close_callback> and
 C<guestfs_set_progress_callback> are no longer documented in this

-manual page.
+manual page.  Because of the ABI guarantee, the old functions continue
+to work.

 
 Handles generate events when certain things happen, such as log
 messages being generated, progress messages during long-running
 
 Handles generate events when certain things happen, such as log
 messages being generated, progress messages during long-running


@@ -1977,12 +1962,13 @@ To attach a named piece of data, use the following call:
 
 C<key> is the name to associate with this data, and C<data> is an
 arbitrary pointer (which can be C<NULL>).  Any previous item with the
 
 C<key> is the name to associate with this data, and C<data> is an
 arbitrary pointer (which can be C<NULL>).  Any previous item with the

-same name is overwritten.
+same key is overwritten.

 
 

-You can use any C<key> you want, but names beginning with an
-underscore character are reserved for internal libguestfs purposes
-(for implementing language bindings).  It is recommended to prefix the
-name with some unique string to avoid collisions with other users.
+You can use any C<key> you want, but your key should I<not> start with
+an underscore character.  Keys beginning with an underscore character
+are reserved for internal libguestfs purposes (eg. for implementing
+language bindings).  It is recommended that you prefix the key with
+some unique string to avoid collisions with other users.

 
 To retrieve the pointer, use:
 
 
 To retrieve the pointer, use:
 


@@ -2672,6 +2658,11 @@ Automated tests of the C API.
 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
 and documentation.
 
 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
 and documentation.
 

+=item C<caution>
+
+Safety and liveness tests of components that libguestfs depends upon
+(not of libguestfs itself).  Mainly this is for qemu and the kernel.
+

 =item C<contrib>
 
 Outside contributions, experimental parts.
 =item C<contrib>
 
 Outside contributions, experimental parts.


@@ -2685,6 +2676,10 @@ actions.
 
 L<virt-df(1)> command and documentation.
 
 
 L<virt-df(1)> command and documentation.
 

+=item C<edit>
+
+L<virt-edit(1)> command and documentation.
+

 =item C<examples>
 
 C API example code.
 =item C<examples>
 
 C API example code.


@@ -2773,6 +2768,106 @@ Language bindings.
 
 =back
 
 
 =back
 

+=head1 LIMITS
+
+=head2 PROTOCOL LIMITS
+
+Internally libguestfs uses a message-based protocol to pass API calls
+and their responses to and from a small "appliance" (see L</INTERNALS>
+for plenty more detail about this).  The maximum message size used by
+the protocol is slightly less than 4 MB.  For some API calls you may
+need to be aware of this limit.  The API calls which may be affected
+are individually documented, with a link back to this section of the
+documentation.
+
+A simple call such as L</guestfs_cat> returns its result (the file
+data) in a simple string.  Because this string is at some point
+internally encoded as a message, the maximum size that it can return
+is slightly under 4 MB.  If the requested file is larger than this
+then you will get an error.
+
+In order to transfer large files into and out of the guest filesystem,
+you need to use particular calls that support this.  The sections
+L</UPLOADING> and L</DOWNLOADING> document how to do this.
+
+You might also consider mounting the disk image using our FUSE
+filesystem support (L<guestmount(1)>).
+
+=head2 MAXIMUM NUMBER OF DISKS
+
+When using virtio disks (the default) the current limit is B<25>
+disks.
+
+Virtio itself consumes 1 virtual PCI slot per disk, and PCI is limited
+to 31 slots.  However febootstrap only understands disks with names
+C</dev/vda> through C</dev/vdz> (26 letters) and it reserves one disk
+for its own purposes.
+
+We are working to substantially raise this limit in future versions
+but it requires complex changes to qemu.
+
+In future versions of libguestfs it should also be possible to "hot
+plug" disks (add and remove disks after calling L</guestfs_launch>).
+This also requires changes to qemu.
+
+=head2 MAXIMUM NUMBER OF PARTITIONS PER DISK
+
+Virtio limits the maximum number of partitions per disk to B<15>.
+
+This is because it reserves 4 bits for the minor device number (thus
+C</dev/vda>, and C</dev/vda1> through C</dev/vda15>).
+
+If you attach a disk with more than 15 partitions, the extra
+partitions are ignored by libguestfs.
+
+=head2 MAXIMUM SIZE OF A DISK
+
+Probably the limit is between 2**63-1 and 2**64-1 bytes.
+
+We have tested block devices up to 1 exabyte (2**60 or
+1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
+host filesystem.
+
+Although libguestfs probably does not impose any limit, the underlying
+host storage will.  If you store disk images on a host ext4
+filesystem, then the maximum size will be limited by the maximum ext4
+file size (currently 16 TB).  If you store disk images as host logical
+volumes then you are limited by the maximum size of an LV.
+
+For the hugest disk image files, we recommend using XFS on the host
+for storage.
+
+=head2 MAXIMUM SIZE OF A PARTITION
+
+The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
+numbers.  Assuming a 512 byte sector size, this means that MBR cannot
+address a partition located beyond 2 TB on the disk.
+
+It is recommended that you use GPT partitions on disks which are
+larger than this size.  GPT uses 64 bit sector numbers and so can
+address partitions which are theoretically larger than the largest
+disk we could support.
+
+=head2 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
+
+This depends on the filesystem type.  libguestfs itself does not
+impose any known limit.  Consult Wikipedia or the filesystem
+documentation to find out what these limits are.
+
+=head2 MAXIMUM UPLOAD AND DOWNLOAD
+
+The API functions L</guestfs_upload>, L</guestfs_download>,
+L</guestfs_tar_in>, L</guestfs_tar_out> and the like allow unlimited
+sized uploads and downloads.
+
+=head2 INSPECTION LIMITS
+
+The inspection code has several arbitrary limits on things like the
+size of Windows Registry hive it will read, and the length of product
+name.  These are intended to stop a malicious guest from consuming
+arbitrary amounts of memory and disk space on the host, and should not
+be reached in practice.  See the source code for more information.
+

 =head1 ENVIRONMENT VARIABLES
 
 =over 4
 =head1 ENVIRONMENT VARIABLES
 
 =over 4