Extracted kernel structures for device addressing in ifconfig.

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

diff --git a/virt-mem.pod b/virt-mem.pod
index f5dc3c3..1eec316 100644 (file)
--- a/virt-mem.pod
+++ b/virt-mem.pod
@@ -1,27 +1,69 @@
 =head1 NAME
 
 =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
 
 
 =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
 
 
 =head1 DESCRIPTION
 

-virt-df is a L<df(1)>-like utility for showing the actual disk usage
-of guests.  Many command line options are the same as for ordinary
-I<df>.
+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<program> [-options] [domains...]
+
+where I<program> is a subtool such as C<uname>, C<dmesg> or C<ps>, and
+I<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 I<domain> may be specified either by its name, by its ID or by its
+UUID.  Use I<virsh list> to get a list of active domain names and IDs.
+
+Equivalently you can use the C<virt-mem> meta-tool with subcommands,
+as in:

 
 

-=item B<-a>, B<--all>
+virt-mem I<program> [...]

 
 

-Show all domains.  The default is show only running (active) domains.
+The C<virt-mem> 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>
 
 
 =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.
 
 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<--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<virt-mem capture> 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</"MEMORY IMAGES"> below.

 
 =item B<--version>
 
 Display version and exit.
 
 
 =item B<--version>
 
 Display version and exit.
 

+=item B<-E auto|littleendian|bigendian>
+
+=item B<-T auto|i386|x86-64|I<address>|I<address,min,max>>
+
+=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<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 (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
 
 =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<dmesg(1)>.
+
+=head1 virt-uname
+
+This prints the contents of the system C<utsname> structure, similar
+to what is printed by the L<uname(1)> command.
+
+=head1 virt-mem
+
+C<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 C<virt-dmesg> you can
+write:
+
+ virt-mem dmesg [...]
+
+Options and other command line arguments work the same.
+
+Additional C<virt-mem> 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<memoryimage> file.  However, if multiple guests are captured,
+then their images are saved in I<memoryimage.ID> where I<ID> is
+replaced with the domain ID.
+
+See also the section L</"MEMORY IMAGES"> 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<virt-mem capture> command (see above).
+
+The memory images which are saved by C<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 I<-t memoryimage> option.
+
+We also support analyzing raw kernel dumps, eg. produced using the
+L<qemu(1)> monitor's C<memsave> 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
 
 
 =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<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.
+
+=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
 
 =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
 
 
 =head1 SEE ALSO
 

-L<df(1)>,
+L<uname(1)>,
+L<dmesg(1)>,

 L<virsh(1)>,
 L<virsh(1)>,

+L<virt-top(1)>,
+L<virt-df(1)>,

 L<xm(1)>,
 L<xm(1)>,

+L<qemu(1)>,

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


@@ -124,7 +277,7 @@ Richard W.M. Jones <rjones @ redhat . com>
 
 =head1 COPYRIGHT
 
 
 =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
 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<https://bugzilla.redhat.com/>.
 
 Bugs can be viewed on the Red Hat Bugzilla page:
 L<https://bugzilla.redhat.com/>.
 

-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
 
 
 =over 4
 


@@ -160,16 +313,16 @@ have fixed it.
 
 Run
 
 
 Run
 

- virt-df --debug > virt-df.log 2>&1
+virt-I<program> --debug > virt-mem.log 2>&1

 
 

-and keep I<virt-df.log>.  It contains error messages which you should
+and keep I<virt-mem.log>.  It contains error messages which you should

 submit with your bug report.
 
 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
 
 
 Run
 

- virt-df --version
+virt-I<program> --version

 
 =item 4. Submit a bug report.
 
 
 =item 4. Submit a bug report.