X-Git-Url: http://git.annexia.org/?p=virt-mem.git;a=blobdiff_plain;f=virt-mem.txt;h=4300f9d0b4018cf7a0f7682e3adb0aef360eb1ae;hp=a8ab3dc82e3194c01322028111ec54307adb541a;hb=9392e738c4c65284145e50644d463fc0aa05bbad;hpb=9414deeb6210c5f2c5219c6e99eb329b4bb1be26 diff --git a/virt-mem.txt b/virt-mem.txt index a8ab3dc..4300f9d 100644 --- a/virt-mem.txt +++ b/virt-mem.txt @@ -1,19 +1,63 @@ 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-ps - list processes for virtual machines + + virt-mem - tool with additional information output SUMMARY - virt-df [-options] + virt-uname [-options] [domains...] + + virt-dmesg [-options] [domains...] + + virt-ps [-options] [domains...] + + virt-mem uname [...] + + virt-mem dmesg [...] + + virt-mem ps [...] + + 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: - It uses libvirt so it is capable of showing stats across a variety of - different virtualization systems. + virt-*program* [-options] [domains...] -OPTIONS - -a, --all - Show all domains. The default is show only running (active) 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. + + 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. + + 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 @@ -23,81 +67,167 @@ OPTIONS 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). + --help + Display usage summary. - -i, --inodes - Display inode information. + --list-kernels + List which guest kernel versions are known/supported, then exit. - This option only works for Unix-like filesystems. + -t memoryimage + Post-mortem analysis mode. - --help - Display usage summary. + 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). - -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. + 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), , - , , - + uname(1), dmesg(1), virsh(1), virt-top(1), virt-df(1), xm(1), qemu(1), + , , + , AUTHORS Richard W.M. Jones 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 @@ -117,7 +247,7 @@ REPORTING BUGS Bugs can be viewed on the Red Hat Bugzilla page: . - 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 and search for similar bugs. @@ -127,15 +257,15 @@ REPORTING 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 and enter a new bug. Please