5 virt-inspector - Display operating system version and other information about a virtual machine
9 virt-inspector [--options] -d domname
11 virt-inspector [--options] -a disk.img [-a disk.img ...]
15 virt-inspector domname
17 virt-inspector disk.img [disk.img ...]
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.
25 Virt-inspector produces XML output for feeding into other programs.
27 In the normal usage, use C<virt-inspector -d domname> where C<domname> is
28 the libvirt domain (see: C<virsh list --all>).
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
37 You can also run virt-inspector on install disks, live CDs, bootable
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
45 Because virt-inspector needs direct access to guest images, it won't
46 normally work over remote libvirt connections.
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
53 (see L<guestfs(3)/USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES>).
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.
71 The format of the disk image is auto-detected. To override this and
72 force a particular format use the I<--format=..> option.
76 =item B<--connect URI>
78 If using libvirt, connect to the given I<URI>. If omitted,
79 then we connect to the default libvirt hypervisor.
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.
87 =item B<--domain> guest
89 Add all the disks from the named libvirt guest. Domain UUIDs can be
90 used instead of names.
94 When prompting for keys and passphrases, virt-inspector normally turns
95 echoing off so you cannot see what you are typing. If you are not
96 worried about Tempest attacks and there is no one else in the room you
97 can specify this flag to see what you are typing.
99 =item B<--format=raw|qcow2|..>
103 Specify the format of disk images given on the command line. If this
104 is omitted then the format is autodetected from the content of the
107 If disk images are requested from libvirt, then this program asks
108 libvirt for this information. In this case, the value of the format
109 parameter is ignored.
111 If working with untrusted raw-format guest disk images, you should
112 ensure the format is always specified.
114 =item B<--keys-from-stdin>
116 Read key or passphrase parameters from stdin. The default is
117 to try to read passphrases from the user by opening C</dev/tty>.
123 Enable verbose messages for debugging.
129 Display version number and exit.
133 Enable tracing of libguestfs API calls.
135 =item B<--xpath> query
137 Perform an XPath query on the XML on stdin, and print the result on
138 stdout. In this mode virt-inspector simply runs an XPath query; all
139 other inspection functions are disabled. See L</XPATH QUERIES> below
144 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
146 Previous versions of virt-inspector allowed you to write either:
148 virt-inspector disk.img [disk.img ...]
152 virt-inspector guestname
154 whereas in this version you should use I<-a> or I<-d> respectively
155 to avoid the confusing case where a disk image might have the same
158 For compatibility the old style is still supported.
162 The virt-inspector XML is described precisely in a RELAX NG schema
163 file C<virt-inspector.rng> which is supplied with libguestfs. This
164 section is just an overview.
166 The top-level element is E<lt>operatingsystemsE<gt>, and it contains
167 one or more E<lt>operatingsystemE<gt> elements. You would only see
168 more than one E<lt>operatingsystemE<gt> element if the virtual machine
169 is multi-boot, which is vanishingly rare in real world VMs.
171 =head2 E<lt>operatingsystemE<gt>
173 In the E<lt>operatingsystemE<gt> tag are various optional fields that
174 describe the operating system, its architecture, the descriptive
175 "product name" string, the type of OS and so on, as in this example:
179 <root>/dev/sda2</root>
182 <distro>windows</distro>
183 <product_name>Windows 7 Enterprise</product_name>
184 <product_variant>Client</product_variant>
185 <major_version>6</major_version>
186 <minor_version>1</minor_version>
187 <windows_systemroot>/Windows</windows_systemroot>
188 <format>installed</format>
190 In brief, E<lt>nameE<gt> is the class of operating system (something
191 like C<linux> or C<windows>), E<lt>distroE<gt> is the distribution
192 (eg. C<fedora> but many other distros are recognized) and
193 E<lt>archE<gt> is the guest architecture. The other fields are fairly
194 self-explanatory, but because these fields are taken directly from the
195 libguestfs inspection API you can find precise information from
196 L<guestfs(3)/INSPECTION>.
198 The E<lt>rootE<gt> element is the root filesystem device, but from the
199 point of view of libguestfs (block devices may have completely
200 different names inside the VM itself).
202 =head2 E<lt>mountpointsE<gt>
204 Un*x-like guests typically have multiple filesystems which are mounted
205 at various mountpoints, and these are described in the
206 E<lt>mountpointsE<gt> element which looks like this:
212 <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
213 <mountpoint dev="/dev/sda1">/boot</mountpoint>
216 As with E<lt>rootE<gt>, devices are from the point of view of
217 libguestfs, and may have completely different names inside the guest.
218 Only mountable filesystems appear in this list, not things like swap
221 =head2 E<lt>filesystemsE<gt>
223 E<lt>filesystemsE<gt> is like E<lt>mountpointsE<gt> but covers I<all>
224 filesystems belonging to the guest, including swap and empty
225 partitions. (In the rare case of a multi-boot guest, it covers
226 filesystems belonging to this OS or shared with this OS and other
229 You might see something like this:
235 <filesystem dev="/dev/vg_f13x64/lv_root">
237 <label>Fedora-13-x86_64</label>
238 <uuid>e6a4db1e-15c2-477b-ac2a-699181c396aa</uuid>
241 The optional elements within E<lt>filesystemE<gt> are the filesystem
242 type, the label, and the UUID.
244 =head2 E<lt>applicationsE<gt>
246 The related elements E<lt>package_formatE<gt>,
247 E<lt>package_managementE<gt> and E<lt>applicationsE<gt> describe
248 applications installed in the virtual machine.
250 E<lt>package_formatE<gt>, if present, describes the packaging
251 system used. Typical values would be C<rpm> and C<deb>.
253 E<lt>package_managementE<gt>, if present, describes the package
254 manager. Typical values include C<yum>, C<up2date> and C<apt>
256 E<lt>applicationsE<gt> lists the packages or applications
264 <name>coreutils</name>
265 <version>8.5</version>
269 The version and release fields may not be available for some types
270 guests. Other fields are possible, see
271 L<guestfs(3)/guestfs_inspect_list_applications>.
273 =head2 E<lt>drive_mappingsE<gt>
275 For operating systems like Windows which use drive letters,
276 virt-inspector is able to find out how drive letters map to
283 <drive_mapping name="C">/dev/sda2</drive_mapping>
284 <drive_mapping name="E">/dev/sdb1</drive_mapping>
287 In the example above, drive C maps to the filesystem on the second
288 partition on the first disk, and drive E maps to the filesystem on the
289 first partition on the second disk.
291 Note that this only covers permanent local filesystem mappings, not
292 things like network shares. Furthermore NTFS volume mount points may
295 =head2 E<lt>iconE<gt>
297 Virt-inspector is sometimes able to extract an icon or logo for the
298 guest. The icon is returned as base64-encoded PNG data. Note that
299 the icon can be very large and high quality.
305 iVBORw0KGgoAAAANSUhEUgAAAGAAAABg[.......]
306 [... many lines of base64 data ...]
309 To display the icon, you have to extract it and convert the base64
310 data back to a binary file. Use an XPath query or simply an editor to
311 extract the data, then use the coreutils L<base64(1)> program to do
312 the conversion back to a PNG file:
314 base64 -i -d < icon.data > icon.png
316 =head2 INSPECTING INSTALL DISKS, LIVE CDs
318 Virt-inspector can detect some operating system installers on
319 install disks, live CDs, bootable USB keys and more.
321 In this case the E<lt>formatE<gt> tag will contain C<installer>
322 and other fields may be present to indicate a live CD, network
323 installer, or one part of a multipart CD. For example:
327 <root>/dev/sda</root>
330 <distro>ubuntu</distro>
331 <product_name>Ubuntu 10.10 "Maverick Meerkat"</product_name>
332 <major_version>10</major_version>
333 <minor_version>10</minor_version>
334 <format>installer</format>
339 Virt-inspector includes built in support for running XPath queries.
340 The reason for including XPath support directly in virt-inspector is
341 simply that there are no good and widely available command line
342 programs that can do XPath queries. The only good one is
343 L<xmlstarlet(1)> and that is not available on Red Hat Enterprise
346 To perform an XPath query, use the I<--xpath> option. Note that in
347 this mode, virt-inspector simply reads XML from stdin and outputs the
348 query result on stdout. All other inspection features are disabled in
353 $ virt-inspector -d Guest | virt-inspector --xpath '//filesystems'
355 <filesystem dev="/dev/vg_f13x64/lv_root">
359 $ virt-inspector -d Guest | \
360 virt-inspector --xpath "string(//filesystem[@dev='/dev/sda1']/type)"
363 $ virt-inspector -d Guest | \
364 virt-inspector --xpath 'string(//icon)' | base64 -i -d | display -
365 [displays the guest icon, if there is one]
369 Libvirt guest names can contain arbitrary characters, some of which
370 have meaning to the shell such as C<#> and space. You may need to
371 quote or escape these characters on the command line. See the shell
372 manual page L<sh(1)> for details.
374 =head1 OLD VERSIONS OF VIRT-INSPECTOR
376 Early versions of libguestfs shipped with a different virt-inspector
377 program written in Perl (the current version is written in C). The
378 XML output of the Perl virt-inspector was different and it could also
379 output in other formats like text.
381 The old virt-inspector is no longer supported or shipped with
384 To confuse matters further, in Red Hat Enterprise Linux 6 we ship two
385 versions of virt-inspector with different names:
387 virt-inspector Old Perl version.
388 virt-inspector2 New C version.
392 This program returns 0 if successful, or non-zero if there was an
399 L<http://www.w3.org/TR/xpath/>,
402 L<http://libguestfs.org/>.
410 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
414 Matthew Booth L<mbooth@redhat.com>
420 Copyright (C) 2010-2011 Red Hat Inc.
422 This program is free software; you can redistribute it and/or modify
423 it under the terms of the GNU General Public License as published by
424 the Free Software Foundation; either version 2 of the License, or
425 (at your option) any later version.
427 This program is distributed in the hope that it will be useful,
428 but WITHOUT ANY WARRANTY; without even the implied warranty of
429 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
430 GNU General Public License for more details.
432 You should have received a copy of the GNU General Public License
433 along with this program; if not, write to the Free Software
434 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.