Rename internal functions.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 0f60c8e..5a2e7a5 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -450,6 +450,37 @@ L</guestfs_chmod> after creating each file or directory.
 
 For more information about umask, see L<umask(2)>.
 
+=head2 ENCRYPTED DISKS
+
+Libguestfs allows you to access Linux guests which have been
+encrypted using whole disk encryption that conforms to the
+Linux Unified Key Setup (LUKS) standard.  This includes
+nearly all whole disk encryption systems used by modern
+Linux guests.
+
+Use L</guestfs_vfs_type> to identify LUKS-encrypted block
+devices (it returns the string C<crypto_LUKS>).
+
+Then open these devices by calling L</guestfs_luks_open>.
+Obviously you will require the passphrase!
+
+Opening a LUKS device creates a new device mapper device
+called C</dev/mapper/mapname> (where C<mapname> is the
+string you supply to L</guestfs_luks_open>).
+Reads and writes to this mapper device are decrypted from and
+encrypted to the underlying block device respectively.
+
+LVM volume groups on the device can be made visible by calling
+L</guestfs_vgscan> followed by L</guestfs_vg_activate_all>.
+The logical volume(s) can now be mounted in the usual way.
+
+Use the reverse process to close a LUKS device.  Unmount
+any logical volumes on it, deactivate the volume groups
+by caling C<guestfs_vg_activate (g, 0, ["/dev/VG"])>.
+Then close the mapper device by calling
+L</guestfs_luks_close> on the C</dev/mapper/mapname>
+device (I<not> the underlying encrypted block device).
+
 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
 
 Libguestfs can mount NTFS partitions.  It does this using the
@@ -612,6 +643,27 @@ the error message was also unintuitive, but we have corrected this
 since.  Like the Bourne shell, we should have used C<guestfish -c
 command> to run commands.
 
+=item guestfish megabyte modifiers don't work right on all commands
+
+In recent guestfish you can use C<1M> to mean 1 megabyte (and
+similarly for other modifiers).  What guestfish actually does is to
+multiply the number part by the modifier part and pass the result to
+the C API.  However this doesn't work for a few APIs which aren't
+expecting bytes, but are already expecting some other unit
+(eg. megabytes).
+
+The most common is L</guestfs_lvcreate>.  The guestfish command:
+
+ lvcreate LV VG 100M
+
+does not do what you might expect.  Instead because
+L</guestfs_lvcreate> is already expecting megabytes, this tries to
+create a 100 I<terabyte> (100 megabytes * megabytes) logical volume.
+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.
+
 =item Protocol limit of 256 characters for error messages
 
 This limit is both rather small and quite unnecessary.  We should be
@@ -654,6 +706,21 @@ 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
+material, passed in as a C string.
+
+In the future we would hope to change the libguestfs implementation so
+that keys are L<mlock(2)>-ed into physical RAM, and thus can never end
+up in swap.  However this is I<not> done at the moment, because of the
+complexity of such an implementation.
+
+Therefore you should be aware that any key parameter you pass to
+libguestfs might end up being written out to the swap partition.  If
+this is a concern, scrub the swap partition or don't use libguestfs on
+encrypted devices.
+
 =head1 CONNECTION MANAGEMENT
 
 =head2 guestfs_h *
@@ -1042,6 +1109,24 @@ The callback function C<cb> will be called when the child process
 becomes ready first time after it has been launched.  (This
 corresponds to a transition from LAUNCHING to the READY state).
 
+=head2 guestfs_set_close_callback
+
+ typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);
+ void guestfs_set_close_callback (guestfs_h *g,
+                                  guestfs_close_cb cb,
+                                  void *opaque);
+
+The callback function C<cb> will be called while the handle
+is being closed (synchronously from L</guestfs_close>).
+
+Note that libguestfs installs an L<atexit(3)> handler to try to
+clean up handles that are open when the program exits.  This
+means that this callback might be called indirectly from
+L<exit(3)>, which can cause unexpected problems in higher-level
+languages (eg. if your HLL interpreter has already been cleaned
+up by the time this is called, and if your callback then jumps
+into some HLL function).
+
 =head1 BLOCK DEVICE NAMING
 
 In the kernel there is now quite a profusion of schemata for naming