Combined binary.
authorRichard W.M. Jones <rjones@redhat.com>
Tue, 15 Jul 2008 12:51:45 +0000 (13:51 +0100)
committerRichard W.M. Jones <rjones@redhat.com>
Tue, 15 Jul 2008 12:51:45 +0000 (13:51 +0100)
 - Link all programs into a single binary to save on disk space.
 - Changed help system to understand this.
 - Additions to manpage.
 - Updated MANIFEST.
 - Added HACKING file describing new code layout.
 - Updated PO files.

25 files changed:
.hgignore
HACKING [new file with mode: 0644]
MANIFEST
Makefile.in
README
configure.ac
dmesg/Makefile.in
dmesg/virt_dmesg.ml
lib/virt_mem.ml
lib/virt_mem.mli
lib/virt_mem_utils.ml
mem/.depend [new file with mode: 0644]
mem/Makefile.in [new file with mode: 0644]
mem/virt_mem_main.ml [new file with mode: 0644]
po/ja.po
po/pl.po
po/pt_BR.po
po/virt-mem.pot
ps/Makefile.in
ps/virt_ps.ml
uname/Makefile.in
uname/virt_uname.ml
virt-mem.1
virt-mem.pod
virt-mem.txt

index 8824d7d..cfb9c0e 100644 (file)
--- a/.hgignore
+++ b/.hgignore
@@ -27,5 +27,6 @@ po/*.po.orig
 uname/virt-uname
 dmesg/virt-dmesg
 ps/virt-ps
+mem/virt-mem
 samples
 lib/*.so
diff --git a/HACKING b/HACKING
new file mode 100644 (file)
index 0000000..82f4461
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,19 @@
+We build all the tools into a single virt-mem executable, in order to
+share the most runtime.  Almost all the code between individual tools
+is shared anyway.
+
+lib/
+
+ - The common core of all the tools.  Library, kernel symbols, command
+   line handling, memory images, etc.
+
+uname/
+dmesg/
+  etc.
+
+ - The code specific to each tool, usually rather small.
+
+mem/
+
+ - This brings everything together and links it into a single executable.
+   Other than that purpose, there is almost nothing in this directory.
index accccbd..976b11f 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -5,6 +5,7 @@ dmesg/.depend
 dmesg/Makefile.in
 dmesg/virt_dmesg.ml
 .hgignore
+HACKING
 install-sh
 lib/.depend
 lib/Makefile.in
@@ -18,6 +19,9 @@ lib/virt_mem_version.ml.in
 Makefile.in
 Make.rules.in
 MANIFEST
+mem/.depend
+mem/Makefile.in
+mem/virt_mem_main.ml
 po/.cvsignore
 po/LINGUAS
 po/Makefile.in
index 8ccb0ef..cca6388 100644 (file)
@@ -27,6 +27,10 @@ mandir               = @mandir@
 HAVE_PERLDOC    = @HAVE_PERLDOC@
 
 TOOLS          = uname dmesg ps
+export TOOLS
+
+SUBDIRS_NOT_PO = lib $(TOOLS) mem
+SUBDIRS                = $(SUBDIRS_NOT_PO) po
 
 ifeq ($(HAVE_PERLDOC),perldoc)
 MANPAGES        = virt-mem.1 $(TOOLS:%=virt-%.1)
@@ -36,40 +40,38 @@ endif
 TARGETS                = $(MANPAGES) $(TEXTMANPAGES)
 
 all: $(TARGETS)
-       for d in lib $(TOOLS) po; do \
+       for d in $(SUBDIRS); do \
          $(MAKE) -C $$d $@; \
          if [ $$? -ne 0 ]; then exit 1; fi; \
        done
 
 install: install-man
-       for d in lib $(TOOLS) po; do \
+       for d in $(SUBDIRS); do \
          $(MAKE) -C $$d $@; \
          if [ $$? -ne 0 ]; then exit 1; fi; \
        done
 
 depend doc:
-       for d in lib $(TOOLS); do \
+       for d in $(SUBDIRS_NOT_PO); do \
          $(MAKE) -C $$d $@; \
          if [ $$? -ne 0 ]; then exit 1; fi; \
        done
 
 clean:
-       for d in . lib $(TOOLS); do \
+       for d in . $(SUBDIRS); do \
          (cd $$d; rm -f *.cmi *.cmo *.cmx *.cma *.cmxa *.o *.a \
            *.so *.opt *~ *.dll *.exe *.annot core); \
        done
-       for d in po; do \
-         (cd $$d; rm -f *~); \
-       done
        rm -f uname/virt-uname
        rm -f dmesg/virt-dmesg
        rm -f ps/virt-ps
+       rm -f mem/virt-mem
 
 distclean: clean
        rm -f config.h config.log config.status configure
        rm -rf autom4te.cache
        rm -f Makefile
-       rm -f virt-df/Makefile
+       rm -f */Makefile
 
 # Manual page.
 
diff --git a/README b/README
index 170a8b6..6fbe3c1 100644 (file)
--- a/README
+++ b/README
@@ -17,11 +17,6 @@ software inside the virtual machine.  At the moment we only support
 virtual machines running Linux kernel >= 2.6, but we expect to support
 other operating systems in the future.
 
-Most of the commands also offer a CSV (comma-separated values) output
-format ('virt-xx --csv'), allowing usage from scripts to update
-spreadsheets, databases or integrate with existing monitoring systems
-like Nagios.
-
 The commands use libvirt to access the underlying virtualization
 system, so we support a variety of different systems such as Xen, QEMU
 and KVM, and more can be added just by adding support to libvirt.
@@ -44,14 +39,12 @@ Then:
 
   make
 
-The binaries are called things like 'virt-dmesg.opt' and located in
-the respective directories, so you could run them by doing:
+Then run the virt-mem meta-tool, for example:
 
-  ./dmesg/virt-dmesg.opt
+  ./mem/virt-mem.opt dmesg
 
-All the binaries understand the --help option to provide a summary of
-options.  All require virtual machines to run against, but most also
-offer a test mode (-t option).
+(If this binary is linked with the name 'virt-dmesg' then it behaves
+in the same way).
 
 To install the binaries, man pages and message catalogs, do this as
 root:
index ce6a7dd..15c5951 100644 (file)
@@ -149,6 +149,7 @@ AC_CONFIG_FILES([Makefile
        uname/Makefile
        dmesg/Makefile
        ps/Makefile
+       mem/Makefile
        po/Makefile
        ])
 AC_OUTPUT
index 10333a4..a598ba9 100644 (file)
@@ -42,25 +42,13 @@ OCAMLDOCFLAGS       = -html -sort $(OCAMLCPACKAGES) $(SYNTAX)
 
 OCAMLDEPFLAGS  = $(SYNTAX)
 
-TARGETS                = virt-dmesg virt-dmesg.opt
-
 OBJS           = virt_dmesg.cmo
 XOBJS          = virt_dmesg.cmx
 
-all:   $(TARGETS)
-
-virt-dmesg: $(OBJS) ../lib/virt_mem.cma
-       ocamlfind ocamlc \
-         $(OCAMLCFLAGS) $(OCAMLCPACKAGES) $(OCAMLCLIBS) $(OBJS) -o $@
+TARGETS                = $(OBJS) $(XOBJS)
 
-virt-dmesg.opt: $(XOBJS) ../lib/virt_mem.cmxa
-       ocamlfind ocamlopt \
-         $(OCAMLOPTFLAGS) $(OCAMLOPTPACKAGES) $(OCAMLOPTLIBS) $(XOBJS) -o $@
+all:   $(TARGETS)
 
 install:
