NAME
virt-uname - system information for virtual machines
virt-dmesg - print kernel messages for virtual machines
virt-ps - list processes for virtual machines
virt-mem - tool with additional information output
SUMMARY
virt-uname [-options] [domains...]
virt-dmesg [-options] [domains...]
virt-ps [-options] [domains...]
virt-mem uname [...]
virt-mem dmesg [...]
virt-mem ps [...]
virt-mem [-options]
DESCRIPTION
These virtualization tools allow you to inspect the status of virtual
machines running Linux.
These tools are designed to work like familiar Linux/Unix command line
tools.
These tools all use libvirt so are capable of showing information across
a variety of different virtualization systems.
The virt-mem tools do not work on domains which are not active (running
or paused). eg. They do not work on shut down domains. However they can
(usually) be used on domains which are active but hanging or
unresponsive. You also have the option of capturing a memory image of a
domain for post-mortem analysis, allowing you to quickly reboot a failed
domain and analyze it later at your leisure.
COMMON OPTIONS
Each command obeys a common set of options. The general form is:
virt-*program* [-options] [domains...]
where *program* is a subtool such as "uname", "dmesg" or "ps", and
*domains* is a list of guest names to act on. If no domains are
specified then we act on all active domains by default.
A *domain* may be specified either by its name, by its ID or by its
UUID. Use *virsh list* to get a list of active domain names and IDs.
Equivalently you can use the "virt-mem" meta-tool with subcommands, as
in:
virt-mem *program* [...]
The "virt-mem" program offers additional features, such as the ability
to capture VM images for post-mortem analysis (see below).
-c uri, --connect uri
Connect to libvirt URI. The default is to connect to the default
libvirt URI, normally Xen.
--csv
Print the results in CSV format, suitable for importing into a
spreadsheet or database.
This option is only supported if virt-mem was built with CSV
support.
--debug
Emit debugging information on stderr. Please supply this if you
report a bug.
--help
Display usage summary.
-t memoryimage
Post-mortem analysis mode.
Instead of checking libvirt for domain information, this runs the
tool directly on the memory image supplied. You may specify the -t
option multiple times. Use the "virt-mem capture" command to capture
images (see below).
See also the section "MEMORY IMAGES" below.
--version
Display version and exit.
-E auto|littleendian|bigendian
-T auto|i386|x86-64|*address*|*address,min,max*
-W auto|32|64
These options force the endianness, text address, and word size for
the subsequent domains listed on the command line (or if no domains
are listed, then for all domains).
These default to *auto* which tries to do automatic detection (using
libvirt, or details from the memory images themselves). You only
need to use these options if virt-mem tools get the automatic
detection wrong.
Endianness (*-E*) sets the memory endianness, for data, pointers and
so on. *-E littleendian* is the endianness used on Intel i386,
x86-64 and (usually) IA64. *-E bigendian* is the endianness used on
many RISC chips such as SPARC and PowerPC.
Text address (*-T*) sets the base address and optionally min and max
addresses of the kernel image. *-T i386* means to try some common
addresses for i386-based kernels. *-T x86-64* means to try some
common addresses for x86-64-based kernels.
*-T address* sets the kernel base address specifically (*0x* prefix
is used to specify hex addresses). *-T address,min,max* sets the
kernel base address, minimum address and maximum address.
Word size (*-W*) sets the word size, 32 or 64 bits.
-A auto|i386|x86-64|...
This option sets the architecture to one of a collection of known
architectures. It is equivalent to setting endianness and wordsize
in one go, but not text address.
virt-dmesg
This prints the latest kernel messages from the virtual machine, as if
you were logged into the machine and used dmesg(1).
virt-uname
This prints the contents of the system "utsname" structure, similar to
what is printed by the uname(1) command.
virt-mem
"virt-mem" is a meta-tool which allows you to run all the commands
above, and provides some extra features.
Instead of the preceeding commands such as "virt-dmesg" you can write:
virt-mem dmesg [...]
Options and other command line arguments work the same.
Additional "virt-mem" subcommands are listed below.
virt-mem capture -o memoryimage [-options] [domains...]
Capture the memory image of a virtual machine for later post-mortem
analysis. Use the *-t memoryimage* option for any other virt-mem tool to
analyze the memory image later.
The *-o memoryimage* option is required, and is used to name the output
file. If a single guest is captured, then the output is saved in the
*memoryimage* file. However, if multiple guests are captured, then their
images are saved in *memoryimage.ID* where *ID* is replaced with the
domain ID.
See also the section "MEMORY IMAGES" below.
EXAMPLES
# virt-uname
f9x32kvm: Linux localhost.localdomain 2.6.24-0.155.rc7.git6.fc9 #1
SMP Tue Jan 15 17:52:31 EST 2008 i686 (none)
# virt-dmesg f9x32kvm | tail
<6>Bluetooth: Core ver 2.11
<6>NET: Registered protocol family 31
<6>Bluetooth: HCI device and connection manager initialized
<6>Bluetooth: HCI socket layer initialized
<6>Bluetooth: L2CAP ver 2.9
<6>Bluetooth: L2CAP socket layer initialized
<6>Bluetooth: RFCOMM socket layer initialized
<6>Bluetooth: RFCOMM TTY layer initialized
<6>Bluetooth: RFCOMM ver 1.8
<7>eth0: no IPv6 routers present
MEMORY IMAGES
All the tools can read dumped kernel images, using the common *-t
memoryimage* option. In addition you can capture memory images from
domains for post-mortem analysis using the "virt-mem capture" command
(see above).
The memory images which are saved by "virt-mem capture" contain a header
and some additional information about the kernel image, such as
architecture, original text address, and so forth. Thus these images can
be reanalysed just using the *-t memoryimage* option.
We also support analyzing raw kernel dumps, eg. produced using the
qemu(1) monitor's "memsave" command. In this case however you usually
need to specify the original architecture, text address and perhaps
other details using the *-A*, *-T* and other command line parameters.
SHORTCOMINGS
The virt-mem tools spy on the guest's memory image. There are some
shortcomings to this, described here.
* Only works on specific, tested releases of Linux kernels. Support
for arbitrary Linux kernel versions may be patchy because of changes
in the internal structures used. Support for non-Linux kernels is
currently non-existent, and probably impossible for Windows because
of lack of an acceptable source license.
* Heuristics are used which may mean in the worst case that the output
is wrong.
* Structures which are frequently modified may cause errors. This
could be a problem if, for example, the process table in the guest
is being rapidly updated.
* We have to scan memory to find kernel symbols, etc., which can be
quite slow. Optimizing the memory scanner would help, and caching
the base address of the symbol table(s) would make it dramatically
faster.
SECURITY
The current code tries hard to be secure against malicious guests, for
example guests which set up malicious kernel memory.
SEE ALSO
uname(1), dmesg(1), virsh(1), virt-top(1), virt-df(1), xm(1), qemu(1),
, ,
,
AUTHORS
Richard W.M. Jones
COPYRIGHT
(C) Copyright 2008 Red Hat Inc., Richard W.M. Jones http://libvirt.org/
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.
REPORTING BUGS
Bugs can be viewed on the Red Hat Bugzilla page:
.
If you find a bug in virt-mem, please follow these steps to report it:
1. Check for existing bug reports
Go to and search for similar bugs.
Someone may already have reported the same bug, and they may even
have fixed it.
2. Capture debug and error messages
Run
virt-*program* --debug > virt-mem.log 2>&1
and keep *virt-mem.log*. It contains error messages which you should
submit with your bug report.
3. Get version of virt-mem and version of libvirt.
Run
virt-*program* --version
4. Submit a bug report.
Go to and enter a new bug. Please
describe the problem in as much detail as possible.
Remember to include the version numbers (step 3) and the debug
messages file (step 2).
5. Assign the bug to rjones @ redhat.com
Assign or reassign the bug to rjones @ redhat.com (without the
spaces). You can also send me an email with the bug number if you
want a faster response.