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