From c5cb65f0aac3298e634b183f73fda6644a158018 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Fri, 19 Nov 2010 12:48:21 +0000 Subject: inspector: Rewrite virt-inspector in C. --- inspector/virt-inspector.pod | 311 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 311 insertions(+) create mode 100755 inspector/virt-inspector.pod (limited to 'inspector/virt-inspector.pod') diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod new file mode 100755 index 00000000..02058429 --- /dev/null +++ b/inspector/virt-inspector.pod @@ -0,0 +1,311 @@ +=encoding utf8 + +=head1 NAME + +virt-inspector - Display operating system version and other information about a virtual machine + +=head1 SYNOPSIS + + virt-inspector [--options] -d domname + + virt-inspector [--options] -a disk.img [-a disk.img ...] + +Old-style: + + virt-inspector domname + + virt-inspector disk.img [disk.img ...] + +=head1 DESCRIPTION + +B examines a virtual machine or disk image and tries +to determine the version of the operating system and other information +about the virtual machine. + +Virt-inspector produces XML output for feeding into other programs. + +In the normal usage, use C where C is +the libvirt domain (see: C). + +You can also run virt-inspector directly on disk images from a single +virtual machine. Use C. In rare cases a +domain has several block devices, in which case you should list +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. + +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 +for-loop). + +Because virt-inspector needs direct access to guest images, it won't +normally work over remote libvirt connections. + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +Display brief help. + +=item B<-a> file + +=item B<--add> file + +Add I which should be a disk image from a virtual machine. If +the virtual machine has multiple block devices, you must supply all of +them with separate I<-a> options. + +The format of the disk image is auto-detected. To override this and +force a particular format use the I<--format=..> option. + +=item B<-c URI> + +=item B<--connect URI> + +If using libvirt, connect to the given I. If omitted, +then we connect to the default libvirt hypervisor. + +Libvirt is only used if you specify a C on the +command line. If you specify guest block devices directly (I<-a>), +then libvirt is not used at all. + +=item B<-d> guest + +=item B<--domain> guest + +Add all the disks from the named libvirt guest. + +=item B<--echo-keys> + +When prompting for keys and passphrases, virt-inspector normally turns +echoing off so you cannot see what you are typing. If you are not +worried about Tempest attacks and there is no one else in the room you +can specify this flag to see what you are typing. + +=item B<--format=raw|qcow2|..> + +=item B<--format> + +Specify the format of disk images given on the command line. If this +is omitted then the format is autodetected from the content of the +disk image. + +If disk images are requested from libvirt, then this program asks +libvirt for this information. In this case, the value of the format +parameter is ignored. + +If working with untrusted raw-format guest disk images, you should +ensure the format is always specified. + +=item B<--keys-from-stdin> + +Read key or passphrase parameters from stdin. The default is +to try to read passphrases from the user by opening C. + +=item B<-v> + +=item B<--verbose> + +Enable verbose messages for debugging. + +=item B<-V> + +=item B<--version> + +Display version number and exit. + +=item B<-x> + +Enable tracing of libguestfs API calls. + +=back + +=head1 OLD-STYLE COMMAND LINE ARGUMENTS + +Previous versions of virt-inspector allowed you to write either: + + virt-inspector disk.img [disk.img ...] + +or + + virt-inspector guestname + +whereas in this version you should use I<-a> or I<-d> respectively +to avoid the confusing case where a disk image might have the same +name as a guest. + +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. + +The top-level element is EoperatingsystemsE, and it contains +one or more EoperatingsystemE elements. You would only see +more than one EoperatingsystemE element if the virtual machine +is multi-boot, which is vanishingly rare in real world VMs. + +=head2 EoperatingsystemE + +In the EoperatingsystemE tag are various optional fields that +describe the operating system, its architecture, the descriptive +"product name" string, the type of OS and so on, as in this example: + + + + /dev/sda2 + windows + i386 + windows + Windows 7 Enterprise + 6 + 1 + /Windows + +These fields are derived from the libguestfs inspection API, and +you can find more details in L. + +The ErootE element is the root filesystem device, but from the +point of view of libguestfs (block devices may have completely +different names inside the VM itself). + +=head2 EmountpointsE + +Un*x-like guests typically have multiple filesystems which are mounted +at various mountpoints, and these are described in the +EmountpointsE element which looks like this: + + + + ... + + / + /boot + + +As with ErootE, devices are from the point of view of +libguestfs, and may have completely different names inside the guest. +Only mountable filesystems appear in this list, not things like swap +devices. + +=head2 EfilesystemsE + +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). + +You might see something like this: + + + + ... + + + ext4 + + e6a4db1e-15c2-477b-ac2a-699181c396aa + + +The optional elements within EfilesystemE are the filesystem +type, the label, and the UUID. + +=head2 EapplicationsE + +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. + +Epackage_formatE, if present, describes the packaging +system used. Typical values would be C and C. + +Epackage_managementE, if present, describes the package +manager. Typical values include C, C and C + +EapplicationsE lists the packages or applications +installed. + + + + ... + + + coreutils + 8.5 + 1 + + +The version and release fields may not be available for some types +guests. Other fields are possible, see +L. + +=head1 USING XPATH + +You can use the XPath query language, and/or the xpath tool, in order +to select parts of the XML. + +For example: + + $ virt-inspector -d Guest | xpath //filesystems + Found 1 nodes: + -- NODE -- + + + ext4 + [etc] + + $ virt-inspector -d Guest | \ + xpath "string(//filesystem[@dev='/dev/sda1']/type)" + Query didn't return a nodeset. Value: ext4 + +=head1 SHELL QUOTING + +Libvirt guest names can contain arbitrary characters, some of which +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 SEE ALSO + +L, +L, +L, +L. + +=head1 AUTHORS + +=over 4 + +=item * + +Richard W.M. Jones L + +=item * + +Matthew Booth L + +=back + +=head1 COPYRIGHT + +Copyright (C) 2010 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 +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +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. -- cgit