-       if [ -x virt-dmesg.opt ]; then \
-         $(MKDIR_P) $(DESTDIR)$(bindir); \
-         $(INSTALL) -m 0755 virt-dmesg.opt $(DESTDIR)$(bindir)/virt-dmesg; \
-       fi
 
 include ../Make.rules
\ No newline at end of file
index 10d231f..0931e91 100644 (file)
@@ -23,20 +23,7 @@ open Virt_mem_gettext.Gettext
 open Virt_mem_utils
 open Virt_mem_mmap
 
-let usage = s_"NAME
-  virt-dmesg - dmesg command for virtual machines
-
-SUMMARY
-  virt-dmesg [-options] [domains]
-
-DESCRIPTION
-  virt-dmesg prints the kernel messages for virtual machines running
-  under libvirt.  The output is similar to the ordinary dmesg command
-  run inside the virtual machine."
-
-let verbose, images = Virt_mem.start usage
-
-let () =
+let run debug images =
   List.iter (
     fun (name, arch, mem, lookup_ksym) ->
       try
@@ -86,3 +73,11 @@ let () =
          eprintf (f_"%s: could not find kernel log buffer in kernel image\n")
            name
   ) images
+
+let summary = s_"display kernel messages"
+let description = s_"\
+virt-dmesg prints the kernel messages for virtual machines running
+under libvirt.  The output is similar to the ordinary dmesg command
+run inside the virtual machine."
+
+let () = Virt_mem.register "dmesg" summary description true run
index dd3c18a..1f21a66 100644 (file)
@@ -52,7 +52,122 @@ type kallsyms_compr =
   | Compressed of (string * MMap.addr) list * MMap.addr
   | Uncompressed of (string * MMap.addr) list
 
