X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=inspector%2Fvirt-inspector.pod;h=54968279a7fe54cec231920d905bcb52fe9ff9dc;hp=0205842907ed7fa7f62e6869be0c22a3b70e82db;hb=f0f3e1621180724e0a907a30ff5dea9695ddead0;hpb=c5cb65f0aac3298e634b183f73fda6644a158018

diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod
index 0205842..5496827 100755
--- a/inspector/virt-inspector.pod
+++ b/inspector/virt-inspector.pod
@@ -34,6 +34,9 @@ several I<-a> options one after another, with the first corresponding
 to the guest's C</dev/sda>, the second to the guest's C</dev/sdb> and
 so on.
 
+You can also run virt-inspector on install disks, live CDs, bootable
+USB keys and similar.
+
 Virt-inspector can only inspect and report upon I<one domain at a
 time>.  To inspect several virtual machines, you have to run
 virt-inspector several times (for example, from a shell script
@@ -42,6 +45,13 @@ for-loop).
 Because virt-inspector needs direct access to guest images, it won't
 normally work over remote libvirt connections.
 
+All of the information available from virt-inspector is also available
+through the core libguestfs inspection API (see
+L<guestfs(3)/INSPECTION>).  The same information can also be fetched
+using guestfish or via libguestfs bindings in many programming
+languages
+(see L<guestfs(3)/USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES>).
+
 =head1 OPTIONS
 
 =over 4
@@ -76,7 +86,8 @@ then libvirt is not used at all.
 
 =item B<--domain> guest
 
-Add all the disks from the named libvirt guest.
+Add all the disks from the named libvirt guest.  Domain UUIDs can be
+used instead of names.
 
 =item B<--echo-keys>
 
@@ -142,7 +153,8 @@ For compatibility the old style is still supported.
 =head1 XML FORMAT
 
 The virt-inspector XML is described precisely in a RELAX NG schema
-which is supplied with libguestfs.  This section is just an overview.
+file C<virt-inspector.rng> which is supplied with libguestfs.  This
+section is just an overview.
 
 The top-level element is E<lt>operatingsystemsE<gt>, and it contains
 one or more E<lt>operatingsystemE<gt> elements.  You would only see
@@ -162,12 +174,19 @@ describe the operating system, its architecture, the descriptive
      <arch>i386</arch>
      <distro>windows</distro>
      <product_name>Windows 7 Enterprise</product_name>
+     <product_variant>Client</product_variant>
      <major_version>6</major_version>
      <minor_version>1</minor_version>
      <windows_systemroot>/Windows</windows_systemroot>
+     <format>installed</format>
 
-These fields are derived from the libguestfs inspection API, and
-you can find more details in L<guestfs(3)/INSPECTION>.
+In brief, E<lt>nameE<gt> is the class of operating system (something
+like C<linux> or C<windows>), E<lt>distroE<gt> is the distribution
+(eg. C<fedora> but many other distros are recognized) and
+E<lt>archE<gt> is the guest architecture.  The other fields are fairly
+self-explanatory, but because these fields are taken directly from the
+libguestfs inspection API you can find precise information from
+L<guestfs(3)/INSPECTION>.
 
 The E<lt>rootE<gt> element is the root filesystem device, but from the
 point of view of libguestfs (block devices may have completely
@@ -197,7 +216,8 @@ devices.
 E<lt>filesystemsE<gt> is like E<lt>mountpointsE<gt> but covers I<all>
 filesystems belonging to the guest, including swap and empty
 partitions.  (In the rare case of a multi-boot guest, it covers
-filesystems belonging to this OS or shared by this OS and other OSes).
+filesystems belonging to this OS or shared with this OS and other
+OSes).
 
 You might see something like this:
 
@@ -218,9 +238,7 @@ type, the label, and the UUID.
 
 The related elements E<lt>package_formatE<gt>,
 E<lt>package_managementE<gt> and E<lt>applicationsE<gt> describe
-applications installed in the virtual machine.  At the moment we are
-only able to list RPMs and Debian packages installed, but in future we
-will support other Linux distros and Windows.
+applications installed in the virtual machine.
 
 E<lt>package_formatE<gt>, if present, describes the packaging
 system used.  Typical values would be C<rpm> and C<deb>.
