New man page: guestfs-performance(1).

This contains tips for engineering libguestfs for greatest performance.

9 files changed, 1127 insertions, 142 deletions

diff --git a/.gitignore b/.gitignore
index 4a5c47dc..3eeb2634 100644
--- a/.gitignore
+++ b/.gitignore
@@ -91,10 +91,12 @@ pod2htm?.tmp
 /examples/create_disk
 /examples/display_icon
 /examples/guestfs-examples.3
+/examples/guestfs-performance.1
 /examples/guestfs-recipes.1
 /examples/guestfs-testing.1
 /examples/inspect_vm
 /examples/stamp-guestfs-examples.pod
+/examples/stamp-guestfs-performance.pod
 /examples/stamp-guestfs-recipes.pod
 /examples/stamp-guestfs-testing.pod
 /examples/virt-dhcp-address
@@ -155,6 +157,7 @@ pod2htm?.tmp
 /html/guestfs-examples.3.html
 /html/guestfs-java.3.html
 /html/guestfs-ocaml.3.html
+/html/guestfs-performance.1.html
 /html/guestfs-perl.3.html
 /html/guestfs-python.3.html
 /html/guestfs-recipes.1.html
diff --git a/Makefile.am b/Makefile.am
index 9714c334..ea4643c7 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -149,6 +149,7 @@ HTMLFILES = \
 	html/guestfs-erlang.3.html \
 	html/guestfs-java.3.html \
 	html/guestfs-ocaml.3.html \
+	html/guestfs-performance.3.html \
 	html/guestfs-perl.3.html \
 	html/guestfs-python.3.html \
 	html/guestfs-recipes.1.html \
diff --git a/examples/Makefile.am b/examples/Makefile.am
index 137dfe6c..5bde7dd2 100644
--- a/examples/Makefile.am
+++ b/examples/Makefile.am
@@ -18,11 +18,13 @@
 EXTRA_DIST = \
 	LICENSE \
 	guestfs-examples.pod \
+	guestfs-performance.pod \
 	guestfs-recipes.pod \
 	guestfs-testing.pod
 
 CLEANFILES = \
 	stamp-guestfs-examples.pod \
+	stamp-guestfs-performance.pod \
 	stamp-guestfs-recipes.pod \
 	stamp-guestfs-testing.pod
 
@@ -83,10 +85,12 @@ virt_dhcp_address_LDADD = \
 
 man_MANS = \
 	guestfs-examples.3 \
+	guestfs-performance.1 \
 	guestfs-recipes.1 \
 	guestfs-testing.1
 noinst_DATA = \
 	$(top_builddir)/html/guestfs-examples.3.html \
+	$(top_builddir)/html/guestfs-performance.1.html \
 	$(top_builddir)/html/guestfs-recipes.1.html \
 	$(top_builddir)/html/guestfs-testing.1.html
 
@@ -102,6 +106,16 @@ stamp-guestfs-examples.pod: guestfs-examples.pod create_disk.c inspect_vm.c
 	  $<
 	touch $@
 
+guestfs-performance.1 $(top_builddir)/html/guestfs-performance.1.html: stamp-guestfs-performance.pod
+
+stamp-guestfs-performance.pod: guestfs-performance.pod
+	$(top_builddir)/podwrapper.sh \
+	  --section 1 \
+	  --man guestfs-performance.1 \
+	  --html $(top_builddir)/html/guestfs-performance.1.html \
+	  $<
+	touch $@
+
 guestfs-recipes.1 $(top_builddir)/html/guestfs-recipes.1.html: stamp-guestfs-recipes.pod
 
 stamp-guestfs-recipes.pod: guestfs-recipes.pod
diff --git a/examples/guestfs-performance.pod b/examples/guestfs-performance.pod
new file mode 100644
index 00000000..cdf9cd81
--- /dev/null
+++ b/examples/guestfs-performance.pod
@@ -0,0 +1,395 @@
+=encoding utf8
+
+=head1 NAME
+
+guestfs-performance - engineering libguestfs for greatest performance
+
+=head1 DESCRIPTION
+
+This page documents how to get the greatest performance out of
+libguestfs, especially when you expect to use libguestfs to manipulate
+thousands of virtual machines or disk images.
+
+Three main areas are covered. Libguestfs runs an appliance (a small
+Linux distribution) inside qemu/KVM.  The first two areas are:
+minimizing the time taken to start this appliance, and the number of
+times the appliance has to be started.  The third area is shortening
+the time taken for inspection of VMs.
+
+=head1 BASELINE MEASUREMENTS
+
+Before making changes to how you use libguestfs, take baseline
+measurements.
+
+=head2 BASELINE: STARTING THE APPLIANCE
+
+On an unloaded machine, time how long it takes to start up the
+appliance:
+
+ time guestfish -a /dev/null run
+
+Run this command several times in a row and discard the first few
+runs, so that you are measuring a typical "hot cache" case.
+
+=head3 Explanation
+
+This command starts up the libguestfs appliance on a null disk, and
+then immediately shuts it down.  The first time you run the command,
+it will create an appliance and cache it (usually under
+C</var/tmp/.guestfs-*>).  Subsequent runs should reuse the cached
+appliance.
+
+=head3 Expected results
+
+You should expect to be getting times under 6 seconds.  If the times
+you see on an unloaded machine are above this, then see the section
+L</TROUBLESHOOTING POOR PERFORMANCE> below.
+
+=head2 BASELINE: PERFORMING INSPECTION OF A GUEST
+
+For this test you will need an unloaded machine and at least one real
+guest or disk image.  If you are planning to use libguestfs against
+only X guests (eg. X = Windows), then using an X guest here would be
+most appropriate.  If you are planning to run libguestfs against a mix
+of guests, then use a mix of guests for testing here.
+
+Time how long it takes to perform inspection and mount the disks of
+the guest.  Use the first command if you will be using disk images,
+and the second command if you will be using libvirt.
+
+ time guestfish --ro -a disk.img -i exit
+
+ time guestfish --ro -d GuestName -i exit
+
+Run the command several times in a row and discard the first few runs,
+so that you are measuring a typical "hot cache" case.
+
+=head3 Explanation
+
+This command starts up the libguestfs appliance on the named disk
+image or libvirt guest, performs libguestfs inspection on it (see
+L<guestfs(3)/INSPECTION>), mounts the guest's disks, then discards all
+these results and shuts down.
+
+The first time you run the command, it will create an appliance and
+cache it (usually under C</var/tmp/.guestfs-*>).  Subsequent runs
+should reuse the cached appliance.
+
+=head3 Expected results
+
+You should expect times which are E<le> 5 seconds greater than
+measured in the first baseline test above.  (For example, if the first
+baseline test ran in 5 seconds, then this test should run in E<le> 10
+seconds).
+
+=head1 UNDERSTANDING THE APPLIANCE AND WHEN IT IS BUILT/CACHED
+
+The first time you use libguestfs, it will build and cache an
+appliance.  This is usually in C</var/tmp/.guestfs-*>, unless you have
+set C<$TMPDIR> in which case it will be under that temporary
+directory.
+
+For more information about how the appliance is constructed, see
+L<febootstrap(8)/SUPERMIN APPLIANCES>.
+
+Every time libguestfs runs it will check that no host files used by
+the appliance have changed.  If any have, then the appliance is
+rebuilt.  This usually happens when a package is installed or updated
+on the host (eg. using programs like C<yum> or C<apt-get>).  The
+reason for reconstructing the appliance is security: the new program
+that has been installed might contain a security fix, and so we want
+to include the fixed program in the appliance automatically.
+
+These are the performance implications:
+
+=over 4
+
+=item *
+
+The process of building (or rebuilding) the cached appliance is slow,
+and you can avoid this happening by using a fixed appliance (see
+below).
+
+=item *
+
+If not using a fixed appliance, be aware that updating software on the
+host will cause a one time rebuild of the appliance.
+
+=item *
+
+C</var/tmp> (or C<$TMPDIR>) should be on a fast disk, and have plenty
+of space for the appliance.
+
+=back
+
+=head1 USING A FIXED APPLIANCE
+
+To fully control when the appliance is built, you can build a fixed
+appliance.  This appliance can and should be stored on a fast, local
+disk.
+
+To build the appliance, run the command:
+
+ libguestfs-make-fixed-appliance <directory>
+
+replacing C<E<lt>directoryE<gt>> with the name of a directory where
+the appliance will be stored (normally you would name a subdirectory,
+for example: C</usr/local/lib/guestfs/appliance> or
+C</dev/shm/appliance>).
+
+Then set C<$LIBGUESTFS_PATH> (and ensure this environment variable is
+set in your libguestfs program), or modify your program so it calls
+C<guestfs_set_path>.  For example:
+
+ export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
+
+Now you can run libguestfs programs, virt tools, guestfish etc. as
+normal.  The programs will use your fixed appliance, and will not ever
+build, rebuild, or cache their own appliance.
+
+(For detailed information on this subject, see:
+L<libguestfs-make-fixed-appliance(1)>).
+
+=head2 PERFORMANCE OF THE FIXED APPLIANCE
+
+In our testing we did not find that using a fixed appliance gave any
+measurable performance benefit, even when the appliance was located in
+memory (ie. on C</dev/shm>).  However there are three points to
+consider:
+
+=over 4
+
+=item 1.
+
+Using a fixed appliance stops libguestfs from ever rebuilding the
+appliance, meaning that libguestfs will have more predictable start-up
+times.
+
+=item 2.
+
+By default libguestfs (or rather, L<febootstrap-supermin-helper(8)>)
+searches over the root filesystem to find out if any host files have
+changed and if it needs to rebuild the appliance.  If these files are
+not cached and the root filesystem is on an HDD, then this generates
+lots of seeks.  Using a fixed appliance avoids all this.
+
+=item 3.
+
+The appliance is loaded on demand.  A simple test such as:
+
+ time guestfish -a /dev/null run
+
+does not load very much of the appliance.  A real libguestfs program
+using complicated API calls would demand-load a lot more of the
+appliance.  Being able to store the appliance in a specified location
+makes the performance more predictable.
+
+=back
+
+=head1 REDUCING THE NUMBER OF TIMES THE APPLIANCE IS LAUNCHED
+
+By far the most effective, though not always the simplest way to get
+good performance is to ensure that the appliance is launched the
+minimum number of times.  This will probably involve changing your
+libguestfs application.
+
+Try to call C<guestfs_launch> at most once per virtual machine.
+
+Instead of using a separate instance of L<guestfish(1)> to make a
+series of changes to the same guest, use a single instance of
+guestfish and/or use the guestfish I<--listen> option.
+
+Consider writing your program as a daemon which holds a guest open
+while making a series of changes.  Or marshal all the operations you
+want to perform before opening the guest.
+
+You can also try adding disks from multiple guests to a single
+appliance.  Before trying this, note the following points:
+
+=over 4
+
+=item 1.
+
+Adding multiple guests to one appliance is a security problem because
+it may allow one guest to interfere with the disks of another guest.
+Only do it if you trust all the guests, or if you can group guests by
+trust.
+
+=item 2.
+
+In current qemu, there is a limit of around 26 disks that can be added
+to the appliance.  In future versions of qemu (and hence libguestfs)
+we hope to lift this limit.
+
+=item 3.
+
+Using libguestfs this way is complicated.  Disks can have unexpected
+interactions: for example, if two guests use the same UUID for a
+filesystem (because they were cloned), or have volume groups with the
+same name (but see C<guestfs_lvm_set_filter>).
+
+=back
+
+L<virt-df(1)> adds multiple disks by default, so the source code for
+this program would be a good place to start.
+
+=head1 SHORTENING THE TIME TAKEN FOR INSPECTION OF VMs
+
+The main advice is obvious: Do not perform inspection (which is
+expensive) unless you need the results.
+
+If you previously performed inspection on the guest, then it may be
+safe to cache and reuse the results from last time.
+
+Some disks don't need to be inspected at all: for example, if you are
+creating a disk image, or if the disk image is not a VM, or if the
+disk image has a known layout.
+
+Even when basic inspection (C<guestfs_inspect_os>) is required,
+auxiliary inspection operations may be avoided:
+
+=over 4
+
+=item *
+
+Mounting disks is only necessary to get further filesystem
+information.
+
+=item *
+
+Listing applications (C<guestfs_inspect_list_applications>) is an
+expensive operation on Linux, but almost free on Windows.
+
+=item *
+
+Generating a guest icon (C<guestfs_inspect_get_icon>) is cheap on
+Linux but expensive on Windows.
+
+=back
+
+=head1 TROUBLESHOOTING POOR PERFORMANCE
+
+=head2 ENSURE HARDWARE VIRTUALIZATION IS AVAILABLE
+
+Use C</proc/cpuinfo> and this page:
+
+http://virt-tools.org/learning/check-hardware-virt/
+
+to ensure that hardware virtualization is available.  Note that you
+may need to enable it in your BIOS.
+
+Hardware virt is not usually available inside VMs, and libguestfs will
+run slowly inside another virtual machine whatever you do.  Nested
+virtualization does not work well in our experience, and is certainly
+no substitute for running libguestfs on baremetal.
+
+=head2 ENSURE KVM IS AVAILABLE
+
+Ensure that KVM is enabled and available to the user that will run
+libguestfs.  It should be safe to set 0666 permissions on C</dev/kvm>
+and most distributions now do this.
+
+=head2 PROCESSORS TO AVOID
+
+Avoid processors that don't have hardware virtualization, and some
+processors which are simply very slow (AMD Geode being a great
+example).
+
+=head1 DETAILED TIMINGS USING SYSTEMTAP
+
+You can use SystemTap (L<stap(1)>) to get detailed timings from
+libguestfs programs.
+
+Save the following script as C<time.stap>:
+
+ global last;
+ 
+ function display_time () {
+       now = gettimeofday_us ();
+       delta = 0;
+       if (last > 0)
+             delta = now - last;
+       last = now;
+ 
+       printf ("%d (+%d):", now, delta);
+ }
+ 
+ probe begin {
+       last = 0;
+       printf ("ready\n");
+ }
+ 
+ /* Display all calls to static markers. */
+ probe process("/usr/lib*/libguestfs.so.0")
+           .provider("guestfs").mark("*") ? {
+       display_time();
+       printf ("\t%s %s\n", $$name, $$parms);
+ }
+ 
+ /* Display all calls to guestfs_* functions. */
+ probe process("/usr/lib*/libguestfs.so.0")
+           .function("guestfs_[a-z]*") ? {
+       display_time();
+       printf ("\t%s %s\n", probefunc(), $$parms);
+ }
+
+Run it as root in one window:
+
+ # stap time.stap
+ ready
+
+It prints "ready" when SystemTap has loaded the program.  Run your
+libguestfs program, guestfish or a virt tool in another window.  For
+example:
+
+ $ guestfish -a /dev/null run
+
+In the stap window you will see a large amount of output, with the
+time taken for each step shown (microseconds in parenthesis).  For
+example:
+
+ xxxx (+0):	guestfs_create 
+ xxxx (+29):	guestfs_set_pgroup g=0x17a9de0 pgroup=0x1
+ xxxx (+9):	guestfs_add_drive_opts_argv g=0x17a9de0 [...]
+ xxxx (+8):	guestfs_safe_strdup g=0x17a9de0 str=0x7f8a153bed5d
+ xxxx (+19):	guestfs_safe_malloc g=0x17a9de0 nbytes=0x38
+ xxxx (+5):	guestfs_safe_strdup g=0x17a9de0 str=0x17a9f60
+ xxxx (+10):	guestfs_launch g=0x17a9de0
+ xxxx (+4):	launch_start 
+ [etc]
+
+You will need to consult, and even modify, the source to libguestfs to
+fully understand the output.
+
+=head1 SEE ALSO
+
+L<febootstrap(8)>,
+L<febootstrap-supermin-helper(8)>,
+L<guestfish(1)>,
+L<guestfs(3)>,
+L<guestfs-examples(3)>,
+L<libguestfs-make-fixed-appliance(1)>,
+L<stap(1)>,
+L<http://libguestfs.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2012 Red Hat Inc. L<http://libguestfs.org/>
+
+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
diff --git a/po-docs/ja.po b/po-docs/ja.po
index 1b9150e2..dfe81a71 100644
--- a/po-docs/ja.po
+++ b/po-docs/ja.po
@@ -11,7 +11,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: libguestfs\n"
 "Report-Msgid-Bugs-To: libguestfs@redhat.com\n"