-let start usage_msg =
+(* When tools register themselves, they are added to this list.
+ * Later, we will alphabetize the list.
+ *)
+let tools = ref [
+  "capture", (
+    "capture",
+    s_"capture memory image for post-mortem analysis",
+    s_"Capture a memory image to a file for later post-mortem
+analysis.  Use the '-o memoryimage' option to specify the
+output file.
+
+Other tools can load the memory image using the '-t' option.",
+    false,
+    (fun _ _ -> ())
+  );
+]
+
+(* Registration function used by the tools. *)
+let register name summary description is_cmd run_fn =
+  tools := (name, (name, summary, description, is_cmd, run_fn)) :: !tools
+
+(* Main program, called from mem/virt_mem_main.ml when all the
+ * tools have had a chance to register themselves.
+ *)
+let main () =
+  (* Get the registered tools, alphabetically. *)
+  let tools = !tools in
+  let tools = List.sort ~cmp:(fun (a,_) (b,_) -> compare a b) tools in
+
+  (* Which tool did the user want to run?  Look at the executable
+   * name (eg. 'virt-dmesg' => tool == dmesg).  If we don't recognise
+   * the executable name then we must look for the first parameter
+   * which doesn't begin with a '-' character.
+   *
+   * Note that we must do all of this before using the OCaml Arg
+   * module to properly parse the command line (below), so that
+   * we can have a usage message ready.
+   *)
+  let tool =
+    let prog = Sys.executable_name in  (* eg. "/usr/bin/virt-dmesg.opt" *)
+    let prog = Filename.basename prog in(* eg. "virt-dmesg.opt" *)
+    let prog =                         (* eg. "virt-dmesg" *)
+      try Filename.chop_extension prog with Invalid_argument _ -> prog in
+    let prog =                         (* eg. "dmesg" *)
+      if String.starts_with prog "virt-" then
+       String.sub prog 5 (String.length prog - 5)
+      else prog in
+    try Some (List.assoc prog tools)
+    with Not_found ->
+      let arg1 =                       (* First non-option argument. *)
+       match Array.to_list Sys.argv with
+       | [] -> None
+       | _::args ->
+           let rec loop = function
+             | [] -> None
+             | a::args when String.length a > 0 && a.[0] = '-' -> loop args
+             | a::_ -> Some a
+           in
+           loop args in
+      match arg1 with
+      | None -> None
+      | Some prog ->                   (* Recognisable first argument? *)
+         let prog =
+           try Filename.chop_extension prog with Invalid_argument _ -> prog in
+         let prog =
+           if String.starts_with prog "virt-" then
+             String.sub prog 5 (String.length prog - 5)
+           else prog in
+         (try Some (List.assoc prog tools) with Not_found -> None) in
+
+  (* Make a usage message. *)
+  let usage_msg =
+    match tool with
+    | None ->                          (* Generic usage message. *)
+       let tools = List.map (
+         fun (name, (_, summary, _, is_cmd, _)) ->
+           if is_cmd then "virt-"^name, summary
+           else           "virt-mem "^name, summary
+       ) tools in
+       (* Maximum width of field in the left hand column. *)
+       let max_width =
+         List.fold_left max 0 (List.map String.length (List.map fst tools)) in
+       let tools = List.map (fun (l,r) -> pad max_width l, r) tools in
+       let tools = List.map (fun (l,r) -> "  " ^ l ^ " - " ^ r) tools in
+       let tools = String.concat "\n" tools in
+
+       sprintf (f_"\
+
+virt-mem: Tools for providing information about virtual machines
+
+Currently available tools include:
+%s
+
+General usage is:
+  <tool> [-options] [domains...]
+
+To display extra help for a single tool, do:
+  virt-mem help <tool>
+
+Options:") tools
+
+                                        (* Tool-specific usage message. *)
+    | Some (name, summary, description, is_cmd, _) ->
+       let cmd = if is_cmd then "virt-" ^ name else "virt-mem " ^ name in
+
+       sprintf (f_"\
+
+%s: %s
+
+Description:
+%s
+
+Options:") cmd summary description in
+
+  (* Now begin proper parsing of the command line arguments. *)
+
   (* Debug messages. *)
   let debug = ref false in
 
@@ -139,7 +254,6 @@ let start usage_msg =
   ] in
 
   let anon_arg str = anon_args := str :: !anon_args in
-  let usage_msg = usage_msg ^ s_"\n\nOPTIONS" in
   Arg.parse argspec anon_arg usage_msg;
 
   let images = !images in
@@ -147,6 +261,22 @@ let start usage_msg =
   let uri = if !uri = "" then None else Some !uri in
   let anon_args = List.rev !anon_args in
 
+  (* At this point, either --help was specified on the command line
+   * (and so the program has exited) or we must have determined tool,
+   * or the user didn't give us a valid tool (eg. "virt-mem foobar").
+   * Detect that final case now and give an error.
+   *)
+  let name, _, _, _, run_fn =
+    match tool with
+    | Some t -> t
+    | None ->
+       prerr_endline (s_"\
+virt-mem: I could not work out which tool you are trying to run.
+Use 'virt-mem --help' for more help or read the manual page virt-mem(1)");
+       exit 1
+  in
+  if debug then eprintf "tool = %s\n%!" name;
+
   (* Get the kernel images. *)
   let images =
     if images = [] then (
@@ -730,4 +860,5 @@ let start usage_msg =
        ((name, arch, mem, lookup_ksym) : image)
     ) images in
 
-  debug, images
+  (* Run the actual tool. *)
+  run_fn debug images
index a0f1963..1dc1c23 100644 (file)
@@ -37,11 +37,16 @@ type image =
         table could not be found at all.
   *)
 
-val start : Arg.usage_msg -> bool * image list
-  (** Programs call this to parse the standard command-line arguments
-      and do all the standard processing of domains into images.
-
-      The returned tuple is:
-      - verbose mode
-      - list of images
+val register : string -> string -> Arg.usage_msg -> bool -> (bool -> image list -> unit) -> unit
+  (** Tools register themselves with this call.
+
+      The parameters are:
+      - tool name (eg. "uname")
+      - short summary
+      - full usage message
+      - is it a virt-cmd?
+      - run function (invoked as [run verbose images])
   *)
+
+val main : unit -> unit
+  (** Entry point for the combined virt-mem executable. *)
index db759dd..6ac7083 100644 (file)
@@ -95,3 +95,9 @@ let frequency xs =
   in
   let xs = loop xs in
   List.rev (List.sort compare xs)
+
+(* Pad a string to a fixed width (from virt-top, but don't truncate). *)
+let pad width str =
+  let n = String.length str in
+  if n >= width then str
+  else (* if n < width then *) str ^ String.make (width-n) ' '
diff --git a/mem/.depend b/mem/.depend
new file mode 100644 (file)
index 0000000..2ad2fc5
--- /dev/null
@@ -0,0 +1,2 @@
+virt_mem_main.cmo: ../lib/virt_mem.cmi 
+virt_mem_main.cmx: ../lib/virt_mem.cmx 
diff --git a/mem/Makefile.in b/mem/Makefile.in
new file mode 100644 (file)
index 0000000..4792802
--- /dev/null
@@ -0,0 +1,69 @@
+# virt-mem
+# @configure_input@
+# Copyright (C) 2008 Red Hat Inc., Richard W.M. Jones
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+
+PACKAGE                = @PACKAGE_NAME@
+VERSION                = @PACKAGE_VERSION@
+
+INSTALL                = @INSTALL@
+MKDIR_P                = @MKDIR_P@
+bindir         = @bindir@
+
+SYNTAX         = -syntax bitmatch.syntax
+
+OCAMLCPACKAGES = -package unix,bigarray,extlib,libvirt,xml-light,bitmatch.syntax -I ../lib
+
+ifneq ($(pkg_gettext),no)
+OCAMLCPACKAGES += -package gettext-stub
+endif
+
+OCAMLCFLAGS    = @OCAMLCFLAGS@ $(SYNTAX)
+OCAMLCLIBS     = -linkpkg bitmatch.cma ../lib/virt_mem.cma
+
+OCAMLOPTFLAGS  = @OCAMLOPTFLAGS@ $(SYNTAX)
+OCAMLOPTPACKAGES = $(OCAMLCPACKAGES)
+OCAMLOPTLIBS   = -linkpkg bitmatch.cmxa ../lib/virt_mem.cmxa
+
+OCAMLDOCFLAGS  = -html -sort $(OCAMLCPACKAGES) $(SYNTAX)
+
+OCAMLDEPFLAGS  = $(SYNTAX)
+
+TARGETS                = virt-mem virt-mem.opt
+
+OBJS           = $(shell for t in $(TOOLS); do echo ../$$t/virt_$$t.cmo; done) virt_mem_main.cmo
+XOBJS          = $(OBJS:%.cmo=%.cmx)
+
+all:   $(TARGETS)
+
+virt-mem: ../lib/virt_mem.cma $(OBJS)
+       ocamlfind ocamlc \
+         $(OCAMLCFLAGS) $(OCAMLCPACKAGES) $(OCAMLCLIBS) $(OBJS) -o $@
+
+virt-mem.opt: ../lib/virt_mem.cmxa $(XOBJS)
+       ocamlfind ocamlopt \
+         $(OCAMLOPTFLAGS) $(OCAMLOPTPACKAGES) $(OCAMLOPTLIBS) $(XOBJS) -o $@
+
+install:
+       if [ -x virt-mem.opt ]; then \
+         $(MKDIR_P) $(DESTDIR)$(bindir); \
+         $(INSTALL) -m 0755 virt-mem.opt $(DESTDIR)$(bindir)/virt-mem; \
+         (cd $(DESTDIR)$(bindir) && \
+           for t in $(TOOLS); do ln -f virt-mem virt-$$t; done \
+         ); \
+       fi
+
+include ../Make.rules
\ No newline at end of file
diff --git a/mem/virt_mem_main.ml b/mem/virt_mem_main.ml
new file mode 100644 (file)
index 0000000..32d89ff
--- /dev/null
@@ -0,0 +1,22 @@
+(* Memory info command for virtual domains.
+   (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
+   http://libvirt.org/
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 2 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, write to the Free Software
+   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+   Links everything into a single executable and invokes 'main'.
+ *)
+
+Virt_mem.main ()
index 8fa53ff..f0f5fa1 100644 (file)
--- a/po/ja.po
+++ b/po/ja.po
@@ -12,111 +12,139 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Plural-Forms: nplurals=1; plural=0;\n"
 
-#: ../lib/virt_mem.ml:442
+#: ../lib/virt_mem.ml:572
 msgid "%s: cannot find start of kernel symbol table\\n"
 msgstr ""
 
-#: ../dmesg/virt_dmesg.ml:86
+#: ../dmesg/virt_dmesg.ml:73
 msgid "%s: could not find kernel log buffer in kernel image\\n"
 msgstr ""
 
-#: ../uname/virt_uname.ml:101
+#: ../uname/virt_uname.ml:88
 msgid "%s: could not find utsname in kernel image\\n"
 msgstr ""
 
-#: ../lib/virt_mem.ml:189
+#: ../lib/virt_mem.ml:319
 msgid "%s: domain is not running"
 msgstr ""
 
-#: ../uname/virt_uname.ml:86
+#: ../uname/virt_uname.ml:73
 msgid "%s: unexpected init_uts_ns in kernel image\\n"
 msgstr ""
 
-#: ../uname/virt_uname.ml:68
+#: ../uname/virt_uname.ml:55
 msgid "%s: unexpected system_utsname in kernel image\\n"
 msgstr ""
 
-#: ../lib/virt_mem.ml:184
+#: ../lib/virt_mem.ml:314
 msgid "%s: unknown domain (not a UUID, name or ID of any active domain)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:304 ../lib/virt_mem.ml:235
+#: ../lib/virt_mem.ml:434 ../lib/virt_mem.ml:365
 msgid "%s: use -A to define architecture (i386/x86-64 only) for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:295 ../lib/virt_mem.ml:226
+#: ../lib/virt_mem.ml:425 ../lib/virt_mem.ml:356
 msgid "%s: use -E to define endianness for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:308 ../lib/virt_mem.ml:239
+#: ../lib/virt_mem.ml:438 ../lib/virt_mem.ml:369
 msgid "%s: use -T to define kernel load address for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:288 ../lib/virt_mem.ml:219
+#: ../lib/virt_mem.ml:418 ../lib/virt_mem.ml:349
 msgid "%s: use -W to define word size for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:132 ../lib/virt_mem.ml:130
+#: ../lib/virt_mem.ml:62
+msgid "Capture a memory image to a file for later post-mortem\nanalysis.  Use the '-o memoryimage' option to specify the\noutput file.\n\nOther tools can load the memory image using the '-t' option."
+msgstr ""
+
+#: ../lib/virt_mem.ml:247 ../lib/virt_mem.ml:245
 msgid "Connect to URI"
 msgstr ""
 
-#: ../lib/virt_mem.ml:134
+#: ../lib/virt_mem.ml:249
 msgid "Debug mode (default: false)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:138
+#: ../lib/virt_mem.ml:253
 msgid "Display version and exit"
 msgstr ""
 
-#: ../dmesg/virt_dmesg.ml:26
-msgid "NAME\n  virt-dmesg - dmesg command for virtual machines\n\nSUMMARY\n  virt-dmesg [-options] [domains]\n\nDESCRIPTION\n  virt-dmesg prints the kernel messages for virtual machines running\n  under libvirt.  The output is similar to the ordinary dmesg command\n  run inside the virtual machine."
+#: ../lib/virt_mem.ml:290
+msgid "NB: If you want to monitor a local Xen hypervisor, you usually need to be root"
 msgstr ""
 
-#: ../ps/virt_ps.ml:26
-msgid "NAME\n  virt-ps - process listing command for virtual machines\n\nSUMMARY\n  virt-ps [-options] [domains]\n\nDESCRIPTION\n  virt-ps prints a process listing for virtual machines running under\n  libvirt."
+#: ../lib/virt_mem.ml:237
+msgid "Set kernel architecture, endianness and word size"
+msgstr ""
+
+#: ../lib/virt_mem.ml:239
+msgid "Set kernel endianness"
+msgstr ""
+
+#: ../lib/virt_mem.ml:241
+msgid "Set kernel text address"
+msgstr ""
+
+#: ../lib/virt_mem.ml:243
+msgid "Set kernel word size"
 msgstr ""
 
-#: ../uname/virt_uname.ml:26
-msgid "NAME\n  virt-uname - uname command for virtual machines\n\nSUMMARY\n  virt-uname [-options] [domains]\n\nDESCRIPTION\n  virt-uname prints the uname information such as OS version,\n  architecture and node name for virtual machines running under\n  libvirt."
+#: ../lib/virt_mem.ml:251
+msgid "Use saved kernel memory image"
 msgstr ""
 
 #: ../lib/virt_mem.ml:160
-msgid "NB: If you want to monitor a local Xen hypervisor, you usually need to be root"
+msgid "\\\n\n%s: %s\n\nDescription:\n%s\n\nOptions:"
 msgstr ""
 
-#: ../lib/virt_mem.ml:122
-msgid "Set kernel architecture, endianness and word size"
+#: ../lib/virt_mem.ml:141
+msgid "\\\n\nvirt-mem: Tools for providing information about virtual machines\n\nCurrently available tools include:\n%s\n\nGeneral usage is:\n  <tool> [-options] [domains...]\n\nTo display extra help for a single tool, do:\n  virt-mem help <tool>\n\nOptions:"
 msgstr ""
 
-#: ../lib/virt_mem.ml:124
-msgid "Set kernel endianness"
+#: ../dmesg/virt_dmesg.ml:78
+msgid "\\\nvirt-dmesg prints the kernel messages for virtual machines running\nunder libvirt.  The output is similar to the ordinary dmesg command\nrun inside the virtual machine."
 msgstr ""
 
-#: ../lib/virt_mem.ml:126
-msgid "Set kernel text address"
+#: ../lib/virt_mem.ml:273
+msgid "\\\nvirt-mem: I could not work out which tool you are trying to run.\nUse 'virt-mem --help' for more help or read the manual page virt-mem(1)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:128
-msgid "Set kernel word size"
+#: ../ps/virt_ps.ml:29
+msgid "\\\nvirt-ps prints a process listing for virtual machines running under\nlibvirt."
 msgstr ""
 
-#: ../lib/virt_mem.ml:136
-msgid "Use saved kernel memory image"
+#: ../uname/virt_uname.ml:92
+msgid "\\\nvirt-uname prints the uname information such as OS version,\narchitecture and node name for virtual machines running under\nlibvirt."
 msgstr ""
 
-#: ../lib/virt_mem.ml:142
-msgid "\\n\\nOPTIONS"
+#: ../lib/virt_mem.ml:61
+msgid "capture memory image for post-mortem analysis"
 msgstr ""
 
-#: ../lib/virt_mem.ml:76
+#: ../dmesg/virt_dmesg.ml:77
+msgid "display kernel messages"
+msgstr ""
+
+#: ../ps/virt_ps.ml:28
+msgid "list processes in virtual machine"
+msgstr ""
+
+#: ../lib/virt_mem.ml:191
 msgid "set_endian: %s: unknown endianness"
 msgstr ""
 
-#: ../lib/virt_mem.ml:65
+#: ../lib/virt_mem.ml:180
 msgid "set_wordsize: %s: unknown wordsize"
 msgstr ""
 
-#: ../lib/virt_mem.ml:276
+#: ../uname/virt_uname.ml:91
+msgid "uname command for virtual machines"
+msgstr ""
+
+#: ../lib/virt_mem.ml:406
 msgid "virt-mem: if -t given on command line, then no domain arguments should be listed"
 msgstr ""
 
index 7d9baa1..d8f52fb 100644 (file)
--- a/po/pl.po
+++ b/po/pl.po
@@ -11,111 +11,139 @@ msgstr ""
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 
-#: ../lib/virt_mem.ml:442
+#: ../lib/virt_mem.ml:572
 msgid "%s: cannot find start of kernel symbol table\\n"
 msgstr ""
 
-#: ../dmesg/virt_dmesg.ml:86
+#: ../dmesg/virt_dmesg.ml:73
 msgid "%s: could not find kernel log buffer in kernel image\\n"
 msgstr ""
 
-#: ../uname/virt_uname.ml:101
+#: ../uname/virt_uname.ml:88
 msgid "%s: could not find utsname in kernel image\\n"
 msgstr ""
 
-#: ../lib/virt_mem.ml:189
+#: ../lib/virt_mem.ml:319
 msgid "%s: domain is not running"
 msgstr ""
 
-#: ../uname/virt_uname.ml:86
+#: ../uname/virt_uname.ml:73
 msgid "%s: unexpected init_uts_ns in kernel image\\n"
 msgstr ""
 
-#: ../uname/virt_uname.ml:68
+#: ../uname/virt_uname.ml:55
 msgid "%s: unexpected system_utsname in kernel image\\n"
 msgstr ""
 
-#: ../lib/virt_mem.ml:184
+#: ../lib/virt_mem.ml:314
 msgid "%s: unknown domain (not a UUID, name or ID of any active domain)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:304 ../lib/virt_mem.ml:235
+#: ../lib/virt_mem.ml:434 ../lib/virt_mem.ml:365
 msgid "%s: use -A to define architecture (i386/x86-64 only) for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:295 ../lib/virt_mem.ml:226
+#: ../lib/virt_mem.ml:425 ../lib/virt_mem.ml:356
 msgid "%s: use -E to define endianness for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:308 ../lib/virt_mem.ml:239
+#: ../lib/virt_mem.ml:438 ../lib/virt_mem.ml:369
 msgid "%s: use -T to define kernel load address for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:288 ../lib/virt_mem.ml:219
+#: ../lib/virt_mem.ml:418 ../lib/virt_mem.ml:349
 msgid "%s: use -W to define word size for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:132 ../lib/virt_mem.ml:130
+#: ../lib/virt_mem.ml:62
+msgid "Capture a memory image to a file for later post-mortem\nanalysis.  Use the '-o memoryimage' option to specify the\noutput file.\n\nOther tools can load the memory image using the '-t' option."
+msgstr ""
+
+#: ../lib/virt_mem.ml:247 ../lib/virt_mem.ml:245
 msgid "Connect to URI"
 msgstr ""
 
-#: ../lib/virt_mem.ml:134
+#: ../lib/virt_mem.ml:249
 msgid "Debug mode (default: false)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:138
+#: ../lib/virt_mem.ml:253
 msgid "Display version and exit"
 msgstr "Wyświetl wersję i zakończ"
 
-#: ../dmesg/virt_dmesg.ml:26
-msgid "NAME\n  virt-dmesg - dmesg command for virtual machines\n\nSUMMARY\n  virt-dmesg [-options] [domains]\n\nDESCRIPTION\n  virt-dmesg prints the kernel messages for virtual machines running\n  under libvirt.  The output is similar to the ordinary dmesg command\n  run inside the virtual machine."
-msgstr ""
-
-#: ../ps/virt_ps.ml:26
-msgid "NAME\n  virt-ps - process listing command for virtual machines\n\nSUMMARY\n  virt-ps [-options] [domains]\n\nDESCRIPTION\n  virt-ps prints a process listing for virtual machines running under\n  libvirt."
-msgstr ""
-
-#: ../uname/virt_uname.ml:26
-msgid "NAME\n  virt-uname - uname command for virtual machines\n\nSUMMARY\n  virt-uname [-options] [domains]\n\nDESCRIPTION\n  virt-uname prints the uname information such as OS version,\n  architecture and node name for virtual machines running under\n  libvirt."
-msgstr ""
-
-#: ../lib/virt_mem.ml:160
+#: ../lib/virt_mem.ml:290
 msgid "NB: If you want to monitor a local Xen hypervisor, you usually need to be root"
 msgstr "NB: jeśli chcesz monitorować lokalnego nadzorcę Xena, zwykle musisz być rootem"
 
-#: ../lib/virt_mem.ml:122
+#: ../lib/virt_mem.ml:237
 msgid "Set kernel architecture, endianness and word size"
 msgstr ""
 
-#: ../lib/virt_mem.ml:124
+#: ../lib/virt_mem.ml:239
 msgid "Set kernel endianness"
 msgstr ""
 
-#: ../lib/virt_mem.ml:126
+#: ../lib/virt_mem.ml:241
 msgid "Set kernel text address"
 msgstr ""
 
-#: ../lib/virt_mem.ml:128
+#: ../lib/virt_mem.ml:243
 msgid "Set kernel word size"
 msgstr ""
 
-#: ../lib/virt_mem.ml:136
+#: ../lib/virt_mem.ml:251
 msgid "Use saved kernel memory image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:142
-msgid "\\n\\nOPTIONS"
+#: ../lib/virt_mem.ml:160
+msgid "\\\n\n%s: %s\n\nDescription:\n%s\n\nOptions:"
+msgstr ""
+
+#: ../lib/virt_mem.ml:141
+msgid "\\\n\nvirt-mem: Tools for providing information about virtual machines\n\nCurrently available tools include:\n%s\n\nGeneral usage is:\n  <tool> [-options] [domains...]\n\nTo display extra help for a single tool, do:\n  virt-mem help <tool>\n\nOptions:"
+msgstr ""
+
+#: ../dmesg/virt_dmesg.ml:78
+msgid "\\\nvirt-dmesg prints the kernel messages for virtual machines running\nunder libvirt.  The output is similar to the ordinary dmesg command\nrun inside the virtual machine."
 msgstr ""
 
-#: ../lib/virt_mem.ml:76
+#: ../lib/virt_mem.ml:273
+msgid "\\\nvirt-mem: I could not work out which tool you are trying to run.\nUse 'virt-mem --help' for more help or read the manual page virt-mem(1)"
+msgstr ""
+
+#: ../ps/virt_ps.ml:29
+msgid "\\\nvirt-ps prints a process listing for virtual machines running under\nlibvirt."
+msgstr ""
+
+#: ../uname/virt_uname.ml:92
+msgid "\\\nvirt-uname prints the uname information such as OS version,\narchitecture and node name for virtual machines running under\nlibvirt."
+msgstr ""
+
+#: ../lib/virt_mem.ml:61
+msgid "capture memory image for post-mortem analysis"
+msgstr ""
+
+#: ../dmesg/virt_dmesg.ml:77
+msgid "display kernel messages"
+msgstr ""
+
+#: ../ps/virt_ps.ml:28
+msgid "list processes in virtual machine"
+msgstr ""
+
+#: ../lib/virt_mem.ml:191
 msgid "set_endian: %s: unknown endianness"
 msgstr ""
 
-#: ../lib/virt_mem.ml:65
+#: ../lib/virt_mem.ml:180
 msgid "set_wordsize: %s: unknown wordsize"
 msgstr ""
 
-#: ../lib/virt_mem.ml:276
+#: ../uname/virt_uname.ml:91
+msgid "uname command for virtual machines"
+msgstr ""
+
+#: ../lib/virt_mem.ml:406
 msgid "virt-mem: if -t given on command line, then no domain arguments should be listed"
 msgstr ""
 
index 72c67ba..b893081 100644 (file)
@@ -15,111 +15,139 @@ msgstr ""
 "X-Poedit-Language: Portuguese\n"
 "X-Poedit-Country: BRAZIL\n"
 
-#: ../lib/virt_mem.ml:442
+#: ../lib/virt_mem.ml:572
 msgid "%s: cannot find start of kernel symbol table\\n"
 msgstr ""
 
-#: ../dmesg/virt_dmesg.ml:86
+#: ../dmesg/virt_dmesg.ml:73
 msgid "%s: could not find kernel log buffer in kernel image\\n"
 msgstr ""
 
-#: ../uname/virt_uname.ml:101
+#: ../uname/virt_uname.ml:88
 msgid "%s: could not find utsname in kernel image\\n"
 msgstr ""
 
-#: ../lib/virt_mem.ml:189
+#: ../lib/virt_mem.ml:319
 msgid "%s: domain is not running"
 msgstr ""
 
-#: ../uname/virt_uname.ml:86
+#: ../uname/virt_uname.ml:73
 msgid "%s: unexpected init_uts_ns in kernel image\\n"
 msgstr ""
 
-#: ../uname/virt_uname.ml:68
+#: ../uname/virt_uname.ml:55
 msgid "%s: unexpected system_utsname in kernel image\\n"
 msgstr ""
 
-#: ../lib/virt_mem.ml:184
+#: ../lib/virt_mem.ml:314
 msgid "%s: unknown domain (not a UUID, name or ID of any active domain)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:304 ../lib/virt_mem.ml:235
+#: ../lib/virt_mem.ml:434 ../lib/virt_mem.ml:365
 msgid "%s: use -A to define architecture (i386/x86-64 only) for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:295 ../lib/virt_mem.ml:226
+#: ../lib/virt_mem.ml:425 ../lib/virt_mem.ml:356
 msgid "%s: use -E to define endianness for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:308 ../lib/virt_mem.ml:239
+#: ../lib/virt_mem.ml:438 ../lib/virt_mem.ml:369
 msgid "%s: use -T to define kernel load address for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:288 ../lib/virt_mem.ml:219
+#: ../lib/virt_mem.ml:418 ../lib/virt_mem.ml:349
 msgid "%s: use -W to define word size for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:132 ../lib/virt_mem.ml:130
+#: ../lib/virt_mem.ml:62
+msgid "Capture a memory image to a file for later post-mortem\nanalysis.  Use the '-o memoryimage' option to specify the\noutput file.\n\nOther tools can load the memory image using the '-t' option."
+msgstr ""
+
+#: ../lib/virt_mem.ml:247 ../lib/virt_mem.ml:245
 msgid "Connect to URI"
 msgstr ""
 
-#: ../lib/virt_mem.ml:134
+#: ../lib/virt_mem.ml:249
 msgid "Debug mode (default: false)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:138
+#: ../lib/virt_mem.ml:253
 msgid "Display version and exit"
 msgstr "Exibe a versão e sai."
 
-#: ../dmesg/virt_dmesg.ml:26
-msgid "NAME\n  virt-dmesg - dmesg command for virtual machines\n\nSUMMARY\n  virt-dmesg [-options] [domains]\n\nDESCRIPTION\n  virt-dmesg prints the kernel messages for virtual machines running\n  under libvirt.  The output is similar to the ordinary dmesg command\n  run inside the virtual machine."
-msgstr ""
-
-#: ../ps/virt_ps.ml:26
-msgid "NAME\n  virt-ps - process listing command for virtual machines\n\nSUMMARY\n  virt-ps [-options] [domains]\n\nDESCRIPTION\n  virt-ps prints a process listing for virtual machines running under\n  libvirt."
-msgstr ""
-
-#: ../uname/virt_uname.ml:26
-msgid "NAME\n  virt-uname - uname command for virtual machines\n\nSUMMARY\n  virt-uname [-options] [domains]\n\nDESCRIPTION\n  virt-uname prints the uname information such as OS version,\n  architecture and node name for virtual machines running under\n  libvirt."
-msgstr ""
-
-#: ../lib/virt_mem.ml:160
+#: ../lib/virt_mem.ml:290
 msgid "NB: If you want to monitor a local Xen hypervisor, you usually need to be root"
 msgstr "NB: Se você quiser monitorar um hipervisor local do Xen, você precisa ser root."
 
-#: ../lib/virt_mem.ml:122
+#: ../lib/virt_mem.ml:237
 msgid "Set kernel architecture, endianness and word size"
 msgstr ""
 
-#: ../lib/virt_mem.ml:124
+#: ../lib/virt_mem.ml:239
 msgid "Set kernel endianness"
 msgstr ""
 
-#: ../lib/virt_mem.ml:126
+#: ../lib/virt_mem.ml:241
 msgid "Set kernel text address"
 msgstr ""
 
-#: ../lib/virt_mem.ml:128
+#: ../lib/virt_mem.ml:243
 msgid "Set kernel word size"
 msgstr ""
 
-#: ../lib/virt_mem.ml:136
+#: ../lib/virt_mem.ml:251
 msgid "Use saved kernel memory image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:142
-msgid "\\n\\nOPTIONS"
+#: ../lib/virt_mem.ml:160
+msgid "\\\n\n%s: %s\n\nDescription:\n%s\n\nOptions:"
+msgstr ""
+
+#: ../lib/virt_mem.ml:141
+msgid "\\\n\nvirt-mem: Tools for providing information about virtual machines\n\nCurrently available tools include:\n%s\n\nGeneral usage is:\n  <tool> [-options] [domains...]\n\nTo display extra help for a single tool, do:\n  virt-mem help <tool>\n\nOptions:"
+msgstr ""
+
+#: ../dmesg/virt_dmesg.ml:78
+msgid "\\\nvirt-dmesg prints the kernel messages for virtual machines running\nunder libvirt.  The output is similar to the ordinary dmesg command\nrun inside the virtual machine."
 msgstr ""
 
-#: ../lib/virt_mem.ml:76
+#: ../lib/virt_mem.ml:273
+msgid "\\\nvirt-mem: I could not work out which tool you are trying to run.\nUse 'virt-mem --help' for more help or read the manual page virt-mem(1)"
+msgstr ""
+
+#: ../ps/virt_ps.ml:29
+msgid "\\\nvirt-ps prints a process listing for virtual machines running under\nlibvirt."
+msgstr ""
+
+#: ../uname/virt_uname.ml:92
+msgid "\\\nvirt-uname prints the uname information such as OS version,\narchitecture and node name for virtual machines running under\nlibvirt."
+msgstr ""
+
+#: ../lib/virt_mem.ml:61
+msgid "capture memory image for post-mortem analysis"
+msgstr ""
+
+#: ../dmesg/virt_dmesg.ml:77
+msgid "display kernel messages"
+msgstr ""
+
+#: ../ps/virt_ps.ml:28
+msgid "list processes in virtual machine"
+msgstr ""
+
+#: ../lib/virt_mem.ml:191
 msgid "set_endian: %s: unknown endianness"
 msgstr ""
 
-#: ../lib/virt_mem.ml:65
+#: ../lib/virt_mem.ml:180
 msgid "set_wordsize: %s: unknown wordsize"
 msgstr ""
 
-#: ../lib/virt_mem.ml:276
+#: ../uname/virt_uname.ml:91
+msgid "uname command for virtual machines"
+msgstr ""
+
+#: ../lib/virt_mem.ml:406
 msgid "virt-mem: if -t given on command line, then no domain arguments should be listed"
 msgstr ""
 
index 760a2b1..b96f079 100644 (file)
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2008-07-09 19:57+0000\n"
+"POT-Creation-Date: 2008-07-15 12:47+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -17,111 +17,139 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"
 
-#: ../lib/virt_mem.ml:442
+#: ../lib/virt_mem.ml:572
 msgid "%s: cannot find start of kernel symbol table\\n"
 msgstr ""
 
-#: ../dmesg/virt_dmesg.ml:86
+#: ../dmesg/virt_dmesg.ml:73
 msgid "%s: could not find kernel log buffer in kernel image\\n"
 msgstr ""
 
-#: ../uname/virt_uname.ml:101
+#: ../uname/virt_uname.ml:88
 msgid "%s: could not find utsname in kernel image\\n"
 msgstr ""
 
-#: ../lib/virt_mem.ml:189
+#: ../lib/virt_mem.ml:319
 msgid "%s: domain is not running"
 msgstr ""
 
-#: ../uname/virt_uname.ml:86
+#: ../uname/virt_uname.ml:73
 msgid "%s: unexpected init_uts_ns in kernel image\\n"
 msgstr ""
 
-#: ../uname/virt_uname.ml:68
+#: ../uname/virt_uname.ml:55
 msgid "%s: unexpected system_utsname in kernel image\\n"
 msgstr ""
 
-#: ../lib/virt_mem.ml:184
+#: ../lib/virt_mem.ml:314
 msgid "%s: unknown domain (not a UUID, name or ID of any active domain)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:304 ../lib/virt_mem.ml:235
+#: ../lib/virt_mem.ml:434 ../lib/virt_mem.ml:365
 msgid "%s: use -A to define architecture (i386/x86-64 only) for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:295 ../lib/virt_mem.ml:226
+#: ../lib/virt_mem.ml:425 ../lib/virt_mem.ml:356
 msgid "%s: use -E to define endianness for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:308 ../lib/virt_mem.ml:239
+#: ../lib/virt_mem.ml:438 ../lib/virt_mem.ml:369
 msgid "%s: use -T to define kernel load address for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:288 ../lib/virt_mem.ml:219
+#: ../lib/virt_mem.ml:418 ../lib/virt_mem.ml:349
 msgid "%s: use -W to define word size for this image"
 msgstr ""
 
-#: ../lib/virt_mem.ml:132 ../lib/virt_mem.ml:130
+#: ../lib/virt_mem.ml:62
+msgid "Capture a memory image to a file for later post-mortem\nanalysis.  Use the '-o memoryimage' option to specify the\noutput file.\n\nOther tools can load the memory image using the '-t' option."
+msgstr ""
+
+#: ../lib/virt_mem.ml:247 ../lib/virt_mem.ml:245
 msgid "Connect to URI"
 msgstr ""
 
-#: ../lib/virt_mem.ml:134
+#: ../lib/virt_mem.ml:249
 msgid "Debug mode (default: false)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:138
+#: ../lib/virt_mem.ml:253
 msgid "Display version and exit"
 msgstr ""
 
-#: ../dmesg/virt_dmesg.ml:26
-msgid "NAME\n  virt-dmesg - dmesg command for virtual machines\n\nSUMMARY\n  virt-dmesg [-options] [domains]\n\nDESCRIPTION\n  virt-dmesg prints the kernel messages for virtual machines running\n  under libvirt.  The output is similar to the ordinary dmesg command\n  run inside the virtual machine."
+#: ../lib/virt_mem.ml:290
+msgid "NB: If you want to monitor a local Xen hypervisor, you usually need to be root"
 msgstr ""
 
-#: ../ps/virt_ps.ml:26
-msgid "NAME\n  virt-ps - process listing command for virtual machines\n\nSUMMARY\n  virt-ps [-options] [domains]\n\nDESCRIPTION\n  virt-ps prints a process listing for virtual machines running under\n  libvirt."
+#: ../lib/virt_mem.ml:237
+msgid "Set kernel architecture, endianness and word size"
+msgstr ""
+
+#: ../lib/virt_mem.ml:239
+msgid "Set kernel endianness"
+msgstr ""
+
+#: ../lib/virt_mem.ml:241
+msgid "Set kernel text address"
+msgstr ""
+
+#: ../lib/virt_mem.ml:243
+msgid "Set kernel word size"
 msgstr ""
 
-#: ../uname/virt_uname.ml:26
-msgid "NAME\n  virt-uname - uname command for virtual machines\n\nSUMMARY\n  virt-uname [-options] [domains]\n\nDESCRIPTION\n  virt-uname prints the uname information such as OS version,\n  architecture and node name for virtual machines running under\n  libvirt."
+#: ../lib/virt_mem.ml:251
+msgid "Use saved kernel memory image"
 msgstr ""
 
 #: ../lib/virt_mem.ml:160
-msgid "NB: If you want to monitor a local Xen hypervisor, you usually need to be root"
+msgid "\\\n\n%s: %s\n\nDescription:\n%s\n\nOptions:"
 msgstr ""
 
-#: ../lib/virt_mem.ml:122
-msgid "Set kernel architecture, endianness and word size"
+#: ../lib/virt_mem.ml:141
+msgid "\\\n\nvirt-mem: Tools for providing information about virtual machines\n\nCurrently available tools include:\n%s\n\nGeneral usage is:\n  <tool> [-options] [domains...]\n\nTo display extra help for a single tool, do:\n  virt-mem help <tool>\n\nOptions:"
 msgstr ""
 
-#: ../lib/virt_mem.ml:124
-msgid "Set kernel endianness"
+#: ../dmesg/virt_dmesg.ml:78
+msgid "\\\nvirt-dmesg prints the kernel messages for virtual machines running\nunder libvirt.  The output is similar to the ordinary dmesg command\nrun inside the virtual machine."
 msgstr ""
 
-#: ../lib/virt_mem.ml:126
-msgid "Set kernel text address"
+#: ../lib/virt_mem.ml:273
+msgid "\\\nvirt-mem: I could not work out which tool you are trying to run.\nUse 'virt-mem --help' for more help or read the manual page virt-mem(1)"
 msgstr ""
 
-#: ../lib/virt_mem.ml:128
-msgid "Set kernel word size"
+#: ../ps/virt_ps.ml:29
+msgid "\\\nvirt-ps prints a process listing for virtual machines running under\nlibvirt."
 msgstr ""
 
-#: ../lib/virt_mem.ml:136
-msgid "Use saved kernel memory image"
+#: ../uname/virt_uname.ml:92
+msgid "\\\nvirt-uname prints the uname information such as OS version,\narchitecture and node name for virtual machines running under\nlibvirt."
 msgstr ""
 
-#: ../lib/virt_mem.ml:142
-msgid "\\n\\nOPTIONS"
+#: ../lib/virt_mem.ml:61
+msgid "capture memory image for post-mortem analysis"
 msgstr ""
 
-#: ../lib/virt_mem.ml:76
+#: ../dmesg/virt_dmesg.ml:77
+msgid "display kernel messages"
+msgstr ""
+
+#: ../ps/virt_ps.ml:28
+msgid "list processes in virtual machine"
+msgstr ""
+
+#: ../lib/virt_mem.ml:191
 msgid "set_endian: %s: unknown endianness"
 msgstr ""
 
-#: ../lib/virt_mem.ml:65
+#: ../lib/virt_mem.ml:180
 msgid "set_wordsize: %s: unknown wordsize"
 msgstr ""
 
-#: ../lib/virt_mem.ml:276
+#: ../uname/virt_uname.ml:91
+msgid "uname command for virtual machines"
+msgstr ""
+
+#: ../lib/virt_mem.ml:406
 msgid "virt-mem: if -t given on command line, then no domain arguments should be listed"
 msgstr ""
 
index 1186c69..3db43fe 100644 (file)
@@ -42,25 +42,13 @@ OCAMLDOCFLAGS       = -html -sort $(OCAMLCPACKAGES) $(SYNTAX)
 
 OCAMLDEPFLAGS  = $(SYNTAX)
 
-TARGETS                = virt-ps virt-ps.opt
-
 OBJS           = virt_ps.cmo
 XOBJS          = virt_ps.cmx
 
-all:   $(TARGETS)
-
-virt-ps: $(OBJS) ../lib/virt_mem.cma
-       ocamlfind ocamlc \
-         $(OCAMLCFLAGS) $(OCAMLCPACKAGES) $(OCAMLCLIBS) $(OBJS) -o $@
+TARGETS                = $(OBJS) $(XOBJS)
 
-virt-ps.opt: $(XOBJS) ../lib/virt_mem.cmxa
-       ocamlfind ocamlopt \
-         $(OCAMLOPTFLAGS) $(OCAMLOPTPACKAGES) $(OCAMLOPTLIBS) $(XOBJS) -o $@
+all:   $(TARGETS)
 
 install:
-       if [ -x virt-ps.opt ]; then \
-         $(MKDIR_P) $(DESTDIR)$(bindir); \
-         $(INSTALL) -m 0755 virt-ps.opt $(DESTDIR)$(bindir)/virt-ps; \
-       fi
 
 include ../Make.rules
\ No newline at end of file
index 94301ce..4c995d8 100644 (file)
@@ -23,14 +23,11 @@ open Virt_mem_gettext.Gettext
 open Virt_mem_utils
 open Virt_mem_mmap
 
-let usage = s_"NAME
-  virt-ps - process listing command for virtual machines
+let run debug images = ()
 
-SUMMARY
-  virt-ps [-options] [domains]
+let summary = s_"list processes in virtual machine"
+let description = s_"\
+virt-ps prints a process listing for virtual machines running under
+libvirt."
 
-DESCRIPTION
-  virt-ps prints a process listing for virtual machines running under
-  libvirt."
-
-let debug, images = Virt_mem.start usage
+let () = Virt_mem.register "ps" summary description true run
index d44b043..dfcd48b 100644 (file)
@@ -42,25 +42,13 @@ OCAMLDOCFLAGS       = -html -sort $(OCAMLCPACKAGES) $(SYNTAX)
 
 OCAMLDEPFLAGS  = $(SYNTAX)
 
-TARGETS                = virt-uname virt-uname.opt
-
 OBJS           = virt_uname.cmo
 XOBJS          = virt_uname.cmx
 
-all:   $(TARGETS)
-
-virt-uname: $(OBJS) ../lib/virt_mem.cma
-       ocamlfind ocamlc \
-         $(OCAMLCFLAGS) $(OCAMLCPACKAGES) $(OCAMLCLIBS) $(OBJS) -o $@
+TARGETS                = $(OBJS) $(XOBJS)
 
-virt-uname.opt: $(XOBJS) ../lib/virt_mem.cmxa
-       ocamlfind ocamlopt \
-         $(OCAMLOPTFLAGS) $(OCAMLOPTPACKAGES) $(OCAMLOPTLIBS) $(XOBJS) -o $@
+all:   $(TARGETS)
 
 install:
-       if [ -x virt-uname.opt ]; then \
-         $(MKDIR_P) $(DESTDIR)$(bindir); \
-         $(INSTALL) -m 0755 virt-uname.opt $(DESTDIR)$(bindir)/virt-uname; \
-       fi
 
 include ../Make.rules
\ No newline at end of file
index fff6d7f..f2f6ddc 100644 (file)
@@ -23,20 +23,7 @@ open Virt_mem_gettext.Gettext
 open Virt_mem_utils
 open Virt_mem_mmap
 
-let usage = s_"NAME
-  virt-uname - uname command for virtual machines
-
-SUMMARY
-  virt-uname [-options] [domains]
-
-DESCRIPTION
-  virt-uname prints the uname information such as OS version,
-  architecture and node name for virtual machines running under
-  libvirt."
-
-let _, images = Virt_mem.start usage
-
-let () =
+let run debug images =
   (* Print new_utsname structure from bitstring. *)
   let print_new_utsname name bs =
     (* Truncate an OCaml string at the first ASCII NUL character, ie. as
@@ -100,3 +87,11 @@ let () =
            Not_found ->
              eprintf (f_"%s: could not find utsname in kernel image\n") name
   ) images
+
+let summary = s_"uname command for virtual machines"
+let description = s_"\
+virt-uname prints the uname information such as OS version,
+architecture and node name for virtual machines running under
+libvirt."
+
+let () = Virt_mem.register "uname" summary description true run
index eb35098..53f61a1 100644 (file)
@@ -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:
 .\" ========================================================================
 ..
 .\" 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-14" "virt-mem-0.2.4" "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\-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-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"
-These virtualization tools allow you to inspect the status of
-virtual machines running Linux.
+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 tools all use libvirt so are capable of showing stats 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.
 .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 \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.
+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 or by its \s-1ID\s0.  Use
-\&\fIvirsh list\fR to get a list of active domain names and IDs.
+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
-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 \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
@@ -179,9 +210,14 @@ report a bug.
 Display usage summary.
 .IP "\fB\-t memoryimage\fR" 4
 .IX Item "-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 \fB\-t\fR option multiple times.
+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.
@@ -203,13 +239,15 @@ 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.
+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 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.
-\&\fI\-T \fIaddress\fI\fR sets the address specifically (\fI0x\fR prefix is
-allowed to specify hex addresses).
+\&\fI\-T \fIaddress\fI\fR sets the address specifically (\fI0x\fR prefix is used
+to specify hex addresses).
 .Sp
 Word size (\fI\-W\fR) sets the word size, 32 or 64 bits.
 .IP "\fB\-A auto|i386|x86\-64|...\fR" 4
@@ -217,16 +255,50 @@ Word size (\fI\-W\fR) sets the word size, 32 or 64 bits.
 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
+\& # 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)
-.Ve
-.PP
-.Vb 11
-\& # virt-dmesg f9x32kvm | tail
+\&
+\& # virt\-dmesg f9x32kvm | tail
 \& <6>Bluetooth: Core ver 2.11
 \& <6>NET: Registered protocol family 31
 \& <6>Bluetooth: HCI device and connection manager initialized
@@ -238,25 +310,42 @@ one go, but not text address.
 \& <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
+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.
-.PP
-(1) Only works on specific, tested releases of Linux kernels.  Support
+.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
+currently non-existent, and probably impossible for Windows because of
 lack of an acceptable source license.
-.PP
-(2) Heuristics are used which may mean in the worst case that the
+.IP "\(bu" 4
+Heuristics are used which may mean in the worst case that the
 output is wrong.
-.PP
-(3) Structures which are frequently modified may cause errors.  This
+.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.
-.PP
-(4) We have to scan memory to find kernel symbols, etc., which can be
+.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"
@@ -268,7 +357,10 @@ example guests which set up malicious kernel memory.
 \&\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/>,
@@ -299,7 +391,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
-If you find a bug in virt\-mem, 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.
index eeb027b..cbfd0bb 100644 (file)
@@ -4,19 +4,37 @@ virt-uname - system information for virtual machines
 
 virt-dmesg - print kernel messages for virtual machines
 
+virt-mem - tool with additional information output
+
 =head1 SUMMARY
 
 virt-uname [-options] [domains...]
 
 virt-dmesg [-options] [domains...]
 
+virt-mem uname [...]
+
+virt-mem dmesg [...]
+
+virt-mem [-options]
+
 =head1 DESCRIPTION
 
-These virtualization tools allow you to inspect the status of
-virtual machines running Linux.
+These virtualization tools allow you to inspect the status of virtual
+machines running Linux.
+
+These tools are designed to work like familiar Linux/Unix command line
+tools.
 
-The tools all use libvirt so are capable of showing stats across a
-variety of different virtualization systems.
+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.
 
 =head1 COMMON OPTIONS
 
@@ -24,14 +42,20 @@ Each command obeys a common set of options.  The general form is:
 
 virt-I<program> [-options] [domains...]
 
-where 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.
+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 or by its ID.  Use
-I<virsh list> to get a list of active domain names and IDs.
+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.
 
-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 C<virt-mem> meta-tool with subcommands,
+as in:
+
+virt-mem I<program> [...]
+
+The C<virt-mem> program offers additional features, such as the
+ability to capture VM images for post-mortem analysis (see below).
 
 =over 4
 
@@ -58,9 +82,14 @@ Display usage summary.
 
 =item B<-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 B<-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 B<-t>
+option multiple times.  Use the C<virt-mem capture> command to capture
+images (see below).
+
+See also the section L</"MEMORY IMAGES"> below.
 
 =item B<--version>
 
@@ -82,13 +111,15 @@ 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.
+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 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 I<address>> sets the address specifically (I<0x> prefix is
-allowed to specify hex addresses).
+I<-T I<address>> sets the address specifically (I<0x> prefix is used
+to specify hex addresses).
 
 Word size (I<-W>) sets the word size, 32 or 64 bits.
 
@@ -100,6 +131,44 @@ one go, but not text address.
 
 =back
 
+=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-uname
@@ -118,28 +187,58 @@ one go, but not text address.
  <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
 
 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
+=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.
 
-(2) Heuristics are used which may mean in the worst case that the
+=item *
+
+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
+=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.
 
-(4) We have to scan memory to find kernel symbols, etc., which can be
+=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
@@ -150,7 +249,10 @@ example guests which set up malicious kernel memory.
 L<uname(1)>,
 L<dmesg(1)>,
 L<virsh(1)>,
+L<virt-top(1)>,
+L<virt-df(1)>,
 L<xm(1)>,
+L<qemu(1)>,
 L<http://www.libvirt.org/ocaml/>,
 L<http://www.libvirt.org/>,
 L<http://et.redhat.com/~rjones/>,
index bac5e16..9c00d79 100644 (file)
@@ -3,31 +3,55 @@ NAME
 
     virt-dmesg - print kernel messages for virtual machines
 
+    virt-mem - tool with additional information output
+
 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.
 
-    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
@@ -48,9 +72,14 @@ COMMON OPTIONS
         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.
@@ -68,13 +97,15 @@ 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 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.
 
@@ -83,6 +114,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 +164,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>