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 =head1 OPTIONS
  49
  50 =over 4
  51
  52 =item B<--help>
  53
  54 Display brief help.
  55
  56 =item B<-a> file
  57
  58 =item B<--add> file
  59
  60 Add I<file> which should be a disk image from a virtual machine.  If
  61 the virtual machine has multiple block devices, you must supply all of
  62 them with separate I<-a> options.
  63
  64 The format of the disk image is auto-detected.  To override this and
  65 force a particular format use the I<--format=..> option.
  66
  67 =item B<-c URI>
  68
  69 =item B<--connect URI>
  70
  71 If using libvirt, connect to the given I<URI>.  If omitted,
  72 then we connect to the default libvirt hypervisor.
  73
  74 Libvirt is only used if you specify a C<domname> on the
  75 command line.  If you specify guest block devices directly (I<-a>),
  76 then libvirt is not used at all.
  77
  78 =item B<-d> guest
  79
  80 =item B<--domain> guest
  81
  82 Add all the disks from the named libvirt guest.
  83
  84 =item B<--echo-keys>
  85
  86 When prompting for keys and passphrases, virt-inspector normally turns
  87 echoing off so you cannot see what you are typing.  If you are not
  88 worried about Tempest attacks and there is no one else in the room you
  89 can specify this flag to see what you are typing.
  90
  91 =item B<--format=raw|qcow2|..>
  92
  93 =item B<--format>
  94
  95 Specify the format of disk images given on the command line.  If this
  96 is omitted then the format is autodetected from the content of the
  97 disk image.
  98
  99 If disk images are requested from libvirt, then this program asks
 100 libvirt for this information.  In this case, the value of the format
 101 parameter is ignored.
 102
 103 If working with untrusted raw-format guest disk images, you should
 104 ensure the format is always specified.
 105
 106 =item B<--keys-from-stdin>
 107
 108 Read key or passphrase parameters from stdin.  The default is
 109 to try to read passphrases from the user by opening C</dev/tty>.
 110
 111 =item B<-v>
 112
 113 =item B<--verbose>
 114
 115 Enable verbose messages for debugging.
 116
 117 =item B<-V>
 118
 119 =item B<--version>
 120
 121 Display version number and exit.
 122
 123 =item B<-x>
 124
 125 Enable tracing of libguestfs API calls.
 126
 127 =back
 128
 129 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
 130
 131 Previous versions of virt-inspector allowed you to write either:
 132
 133  virt-inspector disk.img [disk.img ...]
 134
 135 or
 136
 137  virt-inspector guestname
 138
 139 whereas in this version you should use I<-a> or I<-d> respectively
 140 to avoid the confusing case where a disk image might have the same
 141 name as a guest.
 142
 143 For compatibility the old style is still supported.
 144
 145 =head1 XML FORMAT
 146
 147 The virt-inspector XML is described precisely in a RELAX NG schema
 148 which is supplied with libguestfs.  This section is just an overview.
 149
 150 The top-level element is E<lt>operatingsystemsE<gt>, and it contains
 151 one or more E<lt>operatingsystemE<gt> elements.  You would only see
 152 more than one E<lt>operatingsystemE<gt> element if the virtual machine
 153 is multi-boot, which is vanishingly rare in real world VMs.
 154
 155 =head2 E<lt>operatingsystemE<gt>
 156
 157 In the E<lt>operatingsystemE<gt> tag are various optional fields that
 158 describe the operating system, its architecture, the descriptive
 159 "product name" string, the type of OS and so on, as in this example:
 160
 161  <operatingsystems>
 162    <operatingsystem>
 163      <root>/dev/sda2</root>
 164      <name>windows</name>
 165      <arch>i386</arch>
 166      <distro>windows</distro>
 167      <product_name>Windows 7 Enterprise</product_name>
 168      <product_variant>Client</product_variant>
 169      <major_version>6</major_version>
 170      <minor_version>1</minor_version>
 171      <windows_systemroot>/Windows</windows_systemroot>
 172      <format>installed</format>
 173
 174 These fields are derived from the libguestfs inspection API, and
 175 you can find more details in L<guestfs(3)/INSPECTION>.
 176
 177 The E<lt>rootE<gt> element is the root filesystem device, but from the
 178 point of view of libguestfs (block devices may have completely
 179 different names inside the VM itself).
 180
 181 =head2 E<lt>mountpointsE<gt>
 182
 183 Un*x-like guests typically have multiple filesystems which are mounted
 184 at various mountpoints, and these are described in the
 185 E<lt>mountpointsE<gt> element which looks like this:
 186
 187  <operatingsystems>
 188    <operatingsystem>
 189      ...
 190      <mountpoints>
 191        <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
 192        <mountpoint dev="/dev/sda1">/boot</mountpoint>
 193      </mountpoints>
 194
 195 As with E<lt>rootE<gt>, devices are from the point of view of
 196 libguestfs, and may have completely different names inside the guest.
 197 Only mountable filesystems appear in this list, not things like swap
 198 devices.
 199
 200 =head2 E<lt>filesystemsE<gt>
 201
 202 E<lt>filesystemsE<gt> is like E<lt>mountpointsE<gt> but covers I<all>
 203 filesystems belonging to the guest, including swap and empty
 204 partitions.  (In the rare case of a multi-boot guest, it covers
 205 filesystems belonging to this OS or shared by this OS and other OSes).
 206
 207 You might see something like this:
 208
 209  <operatingsystems>
 210    <operatingsystem>
 211      ...
 212      <filesystems>
 213        <filesystem dev="/dev/vg_f13x64/lv_root">
 214          <type>ext4</type>
 215          <label>Fedora-13-x86_64</label>
 216          <uuid>e6a4db1e-15c2-477b-ac2a-699181c396aa</uuid>
 217        </filesystem>
 218
 219 The optional elements within E<lt>filesystemE<gt> are the filesystem
 220 type, the label, and the UUID.
 221
 222 =head2 E<lt>applicationsE<gt>
 223
 224 The related elements E<lt>package_formatE<gt>,
 225 E<lt>package_managementE<gt> and E<lt>applicationsE<gt> describe
 226 applications installed in the virtual machine.
 227
 228 E<lt>package_formatE<gt>, if present, describes the packaging
 229 system used.  Typical values would be C<rpm> and C<deb>.
 230
 231 E<lt>package_managementE<gt>, if present, describes the package
 232 manager.  Typical values include C<yum>, C<up2date> and C<apt>
 233
 234 E<lt>applicationsE<gt> lists the packages or applications
 235 installed.
 236
 237  <operatingsystems>
 238    <operatingsystem>
 239      ...
 240      <applications>
 241        <application>
 242          <name>coreutils</name>
 243          <version>8.5</version>
 244          <release>1</release>
 245        </application>
 246
 247 The version and release fields may not be available for some types
 248 guests.  Other fields are possible, see
 249 L<guestfs(3)/guestfs_inspect_list_applications>.
 250
 251 =head2 INSPECTING INSTALL DISKS, LIVE CDs
 252
 253 Virt-inspector can detect some operating system installers on
 254 install disks, live CDs, bootable USB keys and more.
 255
 256 In this case the E<lt>formatE<gt> tag will contain C<installer>
 257 and other fields may be present to indicate a live CD, network
 258 installer, or one part of a multipart CD.  For example:
 259
 260  <operatingsystems>
 261    <operatingsystem>
 262      <root>/dev/sda</root>
 263      <name>linux</name>
 264      <arch>i386</arch>
 265      <distro>ubuntu</distro>
 266      <product_name>Ubuntu 10.10 &quot;Maverick Meerkat&quot;</product_name>
 267      <major_version>10</major_version>
 268      <minor_version>10</minor_version>
 269      <format>installer</format>
 270      <live/>
 271
 272 =head1 USING XPATH
 273
 274 You can use the XPath query language, and/or the xpath tool, in order
 275 to select parts of the XML.
 276
 277 For example:
 278
 279  $ virt-inspector -d Guest | xpath //filesystems
 280  Found 1 nodes:
 281  -- NODE --
 282  <filesystems>
 283       <filesystem dev="/dev/vg_f13x64/lv_root">
 284         <type>ext4</type>
 285  [etc]
 286
 287  $ virt-inspector -d Guest | \
 288      xpath "string(//filesystem[@dev='/dev/sda1']/type)"
 289  Query didn't return a nodeset. Value: ext4
 290
 291 =head1 SHELL QUOTING
 292
 293 Libvirt guest names can contain arbitrary characters, some of which
 294 have meaning to the shell such as C<#> and space.  You may need to
 295 quote or escape these characters on the command line.  See the shell
 296 manual page L<sh(1)> for details.
 297
 298 =head1 SEE ALSO
 299
 300 L<guestfs(3)>,
 301 L<guestfish(1)>,
 302 L<http://www.w3.org/TR/xpath/>,
 303 L<http://libguestfs.org/>.
 304
 305 =head1 AUTHORS
 306
 307 =over 4
 308
 309 =item *
 310
 311 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 312
 313 =item *
 314
 315 Matthew Booth L<mbooth@redhat.com>
 316
 317 =back
 318
 319 =head1 COPYRIGHT
 320
 321 Copyright (C) 2010-2011 Red Hat Inc.
 322
 323 This program is free software; you can redistribute it and/or modify
 324 it under the terms of the GNU General Public License as published by
 325 the Free Software Foundation; either version 2 of the License, or
 326 (at your option) any later version.
 327
 328 This program is distributed in the hope that it will be useful,
 329 but WITHOUT ANY WARRANTY; without even the implied warranty of
 330 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 331 GNU General Public License for more details.
 332
 333 You should have received a copy of the GNU General Public License
 334 along with this program; if not, write to the Free Software
 335 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.