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