-"POT-Creation-Date: 2012-04-03 12:57+0200\n"
+"POT-Creation-Date: 2012-04-10 20:06+0200\n"
 "PO-Revision-Date: 2012-03-30 17:30+0000\n"
 "Last-Translator: rjones <rjones@redhat.com>\n"
 "Language-Team: Japanese <trans-ja@lists.fedoraproject.org>\n"
@@ -26,17 +26,18 @@ msgstr ""
 #: ../appliance/libguestfs-make-fixed-appliance.pod:3 ../cat/virt-cat.pod:3
 #: ../cat/virt-filesystems.pod:3 ../cat/virt-ls.pod:3 ../df/virt-df.pod:3
 #: ../edit/virt-edit.pod:3 ../erlang/examples/guestfs-erlang.pod:3
-#: ../examples/guestfs-examples.pod:3 ../examples/guestfs-recipes.pod:14
-#: ../examples/guestfs-testing.pod:3 ../fish/guestfish.pod:3
-#: ../fish/virt-copy-in.pod:3 ../fish/virt-copy-out.pod:3
-#: ../fish/virt-tar-in.pod:3 ../fish/virt-tar-out.pod:3
-#: ../format/virt-format.pod:3 ../fuse/guestmount.pod:3
-#: ../inspector/virt-inspector.pod:3 ../java/examples/guestfs-java.pod:3
-#: ../ocaml/examples/guestfs-ocaml.pod:3 ../perl/examples/guestfs-perl.pod:3
-#: ../python/examples/guestfs-python.pod:3 ../rescue/virt-rescue.pod:3
-#: ../resize/virt-resize.pod:3 ../ruby/examples/guestfs-ruby.pod:3
-#: ../sparsify/virt-sparsify.pod:3 ../src/guestfs.pod:3
-#: ../sysprep/virt-sysprep.pod:3 ../test-tool/libguestfs-test-tool.pod:3
+#: ../examples/guestfs-examples.pod:3 ../examples/guestfs-performance.pod:3
+#: ../examples/guestfs-recipes.pod:14 ../examples/guestfs-testing.pod:3
+#: ../fish/guestfish.pod:3 ../fish/virt-copy-in.pod:3
+#: ../fish/virt-copy-out.pod:3 ../fish/virt-tar-in.pod:3
+#: ../fish/virt-tar-out.pod:3 ../format/virt-format.pod:3
+#: ../fuse/guestmount.pod:3 ../inspector/virt-inspector.pod:3
+#: ../java/examples/guestfs-java.pod:3 ../ocaml/examples/guestfs-ocaml.pod:3
+#: ../perl/examples/guestfs-perl.pod:3 ../python/examples/guestfs-python.pod:3
+#: ../rescue/virt-rescue.pod:3 ../resize/virt-resize.pod:3
+#: ../ruby/examples/guestfs-ruby.pod:3 ../sparsify/virt-sparsify.pod:3
+#: ../src/guestfs.pod:3 ../sysprep/virt-sysprep.pod:3
+#: ../test-tool/libguestfs-test-tool.pod:3
 #: ../tools/virt-list-filesystems.pl:30 ../tools/virt-list-partitions.pl:30
 #: ../tools/virt-make-fs.pl:35 ../tools/virt-tar.pl:31
 #: ../tools/virt-win-reg.pl:35
@@ -94,13 +95,14 @@ msgstr ""
 #: ../appliance/libguestfs-make-fixed-appliance.pod:13 ../cat/virt-cat.pod:19
 #: ../cat/virt-filesystems.pod:13 ../cat/virt-ls.pod:19 ../df/virt-df.pod:21
 #: ../edit/virt-edit.pod:27 ../erlang/examples/guestfs-erlang.pod:16
-#: ../examples/guestfs-examples.pod:19 ../examples/guestfs-recipes.pod:18
-#: ../examples/guestfs-testing.pod:7 ../fish/guestfish.pod:30
-#: ../fish/virt-copy-in.pod:19 ../fish/virt-copy-out.pod:13
-#: ../fish/virt-tar-in.pod:21 ../fish/virt-tar-out.pod:15
-#: ../format/virt-format.pod:11 ../fuse/guestmount.pod:20
-#: ../inspector/virt-inspector.pod:19 ../java/examples/guestfs-java.pod:15
-#: ../ocaml/examples/guestfs-ocaml.pod:25 ../perl/examples/guestfs-perl.pod:18
+#: ../examples/guestfs-examples.pod:19 ../examples/guestfs-performance.pod:7
+#: ../examples/guestfs-recipes.pod:18 ../examples/guestfs-testing.pod:7
+#: ../fish/guestfish.pod:30 ../fish/virt-copy-in.pod:19
+#: ../fish/virt-copy-out.pod:13 ../fish/virt-tar-in.pod:21
+#: ../fish/virt-tar-out.pod:15 ../format/virt-format.pod:11
+#: ../fuse/guestmount.pod:20 ../inspector/virt-inspector.pod:19
+#: ../java/examples/guestfs-java.pod:15 ../ocaml/examples/guestfs-ocaml.pod:25
+#: ../perl/examples/guestfs-perl.pod:18
 #: ../python/examples/guestfs-python.pod:14 ../rescue/virt-rescue.pod:31
 #: ../resize/virt-resize.pod:13 ../ruby/examples/guestfs-ruby.pod:15
 #: ../sparsify/virt-sparsify.pod:11 ../src/guestfs.pod:23
@@ -1186,13 +1188,14 @@ msgstr ""
 #: ../cat/virt-cat.pod:243 ../cat/virt-filesystems.pod:389
 #: ../cat/virt-ls.pod:495 ../df/virt-df.pod:253 ../edit/virt-edit.pod:354
 #: ../erlang/examples/guestfs-erlang.pod:97
