Combined binary.

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

diff --git a/virt-mem.txt b/virt-mem.txt
index bac5e16..9c00d79 100644 (file)
--- a/virt-mem.txt
+++ b/virt-mem.txt
@@ -3,31 +3,55 @@ NAME
 
     virt-dmesg - print kernel messages for virtual machines
 
 
     virt-dmesg - print kernel messages for virtual machines
 

+    virt-mem - tool with additional information output
+

 SUMMARY
     virt-uname [-options] [domains...]
 
     virt-dmesg [-options] [domains...]
 
 SUMMARY
     virt-uname [-options] [domains...]
 
     virt-dmesg [-options] [domains...]
 

+    virt-mem uname [...]
+
+    virt-mem dmesg [...]
+
+    virt-mem [-options]
+

 DESCRIPTION
     These virtualization tools allow you to inspect the status of virtual
     machines running Linux.
 
 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...]
 
 
 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.
 
     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
 
     -c uri, --connect uri
         Connect to libvirt URI. The default is to connect to the default


@@ -48,9 +72,14 @@ COMMON OPTIONS
         Display usage summary.
 
     -t memoryimage
         Display usage summary.
 
     -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.
 
     --version
         Display version and exit.


@@ -68,13 +97,15 @@ COMMON OPTIONS
         detection wrong.
 
         Endianness (*-E*) sets the memory endianness, for data, pointers and
         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 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 address specifically (*0x* prefix is used to
+        specify hex addresses).

 
         Word size (*-W*) sets the word size, 32 or 64 bits.
 
 
         Word size (*-W*) sets the word size, 32 or 64 bits.
 


@@ -83,6 +114,39 @@ COMMON OPTIONS
         architectures. It is equivalent to setting endianness and wordsize
         in one go, but not text address.
 
         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
 EXAMPLES
      # virt-uname
      f9x32kvm: Linux localhost.localdomain 2.6.24-0.155.rc7.git6.fc9 #1


@@ -100,35 +164,52 @@ EXAMPLES
      <6>Bluetooth: RFCOMM ver 1.8
      <7>eth0: no IPv6 routers present
 
      <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.
 
 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
 
 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>
 
 AUTHORS
     Richard W.M. Jones <rjones @ redhat . com>