X-Git-Url: http://git.annexia.org/?p=virt-mem.git;a=blobdiff_plain;f=virt-mem.pod;h=1eec316c76dfa2f0f8839b9807b307ecb480b216;hp=f5dc3c34443d03230718ec234e47a6b31c30a518;hb=2e1de51e35bea53ebece1a6fd6d6970534f4cbe9;hpb=9414deeb6210c5f2c5219c6e99eb329b4bb1be26;ds=sidebyside diff --git a/virt-mem.pod b/virt-mem.pod index f5dc3c3..1eec316 100644 --- a/virt-mem.pod +++ b/virt-mem.pod @@ -1,27 +1,69 @@ =head1 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 =head1 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] =head1 DESCRIPTION -virt-df is a L-like utility for showing the actual disk usage -of guests. Many command line options are the same as for ordinary -I. +These virtualization tools allow you to inspect the status of virtual +machines running Linux. -It uses libvirt so it is capable of showing stats across a variety of -different virtualization systems. +These tools are designed to work like familiar Linux/Unix command line +tools. -=head1 OPTIONS +These tools all use libvirt so are capable of showing information +across a variety of different virtualization systems. -=over 4 +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. + +=head1 COMMON OPTIONS + +Each command obeys a common set of options. The general form is: + +virt-I [-options] [domains...] + +where I is a subtool such as C, C or C, and +I is a list of guest names to act on. If no domains are +specified then we act on all active domains by default. + +A I may be specified either by its name, by its ID or by its +UUID. Use I to get a list of active domain names and IDs. + +Equivalently you can use the C meta-tool with subcommands, +as in: -=item B<-a>, B<--all> +virt-mem I [...] -Show all domains. The default is show only running (active) domains. +The C program offers additional features, such as the +ability to capture VM images for post-mortem analysis (see below). + +=over 4 =item B<-c uri>, B<--connect uri> @@ -33,86 +75,197 @@ libvirt URI, normally Xen. 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. =item B<--debug> Emit debugging information on stderr. Please supply this if you report a bug. -=item B<-h>, B<--human-readable> - -Display human-readable sizes (eg. "10GiB" instead of large numbers). +=item B<--help> -=item B<-i>, B<--inodes> +Display usage summary. -Display inode information. +=item B<--list-kernels> -This option only works for Unix-like filesystems. +List which guest kernel versions are known/supported, then exit. -=item B<--help> +=item B<-t memoryimage> -Display usage summary. +Post-mortem analysis mode. -=item B<-t diskimage> +Instead of checking libvirt for domain information, this runs the tool +directly on the memory image supplied. You may specify the B<-t> +option multiple times. Use the C command to capture +images (see below). -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 B<-t> option multiple times. +See also the section L below. =item B<--version> Display version and exit. +=item B<-E auto|littleendian|bigendian> + +=item B<-T auto|i386|x86-64|I
|I> + +=item B<-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 I 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 (I<-E>) sets the memory endianness, for data, pointers and +so on. I<-E littleendian> is the endianness used on Intel i386, +x86-64 and (usually) IA64. I<-E bigendian> is the endianness used on +many RISC chips such as SPARC and PowerPC. + +Text address (I<-T>) sets the base address and optionally min and max +addresses of the kernel image. I<-T i386> means to try some common +addresses for i386-based kernels. I<-T x86-64> means to try some +common addresses for x86-64-based kernels. + +I<-T address> sets the kernel base address specifically (I<0x> prefix +is used to specify hex addresses). I<-T address,min,max> sets the +kernel base address, minimum address and maximum address. + +Word size (I<-W>) sets the word size, 32 or 64 bits. + +=item B<-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. + =back -=head1 EXAMPLE +=head1 virt-dmesg + +This prints the latest kernel messages from the virtual machine, as if +you were logged into the machine and used L. + +=head1 virt-uname + +This prints the contents of the system C structure, similar +to what is printed by the L command. + +=head1 virt-mem + +C 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 C you can +write: + + virt-mem dmesg [...] + +Options and other command line arguments work the same. + +Additional C subcommands are listed below. + +=head2 virt-mem capture -o memoryimage [-options] [domains...] + +Capture the memory image of a virtual machine for later post-mortem +analysis. Use the I<-t memoryimage> option for any other virt-mem +tool to analyze the memory image later. + +The I<-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 I file. However, if multiple guests are captured, +then their images are saved in I where I is +replaced with the domain ID. + +See also the section L below. + +=head1 EXAMPLES - # 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 + # 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 + +=head1 MEMORY IMAGES + +All the tools can read dumped kernel images, using the common +I<-t memoryimage> option. In addition you can capture memory +images from domains for post-mortem analysis using the +C command (see above). + +The memory images which are saved by C 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 I<-t memoryimage> option. + +We also support analyzing raw kernel dumps, eg. produced using the +L monitor's C command. In this case however you +usually need to specify the original architecture, text address and +perhaps other details using the I<-A>, I<-T> and other command line +parameters. =head1 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 L [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. + +=over + +=item * + +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. + +=item * + +Heuristics are used which may mean in the worst case that the +output is wrong. + +=item * + +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. + +=item * + +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. + +=back =head1 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. =head1 SEE ALSO -L, +L, +L, L, +L, +L, L, +L, L, L, L, @@ -124,7 +277,7 @@ Richard W.M. Jones =head1 COPYRIGHT -(C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones +(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 @@ -146,7 +299,7 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Bugs can be viewed on the Red Hat Bugzilla page: L. -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: =over 4 @@ -160,16 +313,16 @@ have fixed it. Run - virt-df --debug > virt-df.log 2>&1 +virt-I --debug > virt-mem.log 2>&1 -and keep I. It contains error messages which you should +and keep I. It contains error messages which you should submit with your bug report. -=item 3. Get version of virt-df and version of libvirt. +=item 3. Get version of virt-mem and version of libvirt. Run - virt-df --version +virt-I --version =item 4. Submit a bug report.