3 virt-uname - system information for virtual machines
5 virt-dmesg - print kernel messages for virtual machines
7 virt-ps - list processes for virtual machines
9 virt-mem - tool with additional information output
13 virt-uname [-options] [domains...]
15 virt-dmesg [-options] [domains...]
17 virt-ps [-options] [domains...]
29 These virtualization tools allow you to inspect the status of virtual
30 machines running Linux.
32 These tools are designed to work like familiar Linux/Unix command line
35 These tools all use libvirt so are capable of showing information
36 across a variety of different virtualization systems.
38 The virt-mem tools do not work on domains which are not active
39 (running or paused). eg. They do not work on shut down domains.
40 However they can (usually) be used on domains which are active but
41 hanging or unresponsive. You also have the option of capturing a
42 memory image of a domain for post-mortem analysis, allowing you to
43 quickly reboot a failed domain and analyze it later at your leisure.
47 Each command obeys a common set of options. The general form is:
49 virt-I<program> [-options] [domains...]
51 where I<program> is a subtool such as C<uname>, C<dmesg> or C<ps>, and
52 I<domains> is a list of guest names to act on. If no domains are
53 specified then we act on all active domains by default.
55 A I<domain> may be specified either by its name, by its ID or by its
56 UUID. Use I<virsh list> to get a list of active domain names and IDs.
58 Equivalently you can use the C<virt-mem> meta-tool with subcommands,
61 virt-mem I<program> [...]
63 The C<virt-mem> program offers additional features, such as the
64 ability to capture VM images for post-mortem analysis (see below).
68 =item B<-c uri>, B<--connect uri>
70 Connect to libvirt URI. The default is to connect to the default
71 libvirt URI, normally Xen.
75 Print the results in CSV format, suitable for importing into a
76 spreadsheet or database.
78 This option is only supported if virt-mem was built with CSV support.
82 Emit debugging information on stderr. Please supply this if you
87 Display usage summary.
89 =item B<-t memoryimage>
91 Post-mortem analysis mode.
93 Instead of checking libvirt for domain information, this runs the tool
94 directly on the memory image supplied. You may specify the B<-t>
95 option multiple times. Use the C<virt-mem capture> command to capture
98 See also the section L</"MEMORY IMAGES"> below.
102 Display version and exit.
104 =item B<-E auto|littleendian|bigendian>
106 =item B<-T auto|i386|x86-64|I<address>|I<address,min,max>>
108 =item B<-W auto|32|64>
110 These options force the endianness, text address, and word size for
111 the subsequent domains listed on the command line (or if no domains
112 are listed, then for all domains).
114 These default to I<auto> which tries to do automatic detection (using
115 libvirt, or details from the memory images themselves). You only need
116 to use these options if virt-mem tools get the automatic detection
119 Endianness (I<-E>) sets the memory endianness, for data, pointers and
120 so on. I<-E littleendian> is the endianness used on Intel i386,
121 x86-64 and (usually) IA64. I<-E bigendian> is the endianness used on
122 many RISC chips such as SPARC and PowerPC.
124 Text address (I<-T>) sets the base address and optionally min and max
125 addresses of the kernel image. I<-T i386> means to try some common
126 addresses for i386-based kernels. I<-T x86-64> means to try some
127 common addresses for x86-64-based kernels.
129 I<-T address> sets the kernel base address specifically (I<0x> prefix
130 is used to specify hex addresses). I<-T address,min,max> sets the
131 kernel base address, minimum address and maximum address.
133 Word size (I<-W>) sets the word size, 32 or 64 bits.
135 =item B<-A auto|i386|x86-64|...>
137 This option sets the architecture to one of a collection of known
138 architectures. It is equivalent to setting endianness and wordsize in
139 one go, but not text address.
145 This prints the latest kernel messages from the virtual machine, as if
146 you were logged into the machine and used L<dmesg(1)>.
150 This prints the contents of the system C<utsname> structure, similar
151 to what is printed by the L<uname(1)> command.
155 C<virt-mem> is a meta-tool which allows you to run all the commands
156 above, and provides some extra features.
158 Instead of the preceeding commands such as C<virt-dmesg> you can
163 Options and other command line arguments work the same.
165 Additional C<virt-mem> subcommands are listed below.
167 =head2 virt-mem capture -o memoryimage [-options] [domains...]
169 Capture the memory image of a virtual machine for later post-mortem
170 analysis. Use the I<-t memoryimage> option for any other virt-mem
171 tool to analyze the memory image later.
173 The I<-o memoryimage> option is required, and is used to name the
174 output file. If a single guest is captured, then the output is saved
175 in the I<memoryimage> file. However, if multiple guests are captured,
176 then their images are saved in I<memoryimage.ID> where I<ID> is
177 replaced with the domain ID.
179 See also the section L</"MEMORY IMAGES"> below.
184 f9x32kvm: Linux localhost.localdomain 2.6.24-0.155.rc7.git6.fc9 #1
185 SMP Tue Jan 15 17:52:31 EST 2008 i686 (none)
187 # virt-dmesg f9x32kvm | tail
188 <6>Bluetooth: Core ver 2.11
189 <6>NET: Registered protocol family 31
190 <6>Bluetooth: HCI device and connection manager initialized
191 <6>Bluetooth: HCI socket layer initialized
192 <6>Bluetooth: L2CAP ver 2.9
193 <6>Bluetooth: L2CAP socket layer initialized
194 <6>Bluetooth: RFCOMM socket layer initialized
195 <6>Bluetooth: RFCOMM TTY layer initialized
196 <6>Bluetooth: RFCOMM ver 1.8
197 <7>eth0: no IPv6 routers present
201 All the tools can read dumped kernel images, using the common
202 I<-t memoryimage> option. In addition you can capture memory
203 images from domains for post-mortem analysis using the
204 C<virt-mem capture> command (see above).
206 The memory images which are saved by C<virt-mem capture> contain a
207 header and some additional information about the kernel image, such as
208 architecture, original text address, and so forth. Thus these images
209 can be reanalysed just using the I<-t memoryimage> option.
211 We also support analyzing raw kernel dumps, eg. produced using the
212 L<qemu(1)> monitor's C<memsave> command. In this case however you
213 usually need to specify the original architecture, text address and
214 perhaps other details using the I<-A>, I<-T> and other command line
219 The virt-mem tools spy on the guest's memory image. There are some
220 shortcomings to this, described here.
226 Only works on specific, tested releases of Linux kernels. Support
227 for arbitrary Linux kernel versions may be patchy because of changes
228 in the internal structures used. Support for non-Linux kernels is
229 currently non-existent, and probably impossible for Windows because of
230 lack of an acceptable source license.
234 Heuristics are used which may mean in the worst case that the
239 Structures which are frequently modified may cause errors. This
240 could be a problem if, for example, the process table in the guest is
241 being rapidly updated.
245 We have to scan memory to find kernel symbols, etc., which can be
246 quite slow. Optimizing the memory scanner would help, and caching the
247 base address of the symbol table(s) would make it dramatically faster.
253 The current code tries hard to be secure against malicious guests, for
254 example guests which set up malicious kernel memory.
265 L<http://www.libvirt.org/ocaml/>,
266 L<http://www.libvirt.org/>,
267 L<http://et.redhat.com/~rjones/>,
268 L<http://caml.inria.fr/>
272 Richard W.M. Jones <rjones @ redhat . com>
276 (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones
279 This program is free software; you can redistribute it and/or modify
280 it under the terms of the GNU General Public License as published by
281 the Free Software Foundation; either version 2 of the License, or
282 (at your option) any later version.
284 This program is distributed in the hope that it will be useful,
285 but WITHOUT ANY WARRANTY; without even the implied warranty of
286 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
287 GNU General Public License for more details.
289 You should have received a copy of the GNU General Public License
290 along with this program; if not, write to the Free Software
291 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
293 =head1 REPORTING BUGS
295 Bugs can be viewed on the Red Hat Bugzilla page:
296 L<https://bugzilla.redhat.com/>.
298 If you find a bug in virt-mem, please follow these steps to report it:
302 =item 1. Check for existing bug reports
304 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
305 Someone may already have reported the same bug, and they may even
308 =item 2. Capture debug and error messages
312 virt-I<program> --debug > virt-mem.log 2>&1
314 and keep I<virt-mem.log>. It contains error messages which you should
315 submit with your bug report.
317 =item 3. Get version of virt-mem and version of libvirt.
321 virt-I<program> --version
323 =item 4. Submit a bug report.
325 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
326 Please describe the problem in as much detail as possible.
328 Remember to include the version numbers (step 3) and the debug
329 messages file (step 2).
331 =item 5. Assign the bug to rjones @ redhat.com
333 Assign or reassign the bug to B<rjones @ redhat.com> (without the
334 spaces). You can also send me an email with the bug number if you
335 want a faster response.