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
=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>
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
=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
<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
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:
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
<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 | \
+ virt-inspector --xpath "string(//filesystem[@dev='/dev/sda1']/type)"
+ ext4
$ virt-inspector -d Guest | \
- xpath "string(//filesystem[@dev='/dev/sda1']/type)"
- Query didn't return a nodeset. Value: ext4
+ virt-inspector --xpath 'string(//icon)' | base64 -i -d | display -
+ [displays the guest icon, if there is one]
=head1 SHELL QUOTING
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<xmlstarlet(1)>,
L<http://libguestfs.org/>.
=head1 AUTHORS
=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
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.
git.annexia.org / libguestfs.git / blobdiff