virt-mem.pod

   1 =head1 NAME
   2
   3 virt-uname - system information for virtual machines
   4
   5 virt-dmesg - print kernel messages for virtual machines
   6
   7 virt-mem - tool with additional information output
   8
   9 =head1 SUMMARY
  10
  11 virt-uname [-options] [domains...]
  12
  13 virt-dmesg [-options] [domains...]
  14
  15 virt-mem uname [...]
  16
  17 virt-mem dmesg [...]
  18
  19 virt-mem [-options]
  20
  21 =head1 DESCRIPTION
  22
  23 These virtualization tools allow you to inspect the status of virtual
  24 machines running Linux.
  25
  26 These tools are designed to work like familiar Linux/Unix command line
  27 tools.
  28
  29 These tools all use libvirt so are capable of showing information
  30 across a variety of different virtualization systems.
  31
  32 The virt-mem tools do not work on domains which are not active
  33 (running or paused).  eg. They do not work on shut down domains.
  34 However they can (usually) be used on domains which are active but
  35 hanging or unresponsive.  You also have the option of capturing a
  36 memory image of a domain for post-mortem analysis, allowing you to
  37 quickly reboot a failed domain and analyze it later at your leisure.
  38
  39 =head1 COMMON OPTIONS
  40
  41 Each command obeys a common set of options.  The general form is:
  42
  43 virt-I<program> [-options] [domains...]
  44
  45 where I<program> is a subtool such as C<uname>, C<dmesg> or C<ps>, and
  46 I<domains> is a list of guest names to act on.  If no domains are
  47 specified then we act on all active domains by default.
  48
  49 A I<domain> may be specified either by its name, by its ID or by its
  50 UUID.  Use I<virsh list> to get a list of active domain names and IDs.
  51
  52 Equivalently you can use the C<virt-mem> meta-tool with subcommands,
  53 as in:
  54
  55 virt-mem I<program> [...]
  56
  57 The C<virt-mem> program offers additional features, such as the
  58 ability to capture VM images for post-mortem analysis (see below).
  59
  60 =over 4
  61
  62 =item B<-c uri>, B<--connect uri>
  63
  64 Connect to libvirt URI.  The default is to connect to the default
  65 libvirt URI, normally Xen.
  66
  67 =item B<--csv>
  68
  69 Print the results in CSV format, suitable for importing into a
  70 spreadsheet or database.
  71
  72 This option is only supported if virt-mem was built with CSV support.
  73
  74 =item B<--debug>
  75
  76 Emit debugging information on stderr.  Please supply this if you
  77 report a bug.
  78
  79 =item B<--help>
  80
  81 Display usage summary.
  82
  83 =item B<-t memoryimage>
  84
  85 Post-mortem analysis mode.
  86
  87 Instead of checking libvirt for domain information, this runs the tool
  88 directly on the memory image supplied.  You may specify the B<-t>
  89 option multiple times.  Use the C<virt-mem capture> command to capture
  90 images (see below).
  91
  92 See also the section L</"MEMORY IMAGES"> below.
  93
  94 =item B<--version>
  95
  96 Display version and exit.
  97
  98 =item B<-E auto|littleendian|bigendian>
  99
 100 =item B<-T auto|i386|x86-64|I<address>|I<address,min,max>>
 101
 102 =item B<-W auto|32|64>
 103
 104 These options force the endianness, text address, and word size for
 105 the subsequent domains listed on the command line (or if no domains
 106 are listed, then for all domains).
 107
 108 These default to I<auto> which tries to do automatic detection (using
 109 libvirt, or details from the memory images themselves).  You only need
 110 to use these options if virt-mem tools get the automatic detection
 111 wrong.
 112
 113 Endianness (I<-E>) sets the memory endianness, for data, pointers and
 114 so on.  I<-E littleendian> is the endianness used on Intel i386,
 115 x86-64 and (usually) IA64.  I<-E bigendian> is the endianness used on
 116 many RISC chips such as SPARC and PowerPC.
 117
 118 Text address (I<-T>) sets the base address and optionally min and max
 119 addresses of the kernel image.  I<-T i386> means to try some common
 120 addresses for i386-based kernels.  I<-T x86-64> means to try some
 121 common addresses for x86-64-based kernels.
 122
 123 I<-T address> sets the kernel base address specifically (I<0x> prefix
 124 is used to specify hex addresses).  I<-T address,min,max> sets the
 125 kernel base address, minimum address and maximum address.
 126
 127 Word size (I<-W>) sets the word size, 32 or 64 bits.
 128
 129 =item B<-A auto|i386|x86-64|...>
 130
 131 This option sets the architecture to one of a collection of known
 132 architectures.  It is equivalent to setting endianness and wordsize in
 133 one go, but not text address.
 134
 135 =back
 136
 137 =head1 virt-dmesg
 138
 139 This prints the latest kernel messages from the virtual machine, as if
 140 you were logged into the machine and used L<dmesg(1)>.
 141
 142 =head1 virt-uname
 143
 144 This prints the contents of the system C<utsname> structure, similar
 145 to what is printed by the L<uname(1)> command.
 146
 147 =head1 virt-mem
 148
 149 C<virt-mem> is a meta-tool which allows you to run all the commands
 150 above, and provides some extra features.
 151
 152 Instead of the preceeding commands such as C<virt-dmesg> you can
 153 write:
 154
 155  virt-mem dmesg [...]
 156
 157 Options and other command line arguments work the same.
 158
 159 Additional C<virt-mem> subcommands are listed below.
 160
 161 =head2 virt-mem capture -o memoryimage [-options] [domains...]
 162
 163 Capture the memory image of a virtual machine for later post-mortem
 164 analysis.  Use the I<-t memoryimage> option for any other virt-mem
 165 tool to analyze the memory image later.
 166
 167 The I<-o memoryimage> option is required, and is used to name the
 168 output file.  If a single guest is captured, then the output is saved
 169 in the I<memoryimage> file.  However, if multiple guests are captured,
 170 then their images are saved in I<memoryimage.ID> where I<ID> is
 171 replaced with the domain ID.
 172
 173 See also the section L</"MEMORY IMAGES"> below.
 174
 175 =head1 EXAMPLES
 176
 177  # virt-uname
 178  f9x32kvm: Linux localhost.localdomain 2.6.24-0.155.rc7.git6.fc9 #1
 179  SMP Tue Jan 15 17:52:31 EST 2008 i686 (none)
 180
 181  # virt-dmesg f9x32kvm | tail
 182  <6>Bluetooth: Core ver 2.11
 183  <6>NET: Registered protocol family 31
 184  <6>Bluetooth: HCI device and connection manager initialized
 185  <6>Bluetooth: HCI socket layer initialized
 186  <6>Bluetooth: L2CAP ver 2.9
 187  <6>Bluetooth: L2CAP socket layer initialized
 188  <6>Bluetooth: RFCOMM socket layer initialized
 189  <6>Bluetooth: RFCOMM TTY layer initialized
 190  <6>Bluetooth: RFCOMM ver 1.8
 191  <7>eth0: no IPv6 routers present
 192
 193 =head1 MEMORY IMAGES
 194
 195 All the tools can read dumped kernel images, using the common
 196 I<-t memoryimage> option.  In addition you can capture memory
 197 images from domains for post-mortem analysis using the
 198 C<virt-mem capture> command (see above).
 199
 200 The memory images which are saved by C<virt-mem capture> contain a
 201 header and some additional information about the kernel image, such as
 202 architecture, original text address, and so forth.  Thus these images
 203 can be reanalysed just using the I<-t memoryimage> option.
 204
 205 We also support analyzing raw kernel dumps, eg. produced using the
 206 L<qemu(1)> monitor's C<memsave> command.  In this case however you
 207 usually need to specify the original architecture, text address and
 208 perhaps other details using the I<-A>, I<-T> and other command line
 209 parameters.
 210
 211 =head1 SHORTCOMINGS
 212
 213 The virt-mem tools spy on the guest's memory image.  There are some
 214 shortcomings to this, described here.
 215
 216 =over
 217
 218 =item *
 219
 220 Only works on specific, tested releases of Linux kernels.  Support
 221 for arbitrary Linux kernel versions may be patchy because of changes
 222 in the internal structures used.  Support for non-Linux kernels is
 223 currently non-existent, and probably impossible for Windows because of
 224 lack of an acceptable source license.
 225
 226 =item *
 227
 228 Heuristics are used which may mean in the worst case that the
 229 output is wrong.
 230
 231 =item *
 232
 233 Structures which are frequently modified may cause errors.  This
 234 could be a problem if, for example, the process table in the guest is
 235 being rapidly updated.
 236
 237 =item *
 238
 239 We have to scan memory to find kernel symbols, etc., which can be
 240 quite slow.  Optimizing the memory scanner would help, and caching the
 241 base address of the symbol table(s) would make it dramatically faster.
 242
 243 =back
 244
 245 =head1 SECURITY
 246
 247 The current code tries hard to be secure against malicious guests, for
 248 example guests which set up malicious kernel memory.
 249
 250 =head1 SEE ALSO
 251
 252 L<uname(1)>,
 253 L<dmesg(1)>,
 254 L<virsh(1)>,
 255 L<virt-top(1)>,
 256 L<virt-df(1)>,
 257 L<xm(1)>,
 258 L<qemu(1)>,
 259 L<http://www.libvirt.org/ocaml/>,
 260 L<http://www.libvirt.org/>,
 261 L<http://et.redhat.com/~rjones/>,
 262 L<http://caml.inria.fr/>
 263
 264 =head1 AUTHORS
 265
 266 Richard W.M. Jones <rjones @ redhat . com>
 267
 268 =head1 COPYRIGHT
 269
 270 (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones
 271 http://libvirt.org/
 272
 273 This program is free software; you can redistribute it and/or modify
 274 it under the terms of the GNU General Public License as published by
 275 the Free Software Foundation; either version 2 of the License, or
 276 (at your option) any later version.
 277
 278 This program is distributed in the hope that it will be useful,
 279 but WITHOUT ANY WARRANTY; without even the implied warranty of
 280 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 281 GNU General Public License for more details.
 282
 283 You should have received a copy of the GNU General Public License
 284 along with this program; if not, write to the Free Software
 285 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 286
 287 =head1 REPORTING BUGS
 288
 289 Bugs can be viewed on the Red Hat Bugzilla page:
 290 L<https://bugzilla.redhat.com/>.
 291
 292 If you find a bug in virt-mem, please follow these steps to report it:
 293
 294 =over 4
 295
 296 =item 1. Check for existing bug reports
 297
 298 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 299 Someone may already have reported the same bug, and they may even
 300 have fixed it.
 301
 302 =item 2. Capture debug and error messages
 303
 304 Run
 305
 306 virt-I<program> --debug > virt-mem.log 2>&1
 307
 308 and keep I<virt-mem.log>.  It contains error messages which you should
 309 submit with your bug report.
 310
 311 =item 3. Get version of virt-mem and version of libvirt.
 312
 313 Run
 314
 315 virt-I<program> --version
 316
 317 =item 4. Submit a bug report.
 318
 319 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 320 Please describe the problem in as much detail as possible.
 321
 322 Remember to include the version numbers (step 3) and the debug
 323 messages file (step 2).
 324
 325 =item 5. Assign the bug to rjones @ redhat.com
 326
 327 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 328 spaces).  You can also send me an email with the bug number if you
 329 want a faster response.
 330
 331 =back