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