Fix inspection code when PCRE or hivex is missing.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index d9045a5..0b3b654 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -550,10 +550,11 @@ device (I<not> the underlying encrypted block device).
 =head2 INSPECTION
 
 Libguestfs has APIs for inspecting an unknown disk image to find out
 =head2 INSPECTION
 
 Libguestfs has APIs for inspecting an unknown disk image to find out

-if it contains operating systems.  (These APIs used to be in a
-separate Perl-only library called L<Sys::Guestfs::Lib(3)> but since
-version 1.5.3 the most frequently used part of this library has been
-rewritten in C and moved into the core code).
+if it contains operating systems, an install CD or a live CD.  (These
+APIs used to be in a separate Perl-only library called
+L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most frequently
+used part of this library has been rewritten in C and moved into the
+core code).

 
 Add all disks belonging to the unknown virtual machine and call
 L</guestfs_launch> in the usual way.
 
 Add all disks belonging to the unknown virtual machine and call
 L</guestfs_launch> in the usual way.


@@ -608,6 +609,25 @@ again.  (L</guestfs_inspect_list_applications> works a little
 differently from the other calls and does read the disks.  See
 documentation for that function for details).
 
 differently from the other calls and does read the disks.  See
 documentation for that function for details).
 

+=head3 INSPECTING INSTALL DISKS
+
+Libguestfs (since 1.9.4) can detect some install disks, install
+CDs, live CDs and more.
+
+Call L</guestfs_inspect_get_format> to return the format of the
+operating system, which currently can be C<installed> (a regular
+operating system) or C<installer> (some sort of install disk).
+
+Further information is available about the operating system that can
+be installed using the regular inspection APIs like
+L</guestfs_inspect_get_product_name>,
+L</guestfs_inspect_get_major_version> etc.
+
+Some additional information specific to installer disks is also
+available from the L</guestfs_inspect_is_live>,
+L</guestfs_inspect_is_netinst> and L</guestfs_inspect_is_multipart>
+calls.
+

 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
 
 Libguestfs can mount NTFS partitions.  It does this using the
 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
 
 Libguestfs can mount NTFS partitions.  It does this using the


@@ -717,7 +737,7 @@ See L<guestfs-ocaml(3)>.
 
 =item B<Perl>
 
 
 =item B<Perl>
 

-See L<Sys::Guestfs(3)>.
+See L<guestfs-perl(3)> and L<Sys::Guestfs(3)>.

 
 =item B<PHP>
 
 
 =item B<PHP>
 


@@ -952,6 +972,63 @@ For example:
 Note that libguestfs also calls qemu with the -help and -version
 options in order to determine features.
 
 Note that libguestfs also calls qemu with the -help and -version
 options in order to determine features.
 

+=head2 ATTACHING TO RUNNING DAEMONS
+
+I<Note (1):> This is B<highly experimental> and has a tendency to eat
+babies.  Use with caution.
+
+I<Note (2):> This section explains how to attach to a running daemon
+from a low level perspective.  For most users, simply using virt tools
+such as L<guestfish(1)> with the I<--live> option will "just work".
+
+=head3 Using guestfs_set_attach_method
+
+By calling L</guestfs_set_attach_method> you can change how the
+library connects to the C<guestfsd> daemon in L</guestfs_launch>
+(read L</ARCHITECTURE> for some background).
+
+The normal attach method is C<appliance>, where a small appliance is
+created containing the daemon, and then the library connects to this.
+
+Setting attach method to C<unix:I<path>> (where I<path> is the path of
+a Unix domain socket) causes L</guestfs_launch> to connect to an
+existing daemon over the Unix domain socket.
+
+The normal use for this is to connect to a running virtual machine
+that contains a C<guestfsd> daemon, and send commands so you can read
+and write files inside the live virtual machine.
+
+=head3 Using guestfs_add_domain with live flag
+
+L</guestfs_add_domain> provides some help for getting the
+correct attach method.  If you pass the C<live> option to this
+function, then (if the virtual machine is running) it will
+examine the libvirt XML looking for a virtio-serial channel
+to connect to:
+
+ <domain>
+   ...
+   <devices>
+     ...
+     <channel type='unix'>
+       <source mode='bind' path='/path/to/socket'/>
+       <target type='virtio' name='org.libguestfs.channel.0'/>
+     </channel>
+     ...
+   </devices>
+ </domain>
+
+L</guestfs_add_domain> extracts C</path/to/socket> and sets the attach
+method to C<unix:/path/to/socket>.
+
+Some of the libguestfs tools (including guestfish) support a I<--live>
+option which is passed through to L</guestfs_add_domain> thus allowing
+you to attach to and modify live virtual machines.
+
+The virtual machine needs to have been set up beforehand so that it
+has the virtio-serial channel and so that guestfsd is running inside
+it.
+

 =head2 ABI GUARANTEE
 
 We guarantee the libguestfs ABI (binary interface), for public,
 =head2 ABI GUARANTEE
 
 We guarantee the libguestfs ABI (binary interface), for public,


@@ -2481,12 +2558,13 @@ has the same effect as calling C<guestfs_set_trace (g, 1)>.
 
 =item TMPDIR
 
 
 =item TMPDIR
 

-Location of temporary directory, defaults to C</tmp>.
+Location of temporary directory, defaults to C</tmp> except for the
+cached supermin appliance which defaults to C</var/tmp>.

 
 If libguestfs was compiled to use the supermin appliance then the
 real appliance is cached in this directory, shared between all
 handles belonging to the same EUID.  You can use C<$TMPDIR> to
 
 If libguestfs was compiled to use the supermin appliance then the
 real appliance is cached in this directory, shared between all
 handles belonging to the same EUID.  You can use C<$TMPDIR> to

-configure another directory to use in case C</tmp> is not large
+configure another directory to use in case C</var/tmp> is not large

 enough.
 
 =back
 enough.
 
 =back