@@ -245,6 +263,70 @@ The version and release fields may not be available for some types
 guests.  Other fields are possible, see
 L<guestfs(3)/guestfs_inspect_list_applications>.
 
+=head2 E<lt>drive_mappingsE<gt>
+
+For operating systems like Windows which use drive letters,
+virt-inspector is able to find out how drive letters map to
+filesystems.
+
+ <operatingsystems>
+   <operatingsystem>
+     ...
+     <drive_mappings>
+       <drive_mapping name="C">/dev/sda2</drive_mapping>
+       <drive_mapping name="E">/dev/sdb1</drive_mapping>
+     </drive_mappings>
+
+In the example above, drive C maps to the filesystem on the second
+partition on the first disk, and drive E maps to the filesystem on the
+first partition on the second disk.
+
+Note that this only covers permanent local filesystem mappings, not
+things like network shares.  Furthermore NTFS volume mount points may
+not be listed here.
+
+=head2 E<lt>iconE<gt>
+
+Virt-inspector is sometimes able to extract an icon or logo for the
+guest.  The icon is returned as base64-encoded PNG data.  Note that
+the icon can be very large and high quality.
+
+ <operatingsystems>
+   <operatingsystem>
+     ...
+     <icon>
+       iVBORw0KGgoAAAANSUhEUgAAAGAAAABg[.......]
+       [... many lines of base64 data ...]
+     </icon>
+
+To display the icon, you have to extract it and convert the base64
+data back to a binary file.  Use an XPath query or simply an editor to
+extract the data, then use the coreutils L<base64(1)> program to do
+the conversion back to a PNG file:
+
+ base64 -i -d < icon.data > icon.png
+
+=head2 INSPECTING INSTALL DISKS, LIVE CDs
+
+Virt-inspector can detect some operating system installers on
+install disks, live CDs, bootable USB keys and more.
+
+In this case the E<lt>formatE<gt> tag will contain C<installer>
+and other fields may be present to indicate a live CD, network
+installer, or one part of a multipart CD.  For example:
+
+ <operatingsystems>
+   <operatingsystem>
+     <root>/dev/sda</root>
+     <name>linux</name>
+     <arch>i386</arch>
+     <distro>ubuntu</distro>
+     <product_name>Ubuntu 10.10 &quot;Maverick Meerkat&quot;</product_name>
+     <major_version>10</major_version>
+     <minor_version>10</minor_version>
+     <format>installer</format>
+     <live/>
+
 =head1 USING XPATH
 
 You can use the XPath query language, and/or the xpath tool, in order
@@ -271,11 +353,33 @@ have meaning to the shell such as C<#> and space.  You may need to
 quote or escape these characters on the command line.  See the shell
 manual page L<sh(1)> for details.
 
+=head1 OLD VERSIONS OF VIRT-INSPECTOR
+
+Early versions of libguestfs shipped with a different virt-inspector
+program written in Perl (the current version is written in C).  The
+XML output of the Perl virt-inspector was different and it could also
+output in other formats like text.
+
+The old virt-inspector is no longer supported or shipped with
+libguestfs.
+
+To confuse matters further, in Red Hat Enterprise Linux 6 we ship two
+versions of virt-inspector with different names:
+
+ virt-inspector     Old Perl version.
+ virt-inspector2    New C version.
+
+=head1 EXIT STATUS
+
+This program returns 0 if successful, or non-zero if there was an
+error.
+
 =head1 SEE ALSO
 
 L<guestfs(3)>,
 L<guestfish(1)>,
 L<http://www.w3.org/TR/xpath/>,
+L<base64(1)>,
 L<http://libguestfs.org/>.
 
 =head1 AUTHORS
@@ -294,7 +398,7 @@ Matthew Booth L<mbooth@redhat.com>
 
 =head1 COPYRIGHT
 
-Copyright (C) 2010 Red Hat Inc.
+Copyright (C) 2010-2011 Red Hat Inc.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by