-#: ../examples/guestfs-examples.pod:33 ../examples/guestfs-recipes.pod:384
-#: ../examples/guestfs-testing.pod:291 ../fish/guestfish.pod:1268
-#: ../fish/virt-copy-in.pod:50 ../fish/virt-copy-out.pod:39
-#: ../fish/virt-tar-in.pod:47 ../fish/virt-tar-out.pod:41
-#: ../format/virt-format.pod:177 ../fuse/guestmount.pod:317
-#: ../inspector/virt-inspector.pod:501 ../java/examples/guestfs-java.pod:45
-#: ../ocaml/examples/guestfs-ocaml.pod:78 ../perl/examples/guestfs-perl.pod:39
+#: ../examples/guestfs-examples.pod:33 ../examples/guestfs-performance.pod:102
+#: ../examples/guestfs-recipes.pod:384 ../examples/guestfs-testing.pod:291
+#: ../fish/guestfish.pod:1268 ../fish/virt-copy-in.pod:50
+#: ../fish/virt-copy-out.pod:39 ../fish/virt-tar-in.pod:47
+#: ../fish/virt-tar-out.pod:41 ../format/virt-format.pod:177
+#: ../fuse/guestmount.pod:317 ../inspector/virt-inspector.pod:501
+#: ../java/examples/guestfs-java.pod:45 ../ocaml/examples/guestfs-ocaml.pod:78
+#: ../perl/examples/guestfs-perl.pod:39
 #: ../python/examples/guestfs-python.pod:42 ../rescue/virt-rescue.pod:325
 #: ../resize/virt-resize.pod:702 ../ruby/examples/guestfs-ruby.pod:36
 #: ../sparsify/virt-sparsify.pod:278 ../src/guestfs.pod:3346
@@ -1243,13 +1246,14 @@ msgstr "Richard W.M. Jones L<http://people.redhat.com/~rjones/>"
 #: ../cat/virt-cat.pod:256 ../cat/virt-filesystems.pod:404
 #: ../cat/virt-ls.pod:511 ../df/virt-df.pod:265 ../edit/virt-edit.pod:372
 #: ../erlang/examples/guestfs-erlang.pod:114
-#: ../examples/guestfs-examples.pod:49 ../examples/guestfs-recipes.pod:401
-#: ../examples/guestfs-testing.pod:302 ../fish/guestfish.pod:1300
-#: ../fish/virt-copy-in.pod:64 ../fish/virt-copy-out.pod:53
-#: ../fish/virt-tar-in.pod:62 ../fish/virt-tar-out.pod:55
-#: ../format/virt-format.pod:191 ../fuse/guestmount.pod:332
-#: ../inspector/virt-inspector.pod:524 ../java/examples/guestfs-java.pod:62
-#: ../ocaml/examples/guestfs-ocaml.pod:95 ../perl/examples/guestfs-perl.pod:56
+#: ../examples/guestfs-examples.pod:49 ../examples/guestfs-performance.pod:114
+#: ../examples/guestfs-recipes.pod:401 ../examples/guestfs-testing.pod:302
+#: ../fish/guestfish.pod:1300 ../fish/virt-copy-in.pod:64
+#: ../fish/virt-copy-out.pod:53 ../fish/virt-tar-in.pod:62
+#: ../fish/virt-tar-out.pod:55 ../format/virt-format.pod:191
+#: ../fuse/guestmount.pod:332 ../inspector/virt-inspector.pod:524
+#: ../java/examples/guestfs-java.pod:62 ../ocaml/examples/guestfs-ocaml.pod:95
+#: ../perl/examples/guestfs-perl.pod:56
 #: ../python/examples/guestfs-python.pod:58 ../rescue/virt-rescue.pod:338
 #: ../resize/virt-resize.pod:729 ../ruby/examples/guestfs-ruby.pod:52
 #: ../sparsify/virt-sparsify.pod:295 ../src/guestfs.pod:3430
@@ -1615,13 +1619,13 @@ msgstr ""
 #. type: =head1
 #: ../appliance/libguestfs-make-fixed-appliance.pod:153
 #: ../erlang/examples/guestfs-erlang.pod:110
-#: ../examples/guestfs-examples.pod:45 ../examples/guestfs-recipes.pod:397
-#: ../examples/guestfs-testing.pod:298 ../fish/guestfish.pod:1296
-#: ../fish/virt-copy-in.pod:60 ../fish/virt-copy-out.pod:49
-#: ../fish/virt-tar-in.pod:58 ../fish/virt-tar-out.pod:51
-#: ../fuse/guestmount.pod:328 ../inspector/virt-inspector.pod:510
-#: ../java/examples/guestfs-java.pod:58 ../ocaml/examples/guestfs-ocaml.pod:91
-#: ../perl/examples/guestfs-perl.pod:52
+#: ../examples/guestfs-examples.pod:45 ../examples/guestfs-performance.pod:110
+#: ../examples/guestfs-recipes.pod:397 ../examples/guestfs-testing.pod:298
+#: ../fish/guestfish.pod:1296 ../fish/virt-copy-in.pod:60
+#: ../fish/virt-copy-out.pod:49 ../fish/virt-tar-in.pod:58
+#: ../fish/virt-tar-out.pod:51 ../fuse/guestmount.pod:328
+#: ../inspector/virt-inspector.pod:510 ../java/examples/guestfs-java.pod:58
+#: ../ocaml/examples/guestfs-ocaml.pod:91 ../perl/examples/guestfs-perl.pod:52
 #: ../python/examples/guestfs-python.pod:54
 #: ../ruby/examples/guestfs-ruby.pod:48 ../src/guestfs.pod:3426
 #: ../test-tool/libguestfs-test-tool.pod:106
@@ -1631,12 +1635,13 @@ msgstr "著者"
 #. type: textblock
 #: ../appliance/libguestfs-make-fixed-appliance.pod:155
 #: ../erlang/examples/guestfs-erlang.pod:112
-#: ../examples/guestfs-examples.pod:47 ../examples/guestfs-recipes.pod:399
-#: ../examples/guestfs-testing.pod:300 ../fish/guestfish.pod:1298
-#: ../fish/virt-copy-in.pod:62 ../fish/virt-copy-out.pod:51
-#: ../fish/virt-tar-in.pod:60 ../fish/virt-tar-out.pod:53
-#: ../fuse/guestmount.pod:330 ../java/examples/guestfs-java.pod:60
-#: ../ocaml/examples/guestfs-ocaml.pod:93 ../perl/examples/guestfs-perl.pod:54
+#: ../examples/guestfs-examples.pod:47 ../examples/guestfs-performance.pod:112
+#: ../examples/guestfs-recipes.pod:399 ../examples/guestfs-testing.pod:300
+#: ../fish/guestfish.pod:1298 ../fish/virt-copy-in.pod:62
+#: ../fish/virt-copy-out.pod:51 ../fish/virt-tar-in.pod:60
+#: ../fish/virt-tar-out.pod:53 ../fuse/guestmount.pod:330
+#: ../java/examples/guestfs-java.pod:60 ../ocaml/examples/guestfs-ocaml.pod:93
+#: ../perl/examples/guestfs-perl.pod:54
 #: ../python/examples/guestfs-python.pod:56
 #: ../ruby/examples/guestfs-ruby.pod:50 ../src/guestfs.pod:3428
 #: ../test-tool/libguestfs-test-tool.pod:108
@@ -4895,8 +4900,9 @@ msgstr ""
 
 #. type: textblock
 #: ../erlang/examples/guestfs-erlang.pod:121
-#: ../examples/guestfs-examples.pod:56 ../examples/guestfs-recipes.pod:408
-#: ../examples/guestfs-testing.pod:306 ../java/examples/guestfs-java.pod:69
+#: ../examples/guestfs-examples.pod:56 ../examples/guestfs-performance.pod:118
+#: ../examples/guestfs-recipes.pod:408 ../examples/guestfs-testing.pod:306
+#: ../java/examples/guestfs-java.pod:69
 #: ../ocaml/examples/guestfs-ocaml.pod:102
 #: ../perl/examples/guestfs-perl.pod:63
 #: ../python/examples/guestfs-python.pod:65
@@ -4914,8 +4920,9 @@ msgstr ""
 
 #. type: textblock
 #: ../erlang/examples/guestfs-erlang.pod:126
-#: ../examples/guestfs-examples.pod:61 ../examples/guestfs-recipes.pod:413
-#: ../examples/guestfs-testing.pod:311 ../java/examples/guestfs-java.pod:74
+#: ../examples/guestfs-examples.pod:61 ../examples/guestfs-performance.pod:123
+#: ../examples/guestfs-recipes.pod:413 ../examples/guestfs-testing.pod:311
+#: ../java/examples/guestfs-java.pod:74
 #: ../ocaml/examples/guestfs-ocaml.pod:107
 #: ../perl/examples/guestfs-perl.pod:68
 #: ../python/examples/guestfs-python.pod:70
@@ -4933,8 +4940,9 @@ msgstr ""
 
 #. type: textblock
 #: ../erlang/examples/guestfs-erlang.pod:131
-#: ../examples/guestfs-examples.pod:66 ../examples/guestfs-recipes.pod:418
-#: ../examples/guestfs-testing.pod:316 ../java/examples/guestfs-java.pod:79
+#: ../examples/guestfs-examples.pod:66 ../examples/guestfs-performance.pod:128
+#: ../examples/guestfs-recipes.pod:418 ../examples/guestfs-testing.pod:316
+#: ../java/examples/guestfs-java.pod:79
 #: ../ocaml/examples/guestfs-ocaml.pod:112
 #: ../perl/examples/guestfs-perl.pod:73
 #: ../python/examples/guestfs-python.pod:75
@@ -5018,6 +5026,208 @@ msgstr ""
 msgid "Copyright (C) 2010 Red Hat Inc. L<http://libguestfs.org/>"
 msgstr "Copyright (C) 2010 Red Hat Inc. L<http://libguestfs.org/>"
 
