NAME
- virt-df - 'df'-like utility for virtualization stats
+ virt-uname - system information for virtual machines
+
+ virt-dmesg - print kernel messages for virtual machines
+
+ virt-mem - tool with additional information output
SUMMARY
- virt-df [-options]
+ virt-uname [-options] [domains...]
+
+ virt-dmesg [-options] [domains...]
+
+ virt-mem uname [...]
+
+ virt-mem dmesg [...]
+
+ virt-mem [-options]
DESCRIPTION
- virt-df is a df(1)-like utility for showing the actual disk usage of
- guests. Many command line options are the same as for ordinary *df*.
+ These virtualization tools allow you to inspect the status of virtual
+ machines running Linux.
+
+ 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 *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.
- It uses libvirt so it is capable of showing stats across a variety of
- different virtualization systems.
+ 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.
-OPTIONS
- -a, --all
- Show all domains. The default is show only running (active) 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
Print the results in CSV format, suitable for importing into a
spreadsheet or database.
- This option is only supported if virt-df was built with CSV support.
+ This option is only supported if virt-mem was built with CSV
+ support.
--debug
Emit debugging information on stderr. Please supply this if you
report a bug.
- -h, --human-readable
- Display human-readable sizes (eg. "10GiB" instead of large numbers).
-
- -i, --inodes
- Display inode information.
-
- This option only works for Unix-like filesystems.
-
--help
Display usage summary.
- -t diskimage
- Test mode. Instead of checking libvirt for domain information, this
- runs virt-df directly on the disk image (or device) supplied. You
- may specify the -t option multiple times.
+ -t memoryimage
+ 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.
-EXAMPLE
- # virt-df
- Filesystem 1K-blocks Used Available Type
- f9x32kvm:hda1 190740 24817 165923 Linux ext2/3
- f9x32kvm:VolGroup/LogVol00 6568348 3401656 3166692 Linux ext2/3
- f9x32kvm:VolGroup/LogVol01 1015808 Linux swap
+ -E auto|littleendian|bigendian
+ -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
+ are listed, then for all domains).
+
+ These default to *auto* which tries to do automatic detection (using
+ libvirt, or details from the memory images themselves). You only
+ need to use these options if virt-mem tools get the automatic
+ detection wrong.
+
+ Endianness (*-E*) sets the memory endianness, for data, pointers and
+ 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.
+
+ *-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.
+
+ -A auto|i386|x86-64|...
+ This option sets the architecture to one of a collection of known
+ 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
+ SMP Tue Jan 15 17:52:31 EST 2008 i686 (none)
+
+ # virt-dmesg f9x32kvm | tail
+ <6>Bluetooth: Core ver 2.11
+ <6>NET: Registered protocol family 31
+ <6>Bluetooth: HCI device and connection manager initialized
+ <6>Bluetooth: HCI socket layer initialized
+ <6>Bluetooth: L2CAP ver 2.9
+ <6>Bluetooth: L2CAP socket layer initialized
+ <6>Bluetooth: RFCOMM socket layer initialized
+ <6>Bluetooth: RFCOMM TTY layer initialized
+ <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
- virt-df spies on the guest's disk image to try to work out how much disk
- space it is actually using. There are some shortcomings to this,
- described here.
-
- (1) It only understands a limited set of partition types. Assuming that
- the files and partitions that we get back from libvirt / Xen correspond
- to block devices in the guests, we can go some way towards manually
- parsing those partitions to find out what they contain. We can read the
- MBR, LVM, superblocks and so on. However that's a lot of parsing work,
- and currently there is no library which understands a wide range of
- partition schemes and filesystem types (not even libparted which doesn't
- support LVM yet). The Linux kernel does support that, but there's not
- really any good way to access that work.
-
- The current implementation uses a hand-coded parser which understands
- some formats (MBR, LVM2, ext2/3, DOS FAT, Windows NTFS, Linux swap and
- Linux suspend partitions).
-
- (2) The statistics you get are delayed. The real state of, for example,
- an ext2 filesystem is only stored in the memory of the guest's kernel.
- The ext2 superblock contains some meta-information about blocks used and
- free, but this superblock is not up to date. In fact the guest kernel
- may not update it even on a 'sync', not until the filesystem is
- unmounted. Some operations do appear to write the superblock, for
- example fsync(2) [that is my reading of the ext2/3 source code at
- least].
+ The virt-mem tools spy on the guest's memory image. There are some
+ shortcomings to this, described here.
+
+ * 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.
+
+ * Heuristics are used which may mean in the worst case that the output
+ is wrong.
+
+ * 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.
+
+ * 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 disk partitions.
+ example guests which set up malicious kernel memory.
SEE ALSO
- df(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>
COPYRIGHT
- (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
- http://libvirt.org/
+ (C) Copyright 2008 Red Hat Inc., Richard W.M. Jones http://libvirt.org/
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Bugs can be viewed on the Red Hat Bugzilla page:
<https://bugzilla.redhat.com/>.
- If you find a bug in virt-df, please follow these steps to report it:
+ If you find a bug in virt-mem, please follow these steps to report it:
1. Check for existing bug reports
Go to <https://bugzilla.redhat.com/> and search for similar bugs.
2. Capture debug and error messages
Run
- virt-df --debug > virt-df.log 2>&1
+ virt-*program* --debug > virt-mem.log 2>&1
- and keep *virt-df.log*. It contains error messages which you should
+ and keep *virt-mem.log*. It contains error messages which you should
submit with your bug report.
- 3. Get version of virt-df and version of libvirt.
+ 3. Get version of virt-mem and version of libvirt.
Run
- virt-df --version
+ virt-*program* --version
4. Submit a bug report.
Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
git.annexia.org / virt-mem.git / blobdiff