1virt-inspector(1)           Virtualization Support           virt-inspector(1)
2
3
4

NAME

6       virt-inspector - Display operating system version and other information
7       about a virtual machine
8

SYNOPSIS

10        virt-inspector [--options] -d domname
11
12        virt-inspector [--options] -a disk.img [-a disk.img ...]
13
14       Old-style:
15
16        virt-inspector domname
17
18        virt-inspector disk.img [disk.img ...]
19

DESCRIPTION

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
25       Virt-inspector produces XML output for feeding into other programs.
26
27       In the normal usage, use "virt-inspector -d domname" where "domname" is
28       the libvirt domain (see: "virsh list --all").
29
30       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
36       You can also run virt-inspector on install disks, live CDs, bootable
37       USB keys and similar.
38
39       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
43       Because virt-inspector needs direct access to guest images, it won’t
44       normally work over remote libvirt connections.
45
46       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

OPTIONS

53       --help
54           Display brief help.
55
56       -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
62           The format of the disk image is auto-detected.  To override this
63           and force a particular format use the --format=.. option.
64
65       -a URI
66       --add URI
67           Add a remote disk.  See "ADDING REMOTE STORAGE" in guestfish(1).
68
69       -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
74           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
78       -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
83       --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
89       --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
95           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
99           If working with untrusted raw-format guest disk images, you should
100           ensure the format is always specified.
101
102       --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
107           --key "DEVICE":key:KEY_STRING
108               Use the specified "KEY_STRING" as passphrase.
109
110           --key "DEVICE":file:FILENAME
111               Read the passphrase from FILENAME.
112
113       --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
117       --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
121           Specify this option to disable this part of the resulting XML.
122
123       --no-icon
124           By default the output of virt-inspector includes the icon of the
125           guest, if available (see "icon").
126
127           Specify this option to disable this part of the resulting XML.
128
129       -v
130       --verbose
131           Enable verbose messages for debugging.
132
133       -V
134       --version
135           Display version number and exit.
136
137       -x  Enable tracing of libguestfs API calls.
138
139       --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

OLD-STYLE COMMAND LINE ARGUMENTS

146       Previous versions of virt-inspector allowed you to write either:
147
148        virt-inspector disk.img [disk.img ...]
149
150       or
151
152        virt-inspector guestname
153
154       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
158       For compatibility the old style is still supported.
159

XML FORMAT

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
165       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
170   <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
175        <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
187       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
194       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
198   <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
203        <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
211       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
215   <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
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 <filesystem> are the filesystem type, the
234       label, and the UUID.
235
236   <applications>
237       The related elements <package_format>, <package_management> and
238       <applications> describe applications installed in the virtual machine.
239
240       <package_format>, if present, describes the packaging system used.
241       Typical values would be "rpm" and "deb".
242
243       <package_management>, if present, describes the package manager.
244       Typical values include "yum", "up2date" and "apt"
245
246       <applications> lists the packages or applications installed.
247
248        <operatingsystems>
249          <operatingsystem>
250            ...
251            <applications>
252              <application>
253                <name>coreutils</name>
254                <version>8.5</version>
255                <release>1</release>
256              </application>
257
258       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
262   <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
266        <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
274       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
278       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
282   <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
287        <operatingsystems>
288          <operatingsystem>
289            ...
290            <icon>
291              iVBORw0KGgoAAAANSUhEUgAAAGAAAABg[.......]
292              [... many lines of base64 data ...]
293            </icon>
294
295       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
300        base64 -i -d < icon.data > icon.png
301

XPATH QUERIES

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
309       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
314       For example:
315
316        $ virt-inspector -d Guest | virt-inspector --xpath '//filesystems'
317        <filesystems>
318             <filesystem dev="/dev/vg_f13x64/lv_root">
319               <type>ext4</type>
320        [...]
321
322        $ virt-inspector -d Guest | \
323            virt-inspector --xpath "string(//filesystem[@dev='/dev/sda1']/type)"
324        ext4
325
326        $ virt-inspector -d Guest | \
327            virt-inspector --xpath 'string(//icon)' | base64 -i -d | display -
328        [displays the guest icon, if there is one]
329

GETTING INSPECTION DATA FROM THE LIBGUESTFS API

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
337       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
343       For a description of the C inspection API, read "INSPECTION" in
344       guestfs(3).
345
346       For example code using the C inspection API, look for inspect-vm.c
347       which ships with libguestfs.
348
349       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
355   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
361       "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
368        $ guestfish --ro -a F15x32.img
369        ><fs> run
370        ><fs> inspect-os
371        /dev/vg_f15x32/lv_root
372
373       Using the root device, you can fetch further information about the
374       guest:
375
376        ><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
385       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
390       To list applications, you have to first mount up the disks:
391
392        ><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
398       and then call the inspect-list-applications API:
399
400        ><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
430       To display an icon for the guest, note that filesystems must also be
431       mounted as above.  You can then do:
432
433        ><fs> inspect-get-icon /dev/vg_f15x32/lv_root | display -
434

OLD VERSIONS OF VIRT-INSPECTOR

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
441       The old virt-inspector is no longer supported or shipped with
442       libguestfs.
443
444       To confuse matters further, in Red Hat Enterprise Linux 6 we ship two
445       versions of virt-inspector with different names:
446
447        virt-inspector     Old Perl version.
448        virt-inspector2    New C version.
449

EXIT STATUS

451       This program returns 0 if successful, or non-zero if there was an
452       error.
453

SEE ALSO

455       guestfs(3), guestfish(1), http://www.w3.org/TR/xpath/, base64(1),
456       xmlstarlet(1), http://libguestfs.org/.
457

AUTHORS

459       ·   Richard W.M. Jones http://people.redhat.com/~rjones/
460
461       ·   Matthew Booth mbooth@redhat.com
462
464       Copyright (C) 2010-2012 Red Hat Inc.
465

LICENSE

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
472       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
477       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

BUGS

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
485       To report a new bug against libguestfs, use this link:
486       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
487
488       When reporting a bug, please supply:
489
490       ·   The version of libguestfs.
491
492       ·   Where you got libguestfs (eg. which Linux distro, compiled from
493           source, etc)
494
495       ·   Describe the bug accurately and give a way to reproduce it.
496
497       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
498           into the bug report.
499
500
501
502libguestfs-1.40.2                 2019-02-07                 virt-inspector(1)
Impressum