-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
..
.\" 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 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.
.\" ========================================================================
.\"
.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
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),
<http://www.libvirt.org/ocaml/>,
<http://www.libvirt.org/>,
<http://et.redhat.com/~rjones/>,
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
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.
.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 <https://bugzilla.redhat.com/> and enter a new bug.
git.annexia.org / virt-mem.git / blobdiff