+#. type: textblock
+#: ../examples/guestfs-performance.pod:5
+msgid "guestfs-performance - engineering libguestfs for greatest performance"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:9
+msgid ""
+"This page documents how to get the greatest performance out of libguestfs, "
+"especially when you expect to use libguestfs to manipulate thousands of "
+"virtual machines or disk images."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:13
+msgid ""
+"Three main areas are covered. Libguestfs runs an appliance (a small Linux "
+"distribution) inside qemu/KVM.  The first two areas are: minimizing the time "
+"taken to start this appliance, and the number of times the appliance has to "
+"be started.  The third area is shortening the time taken for inspection of "
+"VMs."
+msgstr ""
+
+#. type: =head1
+#: ../examples/guestfs-performance.pod:19
+msgid "BASELINE MEASUREMENTS"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:21
+msgid ""
+"Before making changes to how you use libguestfs, take baseline measurements."
+msgstr ""
+
+#. type: =head2
+#: ../examples/guestfs-performance.pod:24
+msgid "BASELINE: STARTING THE APPLIANCE"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:26
+msgid ""
+"On an unloaded machine, time how long it takes to start up the appliance:"
+msgstr ""
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:29 ../examples/guestfs-testing.pod:36
+#, no-wrap
+msgid ""
+" time guestfish -a /dev/null run\n"
+"\n"
+msgstr ""
+" time guestfish -a /dev/null run\n"
+"\n"
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:31
+msgid ""
+"Run this command several times in a row and discard the first few runs, so "
+"that you are measuring a typical \"hot cache\" case."
+msgstr ""
+
+#. type: =head3
+#: ../examples/guestfs-performance.pod:34
+#: ../examples/guestfs-performance.pod:67
+msgid "Explanation"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:36
+msgid ""
+"This command starts up the libguestfs appliance on a null disk, and then "
+"immediately shuts it down.  The first time you run the command, it will "
+"create an appliance and cache it (usually under C</var/tmp/.guestfs-*>).  "
+"Subsequent runs should reuse the cached appliance."
+msgstr ""
+
+#. type: =head3
+#: ../examples/guestfs-performance.pod:42
+#: ../examples/guestfs-performance.pod:78
+msgid "Expected results"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:44
+msgid ""
+"You should expect to be getting times under 6 seconds.  If the times you see "
+"on an unloaded machine are above this, then see the section L</"
+"TROUBLESHOOTING POOR PERFORMANCE> below."
+msgstr ""
+
+#. type: =head2
+#: ../examples/guestfs-performance.pod:48
+msgid "BASELINE: PERFORMING INSPECTION OF A GUEST"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:50
+msgid ""
+"For this test you will need an unloaded machine and at least one real guest "
+"or disk image.  If you are planning to use libguestfs against only X guests "
+"(eg. X = Windows), then using an X guest here would be most appropriate.  If "
+"you are planning to run libguestfs against a mix of guests, then use a mix "
+"of guests for testing here."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:56
+msgid ""
+"Time how long it takes to perform inspection and mount the disks of the "
+"guest.  Use the first command if you will be using disk images, and the "
+"second command if you will be using libvirt."
+msgstr ""
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:60
+#, fuzzy, no-wrap
+#| msgid ""
+#| " guestfish [--ro|--rw] -a disk.img -i\n"
+#| "\n"
+msgid ""
+" time guestfish --ro -a disk.img -i exit\n"
+"\n"
+msgstr ""
+" guestfish [--ro|--rw] -a disk.img -i\n"
+"\n"
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:62
+#, fuzzy, no-wrap
+#| msgid ""
+#| " guestfish --ro -d GuestName -i statvfs /\n"
+#| "\n"
+msgid ""
+" time guestfish --ro -d GuestName -i exit\n"
+"\n"
+msgstr ""
+" guestfish --ro -d GuestName -i statvfs /\n"
+"\n"
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:64
+msgid ""
+"Run the command several times in a row and discard the first few runs, so "
+"that you are measuring a typical \"hot cache\" case."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:69
+msgid ""
+"This command starts up the libguestfs appliance on the named disk image or "
+"libvirt guest, performs libguestfs inspection on it (see L<guestfs(3)/"
+"INSPECTION>), mounts the guest's disks, then discards all these results and "
+"shuts down."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:74
+msgid ""
+"The first time you run the command, it will create an appliance and cache it "
+"(usually under C</var/tmp/.guestfs-*>).  Subsequent runs should reuse the "
+"cached appliance."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:80
+msgid ""
+"You should expect times which are E<le> 5 seconds greater than measured in "
+"the first baseline test above.  (For example, if the first baseline test ran "
+"in 5 seconds, then this test should run in E<le> 10 seconds)."
+msgstr ""
+
+#. type: =head1
+#: ../examples/guestfs-performance.pod:92
+msgid "TROUBLESHOOTING POOR PERFORMANCE"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:94
+msgid "** KVM ** Geode ** etc."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:104
+#, fuzzy
+#| msgid ""
+#| "L<guestfs(3)>, L<guestfish(1)>, L<guestfs-examples(3)>, L<http://"
+#| "libguestfs.org/>."
+msgid ""
+"L<guestfish(1)>, L<guestfs(3)>, L<guestfs-examples(3)>, L<libguestfs-make-"
+"fixed-appliance(1)>, L<http://libguestfs.org/>."
+msgstr ""
+"L<guestfs(3)>, L<guestfish(1)>, L<guestfs-examples(3)>, L<http://libguestfs."
+"org/>."
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:116
+#, fuzzy
+#| msgid "Copyright (C) 2011 Red Hat Inc. L<http://libguestfs.org/>"
+msgid "Copyright (C) 2012 Red Hat Inc. L<http://libguestfs.org/>"
+msgstr "Copyright (C) 2011 Red Hat Inc. L<http://libguestfs.org/>"
+
 #. type: =end
 #: ../examples/guestfs-recipes.pod:3 ../examples/guestfs-recipes.pod:12
 msgid "comment"
@@ -6137,16 +6347,6 @@ msgid ""
 "command a few times:"
 msgstr ""
 
-#. type: verbatim
-#: ../examples/guestfs-testing.pod:36
-#, no-wrap
-msgid ""
-" time guestfish -a /dev/null run\n"
-"\n"
-msgstr ""
-" time guestfish -a /dev/null run\n"
-"\n"
-
 #. type: textblock
 #: ../examples/guestfs-testing.pod:38
 msgid ""
diff --git a/po-docs/libguestfs-docs.pot b/po-docs/libguestfs-docs.pot
index 0cc2c585..7534933c 100644
--- a/po-docs/libguestfs-docs.pot
+++ b/po-docs/libguestfs-docs.pot
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: libguestfs 1.17.27\n"
 "Report-Msgid-Bugs-To: libguestfs@redhat.com\n"
-"POT-Creation-Date: 2012-04-10 15:43+0200\n"
+"POT-Creation-Date: 2012-04-10 20:06+0200\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"
@@ -18,7 +18,7 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 
 #. type: =head1
-#: ../align/virt-alignment-scan.pod:3 ../appliance/libguestfs-make-fixed-appliance.pod:3 ../cat/virt-cat.pod:3 ../cat/virt-filesystems.pod:3 ../cat/virt-ls.pod:3 ../df/virt-df.pod:3 ../edit/virt-edit.pod:3 ../erlang/examples/guestfs-erlang.pod:3 ../examples/guestfs-examples.pod:3 ../examples/guestfs-recipes.pod:14 ../examples/guestfs-testing.pod:3 ../fish/guestfish.pod:3 ../fish/virt-copy-in.pod:3 ../fish/virt-copy-out.pod:3 ../fish/virt-tar-in.pod:3 ../fish/virt-tar-out.pod:3 ../format/virt-format.pod:3 ../fuse/guestmount.pod:3 ../inspector/virt-inspector.pod:3 ../java/examples/guestfs-java.pod:3 ../ocaml/examples/guestfs-ocaml.pod:3 ../perl/examples/guestfs-perl.pod:3 ../python/examples/guestfs-python.pod:3 ../rescue/virt-rescue.pod:3 ../resize/virt-resize.pod:3 ../ruby/examples/guestfs-ruby.pod:3 ../sparsify/virt-sparsify.pod:3 ../src/guestfs.pod:3 ../sysprep/virt-sysprep.pod:3 ../test-tool/libguestfs-test-tool.pod:3 ../tools/virt-list-filesystems.pl:30 ../tools/virt-list-partitions.pl:30 ../tools/virt-make-fs.pl:35 ../tools/virt-tar.pl:31 ../tools/virt-win-reg.pl:35
+#: ../align/virt-alignment-scan.pod:3 ../appliance/libguestfs-make-fixed-appliance.pod:3 ../cat/virt-cat.pod:3 ../cat/virt-filesystems.pod:3 ../cat/virt-ls.pod:3 ../df/virt-df.pod:3 ../edit/virt-edit.pod:3 ../erlang/examples/guestfs-erlang.pod:3 ../examples/guestfs-examples.pod:3 ../examples/guestfs-performance.pod:3 ../examples/guestfs-recipes.pod:14 ../examples/guestfs-testing.pod:3 ../fish/guestfish.pod:3 ../fish/virt-copy-in.pod:3 ../fish/virt-copy-out.pod:3 ../fish/virt-tar-in.pod:3 ../fish/virt-tar-out.pod:3 ../format/virt-format.pod:3 ../fuse/guestmount.pod:3 ../inspector/virt-inspector.pod:3 ../java/examples/guestfs-java.pod:3 ../ocaml/examples/guestfs-ocaml.pod:3 ../perl/examples/guestfs-perl.pod:3 ../python/examples/guestfs-python.pod:3 ../rescue/virt-rescue.pod:3 ../resize/virt-resize.pod:3 ../ruby/examples/guestfs-ruby.pod:3 ../sparsify/virt-sparsify.pod:3 ../src/guestfs.pod:3 ../sysprep/virt-sysprep.pod:3 ../test-tool/libguestfs-test-tool.pod:3 ../tools/virt-list-filesystems.pl:30 ../tools/virt-list-partitions.pl:30 ../tools/virt-make-fs.pl:35 ../tools/virt-tar.pl:31 ../tools/virt-win-reg.pl:35
 msgid "NAME"
 msgstr ""
 
@@ -49,7 +49,7 @@ msgid ""
 msgstr ""
 
 #. type: =head1
-#: ../align/virt-alignment-scan.pod:13 ../appliance/libguestfs-make-fixed-appliance.pod:13 ../cat/virt-cat.pod:19 ../cat/virt-filesystems.pod:13 ../cat/virt-ls.pod:19 ../df/virt-df.pod:21 ../edit/virt-edit.pod:27 ../erlang/examples/guestfs-erlang.pod:16 ../examples/guestfs-examples.pod:19 ../examples/guestfs-recipes.pod:18 ../examples/guestfs-testing.pod:7 ../fish/guestfish.pod:30 ../fish/virt-copy-in.pod:19 ../fish/virt-copy-out.pod:13 ../fish/virt-tar-in.pod:21 ../fish/virt-tar-out.pod:15 ../format/virt-format.pod:11 ../fuse/guestmount.pod:20 ../inspector/virt-inspector.pod:19 ../java/examples/guestfs-java.pod:15 ../ocaml/examples/guestfs-ocaml.pod:25 ../perl/examples/guestfs-perl.pod:18 ../python/examples/guestfs-python.pod:14 ../rescue/virt-rescue.pod:31 ../resize/virt-resize.pod:13 ../ruby/examples/guestfs-ruby.pod:15 ../sparsify/virt-sparsify.pod:11 ../src/guestfs.pod:23 ../sysprep/virt-sysprep.pod:13 ../test-tool/libguestfs-test-tool.pod:11 ../tools/virt-list-filesystems.pl:45 ../tools/virt-list-partitions.pl:45 ../tools/virt-make-fs.pl:47 ../tools/virt-tar.pl:77 ../tools/virt-win-reg.pl:63
+#: ../align/virt-alignment-scan.pod:13 ../appliance/libguestfs-make-fixed-appliance.pod:13 ../cat/virt-cat.pod:19 ../cat/virt-filesystems.pod:13 ../cat/virt-ls.pod:19 ../df/virt-df.pod:21 ../edit/virt-edit.pod:27 ../erlang/examples/guestfs-erlang.pod:16 ../examples/guestfs-examples.pod:19 ../examples/guestfs-performance.pod:7 ../examples/guestfs-recipes.pod:18 ../examples/guestfs-testing.pod:7 ../fish/guestfish.pod:30 ../fish/virt-copy-in.pod:19 ../fish/virt-copy-out.pod:13 ../fish/virt-tar-in.pod:21 ../fish/virt-tar-out.pod:15 ../format/virt-format.pod:11 ../fuse/guestmount.pod:20 ../inspector/virt-inspector.pod:19 ../java/examples/guestfs-java.pod:15 ../ocaml/examples/guestfs-ocaml.pod:25 ../perl/examples/guestfs-perl.pod:18 ../python/examples/guestfs-python.pod:14 ../rescue/virt-rescue.pod:31 ../resize/virt-resize.pod:13 ../ruby/examples/guestfs-ruby.pod:15 ../sparsify/virt-sparsify.pod:11 ../src/guestfs.pod:23 ../sysprep/virt-sysprep.pod:13 ../test-tool/libguestfs-test-tool.pod:11 ../tools/virt-list-filesystems.pl:45 ../tools/virt-list-partitions.pl:45 ../tools/virt-make-fs.pl:47 ../tools/virt-tar.pl:77 ../tools/virt-win-reg.pl:63
 msgid "DESCRIPTION"
 msgstr ""
 
