inspector: Rewrite virt-inspector in C.

1 files changed, 311 insertions, 0 deletions

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<virt-inspector> 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<virt-inspector -d domname> where C<domname> is
+the libvirt domain (see: C<virsh list --all>).
+
+You can also run virt-inspector directly on disk images from a single
+virtual machine.  Use C<virt-inspector -a disk.img>.  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</dev/sda>, the second to the guest's C</dev/sdb> and
+so on.
+
+Virt-inspector can only inspect and report upon I<one domain at a
+time>.  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<file> 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<URI>.  If omitted,
+then we connect to the default libvirt hypervisor.
+
+Libvirt is only used if you specify a C<domname> 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</dev/tty>.
+
+=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 E<lt>operatingsystemsE<gt>, and it contains
+one or more E<lt>operatingsystemE<gt> elements.  You would only see
+more than one E<lt>operatingsystemE<gt> element if the virtual machine
+is multi-boot, which is vanishingly rare in real world VMs.
+
+=head2 E<lt>operatingsystemE<gt>
+
+In the E<lt>operatingsystemE<gt> 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:
+
+ <operatingsystems>
+   <operatingsystem>
+     <root>/dev/sda2</root>
+     <name>windows</name>
+     <arch>i386</arch>
+     <distro>windows</distro>
+     <product_name>Windows 7 Enterprise</product_name>
+     <major_version>6</major_version>
+     <minor_version>1</minor_version>
+     <windows_systemroot>/Windows</windows_systemroot>
+
+These fields are derived from the libguestfs inspection API, and
+you can find more details in 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
+different names inside the VM itself).
+
+=head2 E<lt>mountpointsE<gt>
+
+Un*x-like guests typically have multiple filesystems which are mounted
+at various mountpoints, and these are described in the
+E<lt>mountpointsE<gt> element which looks like this:
+
+ <operatingsystems>
+   <operatingsystem>
+     ...
+     <mountpoints>
+       <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
+       <mountpoint dev="/dev/sda1">/boot</mountpoint>
+     </mountpoints>
+
+As with E<lt>rootE<gt>, 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 E<lt>filesystemsE<gt>
+
+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).
+
+You might see something like this:
+
+ <operatingsystems>
+   <operatingsystem>
+     ...
+     <filesystems>
+       <filesystem dev="/dev/vg_f13x64/lv_root">
+         <type>ext4</type>
+         <label>Fedora-13-x86_64</label>
+         <uuid>e6a4db1e-15c2-477b-ac2a-699181c396aa</uuid>
+       </filesystem>
+
+The optional elements within E<lt>filesystemE<gt> are the filesystem
+type, the label, and the UUID.
+
+=head2 E<lt>applicationsE<gt>
+
+The related elements E<lt>package_formatE<gt>,
+E<lt>package_managementE<gt> and E<lt>applicationsE<gt> 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.
+
+E<lt>package_formatE<gt>, if present, describes the packaging
+system used.  Typical values would be C<rpm> and C<deb>.
+
+E<lt>package_managementE<gt>, if present, describes the package
+manager.  Typical values include C<yum>, C<up2date> and C<apt>
+
+E<lt>applicationsE<gt> lists the packages or applications
+installed.
+
+ <operatingsystems>
+   <operatingsystem>
+     ...
+     <applications>
+       <application>
+         <name>coreutils</name>
+         <version>8.5</version>
+         <release>1</release>
+       </application>
+
+The version and release fields may not be available for some types
+guests.  Other fields are possible, see
+L<guestfs(3)/guestfs_inspect_list_applications>.
+
+=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 --
+ <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
+
+=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<sh(1)> for details.
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<guestfish(1)>,
+L<http://www.w3.org/TR/xpath/>,
+L<http://libguestfs.org/>.
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
+
+=item *
+
+Matthew Booth L<mbooth@redhat.com>
+
+=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.