X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=inspector%2Fvirt-inspector.pod;h=04e421dc3b1e34c18070cdb423f2a1912e813289;hb=be1419a442d9936e737fb2ca6f0fdba36a048964;hp=225e3f6f2d0bc7f8409b366ee39e8987965d6ba5;hpb=34d9fed24ad6a2d2e13bb817820e31373f6756e1;p=libguestfs.git

diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod
index 225e3f6..04e421d 100755
--- a/inspector/virt-inspector.pod
+++ b/inspector/virt-inspector.pod
@@ -86,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>
 
@@ -131,6 +132,13 @@ Display version number and exit.
 
 Enable tracing of libguestfs API calls.
 
+=item B<--xpath> query
+
+Perform an XPath query on the XML on stdin, and print the result on
+stdout.  In this mode virt-inspector simply runs an XPath query; all
+other inspection functions are disabled.  See L</XPATH QUERIES> below
+for some examples.
+
 =back
 
 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
@@ -284,6 +292,27 @@ 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
@@ -305,24 +334,35 @@ installer, or one part of a multipart CD.  For example:
      <format>installer</format>
      <live/>
 
-=head1 USING XPATH
+=head1 XPATH QUERIES
 
-You can use the XPath query language, and/or the xpath tool, in order
-to select parts of the XML.
+Virt-inspector includes built in support for running XPath queries.
+The reason for including XPath support directly in virt-inspector is
+simply that there are no good and widely available command line
+programs that can do XPath queries.  The only good one is
+L<xmlstarlet(1)> and that is not available on Red Hat Enterprise
+Linux.
+
+To perform an XPath query, use the I<--xpath> option.  Note that in
+this mode, virt-inspector simply reads XML from stdin and outputs the
+query result on stdout.  All other inspection features are disabled in
+this mode.
 
 For example:
 
- $ virt-inspector -d Guest | xpath //filesystems
- Found 1 nodes:
- -- NODE --
+ $ virt-inspector -d Guest | virt-inspector --xpath '//filesystems'
  <filesystems>
       <filesystem dev="/dev/vg_f13x64/lv_root">
         <type>ext4</type>
- [etc]
+ [...]
 
  $ virt-inspector -d Guest | \
-     xpath "string(//filesystem[@dev='/dev/sda1']/type)"
- Query didn't return a nodeset. Value: ext4
+     virt-inspector --xpath "string(//filesystem[@dev='/dev/sda1']/type)"
+ ext4
+
+ $ virt-inspector -d Guest | \
+     virt-inspector --xpath 'string(//icon)' | base64 -i -d | display -
+ [displays the guest icon, if there is one]
 
 =head1 SHELL QUOTING
 
@@ -347,11 +387,18 @@ 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<xmlstarlet(1)>,
 L<http://libguestfs.org/>.
 
 =head1 AUTHORS
@@ -384,4 +431,4 @@ GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
-Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.