X-Git-Url: http://git.annexia.org/?p=virt-mem.git;a=blobdiff_plain;f=virt-mem.1;h=94be74db79a0719279c3620446a424117fd89e77;hp=9f4bf5993efb0aaf7ddea5f6cc9d4d7271a90988;hb=bfc24fb66bd8694724f69f192282283d7bcc5538;hpb=9414deeb6210c5f2c5219c6e99eb329b4bb1be26 diff --git a/virt-mem.1 b/virt-mem.1 index 9f4bf59..94be74d 100644 --- a/virt-mem.1 +++ b/virt-mem.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05) .\" .\" Standard preamble: .\" ======================================================================== @@ -25,11 +25,11 @@ .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- @@ -48,22 +48,25 @@ . ds R" '' 'br\} .\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. -.if \nF \{\ +.ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na +.el \{\ +. de IX +.. +.\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -129,25 +132,65 @@ .\" ======================================================================== .\" .IX Title "VIRT-MEM 1" -.TH VIRT-MEM 1 "2008-06-10" "virt-mem-0.2.1" "Virtualization Support" +.TH VIRT-MEM 1 "2008-07-24" "virt-mem-0.2.7" "Virtualization Support" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh .SH "NAME" -virt\-df \- 'df'\-like utility for virtualization stats +virt\-uname \- system information for virtual machines +.PP +virt\-dmesg \- print kernel messages for virtual machines +.PP +virt\-mem \- tool with additional information output .SH "SUMMARY" .IX Header "SUMMARY" -virt-df [\-options] +virt-uname [\-options] [domains...] +.PP +virt-dmesg [\-options] [domains...] +.PP +virt-mem uname [...] +.PP +virt-mem dmesg [...] +.PP +virt-mem [\-options] .SH "DESCRIPTION" .IX Header "DESCRIPTION" -virt-df is a \fIdf\fR\|(1)\-like utility for showing the actual disk usage -of guests. Many command line options are the same as for ordinary -\&\fIdf\fR. +These virtualization tools allow you to inspect the status of virtual +machines running Linux. +.PP +These tools are designed to work like familiar Linux/Unix command line +tools. +.PP +These tools all use libvirt so are capable of showing information +across a variety of different virtualization systems. +.PP +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. +.SH "COMMON OPTIONS" +.IX Header "COMMON OPTIONS" +Each command obeys a common set of options. The general form is: +.PP +virt\-\fIprogram\fR [\-options] [domains...] +.PP +where \fIprogram\fR is a subtool such as \f(CW\*(C`uname\*(C'\fR, \f(CW\*(C`dmesg\*(C'\fR or \f(CW\*(C`ps\*(C'\fR, and +\&\fIdomains\fR is a list of guest names to act on. If no domains are +specified then we act on all active domains by default. +.PP +A \fIdomain\fR may be specified either by its name, by its \s-1ID\s0 or by its +\&\s-1UUID\s0. Use \fIvirsh list\fR to get a list of active domain names and IDs. +.PP +Equivalently you can use the \f(CW\*(C`virt\-mem\*(C'\fR meta-tool with subcommands, +as in: +.PP +virt-mem \fIprogram\fR [...] .PP -It uses libvirt so it is capable of showing stats across a variety of -different virtualization systems. -.SH "OPTIONS" -.IX Header "OPTIONS" -.IP "\fB\-a\fR, \fB\-\-all\fR" 4 -.IX Item "-a, --all" -Show all domains. The default is show only running (active) domains. +The \f(CW\*(C`virt\-mem\*(C'\fR program offers additional features, such as the +ability to capture \s-1VM\s0 images for post-mortem analysis (see below). .IP "\fB\-c uri\fR, \fB\-\-connect uri\fR" 4 .IX Item "-c uri, --connect uri" Connect to libvirt \s-1URI\s0. The default is to connect to the default @@ -157,76 +200,170 @@ libvirt \s-1URI\s0, normally Xen. Print the results in \s-1CSV\s0 format, suitable for importing into a spreadsheet or database. .Sp -This option is only supported if virt-df was built with \s-1CSV\s0 support. +This option is only supported if virt-mem was built with \s-1CSV\s0 support. .IP "\fB\-\-debug\fR" 4 .IX Item "--debug" Emit debugging information on stderr. Please supply this if you report a bug. -.IP "\fB\-h\fR, \fB\-\-human\-readable\fR" 4 -.IX Item "-h, --human-readable" -Display human-readable sizes (eg. \*(L"10GiB\*(R" instead of large numbers). -.IP "\fB\-i\fR, \fB\-\-inodes\fR" 4 -.IX Item "-i, --inodes" -Display inode information. -.Sp -This option only works for Unix-like filesystems. .IP "\fB\-\-help\fR" 4 .IX Item "--help" Display usage summary. -.IP "\fB\-t diskimage\fR" 4 -.IX Item "-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 \fB\-t\fR option multiple times. +.IP "\fB\-t memoryimage\fR" 4 +.IX Item "-t memoryimage" +Post-mortem analysis mode. +.Sp +Instead of checking libvirt for domain information, this runs the tool +directly on the memory image supplied. You may specify the \fB\-t\fR +option multiple times. Use the \f(CW\*(C`virt\-mem capture\*(C'\fR command to capture +images (see below). +.Sp +See also the section \*(L"\s-1MEMORY\s0 \s-1IMAGES\s0\*(R" below. .IP "\fB\-\-version\fR" 4 .IX Item "--version" Display version and exit. -.SH "EXAMPLE" -.IX Header "EXAMPLE" -.Vb 5 -\& # 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 +.IP "\fB\-E auto|littleendian|bigendian\fR" 4 +.IX Item "-E auto|littleendian|bigendian" +.PD 0 +.IP "\fB\-T auto|i386|x86\-64|\f(BIaddress\fB|\f(BIaddress,min,max\fB\fR" 4 +.IX Item "-T auto|i386|x86-64|address|address,min,max" +.IP "\fB\-W auto|32|64\fR" 4 +.IX Item "-W auto|32|64" +.PD +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). +.Sp +These default to \fIauto\fR 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. +.Sp +Endianness (\fI\-E\fR) sets the memory endianness, for data, pointers and +so on. \fI\-E littleendian\fR is the endianness used on Intel i386, +x86\-64 and (usually) \s-1IA64\s0. \fI\-E bigendian\fR is the endianness used on +many \s-1RISC\s0 chips such as \s-1SPARC\s0 and PowerPC. +.Sp +Text address (\fI\-T\fR) sets the base address and optionally min and max +addresses of the kernel image. \fI\-T i386\fR means to try some common +addresses for i386\-based kernels. \fI\-T x86\-64\fR means to try some +common addresses for x86\-64\-based kernels. +.Sp +\&\fI\-T address\fR sets the kernel base address specifically (\fI0x\fR prefix +is used to specify hex addresses). \fI\-T address,min,max\fR sets the +kernel base address, minimum address and maximum address. +.Sp +Word size (\fI\-W\fR) sets the word size, 32 or 64 bits. +.IP "\fB\-A auto|i386|x86\-64|...\fR" 4 +.IX Item "-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. +.SH "virt-dmesg" +.IX Header "virt-dmesg" +This prints the latest kernel messages from the virtual machine, as if +you were logged into the machine and used \fIdmesg\fR\|(1). +.SH "virt-uname" +.IX Header "virt-uname" +This prints the contents of the system \f(CW\*(C`utsname\*(C'\fR structure, similar +to what is printed by the \fIuname\fR\|(1) command. +.SH "virt-mem" +.IX Header "virt-mem" +\&\f(CW\*(C`virt\-mem\*(C'\fR is a meta-tool which allows you to run all the commands +above, and provides some extra features. +.PP +Instead of the preceeding commands such as \f(CW\*(C`virt\-dmesg\*(C'\fR you can +write: +.PP +.Vb 1 +\& virt\-mem dmesg [...] .Ve -.SH "SHORTCOMINGS" -.IX Header "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. .PP -(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 \s-1MBR\s0, \s-1LVM\s0, 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 \s-1LVM\s0 yet). The Linux kernel does -support that, but there's not really any good way to access that work. +Options and other command line arguments work the same. +.PP +Additional \f(CW\*(C`virt\-mem\*(C'\fR subcommands are listed below. +.Sh "virt-mem capture \-o memoryimage [\-options] [domains...]" +.IX Subsection "virt-mem capture -o memoryimage [-options] [domains...]" +Capture the memory image of a virtual machine for later post-mortem +analysis. Use the \fI\-t memoryimage\fR option for any other virt-mem +tool to analyze the memory image later. +.PP +The \fI\-o memoryimage\fR option is required, and is used to name the +output file. If a single guest is captured, then the output is saved +in the \fImemoryimage\fR file. However, if multiple guests are captured, +then their images are saved in \fImemoryimage.ID\fR where \fI\s-1ID\s0\fR is +replaced with the domain \s-1ID\s0. .PP -The current implementation uses a hand-coded parser which understands -some formats (\s-1MBR\s0, \s-1LVM2\s0, ext2/3, \s-1DOS\s0 \s-1FAT\s0, Windows \s-1NTFS\s0, Linux swap and -Linux suspend partitions). +See also the section \*(L"\s-1MEMORY\s0 \s-1IMAGES\s0\*(R" below. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.Vb 3 +\& # 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 +.Ve +.SH "MEMORY IMAGES" +.IX Header "MEMORY IMAGES" +All the tools can read dumped kernel images, using the common +\&\fI\-t memoryimage\fR option. In addition you can capture memory +images from domains for post-mortem analysis using the +\&\f(CW\*(C`virt\-mem capture\*(C'\fR command (see above). +.PP +The memory images which are saved by \f(CW\*(C`virt\-mem capture\*(C'\fR 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 \fI\-t memoryimage\fR option. .PP -(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 \fIfsync\fR\|(2) [that is my reading of the ext2/3 -source code at least]. +We also support analyzing raw kernel dumps, eg. produced using the +\&\fIqemu\fR\|(1) monitor's \f(CW\*(C`memsave\*(C'\fR command. In this case however you +usually need to specify the original architecture, text address and +perhaps other details using the \fI\-A\fR, \fI\-T\fR and other command line +parameters. +.SH "SHORTCOMINGS" +.IX Header "SHORTCOMINGS" +The virt-mem tools spy on the guest's memory image. There are some +shortcomings to this, described here. +.IP "\(bu" 4 +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. +.IP "\(bu" 4 +Heuristics are used which may mean in the worst case that the +output is wrong. +.IP "\(bu" 4 +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. +.IP "\(bu" 4 +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. .SH "SECURITY" .IX Header "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. .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fIdf\fR\|(1), +\&\fIuname\fR\|(1), +\&\fIdmesg\fR\|(1), \&\fIvirsh\fR\|(1), +\&\fIvirt\-top\fR\|(1), +\&\fIvirt\-df\fR\|(1), \&\fIxm\fR\|(1), +\&\fIqemu\fR\|(1), , , , @@ -236,7 +373,7 @@ example guests which set up malicious disk partitions. Richard W.M. Jones .SH "COPYRIGHT" .IX Header "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/ .PP This program is free software; you can redistribute it and/or modify @@ -257,7 +394,7 @@ Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0. Bugs can be viewed on the Red Hat Bugzilla page: . .PP -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: .IP "1. Check for existing bug reports" 4 .IX Item "1. Check for existing bug reports" Go to and search for similar bugs. @@ -267,19 +404,15 @@ have fixed it. .IX Item "2. Capture debug and error messages" Run .Sp -.Vb 1 -\& virt-df --debug > virt-df.log 2>&1 -.Ve +virt\-\fIprogram\fR \-\-debug > virt\-mem.log 2>&1 .Sp -and keep \fIvirt\-df.log\fR. It contains error messages which you should +and keep \fIvirt\-mem.log\fR. It contains error messages which you should submit with your bug report. -.IP "3. Get version of virt-df and version of libvirt." 4 -.IX Item "3. Get version of virt-df and version of libvirt." +.IP "3. Get version of virt-mem and version of libvirt." 4 +.IX Item "3. Get version of virt-mem and version of libvirt." Run .Sp -.Vb 1 -\& virt-df --version -.Ve +virt\-\fIprogram\fR \-\-version .IP "4. Submit a bug report." 4 .IX Item "4. Submit a bug report." Go to and enter a new bug.