guestfs-performance - Man Page

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.

Before making changes to how you use libguestfs, take baseline measurements.

 time guestfish -a /dev/null run

 time guestfish --ro -a disk.img -i exit

 time guestfish --ro -d GuestName -i exit

The first time you use libguestfs, it will build and cache an appliance.  This is usually in /var/tmp/.guestfs-*, unless you have set $TMPDIR or $LIBGUESTFS_CACHEDIR in which case it will be under that temporary directory.

For more information about how the appliance is constructed, see "SUPERMIN APPLIANCES" in supermin(1).

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 yum or 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:

• The process of building (or rebuilding) the cached appliance is slow, and you can avoid this happening by using a fixed appliance (see below).
• If not using a fixed appliance, be aware that updating software on the host will cause a one time rebuild of the appliance.
• /var/tmp (or $TMPDIR, $LIBGUESTFS_CACHEDIR) should be on a fast disk, and have plenty of space for the appliance.

To fully control when the appliance is built, you can build a fixed appliance.  This appliance should be stored on a fast local disk.

To build the appliance, run the command:

 libguestfs-make-fixed-appliance <directory>

replacing <directory> with the name of a directory where the appliance will be stored (normally you would name a subdirectory, for example: /usr/local/lib/guestfs/appliance or /dev/shm/appliance).

Then set $LIBGUESTFS_PATH (and ensure this environment variable is set in your libguestfs program), or modify your program so it calls 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: libguestfs-make-fixed-appliance(1)).

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 guestfs_launch at most once per target virtual machine or disk image.

Instead of using a separate instance of guestfish(1) to make a series of changes to the same guest, use a single instance of guestfish and/or use the guestfish --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:

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.
2. There is a hard limit to the number of disks you can add to a single appliance.  Call "guestfs_max_disks" in guestfs(3) to get this limit. For further information see "LIMITS" in guestfs(3).
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 guestfs_lvm_set_filter).

virt-df(1) adds multiple disks by default, so the source code for this program would be a good place to start.

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 (guestfs_inspect_os) is required, auxiliary inspection operations may be avoided:

• Mounting disks is only necessary to get further filesystem information.
• Listing applications (guestfs_inspect_list_applications) is an expensive operation on Linux, but almost free on Windows.
• Generating a guest icon (guestfs_inspect_get_icon) is cheap on Linux but expensive on Windows.

Libguestfs appliances are mostly I/O bound and you can launch multiple appliances in parallel.  Provided there is enough free memory, there should be little difference in launching 1 appliance vs N appliances in parallel.

On a 2-core (4-thread) laptop with 16 GB of RAM, using the (not especially realistic) test Perl script below, the following plot shows excellent scalability when running between 1 and 20 appliances in parallel:

  12 ++---+----+----+----+-----+----+----+----+----+---++
     +    +    +    +    +     +    +    +    +    +    *
     |                                                  |
     |                                               *  |
  11 ++                                                ++
     |                                                  |
     |                                                  |
     |                                          *  *    |
  10 ++                                                ++
     |                                        *         |
     |                                                  |
 s   |                                                  |
   9 ++                                                ++
 e   |                                                  |
     |                                     *            |
 c   |                                                  |
   8 ++                                  *             ++
 o   |                                *                 |
     |                                                  |
 n 7 ++                                                ++
     |                              *                   |
 d   |                           *                      |
     |                                                  |
 s 6 ++                                                ++
     |                      *  *                        |
     |                   *                              |
     |                                                  |
   5 ++                                                ++
     |                                                  |
     |                 *                                |
     |            * *                                   |
   4 ++                                                ++
     |                                                  |
     |                                                  |
     +    *  * *    +    +     +    +    +    +    +    +
   3 ++-*-+----+----+----+-----+----+----+----+----+---++
     0    2    4    6    8     10   12   14   16   18   20
               number of parallel appliances

It is possible to run many more than 20 appliances in parallel, but if you are using the libvirt backend then you should be aware that out of the box libvirt limits the number of client connections to 20.

The simple Perl script below was used to collect the data for the plot above, but there is much more information on this subject, including more advanced test scripts and graphs, available in the following blog postings:

http://rwmj.wordpress.com/2013/02/25/multiple-libguestfs-appliances-in-parallel-part-1/ http://rwmj.wordpress.com/2013/02/25/multiple-libguestfs-appliances-in-parallel-part-2/ http://rwmj.wordpress.com/2013/02/25/multiple-libguestfs-appliances-in-parallel-part-3/ http://rwmj.wordpress.com/2013/02/25/multiple-libguestfs-appliances-in-parallel-part-4/

 #!/usr/bin/env perl
 
 use strict;
 use threads;
 use warnings;
 use Sys::Guestfs;
 use Time::HiRes qw(time);
 
 sub test {
     my $g = Sys::Guestfs->new;
     $g->add_drive_ro ("/dev/null");
     $g->launch ();
     
     # You could add some work for libguestfs to do here.
     
     $g->close ();
 }
 
 # Get everything into cache.
 test (); test (); test ();
 
 for my $nr_threads (1..20) {
     my $start_t = time ();
     my @threads;
     foreach (1..$nr_threads) {
         push @threads, threads->create (\&test)
     }
     foreach (@threads) {
         $_->join ();
         if (my $err = $_->error ()) {
             die "launch failed with $nr_threads threads: $err"
         }
     }
     my $end_t = time ();
     printf ("%d %.2f\n", $nr_threads, $end_t - $start_t);
 }

Sometimes performance regressions happen in other programs (eg. qemu, the kernel) that cause problems for libguestfs.

In https://github.com/libguestfs/libguestfs-analysis-tools boot-benchmark/boot-benchmark-range.pl is a script which can be used to benchmark libguestfs across a range of git commits in another project to find out if any commit is causing a slowdown (or speedup).

To find out how to use this script, consult the manual:

 ./boot-benchmark/boot-benchmark-range.pl --man

supermin(1), guestfish(1), guestfs(3), guestfs-examples(3), guestfs-internals(1), libguestfs-make-fixed-appliance(1), stap(1), qemu(1), gdb(1), http://libguestfs.org/.

Richard W.M. Jones (rjones at redhat dot com)

Copyright (C) 2012-2023 Red Hat Inc.

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

To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

When reporting a bug, please supply:

• The version of libguestfs.
• Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
• Describe the bug accurately and give a way to reproduce it.
• Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report.

guestfs(3), guestfs-building(1), guestfs-faq(1), guestfs-hacking(1), guestfs-release-notes(1), guestfs-release-notes-1.10(1), guestfs-release-notes-1.12(1), guestfs-release-notes-1.14(1), guestfs-release-notes-1.16(1), guestfs-release-notes-1.18(1), guestfs-release-notes-1.20(1), guestfs-release-notes-1.22(1), guestfs-release-notes-1.24(1), guestfs-release-notes-1.26(1), guestfs-release-notes-1.28(1), guestfs-release-notes-1.30(1), guestfs-release-notes-1.32(1), guestfs-release-notes-1.34(1), guestfs-release-notes-1.36(1), guestfs-release-notes-1.38(1), guestfs-release-notes-1.4(1), guestfs-release-notes-1.40(1), guestfs-release-notes-1.42(1), guestfs-release-notes-1.44(1), guestfs-release-notes-1.46(1), guestfs-release-notes-1.48(1), guestfs-release-notes-1.50(1), guestfs-release-notes-1.52(1), guestfs-release-notes-1.54(1), guestfs-release-notes-1.6(1), guestfs-release-notes-1.8(1), libguestfs-make-fixed-appliance(1).