fish: Add guestfish --live, guestmount --live options.
[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 =head1 OPTIONS
49
50 =over 4
51
52 =item B<--help>
53
54 Display brief help.
55
56 =item B<-a> file
57
58 =item B<--add> file
59
60 Add I<file> which should be a disk image from a virtual machine.  If
61 the virtual machine has multiple block devices, you must supply all of
62 them with separate I<-a> options.
63
64 The format of the disk image is auto-detected.  To override this and
65 force a particular format use the I<--format=..> option.
66
67 =item B<-c URI>
68
69 =item B<--connect URI>
70
71 If using libvirt, connect to the given I<URI>.  If omitted,
72 then we connect to the default libvirt hypervisor.
73
74 Libvirt is only used if you specify a C<domname> on the
75 command line.  If you specify guest block devices directly (I<-a>),
76 then libvirt is not used at all.
77
78 =item B<-d> guest
79
80 =item B<--domain> guest
81
82 Add all the disks from the named libvirt guest.
83
84 =item B<--echo-keys>
85
86 When prompting for keys and passphrases, virt-inspector normally turns
87 echoing off so you cannot see what you are typing.  If you are not
88 worried about Tempest attacks and there is no one else in the room you
89 can specify this flag to see what you are typing.
90
91 =item B<--format=raw|qcow2|..>
92
93 =item B<--format>
94
95 Specify the format of disk images given on the command line.  If this
96 is omitted then the format is autodetected from the content of the
97 disk image.
98
99 If disk images are requested from libvirt, then this program asks
100 libvirt for this information.  In this case, the value of the format
101 parameter is ignored.
102
103 If working with untrusted raw-format guest disk images, you should
104 ensure the format is always specified.
105
106 =item B<--keys-from-stdin>
107
108 Read key or passphrase parameters from stdin.  The default is
109 to try to read passphrases from the user by opening C</dev/tty>.
110
111 =item B<-v>
112
113 =item B<--verbose>
114
115 Enable verbose messages for debugging.
116
117 =item B<-V>
118
119 =item B<--version>
120
121 Display version number and exit.
122
123 =item B<-x>
124
125 Enable tracing of libguestfs API calls.
126
127 =back
128
129 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
130
131 Previous versions of virt-inspector allowed you to write either:
132
133  virt-inspector disk.img [disk.img ...]
134
135 or
136
137  virt-inspector guestname
138
139 whereas in this version you should use I<-a> or I<-d> respectively
140 to avoid the confusing case where a disk image might have the same
141 name as a guest.
142
143 For compatibility the old style is still supported.
144
145 =head1 XML FORMAT
146
147 The virt-inspector XML is described precisely in a RELAX NG schema
148 which is supplied with libguestfs.  This section is just an overview.
149
150 The top-level element is E<lt>operatingsystemsE<gt>, and it contains
151 one or more E<lt>operatingsystemE<gt> elements.  You would only see
152 more than one E<lt>operatingsystemE<gt> element if the virtual machine
153 is multi-boot, which is vanishingly rare in real world VMs.
154
155 =head2 E<lt>operatingsystemE<gt>
156
157 In the E<lt>operatingsystemE<gt> tag are various optional fields that
158 describe the operating system, its architecture, the descriptive
159 "product name" string, the type of OS and so on, as in this example:
160
161  <operatingsystems>
162    <operatingsystem>
163      <root>/dev/sda2</root>
164      <name>windows</name>
165      <arch>i386</arch>
166      <distro>windows</distro>
167      <product_name>Windows 7 Enterprise</product_name>
168      <major_version>6</major_version>
169      <minor_version>1</minor_version>
170      <windows_systemroot>/Windows</windows_systemroot>
171      <format>installed</format>
172
173 These fields are derived from the libguestfs inspection API, and
174 you can find more details in L<guestfs(3)/INSPECTION>.
175
176 The E<lt>rootE<gt> element is the root filesystem device, but from the
177 point of view of libguestfs (block devices may have completely
178 different names inside the VM itself).
179
180 =head2 E<lt>mountpointsE<gt>
181
182 Un*x-like guests typically have multiple filesystems which are mounted
183 at various mountpoints, and these are described in the
184 E<lt>mountpointsE<gt> element which looks like this:
185
186  <operatingsystems>
187    <operatingsystem>
188      ...
189      <mountpoints>
190        <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
191        <mountpoint dev="/dev/sda1">/boot</mountpoint>
192      </mountpoints>
193
194 As with E<lt>rootE<gt>, devices are from the point of view of
195 libguestfs, and may have completely different names inside the guest.
196 Only mountable filesystems appear in this list, not things like swap
197 devices.
198
199 =head2 E<lt>filesystemsE<gt>
200
201 E<lt>filesystemsE<gt> is like E<lt>mountpointsE<gt> but covers I<all>
202 filesystems belonging to the guest, including swap and empty
203 partitions.  (In the rare case of a multi-boot guest, it covers
204 filesystems belonging to this OS or shared by this OS and other OSes).
205
206 You might see something like this:
207
208  <operatingsystems>
209    <operatingsystem>
210      ...
211      <filesystems>
212        <filesystem dev="/dev/vg_f13x64/lv_root">
213          <type>ext4</type>
214          <label>Fedora-13-x86_64</label>
215          <uuid>e6a4db1e-15c2-477b-ac2a-699181c396aa</uuid>
216        </filesystem>
217
218 The optional elements within E<lt>filesystemE<gt> are the filesystem
219 type, the label, and the UUID.
220
221 =head2 E<lt>applicationsE<gt>
222
223 The related elements E<lt>package_formatE<gt>,
224 E<lt>package_managementE<gt> and E<lt>applicationsE<gt> describe
225 applications installed in the virtual machine.
226
227 E<lt>package_formatE<gt>, if present, describes the packaging
228 system used.  Typical values would be C<rpm> and C<deb>.
229
230 E<lt>package_managementE<gt>, if present, describes the package
231 manager.  Typical values include C<yum>, C<up2date> and C<apt>
232
233 E<lt>applicationsE<gt> lists the packages or applications
234 installed.
235
236  <operatingsystems>
237    <operatingsystem>
238      ...
239      <applications>
240        <application>
241          <name>coreutils</name>
242          <version>8.5</version>
243          <release>1</release>
244        </application>
245
246 The version and release fields may not be available for some types
247 guests.  Other fields are possible, see
248 L<guestfs(3)/guestfs_inspect_list_applications>.
249
250 =head2 INSPECTING INSTALL DISKS, LIVE CDs
251
252 Virt-inspector can detect some operating system installers on
253 install disks, live CDs, bootable USB keys and more.
254
255 In this case the E<lt>formatE<gt> tag will contain C<installer>
256 and other fields may be present to indicate a live CD, network
257 installer, or one part of a multipart CD.  For example:
258
259  <operatingsystems>
260    <operatingsystem>
261      <root>/dev/sda</root>
262      <name>linux</name>
263      <arch>i386</arch>
264      <distro>ubuntu</distro>
265      <product_name>Ubuntu 10.10 &quot;Maverick Meerkat&quot;</product_name>
266      <major_version>10</major_version>
267      <minor_version>10</minor_version>
268      <format>installer</format>
269      <live/>
270
271 =head1 USING XPATH
272
273 You can use the XPath query language, and/or the xpath tool, in order
274 to select parts of the XML.
275
276 For example:
277
278  $ virt-inspector -d Guest | xpath //filesystems
279  Found 1 nodes:
280  -- NODE --
281  <filesystems>
282       <filesystem dev="/dev/vg_f13x64/lv_root">
283         <type>ext4</type>
284  [etc]
285
286  $ virt-inspector -d Guest | \
287      xpath "string(//filesystem[@dev='/dev/sda1']/type)"
288  Query didn't return a nodeset. Value: ext4
289
290 =head1 SHELL QUOTING
291
292 Libvirt guest names can contain arbitrary characters, some of which
293 have meaning to the shell such as C<#> and space.  You may need to
294 quote or escape these characters on the command line.  See the shell
295 manual page L<sh(1)> for details.
296
297 =head1 SEE ALSO
298
299 L<guestfs(3)>,
300 L<guestfish(1)>,
301 L<http://www.w3.org/TR/xpath/>,
302 L<http://libguestfs.org/>.
303
304 =head1 AUTHORS
305
306 =over 4
307
308 =item *
309
310 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
311
312 =item *
313
314 Matthew Booth L<mbooth@redhat.com>
315
316 =back
317
318 =head1 COPYRIGHT
319
320 Copyright (C) 2010 Red Hat Inc.
321
322 This program is free software; you can redistribute it and/or modify
323 it under the terms of the GNU General Public License as published by
324 the Free Software Foundation; either version 2 of the License, or
325 (at your option) any later version.
326
327 This program is distributed in the hope that it will be useful,
328 but WITHOUT ANY WARRANTY; without even the implied warranty of
329 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
330 GNU General Public License for more details.
331
332 You should have received a copy of the GNU General Public License
333 along with this program; if not, write to the Free Software
334 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.