X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=inspector%2Fvirt-inspector.pod;h=04e421dc3b1e34c18070cdb423f2a1912e813289;hb=99ec97dcdfaf242ba0683a230ba51e4a87f7458b;hp=cd0e61758d7e7444e517b998f7c77da98a6fe70e;hpb=c2f2a2c6769be908b25b0946f39770d09bb6ddc9;p=libguestfs.git diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod index cd0e617..04e421d 100755 --- a/inspector/virt-inspector.pod +++ b/inspector/virt-inspector.pod @@ -45,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). The same information can also be fetched +using guestfish or via libguestfs bindings in many programming +languages +(see L). + =head1 OPTIONS =over 4 @@ -79,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> @@ -124,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 below +for some examples. + =back =head1 OLD-STYLE COMMAND LINE ARGUMENTS @@ -145,7 +160,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 which is supplied with libguestfs. This +section is just an overview. The top-level element is EoperatingsystemsE, and it contains one or more EoperatingsystemE elements. You would only see @@ -165,13 +181,19 @@ describe the operating system, its architecture, the descriptive i386 windows Windows 7 Enterprise + Client 6 1 /Windows installed -These fields are derived from the libguestfs inspection API, and -you can find more details in L. +In brief, EnameE is the class of operating system (something +like C or C), EdistroE is the distribution +(eg. C but many other distros are recognized) and +EarchE 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. The ErootE element is the root filesystem device, but from the point of view of libguestfs (block devices may have completely @@ -201,7 +223,8 @@ devices. EfilesystemsE is like EmountpointsE but covers I 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: @@ -247,6 +270,49 @@ The version and release fields may not be available for some types guests. Other fields are possible, see L. +=head2 Edrive_mappingsE + +For operating systems like Windows which use drive letters, +virt-inspector is able to find out how drive letters map to +filesystems. + + + + ... + + /dev/sda2 + /dev/sdb1 + + +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 EiconE + +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. + + + + ... + + iVBORw0KGgoAAAANSUhEUgAAAGAAAABg[.......] + [... many lines of base64 data ...] + + +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 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 @@ -268,24 +334,35 @@ installer, or one part of a multipart CD. For example: installer -=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 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' ext4 - [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 @@ -294,11 +371,34 @@ 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 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, L, L, +L, +L, L. =head1 AUTHORS @@ -317,7 +417,7 @@ Matthew Booth L =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 @@ -331,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.