@@ -746,7 +746,7 @@ msgid ""
 msgstr ""
 
 #. type: =head1
-#: ../align/virt-alignment-scan.pod:352 ../appliance/libguestfs-make-fixed-appliance.pod:144 ../cat/virt-cat.pod:243 ../cat/virt-filesystems.pod:389 ../cat/virt-ls.pod:495 ../df/virt-df.pod:253 ../edit/virt-edit.pod:354 ../erlang/examples/guestfs-erlang.pod:97 ../examples/guestfs-examples.pod:33 ../examples/guestfs-recipes.pod:384 ../examples/guestfs-testing.pod:291 ../fish/guestfish.pod:1268 ../fish/virt-copy-in.pod:50 ../fish/virt-copy-out.pod:39 ../fish/virt-tar-in.pod:47 ../fish/virt-tar-out.pod:41 ../format/virt-format.pod:177 ../fuse/guestmount.pod:317 ../inspector/virt-inspector.pod:501 ../java/examples/guestfs-java.pod:45 ../ocaml/examples/guestfs-ocaml.pod:78 ../perl/examples/guestfs-perl.pod:39 ../python/examples/guestfs-python.pod:42 ../rescue/virt-rescue.pod:325 ../resize/virt-resize.pod:702 ../ruby/examples/guestfs-ruby.pod:36 ../sparsify/virt-sparsify.pod:278 ../src/guestfs.pod:3346 ../sysprep/virt-sysprep.pod:400 ../test-tool/libguestfs-test-tool.pod:100 ../tools/virt-list-filesystems.pl:197 ../tools/virt-list-partitions.pl:267 ../tools/virt-make-fs.pl:559 ../tools/virt-tar.pl:296 ../tools/virt-win-reg.pl:757
+#: ../align/virt-alignment-scan.pod:352 ../appliance/libguestfs-make-fixed-appliance.pod:144 ../cat/virt-cat.pod:243 ../cat/virt-filesystems.pod:389 ../cat/virt-ls.pod:495 ../df/virt-df.pod:253 ../edit/virt-edit.pod:354 ../erlang/examples/guestfs-erlang.pod:97 ../examples/guestfs-examples.pod:33 ../examples/guestfs-performance.pod:102 ../examples/guestfs-recipes.pod:384 ../examples/guestfs-testing.pod:291 ../fish/guestfish.pod:1268 ../fish/virt-copy-in.pod:50 ../fish/virt-copy-out.pod:39 ../fish/virt-tar-in.pod:47 ../fish/virt-tar-out.pod:41 ../format/virt-format.pod:177 ../fuse/guestmount.pod:317 ../inspector/virt-inspector.pod:501 ../java/examples/guestfs-java.pod:45 ../ocaml/examples/guestfs-ocaml.pod:78 ../perl/examples/guestfs-perl.pod:39 ../python/examples/guestfs-python.pod:42 ../rescue/virt-rescue.pod:325 ../resize/virt-resize.pod:702 ../ruby/examples/guestfs-ruby.pod:36 ../sparsify/virt-sparsify.pod:278 ../src/guestfs.pod:3346 ../sysprep/virt-sysprep.pod:400 ../test-tool/libguestfs-test-tool.pod:100 ../tools/virt-list-filesystems.pl:197 ../tools/virt-list-partitions.pl:267 ../tools/virt-make-fs.pl:559 ../tools/virt-tar.pl:296 ../tools/virt-win-reg.pl:757
 msgid "SEE ALSO"
 msgstr ""
 
@@ -768,7 +768,7 @@ msgid "Richard W.M. Jones L<http://people.redhat.com/~rjones/>"
 msgstr ""
 
 #. type: =head1
-#: ../align/virt-alignment-scan.pod:365 ../appliance/libguestfs-make-fixed-appliance.pod:157 ../cat/virt-cat.pod:256 ../cat/virt-filesystems.pod:404 ../cat/virt-ls.pod:511 ../df/virt-df.pod:265 ../edit/virt-edit.pod:372 ../erlang/examples/guestfs-erlang.pod:114 ../examples/guestfs-examples.pod:49 ../examples/guestfs-recipes.pod:401 ../examples/guestfs-testing.pod:302 ../fish/guestfish.pod:1300 ../fish/virt-copy-in.pod:64 ../fish/virt-copy-out.pod:53 ../fish/virt-tar-in.pod:62 ../fish/virt-tar-out.pod:55 ../format/virt-format.pod:191 ../fuse/guestmount.pod:332 ../inspector/virt-inspector.pod:524 ../java/examples/guestfs-java.pod:62 ../ocaml/examples/guestfs-ocaml.pod:95 ../perl/examples/guestfs-perl.pod:56 ../python/examples/guestfs-python.pod:58 ../rescue/virt-rescue.pod:338 ../resize/virt-resize.pod:729 ../ruby/examples/guestfs-ruby.pod:52 ../sparsify/virt-sparsify.pod:295 ../src/guestfs.pod:3430 ../sysprep/virt-sysprep.pod:419 ../test-tool/libguestfs-test-tool.pod:110 ../tools/virt-list-filesystems.pl:214 ../tools/virt-list-partitions.pl:283 ../tools/virt-make-fs.pl:589 ../tools/virt-tar.pl:315 ../tools/virt-win-reg.pl:787
+#: ../align/virt-alignment-scan.pod:365 ../appliance/libguestfs-make-fixed-appliance.pod:157 ../cat/virt-cat.pod:256 ../cat/virt-filesystems.pod:404 ../cat/virt-ls.pod:511 ../df/virt-df.pod:265 ../edit/virt-edit.pod:372 ../erlang/examples/guestfs-erlang.pod:114 ../examples/guestfs-examples.pod:49 ../examples/guestfs-performance.pod:114 ../examples/guestfs-recipes.pod:401 ../examples/guestfs-testing.pod:302 ../fish/guestfish.pod:1300 ../fish/virt-copy-in.pod:64 ../fish/virt-copy-out.pod:53 ../fish/virt-tar-in.pod:62 ../fish/virt-tar-out.pod:55 ../format/virt-format.pod:191 ../fuse/guestmount.pod:332 ../inspector/virt-inspector.pod:524 ../java/examples/guestfs-java.pod:62 ../ocaml/examples/guestfs-ocaml.pod:95 ../perl/examples/guestfs-perl.pod:56 ../python/examples/guestfs-python.pod:58 ../rescue/virt-rescue.pod:338 ../resize/virt-resize.pod:729 ../ruby/examples/guestfs-ruby.pod:52 ../sparsify/virt-sparsify.pod:295 ../src/guestfs.pod:3430 ../sysprep/virt-sysprep.pod:419 ../test-tool/libguestfs-test-tool.pod:110 ../tools/virt-list-filesystems.pl:214 ../tools/virt-list-partitions.pl:283 ../tools/virt-make-fs.pl:589 ../tools/virt-tar.pl:315 ../tools/virt-win-reg.pl:787
 msgid "COPYRIGHT"
 msgstr ""
 
@@ -1069,12 +1069,12 @@ msgid ""
 msgstr ""
 
 #. type: =head1
-#: ../appliance/libguestfs-make-fixed-appliance.pod:153 ../erlang/examples/guestfs-erlang.pod:110 ../examples/guestfs-examples.pod:45 ../examples/guestfs-recipes.pod:397 ../examples/guestfs-testing.pod:298 ../fish/guestfish.pod:1296 ../fish/virt-copy-in.pod:60 ../fish/virt-copy-out.pod:49 ../fish/virt-tar-in.pod:58 ../fish/virt-tar-out.pod:51 ../fuse/guestmount.pod:328 ../inspector/virt-inspector.pod:510 ../java/examples/guestfs-java.pod:58 ../ocaml/examples/guestfs-ocaml.pod:91 ../perl/examples/guestfs-perl.pod:52 ../python/examples/guestfs-python.pod:54 ../ruby/examples/guestfs-ruby.pod:48 ../src/guestfs.pod:3426 ../test-tool/libguestfs-test-tool.pod:106
+#: ../appliance/libguestfs-make-fixed-appliance.pod:153 ../erlang/examples/guestfs-erlang.pod:110 ../examples/guestfs-examples.pod:45 ../examples/guestfs-performance.pod:110 ../examples/guestfs-recipes.pod:397 ../examples/guestfs-testing.pod:298 ../fish/guestfish.pod:1296 ../fish/virt-copy-in.pod:60 ../fish/virt-copy-out.pod:49 ../fish/virt-tar-in.pod:58 ../fish/virt-tar-out.pod:51 ../fuse/guestmount.pod:328 ../inspector/virt-inspector.pod:510 ../java/examples/guestfs-java.pod:58 ../ocaml/examples/guestfs-ocaml.pod:91 ../perl/examples/guestfs-perl.pod:52 ../python/examples/guestfs-python.pod:54 ../ruby/examples/guestfs-ruby.pod:48 ../src/guestfs.pod:3426 ../test-tool/libguestfs-test-tool.pod:106
 msgid "AUTHORS"
 msgstr ""
 
 #. type: textblock
