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-07-24" "virt-mem-0.2.7" "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\-mem \- tool with additional information output
 146 .SH "SUMMARY"
 147 .IX Header "SUMMARY"
 148 virt-uname [\-options] [domains...]
 149 .PP
 150 virt-dmesg [\-options] [domains...]
 151 .PP
 152 virt-mem uname [...]
 153 .PP
 154 virt-mem dmesg [...]
 155 .PP
 156 virt-mem [\-options]
 157 .SH "DESCRIPTION"
 158 .IX Header "DESCRIPTION"
 159 These virtualization tools allow you to inspect the status of virtual
 160 machines running Linux.
 161 .PP
 162 These tools are designed to work like familiar Linux/Unix command line
 163 tools.
 164 .PP
 165 These tools all use libvirt so are capable of showing information
 166 across a variety of different virtualization systems.
 167 .PP
 168 The virt-mem tools do not work on domains which are not active
 169 (running or paused).  eg. They do not work on shut down domains.
 170 However they can (usually) be used on domains which are active but
 171 hanging or unresponsive.  You also have the option of capturing a
 172 memory image of a domain for post-mortem analysis, allowing you to
 173 quickly reboot a failed domain and analyze it later at your leisure.
 174 .SH "COMMON OPTIONS"
 175 .IX Header "COMMON OPTIONS"
 176 Each command obeys a common set of options.  The general form is:
 177 .PP
 178 virt\-\fIprogram\fR [\-options] [domains...]
 179 .PP
 180 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
 181 \&\fIdomains\fR is a list of guest names to act on.  If no domains are
 182 specified then we act on all active domains by default.
 183 .PP
 184 A \fIdomain\fR may be specified either by its name, by its \s-1ID\s0 or by its
 185 \&\s-1UUID\s0.  Use \fIvirsh list\fR to get a list of active domain names and IDs.
 186 .PP
 187 Equivalently you can use the \f(CW\*(C`virt\-mem\*(C'\fR meta-tool with subcommands,
 188 as in:
 189 .PP
 190 virt-mem \fIprogram\fR [...]
 191 .PP
 192 The \f(CW\*(C`virt\-mem\*(C'\fR program offers additional features, such as the
 193 ability to capture \s-1VM\s0 images for post-mortem analysis (see below).
 194 .IP "\fB\-c uri\fR, \fB\-\-connect uri\fR" 4
 195 .IX Item "-c uri, --connect uri"
 196 Connect to libvirt \s-1URI\s0.  The default is to connect to the default
 197 libvirt \s-1URI\s0, normally Xen.
 198 .IP "\fB\-\-csv\fR" 4
 199 .IX Item "--csv"
 200 Print the results in \s-1CSV\s0 format, suitable for importing into a
 201 spreadsheet or database.
 202 .Sp
 203 This option is only supported if virt-mem was built with \s-1CSV\s0 support.
 204 .IP "\fB\-\-debug\fR" 4
 205 .IX Item "--debug"
 206 Emit debugging information on stderr.  Please supply this if you
 207 report a bug.
 208 .IP "\fB\-\-help\fR" 4
 209 .IX Item "--help"
 210 Display usage summary.
 211 .IP "\fB\-t memoryimage\fR" 4
 212 .IX Item "-t memoryimage"
 213 Post-mortem analysis mode.
 214 .Sp
 215 Instead of checking libvirt for domain information, this runs the tool
 216 directly on the memory image supplied.  You may specify the \fB\-t\fR
 217 option multiple times.  Use the \f(CW\*(C`virt\-mem capture\*(C'\fR command to capture
 218 images (see below).
 219 .Sp
 220 See also the section \*(L"\s-1MEMORY\s0 \s-1IMAGES\s0\*(R" below.
 221 .IP "\fB\-\-version\fR" 4
 222 .IX Item "--version"
 223 Display version and exit.
 224 .IP "\fB\-E auto|littleendian|bigendian\fR" 4
 225 .IX Item "-E auto|littleendian|bigendian"
 226 .PD 0
 227 .IP "\fB\-T auto|i386|x86\-64|\f(BIaddress\fB|\f(BIaddress,min,max\fB\fR" 4
 228 .IX Item "-T auto|i386|x86-64|address|address,min,max"
 229 .IP "\fB\-W auto|32|64\fR" 4
 230 .IX Item "-W auto|32|64"
 231 .PD
 232 These options force the endianness, text address, and word size for
 233 the subsequent domains listed on the command line (or if no domains
 234 are listed, then for all domains).
 235 .Sp
 236 These default to \fIauto\fR which tries to do automatic detection (using
 237 libvirt, or details from the memory images themselves).  You only need
 238 to use these options if virt-mem tools get the automatic detection
 239 wrong.
 240 .Sp
 241 Endianness (\fI\-E\fR) sets the memory endianness, for data, pointers and
 242 so on.  \fI\-E littleendian\fR is the endianness used on Intel i386,
 243 x86\-64 and (usually) \s-1IA64\s0.  \fI\-E bigendian\fR is the endianness used on
 244 many \s-1RISC\s0 chips such as \s-1SPARC\s0 and PowerPC.
 245 .Sp
 246 Text address (\fI\-T\fR) sets the base address and optionally min and max
 247 addresses of the kernel image.  \fI\-T i386\fR means to try some common
 248 addresses for i386\-based kernels.  \fI\-T x86\-64\fR means to try some
 249 common addresses for x86\-64\-based kernels.
 250 .Sp
 251 \&\fI\-T address\fR sets the kernel base address specifically (\fI0x\fR prefix
 252 is used to specify hex addresses).  \fI\-T address,min,max\fR sets the
 253 kernel base address, minimum address and maximum address.
 254 .Sp
 255 Word size (\fI\-W\fR) sets the word size, 32 or 64 bits.
 256 .IP "\fB\-A auto|i386|x86\-64|...\fR" 4
 257 .IX Item "-A auto|i386|x86-64|..."
 258 This option sets the architecture to one of a collection of known
 259 architectures.  It is equivalent to setting endianness and wordsize in
 260 one go, but not text address.
 261 .SH "virt-dmesg"
 262 .IX Header "virt-dmesg"
 263 This prints the latest kernel messages from the virtual machine, as if
 264 you were logged into the machine and used \fIdmesg\fR\|(1).
 265 .SH "virt-uname"
 266 .IX Header "virt-uname"
 267 This prints the contents of the system \f(CW\*(C`utsname\*(C'\fR structure, similar
 268 to what is printed by the \fIuname\fR\|(1) command.
 269 .SH "virt-mem"
 270 .IX Header "virt-mem"
 271 \&\f(CW\*(C`virt\-mem\*(C'\fR is a meta-tool which allows you to run all the commands
 272 above, and provides some extra features.
 273 .PP
 274 Instead of the preceeding commands such as \f(CW\*(C`virt\-dmesg\*(C'\fR you can
 275 write:
 276 .PP
 277 .Vb 1
 278 \& virt\-mem dmesg [...]
 279 .Ve
 280 .PP
 281 Options and other command line arguments work the same.
 282 .PP
 283 Additional \f(CW\*(C`virt\-mem\*(C'\fR subcommands are listed below.
 284 .Sh "virt-mem capture \-o memoryimage [\-options] [domains...]"
 285 .IX Subsection "virt-mem capture -o memoryimage [-options] [domains...]"
 286 Capture the memory image of a virtual machine for later post-mortem
 287 analysis.  Use the \fI\-t memoryimage\fR option for any other virt-mem
 288 tool to analyze the memory image later.
 289 .PP
 290 The \fI\-o memoryimage\fR option is required, and is used to name the
 291 output file.  If a single guest is captured, then the output is saved
 292 in the \fImemoryimage\fR file.  However, if multiple guests are captured,
 293 then their images are saved in \fImemoryimage.ID\fR where \fI\s-1ID\s0\fR is
 294 replaced with the domain \s-1ID\s0.
 295 .PP
 296 See also the section \*(L"\s-1MEMORY\s0 \s-1IMAGES\s0\*(R" below.
 297 .SH "EXAMPLES"
 298 .IX Header "EXAMPLES"
 299 .Vb 3
 300 \& # virt\-uname
 301 \& f9x32kvm: Linux localhost.localdomain 2.6.24\-0.155.rc7.git6.fc9 #1
 302 \& SMP Tue Jan 15 17:52:31 EST 2008 i686 (none)
 303 \&
 304 \& # virt\-dmesg f9x32kvm | tail
 305 \& <6>Bluetooth: Core ver 2.11
 306 \& <6>NET: Registered protocol family 31
 307 \& <6>Bluetooth: HCI device and connection manager initialized
 308 \& <6>Bluetooth: HCI socket layer initialized
 309 \& <6>Bluetooth: L2CAP ver 2.9
 310 \& <6>Bluetooth: L2CAP socket layer initialized
 311 \& <6>Bluetooth: RFCOMM socket layer initialized
 312 \& <6>Bluetooth: RFCOMM TTY layer initialized
 313 \& <6>Bluetooth: RFCOMM ver 1.8
 314 \& <7>eth0: no IPv6 routers present
 315 .Ve
 316 .SH "MEMORY IMAGES"
 317 .IX Header "MEMORY IMAGES"
 318 All the tools can read dumped kernel images, using the common
 319 \&\fI\-t memoryimage\fR option.  In addition you can capture memory
 320 images from domains for post-mortem analysis using the
 321 \&\f(CW\*(C`virt\-mem capture\*(C'\fR command (see above).
 322 .PP
 323 The memory images which are saved by \f(CW\*(C`virt\-mem capture\*(C'\fR contain a
 324 header and some additional information about the kernel image, such as
 325 architecture, original text address, and so forth.  Thus these images
 326 can be reanalysed just using the \fI\-t memoryimage\fR option.
 327 .PP
 328 We also support analyzing raw kernel dumps, eg. produced using the
 329 \&\fIqemu\fR\|(1) monitor's \f(CW\*(C`memsave\*(C'\fR command.  In this case however you
 330 usually need to specify the original architecture, text address and
 331 perhaps other details using the \fI\-A\fR, \fI\-T\fR and other command line
 332 parameters.
 333 .SH "SHORTCOMINGS"
 334 .IX Header "SHORTCOMINGS"
 335 The virt-mem tools spy on the guest's memory image.  There are some
 336 shortcomings to this, described here.
 337 .IP "\(bu" 4
 338 Only works on specific, tested releases of Linux kernels.  Support
 339 for arbitrary Linux kernel versions may be patchy because of changes
 340 in the internal structures used.  Support for non-Linux kernels is
 341 currently non-existent, and probably impossible for Windows because of
 342 lack of an acceptable source license.
 343 .IP "\(bu" 4
 344 Heuristics are used which may mean in the worst case that the
 345 output is wrong.
 346 .IP "\(bu" 4
 347 Structures which are frequently modified may cause errors.  This
 348 could be a problem if, for example, the process table in the guest is
 349 being rapidly updated.
 350 .IP "\(bu" 4
 351 We have to scan memory to find kernel symbols, etc., which can be
 352 quite slow.  Optimizing the memory scanner would help, and caching the
 353 base address of the symbol table(s) would make it dramatically faster.
 354 .SH "SECURITY"
 355 .IX Header "SECURITY"
 356 The current code tries hard to be secure against malicious guests, for
 357 example guests which set up malicious kernel memory.
 358 .SH "SEE ALSO"
 359 .IX Header "SEE ALSO"
 360 \&\fIuname\fR\|(1),
 361 \&\fIdmesg\fR\|(1),
 362 \&\fIvirsh\fR\|(1),
 363 \&\fIvirt\-top\fR\|(1),
 364 \&\fIvirt\-df\fR\|(1),
 365 \&\fIxm\fR\|(1),
 366 \&\fIqemu\fR\|(1),
 367 <http://www.libvirt.org/ocaml/>,
 368 <http://www.libvirt.org/>,
 369 <http://et.redhat.com/~rjones/>,
 370 <http://caml.inria.fr/>
 371 .SH "AUTHORS"
 372 .IX Header "AUTHORS"
 373 Richard W.M. Jones <rjones @ redhat . com>
 374 .SH "COPYRIGHT"
 375 .IX Header "COPYRIGHT"
 376 (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones
 377 http://libvirt.org/
 378 .PP
 379 This program is free software; you can redistribute it and/or modify
 380 it under the terms of the \s-1GNU\s0 General Public License as published by
 381 the Free Software Foundation; either version 2 of the License, or
 382 (at your option) any later version.
 383 .PP
 384 This program is distributed in the hope that it will be useful,
 385 but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
 386 \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
 387 \&\s-1GNU\s0 General Public License for more details.
 388 .PP
 389 You should have received a copy of the \s-1GNU\s0 General Public License
 390 along with this program; if not, write to the Free Software
 391 Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
 392 .SH "REPORTING BUGS"
 393 .IX Header "REPORTING BUGS"
 394 Bugs can be viewed on the Red Hat Bugzilla page:
 395 <https://bugzilla.redhat.com/>.
 396 .PP
 397 If you find a bug in virt-mem, please follow these steps to report it:
 398 .IP "1. Check for existing bug reports" 4
 399 .IX Item "1. Check for existing bug reports"
 400 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
 401 Someone may already have reported the same bug, and they may even
 402 have fixed it.
 403 .IP "2. Capture debug and error messages" 4
 404 .IX Item "2. Capture debug and error messages"
 405 Run
 406 .Sp
 407 virt\-\fIprogram\fR \-\-debug > virt\-mem.log 2>&1
 408 .Sp
 409 and keep \fIvirt\-mem.log\fR.  It contains error messages which you should
 410 submit with your bug report.
 411 .IP "3. Get version of virt-mem and version of libvirt." 4
 412 .IX Item "3. Get version of virt-mem and version of libvirt."
 413 Run
 414 .Sp
 415 virt\-\fIprogram\fR \-\-version
 416 .IP "4. Submit a bug report." 4
 417 .IX Item "4. Submit a bug report."
 418 Go to <https://bugzilla.redhat.com/> and enter a new bug.
 419 Please describe the problem in as much detail as possible.
 420 .Sp
 421 Remember to include the version numbers (step 3) and the debug
 422 messages file (step 2).
 423 .IP "5. Assign the bug to rjones @ redhat.com" 4
 424 .IX Item "5. Assign the bug to rjones @ redhat.com"
 425 Assign or reassign the bug to \fBrjones @ redhat.com\fR (without the
 426 spaces).  You can also send me an email with the bug number if you
 427 want a faster response.