Extracted kernel structures for device addressing in ifconfig.
[virt-mem.git] / virt-mem.1
1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
52 .ie \n(.g .ds Aq \(aq
53 .el       .ds Aq '
54 .\"
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD.  Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
59 .ie \nF \{\
60 .    de IX
61 .    tm Index:\\$1\t\\n%\t"\\$2"
62 ..
63 .    nr % 0
64 .    rr F
65 .\}
66 .el \{\
67 .    de IX
68 ..
69 .\}
70 .\"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
73 .    \" fudge factors for nroff and troff
74 .if n \{\
75 .    ds #H 0
76 .    ds #V .8m
77 .    ds #F .3m
78 .    ds #[ \f1
79 .    ds #] \fP
80 .\}
81 .if t \{\
82 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83 .    ds #V .6m
84 .    ds #F 0
85 .    ds #[ \&
86 .    ds #] \&
87 .\}
88 .    \" simple accents for nroff and troff
89 .if n \{\
90 .    ds ' \&
91 .    ds ` \&
92 .    ds ^ \&
93 .    ds , \&
94 .    ds ~ ~
95 .    ds /
96 .\}
97 .if t \{\
98 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
104 .\}
105 .    \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 .    \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 .    \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
120 \{\
121 .    ds : e
122 .    ds 8 ss
123 .    ds o a
124 .    ds d- d\h'-1'\(ga
125 .    ds D- D\h'-1'\(hy
126 .    ds th \o'bp'
127 .    ds Th \o'LP'
128 .    ds ae ae
129 .    ds Ae AE
130 .\}
131 .rm #[ #] #H #V #F C
132 .\" ========================================================================
133 .\"
134 .IX Title "VIRT-MEM 1"
135 .TH VIRT-MEM 1 "2008-08-11" "virt-mem-0.2.9" "Virtualization Support"
136 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
138 .if n .ad l
139 .nh
140 .SH "NAME"
141 virt\-uname \- system information for virtual machines
142 .PP
143 virt\-dmesg \- print kernel messages for virtual machines
144 .PP
145 virt\-ps \- list processes for virtual machines
146 .PP
147 virt\-mem \- tool with additional information output
148 .SH "SUMMARY"
149 .IX Header "SUMMARY"
150 virt-uname [\-options] [domains...]
151 .PP
152 virt-dmesg [\-options] [domains...]
153 .PP
154 virt-ps [\-options] [domains...]
155 .PP
156 virt-mem uname [...]
157 .PP
158 virt-mem dmesg [...]
159 .PP
160 virt-mem ps [...]
161 .PP
162 virt-mem [\-options]
163 .SH "DESCRIPTION"
164 .IX Header "DESCRIPTION"
165 These virtualization tools allow you to inspect the status of virtual
166 machines running Linux.
167 .PP
168 These tools are designed to work like familiar Linux/Unix command line
169 tools.
170 .PP
171 These tools all use libvirt so are capable of showing information
172 across a variety of different virtualization systems.
173 .PP
174 The virt-mem tools do not work on domains which are not active
175 (running or paused).  eg. They do not work on shut down domains.
176 However they can (usually) be used on domains which are active but
177 hanging or unresponsive.  You also have the option of capturing a
178 memory image of a domain for post-mortem analysis, allowing you to
179 quickly reboot a failed domain and analyze it later at your leisure.
180 .SH "COMMON OPTIONS"
181 .IX Header "COMMON OPTIONS"
182 Each command obeys a common set of options.  The general form is:
183 .PP
184 virt\-\fIprogram\fR [\-options] [domains...]
185 .PP
186 where \fIprogram\fR is a subtool such as \f(CW\*(C`uname\*(C'\fR, \f(CW\*(C`dmesg\*(C'\fR or \f(CW\*(C`ps\*(C'\fR, and
187 \&\fIdomains\fR is a list of guest names to act on.  If no domains are
188 specified then we act on all active domains by default.
189 .PP
190 A \fIdomain\fR may be specified either by its name, by its \s-1ID\s0 or by its
191 \&\s-1UUID\s0.  Use \fIvirsh list\fR to get a list of active domain names and IDs.
192 .PP
193 Equivalently you can use the \f(CW\*(C`virt\-mem\*(C'\fR meta-tool with subcommands,
194 as in:
195 .PP
196 virt-mem \fIprogram\fR [...]
197 .PP
198 The \f(CW\*(C`virt\-mem\*(C'\fR program offers additional features, such as the
199 ability to capture \s-1VM\s0 images for post-mortem analysis (see below).
200 .IP "\fB\-c uri\fR, \fB\-\-connect uri\fR" 4
201 .IX Item "-c uri, --connect uri"
202 Connect to libvirt \s-1URI\s0.  The default is to connect to the default
203 libvirt \s-1URI\s0, normally Xen.
204 .IP "\fB\-\-csv\fR" 4
205 .IX Item "--csv"
206 Print the results in \s-1CSV\s0 format, suitable for importing into a
207 spreadsheet or database.
208 .Sp
209 This option is only supported if virt-mem was built with \s-1CSV\s0 support.
210 .IP "\fB\-\-debug\fR" 4
211 .IX Item "--debug"
212 Emit debugging information on stderr.  Please supply this if you
213 report a bug.
214 .IP "\fB\-\-help\fR" 4
215 .IX Item "--help"
216 Display usage summary.
217 .IP "\fB\-\-list\-kernels\fR" 4
218 .IX Item "--list-kernels"
219 List which guest kernel versions are known/supported, then exit.
220 .IP "\fB\-t memoryimage\fR" 4
221 .IX Item "-t memoryimage"
222 Post-mortem analysis mode.
223 .Sp
224 Instead of checking libvirt for domain information, this runs the tool
225 directly on the memory image supplied.  You may specify the \fB\-t\fR
226 option multiple times.  Use the \f(CW\*(C`virt\-mem capture\*(C'\fR command to capture
227 images (see below).
228 .Sp
229 See also the section \*(L"\s-1MEMORY\s0 \s-1IMAGES\s0\*(R" below.
230 .IP "\fB\-\-version\fR" 4
231 .IX Item "--version"
232 Display version and exit.
233 .IP "\fB\-E auto|littleendian|bigendian\fR" 4
234 .IX Item "-E auto|littleendian|bigendian"
235 .PD 0
236 .IP "\fB\-T auto|i386|x86\-64|\f(BIaddress\fB|\f(BIaddress,min,max\fB\fR" 4
237 .IX Item "-T auto|i386|x86-64|address|address,min,max"
238 .IP "\fB\-W auto|32|64\fR" 4
239 .IX Item "-W auto|32|64"
240 .PD
241 These options force the endianness, text address, and word size for
242 the subsequent domains listed on the command line (or if no domains
243 are listed, then for all domains).
244 .Sp
245 These default to \fIauto\fR which tries to do automatic detection (using
246 libvirt, or details from the memory images themselves).  You only need
247 to use these options if virt-mem tools get the automatic detection
248 wrong.
249 .Sp
250 Endianness (\fI\-E\fR) sets the memory endianness, for data, pointers and
251 so on.  \fI\-E littleendian\fR is the endianness used on Intel i386,
252 x86\-64 and (usually) \s-1IA64\s0.  \fI\-E bigendian\fR is the endianness used on
253 many \s-1RISC\s0 chips such as \s-1SPARC\s0 and PowerPC.
254 .Sp
255 Text address (\fI\-T\fR) sets the base address and optionally min and max
256 addresses of the kernel image.  \fI\-T i386\fR means to try some common
257 addresses for i386\-based kernels.  \fI\-T x86\-64\fR means to try some
258 common addresses for x86\-64\-based kernels.
259 .Sp
260 \&\fI\-T address\fR sets the kernel base address specifically (\fI0x\fR prefix
261 is used to specify hex addresses).  \fI\-T address,min,max\fR sets the
262 kernel base address, minimum address and maximum address.
263 .Sp
264 Word size (\fI\-W\fR) sets the word size, 32 or 64 bits.
265 .IP "\fB\-A auto|i386|x86\-64|...\fR" 4
266 .IX Item "-A auto|i386|x86-64|..."
267 This option sets the architecture to one of a collection of known
268 architectures.  It is equivalent to setting endianness and wordsize in
269 one go, but not text address.
270 .SH "virt-dmesg"
271 .IX Header "virt-dmesg"
272 This prints the latest kernel messages from the virtual machine, as if
273 you were logged into the machine and used \fIdmesg\fR\|(1).
274 .SH "virt-uname"
275 .IX Header "virt-uname"
276 This prints the contents of the system \f(CW\*(C`utsname\*(C'\fR structure, similar
277 to what is printed by the \fIuname\fR\|(1) command.
278 .SH "virt-mem"
279 .IX Header "virt-mem"
280 \&\f(CW\*(C`virt\-mem\*(C'\fR is a meta-tool which allows you to run all the commands
281 above, and provides some extra features.
282 .PP
283 Instead of the preceeding commands such as \f(CW\*(C`virt\-dmesg\*(C'\fR you can
284 write:
285 .PP
286 .Vb 1
287 \& virt\-mem dmesg [...]
288 .Ve
289 .PP
290 Options and other command line arguments work the same.
291 .PP
292 Additional \f(CW\*(C`virt\-mem\*(C'\fR subcommands are listed below.
293 .Sh "virt-mem capture \-o memoryimage [\-options] [domains...]"
294 .IX Subsection "virt-mem capture -o memoryimage [-options] [domains...]"
295 Capture the memory image of a virtual machine for later post-mortem
296 analysis.  Use the \fI\-t memoryimage\fR option for any other virt-mem
297 tool to analyze the memory image later.
298 .PP
299 The \fI\-o memoryimage\fR option is required, and is used to name the
300 output file.  If a single guest is captured, then the output is saved
301 in the \fImemoryimage\fR file.  However, if multiple guests are captured,
302 then their images are saved in \fImemoryimage.ID\fR where \fI\s-1ID\s0\fR is
303 replaced with the domain \s-1ID\s0.
304 .PP
305 See also the section \*(L"\s-1MEMORY\s0 \s-1IMAGES\s0\*(R" below.
306 .SH "EXAMPLES"
307 .IX Header "EXAMPLES"
308 .Vb 3
309 \& # virt\-uname
310 \& f9x32kvm: Linux localhost.localdomain 2.6.24\-0.155.rc7.git6.fc9 #1
311 \& SMP Tue Jan 15 17:52:31 EST 2008 i686 (none)
312 \&
313 \& # virt\-dmesg f9x32kvm | tail
314 \& <6>Bluetooth: Core ver 2.11
315 \& <6>NET: Registered protocol family 31
316 \& <6>Bluetooth: HCI device and connection manager initialized
317 \& <6>Bluetooth: HCI socket layer initialized
318 \& <6>Bluetooth: L2CAP ver 2.9
319 \& <6>Bluetooth: L2CAP socket layer initialized
320 \& <6>Bluetooth: RFCOMM socket layer initialized
321 \& <6>Bluetooth: RFCOMM TTY layer initialized
322 \& <6>Bluetooth: RFCOMM ver 1.8
323 \& <7>eth0: no IPv6 routers present
324 .Ve
325 .SH "MEMORY IMAGES"
326 .IX Header "MEMORY IMAGES"
327 All the tools can read dumped kernel images, using the common
328 \&\fI\-t memoryimage\fR option.  In addition you can capture memory
329 images from domains for post-mortem analysis using the
330 \&\f(CW\*(C`virt\-mem capture\*(C'\fR command (see above).
331 .PP
332 The memory images which are saved by \f(CW\*(C`virt\-mem capture\*(C'\fR contain a
333 header and some additional information about the kernel image, such as
334 architecture, original text address, and so forth.  Thus these images
335 can be reanalysed just using the \fI\-t memoryimage\fR option.
336 .PP
337 We also support analyzing raw kernel dumps, eg. produced using the
338 \&\fIqemu\fR\|(1) monitor's \f(CW\*(C`memsave\*(C'\fR command.  In this case however you
339 usually need to specify the original architecture, text address and
340 perhaps other details using the \fI\-A\fR, \fI\-T\fR and other command line
341 parameters.
342 .SH "SHORTCOMINGS"
343 .IX Header "SHORTCOMINGS"
344 The virt-mem tools spy on the guest's memory image.  There are some
345 shortcomings to this, described here.
346 .IP "\(bu" 4
347 Only works on specific, tested releases of Linux kernels.  Support
348 for arbitrary Linux kernel versions may be patchy because of changes
349 in the internal structures used.  Support for non-Linux kernels is
350 currently non-existent, and probably impossible for Windows because of
351 lack of an acceptable source license.
352 .IP "\(bu" 4
353 Heuristics are used which may mean in the worst case that the
354 output is wrong.
355 .IP "\(bu" 4
356 Structures which are frequently modified may cause errors.  This
357 could be a problem if, for example, the process table in the guest is
358 being rapidly updated.
359 .IP "\(bu" 4
360 We have to scan memory to find kernel symbols, etc., which can be
361 quite slow.  Optimizing the memory scanner would help, and caching the
362 base address of the symbol table(s) would make it dramatically faster.
363 .SH "SECURITY"
364 .IX Header "SECURITY"
365 The current code tries hard to be secure against malicious guests, for
366 example guests which set up malicious kernel memory.
367 .SH "SEE ALSO"
368 .IX Header "SEE ALSO"
369 \&\fIuname\fR\|(1),
370 \&\fIdmesg\fR\|(1),
371 \&\fIvirsh\fR\|(1),
372 \&\fIvirt\-top\fR\|(1),
373 \&\fIvirt\-df\fR\|(1),
374 \&\fIxm\fR\|(1),
375 \&\fIqemu\fR\|(1),
376 <http://www.libvirt.org/ocaml/>,
377 <http://www.libvirt.org/>,
378 <http://et.redhat.com/~rjones/>,
379 <http://caml.inria.fr/>
380 .SH "AUTHORS"
381 .IX Header "AUTHORS"
382 Richard W.M. Jones <rjones @ redhat . com>
383 .SH "COPYRIGHT"
384 .IX Header "COPYRIGHT"
385 (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones
386 http://libvirt.org/
387 .PP
388 This program is free software; you can redistribute it and/or modify
389 it under the terms of the \s-1GNU\s0 General Public License as published by
390 the Free Software Foundation; either version 2 of the License, or
391 (at your option) any later version.
392 .PP
393 This program is distributed in the hope that it will be useful,
394 but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
395 \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
396 \&\s-1GNU\s0 General Public License for more details.
397 .PP
398 You should have received a copy of the \s-1GNU\s0 General Public License
399 along with this program; if not, write to the Free Software
400 Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
401 .SH "REPORTING BUGS"
402 .IX Header "REPORTING BUGS"
403 Bugs can be viewed on the Red Hat Bugzilla page:
404 <https://bugzilla.redhat.com/>.
405 .PP
406 If you find a bug in virt-mem, please follow these steps to report it:
407 .IP "1. Check for existing bug reports" 4
408 .IX Item "1. Check for existing bug reports"
409 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
410 Someone may already have reported the same bug, and they may even
411 have fixed it.
412 .IP "2. Capture debug and error messages" 4
413 .IX Item "2. Capture debug and error messages"
414 Run
415 .Sp
416 virt\-\fIprogram\fR \-\-debug > virt\-mem.log 2>&1
417 .Sp
418 and keep \fIvirt\-mem.log\fR.  It contains error messages which you should
419 submit with your bug report.
420 .IP "3. Get version of virt-mem and version of libvirt." 4
421 .IX Item "3. Get version of virt-mem and version of libvirt."
422 Run
423 .Sp
424 virt\-\fIprogram\fR \-\-version
425 .IP "4. Submit a bug report." 4
426 .IX Item "4. Submit a bug report."
427 Go to <https://bugzilla.redhat.com/> and enter a new bug.
428 Please describe the problem in as much detail as possible.
429 .Sp
430 Remember to include the version numbers (step 3) and the debug
431 messages file (step 2).
432 .IP "5. Assign the bug to rjones @ redhat.com" 4
433 .IX Item "5. Assign the bug to rjones @ redhat.com"
434 Assign or reassign the bug to \fBrjones @ redhat.com\fR (without the
435 spaces).  You can also send me an email with the bug number if you
436 want a faster response.