supermin: If disabled, don't compile in supermin code or check for supermin.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index c1e595c..9717543 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -390,6 +390,22 @@ an X86 host).
 For SELinux guests, you may need to enable SELinux and load policy
 first.  See L</SELINUX> in this manpage.
 
 For SELinux guests, you may need to enable SELinux and load policy
 first.  See L</SELINUX> in this manpage.
 

+=item *
+
+I<Security:> It is not safe to run commands from untrusted, possibly
+malicious guests.  These commands may attempt to exploit your program
+by sending unexpected output.  They could also try to exploit the
+Linux kernel or qemu provided by the libguestfs appliance.  They could
+use the network provided by the libguestfs appliance to bypass
+ordinary network partitions and firewalls.  They could use the
+elevated privileges or different SELinux context of your program
+to their advantage.
+
+A secure alternative is to use libguestfs to install a "firstboot"
+script (a script which runs when the guest next boots normally), and
+to have this script run the commands you want in the normal context of
+the running guest, network security and so on.
+

 =back
 
 The two main API calls to run commands are L</guestfs_command> and
 =back
 
 The two main API calls to run commands are L</guestfs_command> and


@@ -701,6 +717,9 @@ 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


@@ -751,17 +770,6 @@ The error message you get from this is also a little obscure.
 This could be fixed in the generator by specially marking parameters
 and return values which take bytes or other units.
 
 This could be fixed in the generator by specially marking parameters
 and return values which take bytes or other units.
 

-=item Library should return errno with error messages.
-
-It would be a nice-to-have to be able to get the original value of
-'errno' from inside the appliance along error paths (where set).
-Currently L<guestmount(1)> goes through hoops to try to reverse the
-error message string into an errno, see the function error() in
-fuse/guestmount.c.
-
-In libguestfs 1.5.4, the protocol was changed so that the
-Linux errno is sent back from the daemon.
-

 =item Ambiguity between devices and paths
 
 There is a subtle ambiguity in the API between a device name
 =item Ambiguity between devices and paths
 
 There is a subtle ambiguity in the API between a device name


@@ -869,17 +877,55 @@ This closes the connection handle and frees up all resources used.
 
 =head1 ERROR HANDLING
 
 
 =head1 ERROR HANDLING
 

-The convention in all functions that return C<int> is that they return
-C<-1> to indicate an error.  You can get additional information on
-errors by calling L</guestfs_last_error> and/or by setting up an error
-handler with L</guestfs_set_error_handler>.
+API functions can return errors.  For example, almost all functions
+that return C<int> will return C<-1> to indicate an error.
+
+Additional information is available for errors: an error message
+string and optionally an error number (errno) if the thing that failed
+was a system call.
+
+You can get at the additional information about the last error on the
+handle by calling L</guestfs_last_error>, L</guestfs_last_errno>,
+and/or by setting up an error handler with
+L</guestfs_set_error_handler>.

 
 

-The default error handler prints the information string to C<stderr>.
+When the handle is created, a default error handler is installed which
+prints the error message string to C<stderr>.  For small short-running
+command line programs it is sufficient to do:
+
+ if (guestfs_launch (g) == -1)
+   exit (EXIT_FAILURE);
+
+since the default error handler will ensure that an error message has
+been printed to C<stderr> before the program exits.
+
+For other programs the caller will almost certainly want to install an
+alternate error handler or do error handling in-line like this:
+
+ g = guestfs_create ();
+ 
+ /* This disables the default behaviour of printing errors
+    on stderr. */
+ guestfs_set_error_handler (g, NULL, NULL);
+ 
+ if (guestfs_launch (g) == -1) {
+   /* Examine the error message and print it etc. */
+   char *msg = guestfs_last_error (g);
+   int errnum = guestfs_last_errno (g);
+   fprintf (stderr, "%s\n", msg);
+   /* ... */
+  }

 
 Out of memory errors are handled differently.  The default action is
 to call L<abort(3)>.  If this is undesirable, then you can set a
 handler using L</guestfs_set_out_of_memory_handler>.
 
 
 Out of memory errors are handled differently.  The default action is
 to call L<abort(3)>.  If this is undesirable, then you can set a
 handler using L</guestfs_set_out_of_memory_handler>.
 

+L</guestfs_create> returns C<NULL> if the handle cannot be created,
+and because there is no handle if this happens there is no way to get
+additional error information.  However L</guestfs_create> is supposed
+to be a lightweight operation which can only fail because of
+insufficient memory (it returns NULL in this case).
+

 =head2 guestfs_last_error
 
  const char *guestfs_last_error (guestfs_h *g);
 =head2 guestfs_last_error
 
  const char *guestfs_last_error (guestfs_h *g);


@@ -891,9 +937,44 @@ returns C<NULL>.
 The lifetime of the returned string is until the next error occurs, or
 L</guestfs_close> is called.
 
 The lifetime of the returned string is until the next error occurs, or
 L</guestfs_close> is called.
 

-The error string is not localized (ie. is always in English), because
-this makes searching for error messages in search engines give the
-largest number of results.
+=head2 guestfs_last_errno
+
+ int guestfs_last_errno (guestfs_h *g);
+
+This returns the last error number (errno) that happened on C<g>.
+
+If successful, an errno integer not equal to zero is returned.
+
+If no error, this returns 0.  This call can return 0 in three
+situations:
+
+=over 4
+
+=item 1.
+
+There has not been any error on the handle.
+
+=item 2.
+
+There has been an error but the errno was meaningless.  This
+corresponds to the case where the error did not come from a
+failed system call, but for some other reason.
+
+=item 3.
+
+There was an error from a failed system call, but for some
+reason the errno was not captured and returned.  This usually
+indicates a bug in libguestfs.
+
+=back
+
+Libguestfs tries to convert the errno from inside the applicance into
+a corresponding errno for the caller (not entirely trivial: the
+appliance might be running a completely different operating system
+from the library and error numbers are not standardized across
+Un*xen).  If this could not be done, then the error is translated to
+C<EINVAL>.  In practice this should only happen in very rare
+circumstances.

 
 =head2 guestfs_set_error_handler
 
 
 =head2 guestfs_set_error_handler
 


@@ -908,6 +989,9 @@ The callback C<cb> will be called if there is an error.  The
 parameters passed to the callback are an opaque data pointer and the
 error message string.
 
 parameters passed to the callback are an opaque data pointer and the
 error message string.
 

+C<errno> is not passed to the callback.  To get that the callback must
+call L</guestfs_last_errno>.
+

 Note that the message string C<msg> is freed as soon as the callback
 function returns, so if you want to stash it somewhere you must make
 your own copy.
 Note that the message string C<msg> is freed as soon as the callback
 function returns, so if you want to stash it somewhere you must make
 your own copy.