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 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
42 Because virt-inspector needs direct access to guest images, it won't
43 normally work over remote libvirt connections.
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.
61 The format of the disk image is auto-detected. To override this and
62 force a particular format use the I<--format=..> option.
66 =item B<--connect URI>
68 If using libvirt, connect to the given I<URI>. If omitted,
69 then we connect to the default libvirt hypervisor.
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.
77 =item B<--domain> guest
79 Add all the disks from the named libvirt guest.
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.
88 =item B<--format=raw|qcow2|..>
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
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
100 If working with untrusted raw-format guest disk images, you should
101 ensure the format is always specified.
103 =item B<--keys-from-stdin>
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>.
112 Enable verbose messages for debugging.
118 Display version number and exit.
122 Enable tracing of libguestfs API calls.
126 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
128 Previous versions of virt-inspector allowed you to write either:
130 virt-inspector disk.img [disk.img ...]
134 virt-inspector guestname
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
140 For compatibility the old style is still supported.
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.
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.
152 =head2 E<lt>operatingsystemE<gt>
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:
160 <root>/dev/sda2</root>
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>
169 These fields are derived from the libguestfs inspection API, and
170 you can find more details in L<guestfs(3)/INSPECTION>.
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).
176 =head2 E<lt>mountpointsE<gt>
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:
186 <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
187 <mountpoint dev="/dev/sda1">/boot</mountpoint>
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
195 =head2 E<lt>filesystemsE<gt>
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).
202 You might see something like this:
208 <filesystem dev="/dev/vg_f13x64/lv_root">
210 <label>Fedora-13-x86_64</label>
211 <uuid>e6a4db1e-15c2-477b-ac2a-699181c396aa</uuid>
214 The optional elements within E<lt>filesystemE<gt> are the filesystem
215 type, the label, and the UUID.
217 =head2 E<lt>applicationsE<gt>
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.
223 E<lt>package_formatE<gt>, if present, describes the packaging
224 system used. Typical values would be C<rpm> and C<deb>.
226 E<lt>package_managementE<gt>, if present, describes the package
227 manager. Typical values include C<yum>, C<up2date> and C<apt>
229 E<lt>applicationsE<gt> lists the packages or applications
237 <name>coreutils</name>
238 <version>8.5</version>
242 The version and release fields may not be available for some types
243 guests. Other fields are possible, see
244 L<guestfs(3)/guestfs_inspect_list_applications>.
248 You can use the XPath query language, and/or the xpath tool, in order
249 to select parts of the XML.
253 $ virt-inspector -d Guest | xpath //filesystems
257 <filesystem dev="/dev/vg_f13x64/lv_root">
261 $ virt-inspector -d Guest | \
262 xpath "string(//filesystem[@dev='/dev/sda1']/type)"
263 Query didn't return a nodeset. Value: ext4
267 Libvirt guest names can contain arbitrary characters, some of which
268 have meaning to the shell such as C<#> and space. You may need to
269 quote or escape these characters on the command line. See the shell
270 manual page L<sh(1)> for details.
276 L<http://www.w3.org/TR/xpath/>,
277 L<http://libguestfs.org/>.
285 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
289 Matthew Booth L<mbooth@redhat.com>
295 Copyright (C) 2010 Red Hat Inc.
297 This program is free software; you can redistribute it and/or modify
298 it under the terms of the GNU General Public License as published by
299 the Free Software Foundation; either version 2 of the License, or
300 (at your option) any later version.
302 This program is distributed in the hope that it will be useful,
303 but WITHOUT ANY WARRANTY; without even the implied warranty of
304 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
305 GNU General Public License for more details.
307 You should have received a copy of the GNU General Public License
308 along with this program; if not, write to the Free Software
309 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.