resize: Clarify examples in the man page.
[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.  Domain UUIDs can be
90 used instead of names.
91
92 =item B<--echo-keys>
93
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.
98
99 =item B<--format=raw|qcow2|..>
100
101 =item B<--format>
102
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
105 disk image.
106
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.
110
111 If working with untrusted raw-format guest disk images, you should
112 ensure the format is always specified.
113
114 =item B<--keys-from-stdin>
115
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>.
118
119 =item B<-v>
120
121 =item B<--verbose>
122
123 Enable verbose messages for debugging.
124
125 =item B<-V>
126
127 =item B<--version>
128
129 Display version number and exit.
130
131 =item B<-x>
132
133 Enable tracing of libguestfs API calls.
134
135 =back
136
137 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
138
139 Previous versions of virt-inspector allowed you to write either:
140
141  virt-inspector disk.img [disk.img ...]
142
143 or
144
145  virt-inspector guestname
146
147 whereas in this version you should use I<-a> or I<-d> respectively
148 to avoid the confusing case where a disk image might have the same
149 name as a guest.
150
151 For compatibility the old style is still supported.
152
153 =head1 XML FORMAT
154
155 The virt-inspector XML is described precisely in a RELAX NG schema
156 file C<virt-inspector.rng> which is supplied with libguestfs.  This
157 section is just an overview.
158
159 The top-level element is E<lt>operatingsystemsE<gt>, and it contains
160 one or more E<lt>operatingsystemE<gt> elements.  You would only see
161 more than one E<lt>operatingsystemE<gt> element if the virtual machine
162 is multi-boot, which is vanishingly rare in real world VMs.
163
164 =head2 E<lt>operatingsystemE<gt>
165
166 In the E<lt>operatingsystemE<gt> tag are various optional fields that
167 describe the operating system, its architecture, the descriptive
168 "product name" string, the type of OS and so on, as in this example:
169
170  <operatingsystems>
171    <operatingsystem>
172      <root>/dev/sda2</root>
173      <name>windows</name>
174      <arch>i386</arch>
175      <distro>windows</distro>
176      <product_name>Windows 7 Enterprise</product_name>
177      <product_variant>Client</product_variant>
178      <major_version>6</major_version>
179      <minor_version>1</minor_version>
180      <windows_systemroot>/Windows</windows_systemroot>
181      <format>installed</format>
182
183 In brief, E<lt>nameE<gt> is the class of operating system (something
184 like C<linux> or C<windows>), E<lt>distroE<gt> is the distribution
185 (eg. C<fedora> but many other distros are recognized) and
186 E<lt>archE<gt> is the guest architecture.  The other fields are fairly
187 self-explanatory, but because these fields are taken directly from the
188 libguestfs inspection API you can find precise information from
189 L<guestfs(3)/INSPECTION>.
190
191 The E<lt>rootE<gt> element is the root filesystem device, but from the
192 point of view of libguestfs (block devices may have completely
193 different names inside the VM itself).
194
195 =head2 E<lt>mountpointsE<gt>
196
197 Un*x-like guests typically have multiple filesystems which are mounted
198 at various mountpoints, and these are described in the
199 E<lt>mountpointsE<gt> element which looks like this:
200
201  <operatingsystems>
202    <operatingsystem>
203      ...
204      <mountpoints>
205        <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
206        <mountpoint dev="/dev/sda1">/boot</mountpoint>
207      </mountpoints>
208
209 As with E<lt>rootE<gt>, devices are from the point of view of
210 libguestfs, and may have completely different names inside the guest.
211 Only mountable filesystems appear in this list, not things like swap
212 devices.
213
214 =head2 E<lt>filesystemsE<gt>
215
216 E<lt>filesystemsE<gt> is like E<lt>mountpointsE<gt> but covers I<all>
217 filesystems belonging to the guest, including swap and empty
218 partitions.  (In the rare case of a multi-boot guest, it covers
219 filesystems belonging to this OS or shared with this OS and other
220 OSes).
221
222 You might see something like this:
223
224  <operatingsystems>
225    <operatingsystem>
226      ...
227      <filesystems>
228        <filesystem dev="/dev/vg_f13x64/lv_root">
229          <type>ext4</type>
230          <label>Fedora-13-x86_64</label>
231          <uuid>e6a4db1e-15c2-477b-ac2a-699181c396aa</uuid>
232        </filesystem>
233
234 The optional elements within E<lt>filesystemE<gt> are the filesystem
235 type, the label, and the UUID.
236
237 =head2 E<lt>applicationsE<gt>
238
239 The related elements E<lt>package_formatE<gt>,
240 E<lt>package_managementE<gt> and E<lt>applicationsE<gt> describe
241 applications installed in the virtual machine.
242
243 E<lt>package_formatE<gt>, if present, describes the packaging
244 system used.  Typical values would be C<rpm> and C<deb>.
245
246 E<lt>package_managementE<gt>, if present, describes the package
247 manager.  Typical values include C<yum>, C<up2date> and C<apt>
248
249 E<lt>applicationsE<gt> lists the packages or applications
250 installed.
251
252  <operatingsystems>
253    <operatingsystem>
254      ...
255      <applications>
256        <application>
257          <name>coreutils</name>
258          <version>8.5</version>
259          <release>1</release>
260        </application>
261
262 The version and release fields may not be available for some types
263 guests.  Other fields are possible, see
264 L<guestfs(3)/guestfs_inspect_list_applications>.
265
266 =head2 E<lt>drive_mappingsE<gt>
267
268 For operating systems like Windows which use drive letters,
269 virt-inspector is able to find out how drive letters map to
270 filesystems.
271
272  <operatingsystems>
273    <operatingsystem>
274      ...
275      <drive_mappings>
276        <drive_mapping name="C">/dev/sda2</drive_mapping>
277        <drive_mapping name="E">/dev/sdb1</drive_mapping>
278      </drive_mappings>
279
280 In the example above, drive C maps to the filesystem on the second
281 partition on the first disk, and drive E maps to the filesystem on the
282 first partition on the second disk.
283
284 Note that this only covers permanent local filesystem mappings, not
285 things like network shares.  Furthermore NTFS volume mount points may
286 not be listed here.
287
288 =head2 E<lt>iconE<gt>
289
290 Virt-inspector is sometimes able to extract an icon or logo for the
291 guest.  The icon is returned as base64-encoded PNG data.  Note that
292 the icon can be very large and high quality.
293
294  <operatingsystems>
295    <operatingsystem>
296      ...
297      <icon>
298        iVBORw0KGgoAAAANSUhEUgAAAGAAAABg[.......]
299        [... many lines of base64 data ...]
300      </icon>
301
302 To display the icon, you have to extract it and convert the base64
303 data back to a binary file.  Use an XPath query or simply an editor to
304 extract the data, then use the coreutils L<base64(1)> program to do
305 the conversion back to a PNG file:
306
307  base64 -i -d < icon.data > icon.png
308
309 =head2 INSPECTING INSTALL DISKS, LIVE CDs
310
311 Virt-inspector can detect some operating system installers on
312 install disks, live CDs, bootable USB keys and more.
313
314 In this case the E<lt>formatE<gt> tag will contain C<installer>
315 and other fields may be present to indicate a live CD, network
316 installer, or one part of a multipart CD.  For example:
317
318  <operatingsystems>
319    <operatingsystem>
320      <root>/dev/sda</root>
321      <name>linux</name>
322      <arch>i386</arch>
323      <distro>ubuntu</distro>
324      <product_name>Ubuntu 10.10 &quot;Maverick Meerkat&quot;</product_name>
325      <major_version>10</major_version>
326      <minor_version>10</minor_version>
327      <format>installer</format>
328      <live/>
329
330 =head1 USING XPATH
331
332 You can use the XPath query language, and/or the xpath tool, in order
333 to select parts of the XML.
334
335 For example:
336
337  $ virt-inspector -d Guest | xpath //filesystems
338  Found 1 nodes:
339  -- NODE --
340  <filesystems>
341       <filesystem dev="/dev/vg_f13x64/lv_root">
342         <type>ext4</type>
343  [etc]
344
345  $ virt-inspector -d Guest | \
346      xpath "string(//filesystem[@dev='/dev/sda1']/type)"
347  Query didn't return a nodeset. Value: ext4
348
349 =head1 SHELL QUOTING
350
351 Libvirt guest names can contain arbitrary characters, some of which
352 have meaning to the shell such as C<#> and space.  You may need to
353 quote or escape these characters on the command line.  See the shell
354 manual page L<sh(1)> for details.
355
356 =head1 OLD VERSIONS OF VIRT-INSPECTOR
357
358 Early versions of libguestfs shipped with a different virt-inspector
359 program written in Perl (the current version is written in C).  The
360 XML output of the Perl virt-inspector was different and it could also
361 output in other formats like text.
362
363 The old virt-inspector is no longer supported or shipped with
364 libguestfs.
365
366 To confuse matters further, in Red Hat Enterprise Linux 6 we ship two
367 versions of virt-inspector with different names:
368
369  virt-inspector     Old Perl version.
370  virt-inspector2    New C version.
371
372 =head1 SEE ALSO
373
374 L<guestfs(3)>,
375 L<guestfish(1)>,
376 L<http://www.w3.org/TR/xpath/>,
377 L<base64(1)>,
378 L<http://libguestfs.org/>.
379
380 =head1 AUTHORS
381
382 =over 4
383
384 =item *
385
386 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
387
388 =item *
389
390 Matthew Booth L<mbooth@redhat.com>
391
392 =back
393
394 =head1 COPYRIGHT
395
396 Copyright (C) 2010-2011 Red Hat Inc.
397
398 This program is free software; you can redistribute it and/or modify
399 it under the terms of the GNU General Public License as published by
400 the Free Software Foundation; either version 2 of the License, or
401 (at your option) any later version.
402
403 This program is distributed in the hope that it will be useful,
404 but WITHOUT ANY WARRANTY; without even the implied warranty of
405 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
406 GNU General Public License for more details.
407
408 You should have received a copy of the GNU General Public License
409 along with this program; if not, write to the Free Software
410 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.