virt-mem.txt

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