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