Version 1.10.6.
[libguestfs.git] / 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 You can also run virt-inspector on install disks, live CDs, bootable
38 USB keys and similar.
39
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
43 for-loop).
44
45 Because virt-inspector needs direct access to guest images, it won't
46 normally work over remote libvirt connections.
47
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
52 languages
53 (see L<guestfs(3)/USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES>).
54
55 =head1 OPTIONS
56
57 =over 4
58
59 =item B<--help>
60
61 Display brief help.
62
63 =item B<-a> file
64
65 =item B<--add> file
66
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.
70
71 The format of the disk image is auto-detected.  To override this and
72 force a particular format use the I<--format=..> option.
73
74 =item B<-c URI>
75
76 =item B<--connect URI>
77
78 If using libvirt, connect to the given I<URI>.  If omitted,
79 then we connect to the default libvirt hypervisor.
80
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.
84
85 =item B<-d> guest
86
87 =item B<--domain> guest
88
89 Add all the disks from the named libvirt guest.
90
91 =item B<--echo-keys>
92
93 When prompting for keys and passphrases, virt-inspector normally turns
94 echoing off so you cannot see what you are typing.  If you are not
95 worried about Tempest attacks and there is no one else in the room you
96 can specify this flag to see what you are typing.
97
98 =item B<--format=raw|qcow2|..>
99
100 =item B<--format>
101
102 Specify the format of disk images given on the command line.  If this
103 is omitted then the format is autodetected from the content of the
104 disk image.
105
106 If disk images are requested from libvirt, then this program asks
107 libvirt for this information.  In this case, the value of the format
108 parameter is ignored.
109
110 If working with untrusted raw-format guest disk images, you should
111 ensure the format is always specified.
112
113 =item B<--keys-from-stdin>
114
115 Read key or passphrase parameters from stdin.  The default is
116 to try to read passphrases from the user by opening C</dev/tty>.
117
118 =item B<-v>
119
120 =item B<--verbose>
121
122 Enable verbose messages for debugging.
123
124 =item B<-V>
125
126 =item B<--version>
127
128 Display version number and exit.
129
130 =item B<-x>
131
132 Enable tracing of libguestfs API calls.
133
134 =back
135
136 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
137
138 Previous versions of virt-inspector allowed you to write either:
139
140  virt-inspector disk.img [disk.img ...]
141
142 or
143
144  virt-inspector guestname
145
146 whereas in this version you should use I<-a> or I<-d> respectively
147 to avoid the confusing case where a disk image might have the same
148 name as a guest.
149
150 For compatibility the old style is still supported.
151
152 =head1 XML FORMAT
153
154 The virt-inspector XML is described precisely in a RELAX NG schema
155 file C<virt-inspector.rng> which is supplied with libguestfs.  This
156 section is just an overview.
157
158 The top-level element is E<lt>operatingsystemsE<gt>, and it contains
159 one or more E<lt>operatingsystemE<gt> elements.  You would only see
160 more than one E<lt>operatingsystemE<gt> element if the virtual machine
161 is multi-boot, which is vanishingly rare in real world VMs.
162
163 =head2 E<lt>operatingsystemE<gt>
164
165 In the E<lt>operatingsystemE<gt> tag are various optional fields that
166 describe the operating system, its architecture, the descriptive
167 "product name" string, the type of OS and so on, as in this example:
168
169  <operatingsystems>
170    <operatingsystem>
171      <root>/dev/sda2</root>
172      <name>windows</name>
173      <arch>i386</arch>
174      <distro>windows</distro>
175      <product_name>Windows 7 Enterprise</product_name>
176      <product_variant>Client</product_variant>
177      <major_version>6</major_version>
178      <minor_version>1</minor_version>
179      <windows_systemroot>/Windows</windows_systemroot>
180      <format>installed</format>
181
182 In brief, E<lt>nameE<gt> is the class of operating system (something
183 like C<linux> or C<windows>), E<lt>distroE<gt> is the distribution
184 (eg. C<fedora> but many other distros are recognized) and
185 E<lt>archE<gt> is the guest architecture.  The other fields are fairly
186 self-explanatory, but because these fields are taken directly from the
187 libguestfs inspection API you can find precise information from
188 L<guestfs(3)/INSPECTION>.
189
190 The E<lt>rootE<gt> element is the root filesystem device, but from the
191 point of view of libguestfs (block devices may have completely
192 different names inside the VM itself).
193
194 =head2 E<lt>mountpointsE<gt>
195
196 Un*x-like guests typically have multiple filesystems which are mounted
197 at various mountpoints, and these are described in the
198 E<lt>mountpointsE<gt> element which looks like this:
199
200  <operatingsystems>
201    <operatingsystem>
202      ...
203      <mountpoints>
204        <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
205        <mountpoint dev="/dev/sda1">/boot</mountpoint>
206      </mountpoints>
207
208 As with E<lt>rootE<gt>, devices are from the point of view of
209 libguestfs, and may have completely different names inside the guest.
210 Only mountable filesystems appear in this list, not things like swap
211 devices.
212
213 =head2 E<lt>filesystemsE<gt>
214
215 E<lt>filesystemsE<gt> is like E<lt>mountpointsE<gt> but covers I<all>
216 filesystems belonging to the guest, including swap and empty
217 partitions.  (In the rare case of a multi-boot guest, it covers
218 filesystems belonging to this OS or shared with this OS and other
219 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 E<lt>filesystemE<gt> are the filesystem
234 type, the label, and the UUID.
235
236 =head2 E<lt>applicationsE<gt>
237
238 The related elements E<lt>package_formatE<gt>,
239 E<lt>package_managementE<gt> and E<lt>applicationsE<gt> describe
240 applications installed in the virtual machine.
241
242 E<lt>package_formatE<gt>, if present, describes the packaging
243 system used.  Typical values would be C<rpm> and C<deb>.
244
245 E<lt>package_managementE<gt>, if present, describes the package
246 manager.  Typical values include C<yum>, C<up2date> and C<apt>
247
248 E<lt>applicationsE<gt> lists the packages or applications
249 installed.
250
251  <operatingsystems>
252    <operatingsystem>
253      ...
254      <applications>
255        <application>
256          <name>coreutils</name>
257          <version>8.5</version>
258          <release>1</release>
259        </application>
260
261 The version and release fields may not be available for some types
262 guests.  Other fields are possible, see
263 L<guestfs(3)/guestfs_inspect_list_applications>.
264
265 =head2 E<lt>drive_mappingsE<gt>
266
267 For operating systems like Windows which use drive letters,
268 virt-inspector is able to find out how drive letters map to
269 filesystems.
270
271  <operatingsystems>
272    <operatingsystem>
273      ...
274      <drive_mappings>
275        <drive_mapping name="C">/dev/sda2</drive_mapping>
276        <drive_mapping name="E">/dev/sdb1</drive_mapping>
277      </drive_mappings>
278
279 In the example above, drive C maps to the filesystem on the second
280 partition on the first disk, and drive E maps to the filesystem on the
281 first partition on the second disk.
282
283 Note that this only covers permanent local filesystem mappings, not
284 things like network shares.  Furthermore NTFS volume mount points may
285 not be listed here.
286
287 =head2 INSPECTING INSTALL DISKS, LIVE CDs
288
289 Virt-inspector can detect some operating system installers on
290 install disks, live CDs, bootable USB keys and more.
291
292 In this case the E<lt>formatE<gt> tag will contain C<installer>
293 and other fields may be present to indicate a live CD, network
294 installer, or one part of a multipart CD.  For example:
295
296  <operatingsystems>
297    <operatingsystem>
298      <root>/dev/sda</root>
299      <name>linux</name>
300      <arch>i386</arch>
301      <distro>ubuntu</distro>
302      <product_name>Ubuntu 10.10 &quot;Maverick Meerkat&quot;</product_name>
303      <major_version>10</major_version>
304      <minor_version>10</minor_version>
305      <format>installer</format>
306      <live/>
307
308 =head1 USING XPATH
309
310 You can use the XPath query language, and/or the xpath tool, in order
311 to select parts of the XML.
312
313 For example:
314
315  $ virt-inspector -d Guest | xpath //filesystems
316  Found 1 nodes:
317  -- NODE --
318  <filesystems>
319       <filesystem dev="/dev/vg_f13x64/lv_root">
320         <type>ext4</type>
321  [etc]
322
323  $ virt-inspector -d Guest | \
324      xpath "string(//filesystem[@dev='/dev/sda1']/type)"
325  Query didn't return a nodeset. Value: ext4
326
327 =head1 SHELL QUOTING
328
329 Libvirt guest names can contain arbitrary characters, some of which
330 have meaning to the shell such as C<#> and space.  You may need to
331 quote or escape these characters on the command line.  See the shell
332 manual page L<sh(1)> for details.
333
334 =head1 OLD VERSIONS OF VIRT-INSPECTOR
335
336 Early versions of libguestfs shipped with a different virt-inspector
337 program written in Perl (the current version is written in C).  The
338 XML output of the Perl virt-inspector was different and it could also
339 output in other formats like text.
340
341 The old virt-inspector is no longer supported or shipped with
342 libguestfs.
343
344 To confuse matters further, in Red Hat Enterprise Linux 6 we ship two
345 versions of virt-inspector with different names:
346
347  virt-inspector     Old Perl version.
348  virt-inspector2    New C version.
349
350 =head1 SEE ALSO
351
352 L<guestfs(3)>,
353 L<guestfish(1)>,
354 L<http://www.w3.org/TR/xpath/>,
355 L<http://libguestfs.org/>.
356
357 =head1 AUTHORS
358
359 =over 4
360
361 =item *
362
363 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
364
365 =item *
366
367 Matthew Booth L<mbooth@redhat.com>
368
369 =back
370
371 =head1 COPYRIGHT
372
373 Copyright (C) 2010-2011 Red Hat Inc.
374
375 This program is free software; you can redistribute it and/or modify
376 it under the terms of the GNU General Public License as published by
377 the Free Software Foundation; either version 2 of the License, or
378 (at your option) any later version.
379
380 This program is distributed in the hope that it will be useful,
381 but WITHOUT ANY WARRANTY; without even the implied warranty of
382 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
383 GNU General Public License for more details.
384
385 You should have received a copy of the GNU General Public License
386 along with this program; if not, write to the Free Software
387 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.