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