1virt-inspector(1) Virtualization Support virt-inspector(1)
2
6 virt-inspector - Display operating system version and other information
7 about a virtual machine
8
10 virt-inspector [--options] -d domname
11 virt-inspector [--options] -a disk.img [-a disk.img ...]
13 Old-style:
15 virt-inspector domname
17 virt-inspector disk.img [disk.img ...]
19
21 virt-inspector examines a virtual machine or disk image and tries to
22 determine the version of the operating system and other information
23 about the virtual machine.
24 Virt-inspector produces XML output for feeding into other programs.
26 In the normal usage, use "virt-inspector -d domname" where "domname" is
28 the libvirt domain (see: "virsh list --all").
29 You can also run virt-inspector directly on disk images from a single
31 virtual machine. Use "virt-inspector -a disk.img". In rare cases a
32 domain has several block devices, in which case you should list several
33 -a options one after another, with the first corresponding to the
34 guest’s /dev/sda, the second to the guest’s /dev/sdb and so on.
35 You can also run virt-inspector on install disks, live CDs, bootable
37 USB keys and similar.
38 Virt-inspector can only inspect and report upon one domain at a time.
40 To inspect several virtual machines, you have to run virt-inspector
41 several times (for example, from a shell script for-loop).
42 Because virt-inspector needs direct access to guest images, it won’t
44 normally work over remote libvirt connections.
45 All of the information available from virt-inspector is also available
47 through the core libguestfs inspection API (see "INSPECTION" in
48 guestfs(3)). The same information can also be fetched using guestfish
49 or via libguestfs bindings in many programming languages (see "GETTING
50 INSPECTION DATA FROM THE LIBGUESTFS API").
51
53 --help
54 Display brief help.
55 -a file
57 --add file
58 Add file which should be a disk image from a virtual machine. If
59 the virtual machine has multiple block devices, you must supply all
60 of them with separate -a options.
61 The format of the disk image is auto-detected. To override this
63 and force a particular format use the --format=.. option.
64 -a URI
66 --add URI
67 Add a remote disk. See "ADDING REMOTE STORAGE" in guestfish(1).
68 -c URI
70 --connect URI
71 If using libvirt, connect to the given URI. If omitted, then we
72 connect to the default libvirt hypervisor.
73 Libvirt is only used if you specify a "domname" on the command
75 line. If you specify guest block devices directly (-a), then
76 libvirt is not used at all.
77 -d guest
79 --domain guest
80 Add all the disks from the named libvirt guest. Domain UUIDs can
81 be used instead of names.
82 --echo-keys
84 When prompting for keys and passphrases, virt-inspector normally
85 turns echoing off so you cannot see what you are typing. If you
86 are not worried about Tempest attacks and there is no one else in
87 the room you can specify this flag to see what you are typing.
88 --format=raw|qcow2|..
90 --format
91 Specify the format of disk images given on the command line. If
92 this is omitted then the format is autodetected from the content of
93 the disk image.
94 If disk images are requested from libvirt, then this program asks
96 libvirt for this information. In this case, the value of the
97 format parameter is ignored.
98 If working with untrusted raw-format guest disk images, you should
100 ensure the format is always specified.
101 --key SELECTOR
103 Specify a key for LUKS, to automatically open a LUKS device when
104 using the inspection. "SELECTOR" can be in one of the following
105 formats:
106 --key "DEVICE":key:KEY_STRING
108 Use the specified "KEY_STRING" as passphrase.
109 --key "DEVICE":file:FILENAME
111 Read the passphrase from FILENAME.
112 --keys-from-stdin
114 Read key or passphrase parameters from stdin. The default is to
115 try to read passphrases from the user by opening /dev/tty.
116 --no-applications
118 By default the output of virt-inspector includes the list of all
119 the applications installed in the guest, if available.
120 Specify this option to disable this part of the resulting XML.
122 --no-icon
124 By default the output of virt-inspector includes the icon of the
125 guest, if available (see "icon").
126 Specify this option to disable this part of the resulting XML.
128 -v
130 --verbose
131 Enable verbose messages for debugging.
132 -V
134 --version
135 Display version number and exit.
136 -x Enable tracing of libguestfs API calls.
138 --xpath query
140 Perform an XPath query on the XML on stdin, and print the result on
141 stdout. In this mode virt-inspector simply runs an XPath query;
142 all other inspection functions are disabled. See "XPATH QUERIES"
143 below for some examples.
144
146 Previous versions of virt-inspector allowed you to write either:
147 virt-inspector disk.img [disk.img ...]
149 or
151 virt-inspector guestname
153 whereas in this version you should use -a or -d respectively to avoid
155 the confusing case where a disk image might have the same name as a
156 guest.
157 For compatibility the old style is still supported.
159
161 The virt-inspector XML is described precisely in a RELAX NG schema file
162 virt-inspector.rng which is supplied with libguestfs. This section is
163 just an overview.
164 The top-level element is <operatingsystems>, and it contains one or
166 more <operatingsystem> elements. You would only see more than one
167 <operatingsystem> element if the virtual machine is multi-boot, which
168 is vanishingly rare in real world VMs.
169 <operatingsystem>
171 In the <operatingsystem> tag are various optional fields that describe
172 the operating system, its architecture, the descriptive "product name"
173 string, the type of OS and so on, as in this example:
174 <operatingsystems>
176 <operatingsystem>
177 <root>/dev/sda2</root>
178 <name>windows</name>
179 <arch>i386</arch>
180 <distro>windows</distro>
181 <product_name>Windows 7 Enterprise</product_name>
182 <product_variant>Client</product_variant>
183 <major_version>6</major_version>
184 <minor_version>1</minor_version>
185 <windows_systemroot>/Windows</windows_systemroot>
186 In brief, <name> is the class of operating system (something like
188 "linux" or "windows"), <distro> is the distribution (eg. "fedora" but
189 many other distros are recognized) and <arch> is the guest
190 architecture. The other fields are fairly self-explanatory, but
191 because these fields are taken directly from the libguestfs inspection
192 API you can find precise information from "INSPECTION" in guestfs(3).
193 The <root> element is the root filesystem device, but from the point of
195 view of libguestfs (block devices may have completely different names
196 inside the VM itself).
197 <mountpoints>
199 Un*x-like guests typically have multiple filesystems which are mounted
200 at various mountpoints, and these are described in the <mountpoints>
201 element which looks like this:
202 <operatingsystems>
204 <operatingsystem>
205 ...
206 <mountpoints>
207 <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
208 <mountpoint dev="/dev/sda1">/boot</mountpoint>
209 </mountpoints>
210 As with <root>, devices are from the point of view of libguestfs, and
212 may have completely different names inside the guest. Only mountable
213 filesystems appear in this list, not things like swap devices.
214 <filesystems>
216 <filesystems> is like <mountpoints> but covers all filesystems
217 belonging to the guest, including swap and empty partitions. (In the
218 rare case of a multi-boot guest, it covers filesystems belonging to
219 this OS or shared with this OS and other OSes).
220 You might see something like this:
222 <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 The optional elements within <filesystem> are the filesystem type, the
234 label, and the UUID.
235 <applications>
237 The related elements <package_format>, <package_management> and
238 <applications> describe applications installed in the virtual machine.
239 <package_format>, if present, describes the packaging system used.
241 Typical values would be "rpm" and "deb".
242 <package_management>, if present, describes the package manager.
244 Typical values include "yum", "up2date" and "apt"
245 <applications> lists the packages or applications installed.
247 <operatingsystems>
249 <operatingsystem>
250 ...
251 <applications>
252 <application>
253 <name>coreutils</name>
254 <version>8.5</version>
255 <release>1</release>
256 </application>
257 The version and release fields may not be available for some types
259 guests. Other fields are possible, see
260 "guestfs_inspect_list_applications" in guestfs(3).
261 <drive_mappings>
263 For operating systems like Windows which use drive letters, virt-
264 inspector is able to find out how drive letters map to filesystems.
265 <operatingsystems>
267 <operatingsystem>
268 ...
269 <drive_mappings>
270 <drive_mapping name="C">/dev/sda2</drive_mapping>
271 <drive_mapping name="E">/dev/sdb1</drive_mapping>
272 </drive_mappings>
273 In the example above, drive C maps to the filesystem on the second
275 partition on the first disk, and drive E maps to the filesystem on the
276 first partition on the second disk.
277 Note that this only covers permanent local filesystem mappings, not
279 things like network shares. Furthermore NTFS volume mount points may
280 not be listed here.
281 <icon>
283 Virt-inspector is sometimes able to extract an icon or logo for the
284 guest. The icon is returned as base64-encoded PNG data. Note that the
285 icon can be very large and high quality.
286 <operatingsystems>
288 <operatingsystem>
289 ...
290 <icon>
291 iVBORw0KGgoAAAANSUhEUgAAAGAAAABg[.......]
292 [... many lines of base64 data ...]
293 </icon>
294 To display the icon, you have to extract it and convert the base64 data
296 back to a binary file. Use an XPath query or simply an editor to
297 extract the data, then use the coreutils base64(1) program to do the
298 conversion back to a PNG file:
299 base64 -i -d < icon.data > icon.png
301
303 Virt-inspector includes built in support for running XPath queries.
304 The reason for including XPath support directly in virt-inspector is
305 simply that there are no good and widely available command line
306 programs that can do XPath queries. The only good one is xmlstarlet(1)
307 and that is not available on Red Hat Enterprise Linux.
308 To perform an XPath query, use the --xpath option. Note that in this
310 mode, virt-inspector simply reads XML from stdin and outputs the query
311 result on stdout. All other inspection features are disabled in this
312 mode.
313 For example:
315 $ virt-inspector -d Guest | virt-inspector --xpath '//filesystems'
317 <filesystems>
318 <filesystem dev="/dev/vg_f13x64/lv_root">
319 <type>ext4</type>
320 [...]
321 $ virt-inspector -d Guest | \
323 virt-inspector --xpath "string(//filesystem[@dev='/dev/sda1']/type)"
324 ext4
325 $ virt-inspector -d Guest | \
327 virt-inspector --xpath 'string(//icon)' | base64 -i -d | display -
328 [displays the guest icon, if there is one]
329
331 In early versions of libguestfs, virt-inspector was a large Perl script
332 that contained many heuristics for inspecting guests. This had several
333 problems: in order to do inspection from other tools (like guestfish)
334 we had to call out to this Perl script; and it privileged Perl over
335 other languages that libguestfs supports.
336 By libguestfs 1.8 we had rewritten the Perl code in C, and incorporated
338 it all into the core libguestfs API (guestfs(3)). Now virt-inspector
339 is simply a thin C program over the core C API. All of the inspection
340 information is available from all programming languages that libguestfs
341 supports, and from guestfish.
342 For a description of the C inspection API, read "INSPECTION" in
344 guestfs(3).
345 For example code using the C inspection API, look for inspect-vm.c
347 which ships with libguestfs.
348 inspect-vm.c has also been translated into other languages. For
350 example, inspect_vm.pl is the Perl translation, and there are other
351 translations for OCaml, Python, etc. See "USING LIBGUESTFS WITH OTHER
352 PROGRAMMING LANGUAGES" in guestfs(3) for a list of man pages which
353 contain this example code.
354 GETTING INSPECTION DATA FROM GUESTFISH
356 If you use the guestfish -i option, then the main C inspection API
357 "guestfs_inspect_os" in guestfs(3) is called. This is equivalent to
358 the guestfish command "inspect-os". You can also call this guestfish
359 command by hand.
360 "inspect-os" performs inspection on the current disk image, returning
362 the list of operating systems found. Each OS is represented by its
363 root filesystem device. In the majority of cases, this command prints
364 nothing (no OSes found), or a single root device, but beware that it
365 can print multiple lines if there are multiple OSes or if there is an
366 install CD attached to the guest.
367 $ guestfish --ro -a F15x32.img
369 ><fs> run
370 ><fs> inspect-os
371 /dev/vg_f15x32/lv_root
372 Using the root device, you can fetch further information about the
374 guest:
375 ><fs> inspect-get-type /dev/vg_f15x32/lv_root
377 linux
378 ><fs> inspect-get-distro /dev/vg_f15x32/lv_root
379 fedora
380 ><fs> inspect-get-major-version /dev/vg_f15x32/lv_root
381 15
382 ><fs> inspect-get-product-name /dev/vg_f15x32/lv_root
383 Fedora release 15 (Lovelock)
384 Limitations of guestfish make it hard to assign the root device to a
386 variable (since guestfish doesn't have variables), so if you want to do
387 this reproducibly you are better off writing a script using one of the
388 other languages that the libguestfs API supports.
389 To list applications, you have to first mount up the disks:
391 ><fs> inspect-get-mountpoints /dev/vg_f15x32/lv_root
393 /: /dev/vg_f15x32/lv_root
394 /boot: /dev/vda1
395 ><fs> mount-ro /dev/vg_f15x32/lv_root /
396 ><fs> mount-ro /dev/vda1 /boot
397 and then call the inspect-list-applications API:
399 ><fs> inspect-list-applications /dev/vg_f15x32/lv_root | head -28
401 [0] = {
402 app_name: ConsoleKit
403 app_display_name:
404 app_epoch: 0
405 app_version: 0.4.5
406 app_release: 1.fc15
407 app_install_path:
408 app_trans_path:
409 app_publisher:
410 app_url:
411 app_source_package:
412 app_summary:
413 app_description:
414 }
415 [1] = {
416 app_name: ConsoleKit-libs
417 app_display_name:
418 app_epoch: 0
419 app_version: 0.4.5
420 app_release: 1.fc15
421 app_install_path:
422 app_trans_path:
423 app_publisher:
424 app_url:
425 app_source_package:
426 app_summary:
427 app_description:
428 }
429 To display an icon for the guest, note that filesystems must also be
431 mounted as above. You can then do:
432 ><fs> inspect-get-icon /dev/vg_f15x32/lv_root | display -
434
436 As described above, early versions of libguestfs shipped with a
437 different virt-inspector program written in Perl (the current version
438 is written in C). The XML output of the Perl virt-inspector was
439 different and it could also output in other formats like text.
440 The old virt-inspector is no longer supported or shipped with
442 libguestfs.
443 To confuse matters further, in Red Hat Enterprise Linux 6 we ship two
445 versions of virt-inspector with different names:
446 virt-inspector Old Perl version.
448 virt-inspector2 New C version.
449
451 This program returns 0 if successful, or non-zero if there was an
452 error.
453
455 guestfs(3), guestfish(1), http://www.w3.org/TR/xpath/, base64(1),
456 xmlstarlet(1), http://libguestfs.org/.
457
459 · Richard W.M. Jones http://people.redhat.com/~rjones/
460 · Matthew Booth mbooth@redhat.com
462
464 Copyright (C) 2010-2012 Red Hat Inc.
465
467 This program is free software; you can redistribute it and/or modify it
468 under the terms of the GNU General Public License as published by the
469 Free Software Foundation; either version 2 of the License, or (at your
470 option) any later version.
471 This program is distributed in the hope that it will be useful, but
473 WITHOUT ANY WARRANTY; without even the implied warranty of
474 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
475 General Public License for more details.
476 You should have received a copy of the GNU General Public License along
478 with this program; if not, write to the Free Software Foundation, Inc.,
479 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
480
482 To get a list of bugs against libguestfs, use this link:
483 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
484 To report a new bug against libguestfs, use this link:
486 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
487 When reporting a bug, please supply:
489 · The version of libguestfs.
491 · Where you got libguestfs (eg. which Linux distro, compiled from
493 source, etc)
494 · Describe the bug accurately and give a way to reproduce it.
496 · Run libguestfs-test-tool(1) and paste the complete, unedited output
498 into the bug report.
499libguestfs-1.40.1 2019-01-17 virt-inspector(1)