-#: ../appliance/libguestfs-make-fixed-appliance.pod:155 ../erlang/examples/guestfs-erlang.pod:112 ../examples/guestfs-examples.pod:47 ../examples/guestfs-recipes.pod:399 ../examples/guestfs-testing.pod:300 ../fish/guestfish.pod:1298 ../fish/virt-copy-in.pod:62 ../fish/virt-copy-out.pod:51 ../fish/virt-tar-in.pod:60 ../fish/virt-tar-out.pod:53 ../fuse/guestmount.pod:330 ../java/examples/guestfs-java.pod:60 ../ocaml/examples/guestfs-ocaml.pod:93 ../perl/examples/guestfs-perl.pod:54 ../python/examples/guestfs-python.pod:56 ../ruby/examples/guestfs-ruby.pod:50 ../src/guestfs.pod:3428 ../test-tool/libguestfs-test-tool.pod:108
+#: ../appliance/libguestfs-make-fixed-appliance.pod:155 ../erlang/examples/guestfs-erlang.pod:112 ../examples/guestfs-examples.pod:47 ../examples/guestfs-performance.pod:112 ../examples/guestfs-recipes.pod:399 ../examples/guestfs-testing.pod:300 ../fish/guestfish.pod:1298 ../fish/virt-copy-in.pod:62 ../fish/virt-copy-out.pod:51 ../fish/virt-tar-in.pod:60 ../fish/virt-tar-out.pod:53 ../fuse/guestmount.pod:330 ../java/examples/guestfs-java.pod:60 ../ocaml/examples/guestfs-ocaml.pod:93 ../perl/examples/guestfs-perl.pod:54 ../python/examples/guestfs-python.pod:56 ../ruby/examples/guestfs-ruby.pod:50 ../src/guestfs.pod:3428 ../test-tool/libguestfs-test-tool.pod:108
 msgid "Richard W.M. Jones (C<rjones at redhat dot com>)"
 msgstr ""
 
@@ -3887,7 +3887,7 @@ msgid ""
 msgstr ""
 
 #. type: textblock
-#: ../erlang/examples/guestfs-erlang.pod:121 ../examples/guestfs-examples.pod:56 ../examples/guestfs-recipes.pod:408 ../examples/guestfs-testing.pod:306 ../java/examples/guestfs-java.pod:69 ../ocaml/examples/guestfs-ocaml.pod:102 ../perl/examples/guestfs-perl.pod:63 ../python/examples/guestfs-python.pod:65 ../ruby/examples/guestfs-ruby.pod:59 ../src/guestfs.pod:3435
+#: ../erlang/examples/guestfs-erlang.pod:121 ../examples/guestfs-examples.pod:56 ../examples/guestfs-performance.pod:118 ../examples/guestfs-recipes.pod:408 ../examples/guestfs-testing.pod:306 ../java/examples/guestfs-java.pod:69 ../ocaml/examples/guestfs-ocaml.pod:102 ../perl/examples/guestfs-perl.pod:63 ../python/examples/guestfs-python.pod:65 ../ruby/examples/guestfs-ruby.pod:59 ../src/guestfs.pod:3435
 msgid ""
 "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 "
@@ -3896,7 +3896,7 @@ msgid ""
 msgstr ""
 
 #. type: textblock
-#: ../erlang/examples/guestfs-erlang.pod:126 ../examples/guestfs-examples.pod:61 ../examples/guestfs-recipes.pod:413 ../examples/guestfs-testing.pod:311 ../java/examples/guestfs-java.pod:74 ../ocaml/examples/guestfs-ocaml.pod:107 ../perl/examples/guestfs-perl.pod:68 ../python/examples/guestfs-python.pod:70 ../ruby/examples/guestfs-ruby.pod:64 ../src/guestfs.pod:3440
+#: ../erlang/examples/guestfs-erlang.pod:126 ../examples/guestfs-examples.pod:61 ../examples/guestfs-performance.pod:123 ../examples/guestfs-recipes.pod:413 ../examples/guestfs-testing.pod:311 ../java/examples/guestfs-java.pod:74 ../ocaml/examples/guestfs-ocaml.pod:107 ../perl/examples/guestfs-perl.pod:68 ../python/examples/guestfs-python.pod:70 ../ruby/examples/guestfs-ruby.pod:64 ../src/guestfs.pod:3440
 msgid ""
 "This library is distributed in the hope that it will be useful, but WITHOUT "
 "ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or "
@@ -3905,7 +3905,7 @@ msgid ""
 msgstr ""
 
 #. type: textblock
-#: ../erlang/examples/guestfs-erlang.pod:131 ../examples/guestfs-examples.pod:66 ../examples/guestfs-recipes.pod:418 ../examples/guestfs-testing.pod:316 ../java/examples/guestfs-java.pod:79 ../ocaml/examples/guestfs-ocaml.pod:112 ../perl/examples/guestfs-perl.pod:73 ../python/examples/guestfs-python.pod:75 ../ruby/examples/guestfs-ruby.pod:69 ../src/guestfs.pod:3445
+#: ../erlang/examples/guestfs-erlang.pod:131 ../examples/guestfs-examples.pod:66 ../examples/guestfs-performance.pod:128 ../examples/guestfs-recipes.pod:418 ../examples/guestfs-testing.pod:316 ../java/examples/guestfs-java.pod:79 ../ocaml/examples/guestfs-ocaml.pod:112 ../perl/examples/guestfs-perl.pod:73 ../python/examples/guestfs-python.pod:75 ../ruby/examples/guestfs-ruby.pod:69 ../src/guestfs.pod:3445
 msgid ""
 "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, "
@@ -3966,6 +3966,184 @@ msgstr ""
 msgid "Copyright (C) 2010 Red Hat Inc. L<http://libguestfs.org/>"
 msgstr ""
 
+#. type: textblock
+#: ../examples/guestfs-performance.pod:5
+msgid "guestfs-performance - engineering libguestfs for greatest performance"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:9
+msgid ""
+"This page documents how to get the greatest performance out of libguestfs, "
+"especially when you expect to use libguestfs to manipulate thousands of "
+"virtual machines or disk images."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:13
+msgid ""
+"Three main areas are covered. Libguestfs runs an appliance (a small Linux "
+"distribution) inside qemu/KVM.  The first two areas are: minimizing the time "
+"taken to start this appliance, and the number of times the appliance has to "
+"be started.  The third area is shortening the time taken for inspection of "
+"VMs."
+msgstr ""
+
+#. type: =head1
+#: ../examples/guestfs-performance.pod:19
+msgid "BASELINE MEASUREMENTS"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:21
+msgid "Before making changes to how you use libguestfs, take baseline measurements."
+msgstr ""
+
+#. type: =head2
+#: ../examples/guestfs-performance.pod:24
+msgid "BASELINE: STARTING THE APPLIANCE"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:26
+msgid "On an unloaded machine, time how long it takes to start up the appliance:"
+msgstr ""
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:29 ../examples/guestfs-testing.pod:36
+#, no-wrap
+msgid ""
+" time guestfish -a /dev/null run\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:31
+msgid ""
+"Run this command several times in a row and discard the first few runs, so "
+"that you are measuring a typical \"hot cache\" case."
+msgstr ""
+
+#. type: =head3
+#: ../examples/guestfs-performance.pod:34 ../examples/guestfs-performance.pod:67
+msgid "Explanation"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:36
+msgid ""
+"This command starts up the libguestfs appliance on a null disk, and then "
+"immediately shuts it down.  The first time you run the command, it will "
+"create an appliance and cache it (usually under C</var/tmp/.guestfs-*>).  "
+"Subsequent runs should reuse the cached appliance."
+msgstr ""
+
+#. type: =head3
+#: ../examples/guestfs-performance.pod:42 ../examples/guestfs-performance.pod:78
+msgid "Expected results"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:44
+msgid ""
+"You should expect to be getting times under 6 seconds.  If the times you see "
+"on an unloaded machine are above this, then see the section "
+"L</TROUBLESHOOTING POOR PERFORMANCE> below."
+msgstr ""
+
+#. type: =head2
+#: ../examples/guestfs-performance.pod:48
+msgid "BASELINE: PERFORMING INSPECTION OF A GUEST"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:50
+msgid ""
+"For this test you will need an unloaded machine and at least one real guest "
+"or disk image.  If you are planning to use libguestfs against only X guests "
+"(eg. X = Windows), then using an X guest here would be most appropriate.  If "
+"you are planning to run libguestfs against a mix of guests, then use a mix "
+"of guests for testing here."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:56
+msgid ""
+"Time how long it takes to perform inspection and mount the disks of the "
+"guest.  Use the first command if you will be using disk images, and the "
+"second command if you will be using libvirt."
+msgstr ""
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:60
+#, no-wrap
+msgid ""
+" time guestfish --ro -a disk.img -i exit\n"
+"\n"
+msgstr ""
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:62
+#, no-wrap
+msgid ""
+" time guestfish --ro -d GuestName -i exit\n"
+"\n"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:64
+msgid ""
+"Run the command several times in a row and discard the first few runs, so "
+"that you are measuring a typical \"hot cache\" case."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:69
+msgid ""
+"This command starts up the libguestfs appliance on the named disk image or "
+"libvirt guest, performs libguestfs inspection on it (see "
+"L<guestfs(3)/INSPECTION>), mounts the guest's disks, then discards all these "
+"results and shuts down."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:74
+msgid ""
+"The first time you run the command, it will create an appliance and cache it "
+"(usually under C</var/tmp/.guestfs-*>).  Subsequent runs should reuse the "
+"cached appliance."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:80
+msgid ""
+"You should expect times which are E<le> 5 seconds greater than measured in "
+"the first baseline test above.  (For example, if the first baseline test ran "
+"in 5 seconds, then this test should run in E<le> 10 seconds)."
+msgstr ""
+
+#. type: =head1
+#: ../examples/guestfs-performance.pod:92
+msgid "TROUBLESHOOTING POOR PERFORMANCE"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:94
+msgid "** KVM ** Geode ** etc."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:104
+msgid ""
+"L<guestfish(1)>, L<guestfs(3)>, L<guestfs-examples(3)>, "
+"L<libguestfs-make-fixed-appliance(1)>, L<http://libguestfs.org/>."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:116
+msgid "Copyright (C) 2012 Red Hat Inc. L<http://libguestfs.org/>"
+msgstr ""
+
 #. type: =end
 #: ../examples/guestfs-recipes.pod:3 ../examples/guestfs-recipes.pod:12
 msgid "comment"
@@ -4844,14 +5022,6 @@ msgid ""
 "command a few times:"
 msgstr ""
 
-#. type: verbatim
-#: ../examples/guestfs-testing.pod:36
-#, no-wrap
-msgid ""
-" time guestfish -a /dev/null run\n"
-"\n"
-msgstr ""
-
 #. type: textblock
 #: ../examples/guestfs-testing.pod:38
 msgid ""
diff --git a/po-docs/podfiles b/po-docs/podfiles
index a9139845..c3c6e251 100644
--- a/po-docs/podfiles
+++ b/po-docs/podfiles
@@ -7,6 +7,7 @@
 ../edit/virt-edit.pod
 ../erlang/examples/guestfs-erlang.pod
 ../examples/guestfs-examples.pod
+../examples/guestfs-performance.pod
 ../examples/guestfs-recipes.pod
 ../examples/guestfs-testing.pod
 ../fish/guestfish-actions.pod
diff --git a/po-docs/uk.po b/po-docs/uk.po
index d4364a2a..48020874 100644
--- a/po-docs/uk.po
+++ b/po-docs/uk.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: libguestfs\n"
 "Report-Msgid-Bugs-To: libguestfs@redhat.com\n"
-"POT-Creation-Date: 2012-04-03 12:57+0200\n"
+"POT-Creation-Date: 2012-04-10 20:06+0200\n"
 "PO-Revision-Date: 2012-03-30 17:30+0000\n"
 "Last-Translator: rjones <rjones@redhat.com>\n"
 "Language-Team: Ukrainian <trans-uk@lists.fedoraproject.org>\n"
