2 virt-uname - system information for virtual machines
4 virt-dmesg - print kernel messages for virtual machines
6 virt-mem - tool with additional information output
9 virt-uname [-options] [domains...]
11 virt-dmesg [-options] [domains...]
20 These virtualization tools allow you to inspect the status of virtual
21 machines running Linux.
23 These tools are designed to work like familiar Linux/Unix command line
26 These tools all use libvirt so are capable of showing information across
27 a variety of different virtualization systems.
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.
37 Each command obeys a common set of options. The general form is:
39 virt-*program* [-options] [domains...]
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.
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.
48 Equivalently you can use the "virt-mem" meta-tool with subcommands, as
51 virt-mem *program* [...]
53 The "virt-mem" program offers additional features, such as the ability
54 to capture VM images for post-mortem analysis (see below).
57 Connect to libvirt URI. The default is to connect to the default
58 libvirt URI, normally Xen.
61 Print the results in CSV format, suitable for importing into a
62 spreadsheet or database.
64 This option is only supported if virt-mem was built with CSV
68 Emit debugging information on stderr. Please supply this if you
72 Display usage summary.
75 Post-mortem analysis mode.
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
82 See also the section "MEMORY IMAGES" below.
85 Display version and exit.
87 -E auto|littleendian|bigendian
88 -T auto|i386|x86-64|*address*|*address,min,max*
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).
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
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.
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.
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.
113 Word size (*-W*) sets the word size, 32 or 64 bits.
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.
121 This prints the latest kernel messages from the virtual machine, as if
122 you were logged into the machine and used dmesg(1).
125 This prints the contents of the system "utsname" structure, similar to
126 what is printed by the uname(1) command.
129 "virt-mem" is a meta-tool which allows you to run all the commands
130 above, and provides some extra features.
132 Instead of the preceeding commands such as "virt-dmesg" you can write:
136 Options and other command line arguments work the same.
138 Additional "virt-mem" subcommands are listed below.
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.
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
151 See also the section "MEMORY IMAGES" below.
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)
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
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
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.
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.
187 The virt-mem tools spy on the guest's memory image. There are some
188 shortcomings to this, described here.
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.
196 * Heuristics are used which may mean in the worst case that the output
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.
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
209 The current code tries hard to be secure against malicious guests, for
210 example guests which set up malicious kernel memory.
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/>
218 Richard W.M. Jones <rjones @ redhat . com>
221 (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones http://libvirt.org/
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.
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.
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.
238 Bugs can be viewed on the Red Hat Bugzilla page:
239 <https://bugzilla.redhat.com/>.
241 If you find a bug in virt-mem, please follow these steps to report it:
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
248 2. Capture debug and error messages
251 virt-*program* --debug > virt-mem.log 2>&1
253 and keep *virt-mem.log*. It contains error messages which you should
254 submit with your bug report.
256 3. Get version of virt-mem and version of libvirt.
259 virt-*program* --version
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.
265 Remember to include the version numbers (step 3) and the debug
266 messages file (step 2).
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.