X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=inspector%2Fvirt-inspector.pod;h=04e421dc3b1e34c18070cdb423f2a1912e813289;hb=7708d3e04f6ec3985fd74ee1a44a5615d43065e2;hp=0205842907ed7fa7f62e6869be0c22a3b70e82db;hpb=c5cb65f0aac3298e634b183f73fda6644a158018;p=libguestfs.git diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod index 0205842..04e421d 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, the second to the guest's C 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. 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). The same information can also be fetched +using guestfish or via libguestfs bindings in many programming +languages +(see L). + =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> @@ -121,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 @@ -142,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 @@ -162,12 +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 @@ -197,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: @@ -218,9 +245,7 @@ type, the label, and the UUID. The related elements Epackage_formatE, Epackage_managementE and EapplicationsE 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. Epackage_formatE, if present, describes the packaging system used. Typical values would be C and C. @@ -245,24 +270,99 @@ The version and release fields may not be available for some types guests. Other fields are possible, see L. -=head1 USING XPATH +=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 -You can use the XPath query language, and/or the xpath tool, in order -to select parts of the XML. +Virt-inspector can detect some operating system installers on +install disks, live CDs, bootable USB keys and more. + +In this case the EformatE tag will contain C +and other fields may be present to indicate a live CD, network +installer, or one part of a multipart CD. For example: + + + + /dev/sda + linux + i386 + ubuntu + Ubuntu 10.10 "Maverick Meerkat" + 10 + 10 + installer + + +=head1 XPATH QUERIES + +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 | \ - 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 @@ -271,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 @@ -294,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 @@ -308,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.