@@ -24,17 +24,18 @@ msgstr ""
 #: ../appliance/libguestfs-make-fixed-appliance.pod:3 ../cat/virt-cat.pod:3
 #: ../cat/virt-filesystems.pod:3 ../cat/virt-ls.pod:3 ../df/virt-df.pod:3
 #: ../edit/virt-edit.pod:3 ../erlang/examples/guestfs-erlang.pod:3
-#: ../examples/guestfs-examples.pod:3 ../examples/guestfs-recipes.pod:14
-#: ../examples/guestfs-testing.pod:3 ../fish/guestfish.pod:3
-#: ../fish/virt-copy-in.pod:3 ../fish/virt-copy-out.pod:3
-#: ../fish/virt-tar-in.pod:3 ../fish/virt-tar-out.pod:3
-#: ../format/virt-format.pod:3 ../fuse/guestmount.pod:3
-#: ../inspector/virt-inspector.pod:3 ../java/examples/guestfs-java.pod:3
-#: ../ocaml/examples/guestfs-ocaml.pod:3 ../perl/examples/guestfs-perl.pod:3
-#: ../python/examples/guestfs-python.pod:3 ../rescue/virt-rescue.pod:3
-#: ../resize/virt-resize.pod:3 ../ruby/examples/guestfs-ruby.pod:3
-#: ../sparsify/virt-sparsify.pod:3 ../src/guestfs.pod:3
-#: ../sysprep/virt-sysprep.pod:3 ../test-tool/libguestfs-test-tool.pod:3
+#: ../examples/guestfs-examples.pod:3 ../examples/guestfs-performance.pod:3
+#: ../examples/guestfs-recipes.pod:14 ../examples/guestfs-testing.pod:3
+#: ../fish/guestfish.pod:3 ../fish/virt-copy-in.pod:3
+#: ../fish/virt-copy-out.pod:3 ../fish/virt-tar-in.pod:3
+#: ../fish/virt-tar-out.pod:3 ../format/virt-format.pod:3
+#: ../fuse/guestmount.pod:3 ../inspector/virt-inspector.pod:3
+#: ../java/examples/guestfs-java.pod:3 ../ocaml/examples/guestfs-ocaml.pod:3
+#: ../perl/examples/guestfs-perl.pod:3 ../python/examples/guestfs-python.pod:3
+#: ../rescue/virt-rescue.pod:3 ../resize/virt-resize.pod:3
+#: ../ruby/examples/guestfs-ruby.pod:3 ../sparsify/virt-sparsify.pod:3
+#: ../src/guestfs.pod:3 ../sysprep/virt-sysprep.pod:3
+#: ../test-tool/libguestfs-test-tool.pod:3
 #: ../tools/virt-list-filesystems.pl:30 ../tools/virt-list-partitions.pl:30
 #: ../tools/virt-make-fs.pl:35 ../tools/virt-tar.pl:31
 #: ../tools/virt-win-reg.pl:35
@@ -93,13 +94,14 @@ msgstr ""
 #: ../appliance/libguestfs-make-fixed-appliance.pod:13 ../cat/virt-cat.pod:19
 #: ../cat/virt-filesystems.pod:13 ../cat/virt-ls.pod:19 ../df/virt-df.pod:21
 #: ../edit/virt-edit.pod:27 ../erlang/examples/guestfs-erlang.pod:16
-#: ../examples/guestfs-examples.pod:19 ../examples/guestfs-recipes.pod:18
-#: ../examples/guestfs-testing.pod:7 ../fish/guestfish.pod:30
-#: ../fish/virt-copy-in.pod:19 ../fish/virt-copy-out.pod:13
-#: ../fish/virt-tar-in.pod:21 ../fish/virt-tar-out.pod:15
-#: ../format/virt-format.pod:11 ../fuse/guestmount.pod:20
-#: ../inspector/virt-inspector.pod:19 ../java/examples/guestfs-java.pod:15
-#: ../ocaml/examples/guestfs-ocaml.pod:25 ../perl/examples/guestfs-perl.pod:18
+#: ../examples/guestfs-examples.pod:19 ../examples/guestfs-performance.pod:7
+#: ../examples/guestfs-recipes.pod:18 ../examples/guestfs-testing.pod:7
+#: ../fish/guestfish.pod:30 ../fish/virt-copy-in.pod:19
+#: ../fish/virt-copy-out.pod:13 ../fish/virt-tar-in.pod:21
+#: ../fish/virt-tar-out.pod:15 ../format/virt-format.pod:11
+#: ../fuse/guestmount.pod:20 ../inspector/virt-inspector.pod:19
+#: ../java/examples/guestfs-java.pod:15 ../ocaml/examples/guestfs-ocaml.pod:25
+#: ../perl/examples/guestfs-perl.pod:18
 #: ../python/examples/guestfs-python.pod:14 ../rescue/virt-rescue.pod:31
 #: ../resize/virt-resize.pod:13 ../ruby/examples/guestfs-ruby.pod:15
 #: ../sparsify/virt-sparsify.pod:11 ../src/guestfs.pod:23
@@ -1129,13 +1131,14 @@ msgstr ""
 #: ../cat/virt-cat.pod:243 ../cat/virt-filesystems.pod:389
 #: ../cat/virt-ls.pod:495 ../df/virt-df.pod:253 ../edit/virt-edit.pod:354
 #: ../erlang/examples/guestfs-erlang.pod:97
-#: ../examples/guestfs-examples.pod:33 ../examples/guestfs-recipes.pod:384
-#: ../examples/guestfs-testing.pod:291 ../fish/guestfish.pod:1268
-#: ../fish/virt-copy-in.pod:50 ../fish/virt-copy-out.pod:39
-#: ../fish/virt-tar-in.pod:47 ../fish/virt-tar-out.pod:41
-#: ../format/virt-format.pod:177 ../fuse/guestmount.pod:317
-#: ../inspector/virt-inspector.pod:501 ../java/examples/guestfs-java.pod:45
-#: ../ocaml/examples/guestfs-ocaml.pod:78 ../perl/examples/guestfs-perl.pod:39
+#: ../examples/guestfs-examples.pod:33 ../examples/guestfs-performance.pod:102
+#: ../examples/guestfs-recipes.pod:384 ../examples/guestfs-testing.pod:291
+#: ../fish/guestfish.pod:1268 ../fish/virt-copy-in.pod:50
+#: ../fish/virt-copy-out.pod:39 ../fish/virt-tar-in.pod:47
+#: ../fish/virt-tar-out.pod:41 ../format/virt-format.pod:177
+#: ../fuse/guestmount.pod:317 ../inspector/virt-inspector.pod:501
+#: ../java/examples/guestfs-java.pod:45 ../ocaml/examples/guestfs-ocaml.pod:78
+#: ../perl/examples/guestfs-perl.pod:39
 #: ../python/examples/guestfs-python.pod:42 ../rescue/virt-rescue.pod:325
 #: ../resize/virt-resize.pod:702 ../ruby/examples/guestfs-ruby.pod:36
 #: ../sparsify/virt-sparsify.pod:278 ../src/guestfs.pod:3346
@@ -1186,13 +1189,14 @@ msgstr "Richard W.M. Jones L<http://people.redhat.com/~rjones/>"
 #: ../cat/virt-cat.pod:256 ../cat/virt-filesystems.pod:404
 #: ../cat/virt-ls.pod:511 ../df/virt-df.pod:265 ../edit/virt-edit.pod:372
 #: ../erlang/examples/guestfs-erlang.pod:114
-#: ../examples/guestfs-examples.pod:49 ../examples/guestfs-recipes.pod:401
-#: ../examples/guestfs-testing.pod:302 ../fish/guestfish.pod:1300
-#: ../fish/virt-copy-in.pod:64 ../fish/virt-copy-out.pod:53
-#: ../fish/virt-tar-in.pod:62 ../fish/virt-tar-out.pod:55
-#: ../format/virt-format.pod:191 ../fuse/guestmount.pod:332
-#: ../inspector/virt-inspector.pod:524 ../java/examples/guestfs-java.pod:62
-#: ../ocaml/examples/guestfs-ocaml.pod:95 ../perl/examples/guestfs-perl.pod:56
+#: ../examples/guestfs-examples.pod:49 ../examples/guestfs-performance.pod:114
+#: ../examples/guestfs-recipes.pod:401 ../examples/guestfs-testing.pod:302
+#: ../fish/guestfish.pod:1300 ../fish/virt-copy-in.pod:64
+#: ../fish/virt-copy-out.pod:53 ../fish/virt-tar-in.pod:62
+#: ../fish/virt-tar-out.pod:55 ../format/virt-format.pod:191
+#: ../fuse/guestmount.pod:332 ../inspector/virt-inspector.pod:524
+#: ../java/examples/guestfs-java.pod:62 ../ocaml/examples/guestfs-ocaml.pod:95
+#: ../perl/examples/guestfs-perl.pod:56
 #: ../python/examples/guestfs-python.pod:58 ../rescue/virt-rescue.pod:338
 #: ../resize/virt-resize.pod:729 ../ruby/examples/guestfs-ruby.pod:52
 #: ../sparsify/virt-sparsify.pod:295 ../src/guestfs.pod:3430
@@ -1554,13 +1558,13 @@ msgstr ""
 #. type: =head1
 #: ../appliance/libguestfs-make-fixed-appliance.pod:153
 #: ../erlang/examples/guestfs-erlang.pod:110
-#: ../examples/guestfs-examples.pod:45 ../examples/guestfs-recipes.pod:397
-#: ../examples/guestfs-testing.pod:298 ../fish/guestfish.pod:1296
-#: ../fish/virt-copy-in.pod:60 ../fish/virt-copy-out.pod:49
-#: ../fish/virt-tar-in.pod:58 ../fish/virt-tar-out.pod:51
-#: ../fuse/guestmount.pod:328 ../inspector/virt-inspector.pod:510
-#: ../java/examples/guestfs-java.pod:58 ../ocaml/examples/guestfs-ocaml.pod:91
-#: ../perl/examples/guestfs-perl.pod:52
+#: ../examples/guestfs-examples.pod:45 ../examples/guestfs-performance.pod:110
+#: ../examples/guestfs-recipes.pod:397 ../examples/guestfs-testing.pod:298
+#: ../fish/guestfish.pod:1296 ../fish/virt-copy-in.pod:60
+#: ../fish/virt-copy-out.pod:49 ../fish/virt-tar-in.pod:58
+#: ../fish/virt-tar-out.pod:51 ../fuse/guestmount.pod:328
+#: ../inspector/virt-inspector.pod:510 ../java/examples/guestfs-java.pod:58
+#: ../ocaml/examples/guestfs-ocaml.pod:91 ../perl/examples/guestfs-perl.pod:52
 #: ../python/examples/guestfs-python.pod:54
 #: ../ruby/examples/guestfs-ruby.pod:48 ../src/guestfs.pod:3426
 #: ../test-tool/libguestfs-test-tool.pod:106
@@ -1570,12 +1574,13 @@ msgstr "АВТОРИ"
 #. type: textblock
 #: ../appliance/libguestfs-make-fixed-appliance.pod:155
 #: ../erlang/examples/guestfs-erlang.pod:112
