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.
- The tools all use libvirt so are capable of showing stats across a
- variety of different virtualization systems.
+ 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 *domains* is a list of guest names to act on. If no domains are
+ 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 or by its ID. Use *virsh
- list* to get a list of active domain names and IDs.
+ 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.
- 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.
+ 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
--help
Display usage summary.
+ --list-kernels
+ List which guest kernel versions are known/supported, then exit.
+
-t memoryimage
- Test mode. Instead of checking libvirt for domain information, this
- runs the virt-mem tool directly on the memory image supplied. You
- may specify the -t option multiple times.
+ 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*
+ -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
detection wrong.
Endianness (*-E*) sets the memory endianness, for data, pointers and
- so on.
+ 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.
- Text address (*-T*) sets the base address 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 address specifically (*0x* prefix is allowed
- to specify hex addresses).
+ *-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.
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
<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.
- (1) 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.
+ * 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.
- (2) Heuristics are used which may mean in the worst case that the output
- is wrong.
+ * Heuristics are used which may mean in the worst case that the output
+ is wrong.
- (3) 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.
+ * 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.
- (4) 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.
+ * 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), xm(1), <http://www.libvirt.org/ocaml/>,
- <http://www.libvirt.org/>, <http://et.redhat.com/~rjones/>,
- <http://caml.inria.fr/>
+ uname(1), dmesg(1), virsh(1), virt-top(1), virt-df(1), xm(1), qemu(1),
+ <http://www.libvirt.org/ocaml/>, <http://www.libvirt.org/>,
+ <http://et.redhat.com/~rjones/>, <http://caml.inria.fr/>
AUTHORS
Richard W.M. Jones <rjones @ redhat . com>
git.annexia.org / virt-mem.git / blobdiff