1VIRT-MEM(1) Virtualization Support VIRT-MEM(1)
2
6 virt-uname - system information for virtual machines
7 virt-dmesg - print kernel messages for virtual machines
9 virt-ps - list processes for virtual machines
11 virt-mem - tool with additional information output
13
15 virt-uname [-options] [domains...]
16 virt-dmesg [-options] [domains...]
18 virt-ps [-options] [domains...]
20 virt-mem uname [...]
22 virt-mem dmesg [...]
24 virt-mem ps [...]
26 virt-mem [-options]
28
30 These virtualization tools allow you to inspect the status of virtual
31 machines running Linux.
32 These tools are designed to work like familiar Linux/Unix command line
34 tools.
35 These tools all use libvirt so are capable of showing information
37 across a variety of different virtualization systems.
38 The virt-mem tools do not work on domains which are not active (running
40 or paused). eg. They do not work on shut down domains. However they
41 can (usually) be used on domains which are active but hanging or
42 unresponsive. You also have the option of capturing a memory image of
43 a domain for post-mortem analysis, allowing you to quickly reboot a
44 failed domain and analyze it later at your leisure.
45
47 Each command obeys a common set of options. The general form is:
48 virt-program [-options] [domains...]
50 where program is a subtool such as "uname", "dmesg" or "ps", and
52 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.
54 A domain may be specified either by its name, by its ID or by its UUID.
56 Use virsh list to get a list of active domain names and IDs.
57 Equivalently you can use the "virt-mem" meta-tool with subcommands, as
59 in:
60 virt-mem program [...]
62 The "virt-mem" program offers additional features, such as the ability
64 to capture VM images for post-mortem analysis (see below).
65 -c uri, --connect uri
67 Connect to libvirt URI. The default is to connect to the default
68 libvirt URI, normally Xen.
69 --csv
71 Print the results in CSV format, suitable for importing into a
72 spreadsheet or database.
73 This option is only supported if virt-mem was built with CSV
75 support.
76 --debug
78 Emit debugging information on stderr. Please supply this if you
79 report a bug.
80 --help
82 Display usage summary.
83 --list-kernels
85 List which guest kernel versions are known/supported, then exit.
86 -t memoryimage
88 Post-mortem analysis mode.
89 Instead of checking libvirt for domain information, this runs the
91 tool directly on the memory image supplied. You may specify the -t
92 option multiple times. Use the "virt-mem capture" command to
93 capture images (see below).
94 See also the section "MEMORY IMAGES" below.
96 --version
98 Display version and exit.
99 -E auto|littleendian|bigendian
101 -T auto|i386|x86-64|address|address,min,max
102 -W auto|32|64
103 These options force the endianness, text address, and word size for
104 the subsequent domains listed on the command line (or if no domains
105 are listed, then for all domains).
106 These default to auto which tries to do automatic detection (using
108 libvirt, or details from the memory images themselves). You only
109 need to use these options if virt-mem tools get the automatic
110 detection wrong.
111 Endianness (-E) sets the memory endianness, for data, pointers and
113 so on. -E littleendian is the endianness used on Intel i386,
114 x86-64 and (usually) IA64. -E bigendian is the endianness used on
115 many RISC chips such as SPARC and PowerPC.
116 Text address (-T) sets the base address and optionally min and max
118 addresses of the kernel image. -T i386 means to try some common
119 addresses for i386-based kernels. -T x86-64 means to try some
120 common addresses for x86-64-based kernels.
121 -T address sets the kernel base address specifically (0x prefix is
123 used to specify hex addresses). -T address,min,max sets the kernel
124 base address, minimum address and maximum address.
125 Word size (-W) sets the word size, 32 or 64 bits.
127 -A auto|i386|x86-64|...
129 This option sets the architecture to one of a collection of known
130 architectures. It is equivalent to setting endianness and wordsize
131 in one go, but not text address.
132
134 This prints the latest kernel messages from the virtual machine, as if
135 you were logged into the machine and used dmesg(1).
136
138 This prints the contents of the system "utsname" structure, similar to
139 what is printed by the uname(1) command.
140
142 "virt-mem" is a meta-tool which allows you to run all the commands
143 above, and provides some extra features.
144 Instead of the preceeding commands such as "virt-dmesg" you can write:
146 virt-mem dmesg [...]
148 Options and other command line arguments work the same.
150 Additional "virt-mem" subcommands are listed below.
152 virt-mem capture -o memoryimage [-options] [domains...]
154 Capture the memory image of a virtual machine for later post-mortem
156 analysis. Use the -t memoryimage option for any other virt-mem tool to
157 analyze the memory image later.
158 The -o memoryimage option is required, and is used to name the output
160 file. If a single guest is captured, then the output is saved in the
161 memoryimage file. However, if multiple guests are captured, then their
162 images are saved in memoryimage.ID where ID is replaced with the domain
163 ID.
164 See also the section "MEMORY IMAGES" below.
166
168 # virt-uname
169 f9x32kvm: Linux localhost.localdomain 2.6.24-0.155.rc7.git6.fc9 #1
170 SMP Tue Jan 15 17:52:31 EST 2008 i686 (none)
171 # virt-dmesg f9x32kvm | tail
173 <6>Bluetooth: Core ver 2.11
174 <6>NET: Registered protocol family 31
175 <6>Bluetooth: HCI device and connection manager initialized
176 <6>Bluetooth: HCI socket layer initialized
177 <6>Bluetooth: L2CAP ver 2.9
178 <6>Bluetooth: L2CAP socket layer initialized
179 <6>Bluetooth: RFCOMM socket layer initialized
180 <6>Bluetooth: RFCOMM TTY layer initialized
181 <6>Bluetooth: RFCOMM ver 1.8
182 <7>eth0: no IPv6 routers present
183
185 All the tools can read dumped kernel images, using the common -t
186 memoryimage option. In addition you can capture memory images from
187 domains for post-mortem analysis using the "virt-mem capture" command
188 (see above).
189 The memory images which are saved by "virt-mem capture" contain a
191 header and some additional information about the kernel image, such as
192 architecture, original text address, and so forth. Thus these images
193 can be reanalysed just using the -t memoryimage option.
194 We also support analyzing raw kernel dumps, eg. produced using the
196 qemu(1) monitor's "memsave" command. In this case however you usually
197 need to specify the original architecture, text address and perhaps
198 other details using the -A, -T and other command line parameters.
199
201 The virt-mem tools spy on the guest's memory image. There are some
202 shortcomings to this, described here.
203 · Only works on specific, tested releases of Linux kernels. Support
205 for arbitrary Linux kernel versions may be patchy because of
206 changes in the internal structures used. Support for non-Linux
207 kernels is currently non-existent, and probably impossible for
208 Windows because of lack of an acceptable source license.
209 · Heuristics are used which may mean in the worst case that the
211 output is wrong.
212 · Structures which are frequently modified may cause errors. This
214 could be a problem if, for example, the process table in the guest
215 is being rapidly updated.
216 · We have to scan memory to find kernel symbols, etc., which can be
218 quite slow. Optimizing the memory scanner would help, and caching
219 the base address of the symbol table(s) would make it dramatically
220 faster.
221
223 The current code tries hard to be secure against malicious guests, for
224 example guests which set up malicious kernel memory.
225
227 uname(1), dmesg(1), virsh(1), virt-top(1), virt-df(1), xm(1), qemu(1),
228 <http://www.libvirt.org/ocaml/>, <http://www.libvirt.org/>,
229 <http://et.redhat.com/~rjones/>, <http://caml.inria.fr/>
230
232 Richard W.M. Jones <rjones @ redhat . com>
233
235 (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones http://libvirt.org/
236 This program is free software; you can redistribute it and/or modify it
238 under the terms of the GNU General Public License as published by the
239 Free Software Foundation; either version 2 of the License, or (at your
240 option) any later version.
241 This program is distributed in the hope that it will be useful, but
243 WITHOUT ANY WARRANTY; without even the implied warranty of
244 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
245 General Public License for more details.
246 You should have received a copy of the GNU General Public License along
248 with this program; if not, write to the Free Software Foundation, Inc.,
249 675 Mass Ave, Cambridge, MA 02139, USA.
250
252 Bugs can be viewed on the Red Hat Bugzilla page:
253 <https://bugzilla.redhat.com/>.
254 If you find a bug in virt-mem, please follow these steps to report it:
256 1. Check for existing bug reports
258 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
259 Someone may already have reported the same bug, and they may even
260 have fixed it.
261 2. Capture debug and error messages
263 Run
264 virt-program --debug > virt-mem.log 2>&1
266 and keep virt-mem.log. It contains error messages which you should
268 submit with your bug report.
269 3. Get version of virt-mem and version of libvirt.
271 Run
272 virt-program --version
274 4. Submit a bug report.
276 Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
277 describe the problem in as much detail as possible.
278 Remember to include the version numbers (step 3) and the debug
280 messages file (step 2).
281 5. Assign the bug to rjones @ redhat.com
283 Assign or reassign the bug to rjones @ redhat.com (without the
284 spaces). You can also send me an email with the bug number if you
285 want a faster response.
286virt-mem-0.2.9 2008-08-11 VIRT-MEM(1)