Add .gitignore file for git.

[virt-mem.git] / virt-mem.1

diff --git a/virt-mem.1 b/virt-mem.1
index 9f4bf59..33a3d24 100644 (file)
--- 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:
 .\" ========================================================================
 .\"
 .\" 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
 ..
 .\" 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-
 .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\}
 .\"
 .    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 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
 .\}
 .    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.
 .\"
 .\" 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,71 @@
 .\" ========================================================================
 .\"
 .IX Title "VIRT-MEM 1"
 .\" ========================================================================
 .\"
 .IX Title "VIRT-MEM 1"

-.TH VIRT-MEM 1 "2008-06-10" "virt-mem-0.2.1" "Virtualization Support"
+.TH VIRT-MEM 1 "2008-08-11" "virt-mem-0.2.9" "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"
 .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\-ps \- list processes for virtual machines
+.PP
+virt\-mem \- tool with additional information output

 .SH "SUMMARY"
 .IX Header "SUMMARY"
 .SH "SUMMARY"
 .IX Header "SUMMARY"

-virt-df [\-options]
+virt-uname [\-options] [domains...]
+.PP
+virt-dmesg [\-options] [domains...]
+.PP
+virt-ps [\-options] [domains...]
+.PP
+virt-mem uname [...]
+.PP
+virt-mem dmesg [...]
+.PP
+virt-mem ps [...]
+.PP
+virt-mem [\-options]

 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 .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.
-.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.
+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
+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
 .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 +206,173 @@ libvirt \s-1URI\s0, normally Xen.
 Print the results in \s-1CSV\s0 format, suitable for importing into a
 spreadsheet or database.
 .Sp
 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\-\-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\-\-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\-\-list\-kernels\fR" 4
+.IX Item "--list-kernels"
+List which guest kernel versions are known/supported, then exit.
+.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.
 .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
+.PP
+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
+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
 .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
+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"
 .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.
-.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).
-.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].
+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
 .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"
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"

-\&\fIdf\fR\|(1),
+\&\fIuname\fR\|(1),
+\&\fIdmesg\fR\|(1),

 \&\fIvirsh\fR\|(1),
 \&\fIvirsh\fR\|(1),

+\&\fIvirt\-top\fR\|(1),
+\&\fIvirt\-df\fR\|(1),

 \&\fIxm\fR\|(1),
 \&\fIxm\fR\|(1),

+\&\fIqemu\fR\|(1),

 <http://www.libvirt.org/ocaml/>,
 <http://www.libvirt.org/>,
 <http://et.redhat.com/~rjones/>,
 <http://www.libvirt.org/ocaml/>,
 <http://www.libvirt.org/>,
 <http://et.redhat.com/~rjones/>,


@@ -236,7 +382,7 @@ example guests which set up malicious disk partitions.
 Richard W.M. Jones <rjones @ redhat . com>
 .SH "COPYRIGHT"
 .IX Header "COPYRIGHT"
 Richard W.M. Jones <rjones @ redhat . com>
 .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
 http://libvirt.org/
 .PP
 This program is free software; you can redistribute it and/or modify


@@ -257,7 +403,7 @@ Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
 Bugs can be viewed on the Red Hat Bugzilla page:
 <https://bugzilla.redhat.com/>.
 .PP
 Bugs can be viewed on the Red Hat Bugzilla page:
 <https://bugzilla.redhat.com/>.
 .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 <https://bugzilla.redhat.com/> and search for similar bugs.
 .IP "1. Check for existing bug reports" 4
 .IX Item "1. Check for existing bug reports"
 Go to <https://bugzilla.redhat.com/> and search for similar bugs.


@@ -267,19 +413,15 @@ have fixed it.
 .IX Item "2. Capture debug and error messages"
 Run
 .Sp
 .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
 .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.
 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
 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 <https://bugzilla.redhat.com/> and enter a new bug.
 .IP "4. Submit a bug report." 4
 .IX Item "4. Submit a bug report."
 Go to <https://bugzilla.redhat.com/> and enter a new bug.