mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-21 22:53:37 +00:00
8ba0457e9e
Use the common/options/key-option.pod fragment to document the --key option and selector instead of duplicating the same documentation everywhere.
518 lines
15 KiB
Plaintext
518 lines
15 KiB
Plaintext
=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 F</dev/sda>, the second to the guest’s F</dev/sdb> 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<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.
|
||
|
||
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</GETTING INSPECTION DATA FROM THE LIBGUESTFS API>).
|
||
|
||
=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<-a> URI
|
||
|
||
=item B<--add> URI
|
||
|
||
Add a remote disk. See L<guestfish(1)/ADDING REMOTE STORAGE>.
|
||
|
||
=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. Domain UUIDs can be
|
||
used instead of names.
|
||
|
||
=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.
|
||
|
||
__INCLUDE:key-option.pod__
|
||
|
||
=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 F</dev/tty>.
|
||
|
||
=item B<--no-applications>
|
||
|
||
By default the output of virt-inspector includes the list of all the
|
||
applications installed in the guest, if available.
|
||
|
||
Specify this option to disable this part of the resulting XML.
|
||
|
||
=item B<--no-icon>
|
||
|
||
By default the output of virt-inspector includes the icon of the
|
||
guest, if available (see L</icon>).
|
||
|
||
Specify this option to disable this part of the resulting XML.
|
||
|
||
=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.
|
||
|
||
=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
|
||
|
||
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
|
||
file F<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
|
||
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>
|
||
<product_variant>Client</product_variant>
|
||
<major_version>6</major_version>
|
||
<minor_version>1</minor_version>
|
||
<windows_systemroot>/Windows</windows_systemroot>
|
||
|
||
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
|
||
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 with 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.
|
||
|
||
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>.
|
||
|
||
=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
|
||
|
||
=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<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 | virt-inspector --xpath '//filesystems'
|
||
<filesystems>
|
||
<filesystem dev="/dev/vg_f13x64/lv_root">
|
||
<type>ext4</type>
|
||
[...]
|
||
|
||
$ virt-inspector -d Guest | \
|
||
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 GETTING INSPECTION DATA FROM THE LIBGUESTFS API
|
||
|
||
In early versions of libguestfs, virt-inspector was a large Perl
|
||
script that contained many heuristics for inspecting guests. This had
|
||
several problems: in order to do inspection from other tools (like
|
||
guestfish) we had to call out to this Perl script; and it privileged
|
||
Perl over other languages that libguestfs supports.
|
||
|
||
By libguestfs 1.8 we had rewritten the Perl code in C, and
|
||
incorporated it all into the core libguestfs API (L<guestfs(3)>). Now
|
||
virt-inspector is simply a thin C program over the core C API. All of
|
||
the inspection information is available from all programming languages
|
||
that libguestfs supports, and from guestfish.
|
||
|
||
For a description of the C inspection API, read
|
||
L<guestfs(3)/INSPECTION>.
|
||
|
||
For example code using the C inspection API, look for F<inspect-vm.c>
|
||
which ships with libguestfs.
|
||
|
||
F<inspect-vm.c> has also been translated into other languages. For
|
||
example, F<inspect_vm.pl> is the Perl translation, and there are other
|
||
translations for OCaml, Python, etc. See
|
||
L<guestfs(3)/USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES> for a
|
||
list of man pages which contain this example code.
|
||
|
||
=head2 GETTING INSPECTION DATA FROM GUESTFISH
|
||
|
||
If you use the guestfish I<-i> option, then the main C inspection API
|
||
L<guestfs(3)/guestfs_inspect_os> is called. This is equivalent to the
|
||
guestfish command C<inspect-os>. You can also call this guestfish
|
||
command by hand.
|
||
|
||
C<inspect-os> performs inspection on the current disk image, returning
|
||
the list of operating systems found. Each OS is represented by its
|
||
root filesystem device. In the majority of cases, this command prints
|
||
nothing (no OSes found), or a single root device, but beware that it
|
||
can print multiple lines if there are multiple OSes or if there is an
|
||
install CD attached to the guest.
|
||
|
||
$ guestfish --ro -a F15x32.img
|
||
><fs> run
|
||
><fs> inspect-os
|
||
/dev/vg_f15x32/lv_root
|
||
|
||
Using the root device, you can fetch further information about the
|
||
guest:
|
||
|
||
><fs> inspect-get-type /dev/vg_f15x32/lv_root
|
||
linux
|
||
><fs> inspect-get-distro /dev/vg_f15x32/lv_root
|
||
fedora
|
||
><fs> inspect-get-major-version /dev/vg_f15x32/lv_root
|
||
15
|
||
><fs> inspect-get-product-name /dev/vg_f15x32/lv_root
|
||
Fedora release 15 (Lovelock)
|
||
|
||
Limitations of guestfish make it hard to assign the root device to a
|
||
variable (since guestfish doesn't have variables), so if you want to
|
||
do this reproducibly you are better off writing a script using one of
|
||
the other languages that the libguestfs API supports.
|
||
|
||
To list applications, you have to first mount up the disks:
|
||
|
||
><fs> inspect-get-mountpoints /dev/vg_f15x32/lv_root
|
||
/: /dev/vg_f15x32/lv_root
|
||
/boot: /dev/vda1
|
||
><fs> mount-ro /dev/vg_f15x32/lv_root /
|
||
><fs> mount-ro /dev/vda1 /boot
|
||
|
||
and then call the inspect-list-applications API:
|
||
|
||
><fs> inspect-list-applications /dev/vg_f15x32/lv_root | head -28
|
||
[0] = {
|
||
app_name: ConsoleKit
|
||
app_display_name:
|
||
app_epoch: 0
|
||
app_version: 0.4.5
|
||
app_release: 1.fc15
|
||
app_install_path:
|
||
app_trans_path:
|
||
app_publisher:
|
||
app_url:
|
||
app_source_package:
|
||
app_summary:
|
||
app_description:
|
||
}
|
||
[1] = {
|
||
app_name: ConsoleKit-libs
|
||
app_display_name:
|
||
app_epoch: 0
|
||
app_version: 0.4.5
|
||
app_release: 1.fc15
|
||
app_install_path:
|
||
app_trans_path:
|
||
app_publisher:
|
||
app_url:
|
||
app_source_package:
|
||
app_summary:
|
||
app_description:
|
||
}
|
||
|
||
To display an icon for the guest, note that filesystems must also be
|
||
mounted as above. You can then do:
|
||
|
||
><fs> inspect-get-icon /dev/vg_f15x32/lv_root | display -
|
||
|
||
=head1 OLD VERSIONS OF VIRT-INSPECTOR
|
||
|
||
As described above, 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
|
||
|
||
=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-2012 Red Hat Inc.
|