2 virt-uname - system information for virtual machines
4 virt-dmesg - print kernel messages for virtual machines
6 virt-ps - list processes for virtual machines
8 virt-mem - tool with additional information output
11 virt-uname [-options] [domains...]
13 virt-dmesg [-options] [domains...]
15 virt-ps [-options] [domains...]
26 These virtualization tools allow you to inspect the status of virtual
27 machines running Linux.
29 These tools are designed to work like familiar Linux/Unix command line
32 These tools all use libvirt so are capable of showing information across
33 a variety of different virtualization systems.
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.
43 Each command obeys a common set of options. The general form is:
45 virt-*program* [-options] [domains...]
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.
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.
54 Equivalently you can use the "virt-mem" meta-tool with subcommands, as
57 virt-mem *program* [...]
59 The "virt-mem" program offers additional features, such as the ability
60 to capture VM images for post-mortem analysis (see below).
63 Connect to libvirt URI. The default is to connect to the default
64 libvirt URI, normally Xen.
67 Print the results in CSV format, suitable for importing into a
68 spreadsheet or database.
70 This option is only supported if virt-mem was built with CSV
74 Emit debugging information on stderr. Please supply this if you
78 Display usage summary.
81 List which guest kernel versions are known/supported, then exit.
84 Post-mortem analysis mode.
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
91 See also the section "MEMORY IMAGES" below.
94 Display version and exit.
96 -E auto|littleendian|bigendian
97 -T auto|i386|x86-64|*address*|*address,min,max*
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).
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
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.
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.
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.
122 Word size (*-W*) sets the word size, 32 or 64 bits.
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.
130 This prints the latest kernel messages from the virtual machine, as if
131 you were logged into the machine and used dmesg(1).
134 This prints the contents of the system "utsname" structure, similar to
135 what is printed by the uname(1) command.
138 "virt-mem" is a meta-tool which allows you to run all the commands
139 above, and provides some extra features.
141 Instead of the preceeding commands such as "virt-dmesg" you can write:
145 Options and other command line arguments work the same.
147 Additional "virt-mem" subcommands are listed below.
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.
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
160 See also the section "MEMORY IMAGES" below.
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)
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
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
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.
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.
196 The virt-mem tools spy on the guest's memory image. There are some
197 shortcomings to this, described here.
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.
205 * Heuristics are used which may mean in the worst case that the output
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.
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
218 The current code tries hard to be secure against malicious guests, for
219 example guests which set up malicious kernel memory.
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/>
227 Richard W.M. Jones <rjones @ redhat . com>
230 (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones http://libvirt.org/
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.
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.
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.
247 Bugs can be viewed on the Red Hat Bugzilla page:
248 <https://bugzilla.redhat.com/>.
250 If you find a bug in virt-mem, please follow these steps to report it:
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
257 2. Capture debug and error messages
260 virt-*program* --debug > virt-mem.log 2>&1
262 and keep *virt-mem.log*. It contains error messages which you should
263 submit with your bug report.
265 3. Get version of virt-mem and version of libvirt.
268 virt-*program* --version
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.
274 Remember to include the version numbers (step 3) and the debug
275 messages file (step 2).
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.