-#: ../examples/guestfs-examples.pod:47 ../examples/guestfs-recipes.pod:399
-#: ../examples/guestfs-testing.pod:300 ../fish/guestfish.pod:1298
-#: ../fish/virt-copy-in.pod:62 ../fish/virt-copy-out.pod:51
-#: ../fish/virt-tar-in.pod:60 ../fish/virt-tar-out.pod:53
-#: ../fuse/guestmount.pod:330 ../java/examples/guestfs-java.pod:60
-#: ../ocaml/examples/guestfs-ocaml.pod:93 ../perl/examples/guestfs-perl.pod:54
+#: ../examples/guestfs-examples.pod:47 ../examples/guestfs-performance.pod:112
+#: ../examples/guestfs-recipes.pod:399 ../examples/guestfs-testing.pod:300
+#: ../fish/guestfish.pod:1298 ../fish/virt-copy-in.pod:62
+#: ../fish/virt-copy-out.pod:51 ../fish/virt-tar-in.pod:60
+#: ../fish/virt-tar-out.pod:53 ../fuse/guestmount.pod:330
+#: ../java/examples/guestfs-java.pod:60 ../ocaml/examples/guestfs-ocaml.pod:93
+#: ../perl/examples/guestfs-perl.pod:54
 #: ../python/examples/guestfs-python.pod:56
 #: ../ruby/examples/guestfs-ruby.pod:50 ../src/guestfs.pod:3428
 #: ../test-tool/libguestfs-test-tool.pod:108
@@ -4620,8 +4625,9 @@ msgstr ""
 
 #. type: textblock
 #: ../erlang/examples/guestfs-erlang.pod:121
-#: ../examples/guestfs-examples.pod:56 ../examples/guestfs-recipes.pod:408
-#: ../examples/guestfs-testing.pod:306 ../java/examples/guestfs-java.pod:69
+#: ../examples/guestfs-examples.pod:56 ../examples/guestfs-performance.pod:118
+#: ../examples/guestfs-recipes.pod:408 ../examples/guestfs-testing.pod:306
+#: ../java/examples/guestfs-java.pod:69
 #: ../ocaml/examples/guestfs-ocaml.pod:102
 #: ../perl/examples/guestfs-perl.pod:63
 #: ../python/examples/guestfs-python.pod:65
@@ -4635,8 +4641,9 @@ msgstr ""
 
 #. type: textblock
 #: ../erlang/examples/guestfs-erlang.pod:126
-#: ../examples/guestfs-examples.pod:61 ../examples/guestfs-recipes.pod:413
-#: ../examples/guestfs-testing.pod:311 ../java/examples/guestfs-java.pod:74
+#: ../examples/guestfs-examples.pod:61 ../examples/guestfs-performance.pod:123
+#: ../examples/guestfs-recipes.pod:413 ../examples/guestfs-testing.pod:311
+#: ../java/examples/guestfs-java.pod:74
 #: ../ocaml/examples/guestfs-ocaml.pod:107
 #: ../perl/examples/guestfs-perl.pod:68
 #: ../python/examples/guestfs-python.pod:70
@@ -4654,8 +4661,9 @@ msgstr ""
 
 #. type: textblock
 #: ../erlang/examples/guestfs-erlang.pod:131
-#: ../examples/guestfs-examples.pod:66 ../examples/guestfs-recipes.pod:418
-#: ../examples/guestfs-testing.pod:316 ../java/examples/guestfs-java.pod:79
+#: ../examples/guestfs-examples.pod:66 ../examples/guestfs-performance.pod:128
+#: ../examples/guestfs-recipes.pod:418 ../examples/guestfs-testing.pod:316
+#: ../java/examples/guestfs-java.pod:79
 #: ../ocaml/examples/guestfs-ocaml.pod:112
 #: ../perl/examples/guestfs-perl.pod:73
 #: ../python/examples/guestfs-python.pod:75
@@ -4738,6 +4746,208 @@ msgstr ""
 msgid "Copyright (C) 2010 Red Hat Inc. L<http://libguestfs.org/>"
 msgstr "© Red Hat Inc. L<http://libguestfs.org/>, 2010"
 
+#. type: textblock
+#: ../examples/guestfs-performance.pod:5
+msgid "guestfs-performance - engineering libguestfs for greatest performance"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:9
+msgid ""
+"This page documents how to get the greatest performance out of libguestfs, "
+"especially when you expect to use libguestfs to manipulate thousands of "
+"virtual machines or disk images."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:13
+msgid ""
+"Three main areas are covered. Libguestfs runs an appliance (a small Linux "
+"distribution) inside qemu/KVM.  The first two areas are: minimizing the time "
+"taken to start this appliance, and the number of times the appliance has to "
+"be started.  The third area is shortening the time taken for inspection of "
+"VMs."
+msgstr ""
+
+#. type: =head1
+#: ../examples/guestfs-performance.pod:19
+msgid "BASELINE MEASUREMENTS"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:21
+msgid ""
+"Before making changes to how you use libguestfs, take baseline measurements."
+msgstr ""
+
+#. type: =head2
+#: ../examples/guestfs-performance.pod:24
+msgid "BASELINE: STARTING THE APPLIANCE"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:26
+msgid ""
+"On an unloaded machine, time how long it takes to start up the appliance:"
+msgstr ""
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:29 ../examples/guestfs-testing.pod:36
+#, no-wrap
+msgid ""
+" time guestfish -a /dev/null run\n"
+"\n"
+msgstr ""
+" time guestfish -a /dev/null run\n"
+"\n"
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:31
+msgid ""
+"Run this command several times in a row and discard the first few runs, so "
+"that you are measuring a typical \"hot cache\" case."
+msgstr ""
+
+#. type: =head3
+#: ../examples/guestfs-performance.pod:34
+#: ../examples/guestfs-performance.pod:67
+msgid "Explanation"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:36
+msgid ""
+"This command starts up the libguestfs appliance on a null disk, and then "
+"immediately shuts it down.  The first time you run the command, it will "
+"create an appliance and cache it (usually under C</var/tmp/.guestfs-*>).  "
+"Subsequent runs should reuse the cached appliance."
+msgstr ""
+
+#. type: =head3
+#: ../examples/guestfs-performance.pod:42
+#: ../examples/guestfs-performance.pod:78
+msgid "Expected results"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:44
+msgid ""
+"You should expect to be getting times under 6 seconds.  If the times you see "
+"on an unloaded machine are above this, then see the section L</"
+"TROUBLESHOOTING POOR PERFORMANCE> below."
+msgstr ""
+
+#. type: =head2
+#: ../examples/guestfs-performance.pod:48
+msgid "BASELINE: PERFORMING INSPECTION OF A GUEST"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:50
+msgid ""
+"For this test you will need an unloaded machine and at least one real guest "
+"or disk image.  If you are planning to use libguestfs against only X guests "
+"(eg. X = Windows), then using an X guest here would be most appropriate.  If "
+"you are planning to run libguestfs against a mix of guests, then use a mix "
+"of guests for testing here."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:56
+msgid ""
+"Time how long it takes to perform inspection and mount the disks of the "
+"guest.  Use the first command if you will be using disk images, and the "
+"second command if you will be using libvirt."
+msgstr ""
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:60
+#, fuzzy, no-wrap
+#| msgid ""
+#| " guestfish [--ro] -i disk.img\n"
+#| "\n"
+msgid ""
+" time guestfish --ro -a disk.img -i exit\n"
+"\n"
+msgstr ""
+" guestfish [--ro] -i disk.img\n"
+"\n"
+
+#. type: verbatim
+#: ../examples/guestfs-performance.pod:62
+#, fuzzy, no-wrap
+#| msgid ""
+#| " guestfish --ro -d myguest -i\n"
+#| "\n"
+msgid ""
+" time guestfish --ro -d GuestName -i exit\n"
+"\n"
+msgstr ""
+" guestfish --ro -d myguest -i\n"
+"\n"
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:64
+msgid ""
+"Run the command several times in a row and discard the first few runs, so "
+"that you are measuring a typical \"hot cache\" case."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:69
+msgid ""
+"This command starts up the libguestfs appliance on the named disk image or "
+"libvirt guest, performs libguestfs inspection on it (see L<guestfs(3)/"
+"INSPECTION>), mounts the guest's disks, then discards all these results and "
+"shuts down."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:74
+msgid ""
+"The first time you run the command, it will create an appliance and cache it "
+"(usually under C</var/tmp/.guestfs-*>).  Subsequent runs should reuse the "
+"cached appliance."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:80
+msgid ""
+"You should expect times which are E<le> 5 seconds greater than measured in "
+"the first baseline test above.  (For example, if the first baseline test ran "
+"in 5 seconds, then this test should run in E<le> 10 seconds)."
+msgstr ""
+
+#. type: =head1
+#: ../examples/guestfs-performance.pod:92
+msgid "TROUBLESHOOTING POOR PERFORMANCE"
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:94
+msgid "** KVM ** Geode ** etc."
+msgstr ""
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:104
+#, fuzzy
+#| msgid ""
+#| "L<guestfs(3)>, L<guestfish(1)>, L<virt-filesystems(1)>, L<virt-rescue(1)"
+#| ">, L<virt-resize(1)>, L<http://libguestfs.org/>."
+msgid ""
+"L<guestfish(1)>, L<guestfs(3)>, L<guestfs-examples(3)>, L<libguestfs-make-"
+"fixed-appliance(1)>, L<http://libguestfs.org/>."
+msgstr ""
+"L<guestfs(3)>, L<guestfish(1)>, L<virt-filesystems(1)>, L<virt-rescue(1)>, "
+"L<virt-resize(1)>, L<http://libguestfs.org/>."
+
+#. type: textblock
+#: ../examples/guestfs-performance.pod:116
+#, fuzzy
+#| msgid "Copyright (C) 2011 Red Hat Inc. L<http://libguestfs.org/>"
+msgid "Copyright (C) 2012 Red Hat Inc. L<http://libguestfs.org/>"
+msgstr "© Red Hat Inc. L<http://libguestfs.org/>, 2011"
+
 #. type: =end
 #: ../examples/guestfs-recipes.pod:3 ../examples/guestfs-recipes.pod:12
 msgid "comment"
@@ -5766,16 +5976,6 @@ msgid ""
 "command a few times:"
 msgstr ""
 
-#. type: verbatim
-#: ../examples/guestfs-testing.pod:36
-#, no-wrap
-msgid ""
-" time guestfish -a /dev/null run\n"
-"\n"
-msgstr ""
-" time guestfish -a /dev/null run\n"
-"\n"
-
 #. type: textblock
 #: ../examples/guestfs-testing.pod:38
 msgid ""
diff --git a/src/guestfs.pod b/src/guestfs.pod
index 7dc948e5..3f5410a2 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -3375,6 +3375,7 @@ L<virt-tar(1)>,
 L<virt-tar-in(1)>,
 L<virt-tar-out(1)>,
 L<virt-win-reg(1)>,
+L<guestfs-performance(1)>,
 L<guestfs-testing(1)>,
 L<libguestfs-test-tool(1)>,
 L<libguestfs-make-fixed-appliance(1)>,