X-Git-Url: http://git.annexia.org/?p=virt-mem.git;a=blobdiff_plain;f=virt-mem.txt;h=4300f9d0b4018cf7a0f7682e3adb0aef360eb1ae;hp=bac5e16047158e22b6f5e186701203a6cd16a6d6;hb=2e1de51e35bea53ebece1a6fd6d6970534f4cbe9;hpb=06b518ff4c3e74d9025a5a7b19c90527e5697a0e

diff --git a/virt-mem.txt b/virt-mem.txt
index bac5e16..4300f9d 100644
--- a/virt-mem.txt
+++ b/virt-mem.txt
@@ -3,31 +3,61 @@ NAME
 
     virt-dmesg - print kernel messages for virtual machines
 
+    virt-ps - list processes for virtual machines
+
+    virt-mem - tool with additional information output
+
 SUMMARY
     virt-uname [-options] [domains...]
 
     virt-dmesg [-options] [domains...]
 
+    virt-ps [-options] [domains...]
+
+    virt-mem uname [...]
+
+    virt-mem dmesg [...]
+
+    virt-mem ps [...]
+
+    virt-mem [-options]
+
 DESCRIPTION
     These virtualization tools allow you to inspect the status of virtual
     machines running Linux.
 
-    The tools all use libvirt so are capable of showing stats across a
-    variety of different virtualization systems.
+    These tools are designed to work like familiar Linux/Unix command line
+    tools.
+
+    These tools all use libvirt so are capable of showing information across
+    a variety of different virtualization systems.
+
+    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.
 
 COMMON OPTIONS
     Each command obeys a common set of options. The general form is:
 
     virt-*program* [-options] [domains...]
 
-    where *domains* is a list of guest names to act on. If no domains are
+    where *program* is a subtool such as "uname", "dmesg" or "ps", and
+    *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 *domain* may be specified either by its name or by its ID. Use *virsh
-    list* to get a list of active domain names and IDs.
+    A *domain* may be specified either by its name, by its ID or by its
+    UUID. Use *virsh list* to get a list of active domain names and IDs.
 
-    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.
+    Equivalently you can use the "virt-mem" meta-tool with subcommands, as
+    in:
+
+    virt-mem *program* [...]
+
+    The "virt-mem" program offers additional features, such as the ability
+    to capture VM images for post-mortem analysis (see below).
 
     -c uri, --connect uri
         Connect to libvirt URI. The default is to connect to the default
@@ -47,16 +77,24 @@ COMMON OPTIONS
     --help
         Display usage summary.
 
+    --list-kernels
+        List which guest kernel versions are known/supported, then exit.
+
     -t memoryimage
-        Test mode. Instead of checking libvirt for domain information, this
-        runs the virt-mem tool directly on the memory image supplied. You
-        may specify the -t option multiple times.
+        Post-mortem analysis mode.
+
+        Instead of checking libvirt for domain information, this runs the
+        tool directly on the memory image supplied. You may specify the -t
+        option multiple times. Use the "virt-mem capture" command to capture
+        images (see below).
+
+        See also the section "MEMORY IMAGES" below.
 
     --version
         Display version and exit.
 
     -E auto|littleendian|bigendian
-    -T auto|i386|x86-64|*address*
+    -T auto|i386|x86-64|*address*|*address,min,max*
     -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
@@ -68,13 +106,18 @@ COMMON OPTIONS
         detection wrong.
 
         Endianness (*-E*) sets the memory endianness, for data, pointers and
-        so on.
+        so on. *-E littleendian* is the endianness used on Intel i386,
+        x86-64 and (usually) IA64. *-E bigendian* is the endianness used on
+        many RISC chips such as SPARC and PowerPC.
+
+        Text address (*-T*) sets the base address and optionally min and max
+        addresses of the kernel image. *-T i386* means to try some common
+        addresses for i386-based kernels. *-T x86-64* means to try some
+        common addresses for x86-64-based kernels.
 
-        Text address (*-T*) sets the base address of the kernel image. *-T
-        i386* means to try some common addresses for i386-based kernels. *-T
-        x86-64* means to try some common addresses for x86-64-based kernels.
-        *-T *address** sets the address specifically (*0x* prefix is allowed
-        to specify hex addresses).
+        *-T address* sets the kernel base address specifically (*0x* prefix
+        is used to specify hex addresses). *-T address,min,max* sets the
+        kernel base address, minimum address and maximum address.
 
         Word size (*-W*) sets the word size, 32 or 64 bits.
 
@@ -83,6 +126,39 @@ COMMON OPTIONS
         architectures. It is equivalent to setting endianness and wordsize
         in one go, but not text address.
 
+virt-dmesg
+    This prints the latest kernel messages from the virtual machine, as if
+    you were logged into the machine and used dmesg(1).
+
+virt-uname
+    This prints the contents of the system "utsname" structure, similar to
+    what is printed by the uname(1) command.
+
+virt-mem
+    "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 "virt-dmesg" you can write:
+
+     virt-mem dmesg [...]
+
+    Options and other command line arguments work the same.
+
+    Additional "virt-mem" subcommands are listed below.
+
+  virt-mem capture -o memoryimage [-options] [domains...]
+    Capture the memory image of a virtual machine for later post-mortem
+    analysis. Use the *-t memoryimage* option for any other virt-mem tool to
+    analyze the memory image later.
+
+    The *-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
+    *memoryimage* file. However, if multiple guests are captured, then their
+    images are saved in *memoryimage.ID* where *ID* is replaced with the
+    domain ID.
+
+    See also the section "MEMORY IMAGES" below.
+
 EXAMPLES
      # virt-uname
      f9x32kvm: Linux localhost.localdomain 2.6.24-0.155.rc7.git6.fc9 #1
@@ -100,35 +176,52 @@ EXAMPLES
      <6>Bluetooth: RFCOMM ver 1.8
      <7>eth0: no IPv6 routers present
 
+MEMORY IMAGES
+    All the tools can read dumped kernel images, using the common *-t
+    memoryimage* option. In addition you can capture memory images from
+    domains for post-mortem analysis using the "virt-mem capture" command
+    (see above).
+
+    The memory images which are saved by "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 *-t memoryimage* option.
+
+    We also support analyzing raw kernel dumps, eg. produced using the
+    qemu(1) monitor's "memsave" command. In this case however you usually
+    need to specify the original architecture, text address and perhaps
+    other details using the *-A*, *-T* and other command line parameters.
+
 SHORTCOMINGS
     The virt-mem tools spy on the guest's memory image. There are some
     shortcomings to this, described here.
 
-    (1) 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.
+    *   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.
 
-    (2) Heuristics are used which may mean in the worst case that the output
-    is wrong.
+    *   Heuristics are used which may mean in the worst case that the output
+        is wrong.
 
-    (3) 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.
+    *   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.
 
-    (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.
+    *   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.
 
 SECURITY
     The current code tries hard to be secure against malicious guests, for
     example guests which set up malicious kernel memory.
 
 SEE ALSO
-    uname(1), dmesg(1), virsh(1), xm(1), <http://www.libvirt.org/ocaml/>,
-    <http://www.libvirt.org/>, <http://et.redhat.com/~rjones/>,
-    <http://caml.inria.fr/>
+    uname(1), dmesg(1), virsh(1), virt-top(1), virt-df(1), xm(1), qemu(1),
+    <http://www.libvirt.org/ocaml/>, <http://www.libvirt.org/>,
+    <http://et.redhat.com/~rjones/>, <http://caml.inria.fr/>
 
 AUTHORS
     Richard W.M. Jones <rjones @ redhat . com>