inspector/virt-inspector.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 virt-inspector - Display operating system version and other information about a virtual machine
   6
   7 =head1 SYNOPSIS
   8
   9  virt-inspector [--options] -d domname
  10
  11  virt-inspector [--options] -a disk.img [-a disk.img ...]
  12
  13 Old-style:
  14
  15  virt-inspector domname
  16
  17  virt-inspector disk.img [disk.img ...]
  18
  19 =head1 DESCRIPTION
  20
  21 B<virt-inspector> examines a virtual machine or disk image and tries
  22 to determine the version of the operating system and other information
  23 about the virtual machine.
  24
  25 Virt-inspector produces XML output for feeding into other programs.
  26
  27 In the normal usage, use C<virt-inspector -d domname> where C<domname> is
  28 the libvirt domain (see: C<virsh list --all>).
  29
  30 You can also run virt-inspector directly on disk images from a single
  31 virtual machine.  Use C<virt-inspector -a disk.img>.  In rare cases a
  32 domain has several block devices, in which case you should list
  33 several I<-a> options one after another, with the first corresponding
  34 to the guest's C</dev/sda>, the second to the guest's C</dev/sdb> and
  35 so on.
  36
  37 You can also run virt-inspector on install disks, live CDs, bootable
  38 USB keys and similar.
  39
  40 Virt-inspector can only inspect and report upon I<one domain at a
  41 time>.  To inspect several virtual machines, you have to run
  42 virt-inspector several times (for example, from a shell script
  43 for-loop).
  44
  45 Because virt-inspector needs direct access to guest images, it won't
  46 normally work over remote libvirt connections.
  47
  48 All of the information available from virt-inspector is also available
  49 through the core libguestfs inspection API (see
  50 L<guestfs(3)/INSPECTION>).  The same information can also be fetched
  51 using guestfish or via libguestfs bindings in many programming
  52 languages
  53 (see L<guestfs(3)/USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES>).
  54
  55 =head1 OPTIONS
  56
  57 =over 4
  58
  59 =item B<--help>
  60
  61 Display brief help.
  62
  63 =item B<-a> file
  64
  65 =item B<--add> file
  66
  67 Add I<file> which should be a disk image from a virtual machine.  If
  68 the virtual machine has multiple block devices, you must supply all of
  69 them with separate I<-a> options.
  70
  71 The format of the disk image is auto-detected.  To override this and
  72 force a particular format use the I<--format=..> option.
  73
  74 =item B<-c URI>
  75
  76 =item B<--connect URI>
  77
  78 If using libvirt, connect to the given I<URI>.  If omitted,
  79 then we connect to the default libvirt hypervisor.
  80
  81 Libvirt is only used if you specify a C<domname> on the
  82 command line.  If you specify guest block devices directly (I<-a>),
  83 then libvirt is not used at all.
  84
  85 =item B<-d> guest
  86
  87 =item B<--domain> guest
  88
  89 Add all the disks from the named libvirt guest.
  90
  91 =item B<--echo-keys>
  92
  93 When prompting for keys and passphrases, virt-inspector normally turns
  94 echoing off so you cannot see what you are typing.  If you are not
  95 worried about Tempest attacks and there is no one else in the room you
  96 can specify this flag to see what you are typing.
  97
  98 =item B<--format=raw|qcow2|..>
  99
 100 =item B<--format>
 101
 102 Specify the format of disk images given on the command line.  If this
 103 is omitted then the format is autodetected from the content of the
 104 disk image.
 105
 106 If disk images are requested from libvirt, then this program asks
 107 libvirt for this information.  In this case, the value of the format
 108 parameter is ignored.
 109
 110 If working with untrusted raw-format guest disk images, you should
 111 ensure the format is always specified.
 112
 113 =item B<--keys-from-stdin>
 114
 115 Read key or passphrase parameters from stdin.  The default is
 116 to try to read passphrases from the user by opening C</dev/tty>.
 117
 118 =item B<-v>
 119
 120 =item B<--verbose>
 121
 122 Enable verbose messages for debugging.
 123
 124 =item B<-V>
 125
 126 =item B<--version>
 127
 128 Display version number and exit.
 129
 130 =item B<-x>
 131
 132 Enable tracing of libguestfs API calls.
 133
 134 =back
 135
 136 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
 137
 138 Previous versions of virt-inspector allowed you to write either:
 139
 140  virt-inspector disk.img [disk.img ...]
 141
 142 or
 143
 144  virt-inspector guestname
 145
 146 whereas in this version you should use I<-a> or I<-d> respectively
 147 to avoid the confusing case where a disk image might have the same
 148 name as a guest.
 149
 150 For compatibility the old style is still supported.
 151
 152 =head1 XML FORMAT
 153
 154 The virt-inspector XML is described precisely in a RELAX NG schema
 155 file C<virt-inspector.rng> which is supplied with libguestfs.  This
 156 section is just an overview.
 157
 158 The top-level element is E<lt>operatingsystemsE<gt>, and it contains
 159 one or more E<lt>operatingsystemE<gt> elements.  You would only see
 160 more than one E<lt>operatingsystemE<gt> element if the virtual machine
 161 is multi-boot, which is vanishingly rare in real world VMs.
 162
 163 =head2 E<lt>operatingsystemE<gt>
 164
 165 In the E<lt>operatingsystemE<gt> tag are various optional fields that
 166 describe the operating system, its architecture, the descriptive
 167 "product name" string, the type of OS and so on, as in this example:
 168
 169  <operatingsystems>
 170    <operatingsystem>
 171      <root>/dev/sda2</root>
 172      <name>windows</name>
 173      <arch>i386</arch>
 174      <distro>windows</distro>
 175      <product_name>Windows 7 Enterprise</product_name>
 176      <product_variant>Client</product_variant>
 177      <major_version>6</major_version>
 178      <minor_version>1</minor_version>
 179      <windows_systemroot>/Windows</windows_systemroot>
 180      <format>installed</format>
 181
 182 In brief, E<lt>nameE<gt> is the class of operating system (something
 183 like C<linux> or C<windows>), E<lt>distroE<gt> is the distribution
 184 (eg. C<fedora> but many other distros are recognized) and
 185 E<lt>archE<gt> is the guest architecture.  The other fields are fairly
 186 self-explanatory, but because these fields are taken directly from the
 187 libguestfs inspection API you can find precise information from
 188 L<guestfs(3)/INSPECTION>.
 189
 190 The E<lt>rootE<gt> element is the root filesystem device, but from the
 191 point of view of libguestfs (block devices may have completely
 192 different names inside the VM itself).
 193
 194 =head2 E<lt>mountpointsE<gt>
 195
 196 Un*x-like guests typically have multiple filesystems which are mounted
 197 at various mountpoints, and these are described in the
 198 E<lt>mountpointsE<gt> element which looks like this:
 199
 200  <operatingsystems>
 201    <operatingsystem>
 202      ...
 203      <mountpoints>
 204        <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
 205        <mountpoint dev="/dev/sda1">/boot</mountpoint>
 206      </mountpoints>
 207
 208 As with E<lt>rootE<gt>, devices are from the point of view of
 209 libguestfs, and may have completely different names inside the guest.
 210 Only mountable filesystems appear in this list, not things like swap
 211 devices.
 212
 213 =head2 E<lt>filesystemsE<gt>
 214
 215 E<lt>filesystemsE<gt> is like E<lt>mountpointsE<gt> but covers I<all>
 216 filesystems belonging to the guest, including swap and empty
 217 partitions.  (In the rare case of a multi-boot guest, it covers
 218 filesystems belonging to this OS or shared with this OS and other
 219 OSes).
 220
 221 You might see something like this:
 222
 223  <operatingsystems>
 224    <operatingsystem>
 225      ...
 226      <filesystems>
 227        <filesystem dev="/dev/vg_f13x64/lv_root">
 228          <type>ext4</type>
 229          <label>Fedora-13-x86_64</label>
 230          <uuid>e6a4db1e-15c2-477b-ac2a-699181c396aa</uuid>
 231        </filesystem>
 232
 233 The optional elements within E<lt>filesystemE<gt> are the filesystem
 234 type, the label, and the UUID.
 235
 236 =head2 E<lt>applicationsE<gt>
 237
 238 The related elements E<lt>package_formatE<gt>,
 239 E<lt>package_managementE<gt> and E<lt>applicationsE<gt> describe
 240 applications installed in the virtual machine.
 241
 242 E<lt>package_formatE<gt>, if present, describes the packaging
 243 system used.  Typical values would be C<rpm> and C<deb>.
 244
 245 E<lt>package_managementE<gt>, if present, describes the package
 246 manager.  Typical values include C<yum>, C<up2date> and C<apt>
 247
 248 E<lt>applicationsE<gt> lists the packages or applications
 249 installed.
 250
 251  <operatingsystems>
 252    <operatingsystem>
 253      ...
 254      <applications>
 255        <application>
 256          <name>coreutils</name>
 257          <version>8.5</version>
 258          <release>1</release>
 259        </application>
 260
 261 The version and release fields may not be available for some types
 262 guests.  Other fields are possible, see
 263 L<guestfs(3)/guestfs_inspect_list_applications>.
 264
 265 =head2 E<lt>drive_mappingsE<gt>
 266
 267 For operating systems like Windows which use drive letters,
 268 virt-inspector is able to find out how drive letters map to
 269 filesystems.
 270
 271  <operatingsystems>
 272    <operatingsystem>
 273      ...
 274      <drive_mappings>
 275        <drive_mapping name="C">/dev/sda2</drive_mapping>
 276        <drive_mapping name="E">/dev/sdb1</drive_mapping>
 277      </drive_mappings>
 278
 279 In the example above, drive C maps to the filesystem on the second
 280 partition on the first disk, and drive E maps to the filesystem on the
 281 first partition on the second disk.
 282
 283 Note that this only covers permanent local filesystem mappings, not
 284 things like network shares.  Furthermore NTFS volume mount points may
 285 not be listed here.
 286
 287 =head2 INSPECTING INSTALL DISKS, LIVE CDs
 288
 289 Virt-inspector can detect some operating system installers on
 290 install disks, live CDs, bootable USB keys and more.
 291
 292 In this case the E<lt>formatE<gt> tag will contain C<installer>
 293 and other fields may be present to indicate a live CD, network
 294 installer, or one part of a multipart CD.  For example:
 295
 296  <operatingsystems>
 297    <operatingsystem>
 298      <root>/dev/sda</root>
 299      <name>linux</name>
 300      <arch>i386</arch>
 301      <distro>ubuntu</distro>
 302      <product_name>Ubuntu 10.10 &quot;Maverick Meerkat&quot;</product_name>
 303      <major_version>10</major_version>
 304      <minor_version>10</minor_version>
 305      <format>installer</format>
 306      <live/>
 307
 308 =head1 USING XPATH
 309
 310 You can use the XPath query language, and/or the xpath tool, in order
 311 to select parts of the XML.
 312
 313 For example:
 314
 315  $ virt-inspector -d Guest | xpath //filesystems
 316  Found 1 nodes:
 317  -- NODE --
 318  <filesystems>
 319       <filesystem dev="/dev/vg_f13x64/lv_root">
 320         <type>ext4</type>
 321  [etc]
 322
 323  $ virt-inspector -d Guest | \
 324      xpath "string(//filesystem[@dev='/dev/sda1']/type)"
 325  Query didn't return a nodeset. Value: ext4
 326
 327 =head1 SHELL QUOTING
 328
 329 Libvirt guest names can contain arbitrary characters, some of which
 330 have meaning to the shell such as C<#> and space.  You may need to
 331 quote or escape these characters on the command line.  See the shell
 332 manual page L<sh(1)> for details.
 333
 334 =head1 OLD VERSIONS OF VIRT-INSPECTOR
 335
 336 Early versions of libguestfs shipped with a different virt-inspector
 337 program written in Perl (the current version is written in C).  The
 338 XML output of the Perl virt-inspector was different and it could also
 339 output in other formats like text.
 340
 341 The old virt-inspector is no longer supported or shipped with
 342 libguestfs.
 343
 344 To confuse matters further, in Red Hat Enterprise Linux 6 we ship two
 345 versions of virt-inspector with different names:
 346
 347  virt-inspector     Old Perl version.
 348  virt-inspector2    New C version.
 349
 350 =head1 SEE ALSO
 351
 352 L<guestfs(3)>,
 353 L<guestfish(1)>,
 354 L<http://www.w3.org/TR/xpath/>,
 355 L<http://libguestfs.org/>.
 356
 357 =head1 AUTHORS
 358
 359 =over 4
 360
 361 =item *
 362
 363 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 364
 365 =item *
 366
 367 Matthew Booth L<mbooth@redhat.com>
 368
 369 =back
 370
 371 =head1 COPYRIGHT
 372
 373 Copyright (C) 2010-2011 Red Hat Inc.
 374
 375 This program is free software; you can redistribute it and/or modify
 376 it under the terms of the GNU General Public License as published by
 377 the Free Software Foundation; either version 2 of the License, or
 378 (at your option) any later version.
 379
 380 This program is distributed in the hope that it will be useful,
 381 but WITHOUT ANY WARRANTY; without even the implied warranty of
 382 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 383 GNU General Public License for more details.
 384
 385 You should have received a copy of the GNU General Public License
 386 along with this program; if not, write to the Free Software
 387 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.