libguestfs-test-tool - Man Page

Diagnostics for libguestfs

Synopsis

 libguestfs-test-tool [--options]

Description

libguestfs-test-tool is a test program shipped with libguestfs to allow you to check basic libguestfs functionality is working.  This is needed because libguestfs occasionally breaks for reasons beyond our control: usually because of changes in the underlying qemu or kernel packages, or the host environment.

If you suspect a problem in libguestfs, then just run:

 libguestfs-test-tool

It will print lots of diagnostic messages.

If it runs to completion successfully, you will see this near the end:

 ===== TEST FINISHED OK =====

and the test tool will exit with code 0.

If it fails (and/or exits with non-zero error code), please paste the complete, unedited output of the test tool into a bug report.  More information about reporting bugs can be found on the http://libguestfs.org/ website.

Options

--help

Display short usage information and exit.

--qemu qemu_binary

If you have downloaded another qemu binary, point this option at the full path of the binary to try it.

--qemudir qemu_source_dir

If you have compiled qemu from source, point this option at the source directory to try it.

-t N
--timeout N

Set the launch timeout to N seconds.  The default is 600 seconds (10 minutes) which does not usually need to be adjusted.

-V
--version

Display the libguestfs version number and exit.

Trying out a Different Version of Qemu

If you have compiled another version of qemu from source and would like to try that, then you can use the --qemudir option to point to the qemu source directory.

If you have downloaded a qemu binary from somewhere, use the --qemu option to point to the binary.

Note when using these options, you can ignore the business of qemu wrapper scripts ("QEMU WRAPPERS" in guestfs(3)), since libguestfs-test-tool writes a wrapper script for you if one is needed.

Trying out a Different Kernel

You can tell supermin to try a different kernel.  You do this by setting the environment variables SUPERMIN_KERNEL, SUPERMIN_KERNEL_VERSION and/or SUPERMIN_MODULES.

Refer to "Environment Variables" in supermin(1) for further information.

Trying out a Different Version of Libvirt

To find out which backend is the default in your libguestfs package, do:

 unset LIBGUESTFS_BACKEND
 guestfish get-backend

If you are using the libvirt backend, then you can try out a different (eg. upstream) version of libvirt by running these commands (not as root):

 killall libvirtd lt-libvirtd
 ~/path/to/libvirt/run libguestfs-test-tool

The first command kills any session libvirtd process(es) that may be running on the machine.  The second command uses libvirt’s run script (in the top-level libvirt build directory) to set some environment variables so that the alternate version of libvirt is used to run the program.

Trying out with / Without Libvirt

To find out which backend is the default in your libguestfs package, do:

 unset LIBGUESTFS_BACKEND
 guestfish get-backend

If you are using the libvirt backend, you can try without (ie. libguestfs directly launching qemu) by doing:

 export LIBGUESTFS_BACKEND=direct

Or if you are using the default (direct) backend, then you can try libvirt:

 export LIBGUESTFS_BACKEND=libvirt

or with libvirt and a specific libvirt URI:

 export LIBGUESTFS_BACKEND=libvirt:qemu:///session

Trying out Different Selinux Settings

To find out which backend is the default in your libguestfs package, do:

 unset LIBGUESTFS_BACKEND
 guestfish get-backend

To find out if SELinux is being used, do:

 getenforce

If you are using libvirt, SELinux and sVirt, then you can try to see if changing SELinux to "permissive" mode makes any difference.  Use this command as root:

 setenforce Permissive

If this makes a difference, look in the audit logs for recent failures ("AVCs"):

 ausearch -m avc -ts recent

You can convert AVCs into suggested SELinux policy rules using tools like audit2allow(1).  For more information, see the "Security Enhanced Linux User Guide".

To reenable SELinux and sVirt, do:

 setenforce Enforcing

Self-Diagnosis

Refer to "APPLIANCE BOOT PROCESS" in guestfs(3) to understand the messages produced by libguestfs-test-tool and/or possible errors.

Exit Status

libguestfs-test-tool returns 0 if the tests completed without error, or 1 if there was an error.

Environment Variables

For the full list of environment variables which may affect libguestfs, please see the guestfs(3) manual page.

See Also

guestfs(3), http://libguestfs.org/, http://qemu.org/.

Authors

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

License

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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Bugs

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:

Referenced By

guestfish(1), guestfs(3), guestfs-building(1), guestfs-examples(3), guestfs-faq(1), guestfs-gobject(3), guestfs-hacking(1), guestfs-internals(1), guestfs-lua(3), guestfs-ocaml(3), guestfs-performance(1), guestfs-perl(3), guestfs-python(3), guestfs-recipes(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.6(1), guestfs-release-notes-1.8(1), guestfs-ruby(3), guestfs-security(1), guestfs-testing(1), guestfs-tools-release-notes-1.48(1), guestfs-tools-release-notes-1.50(1), guestfs-tools-release-notes-1.52(1), guestmount(1), guestunmount(1), libguestfs-make-fixed-appliance(1), libguestfs-tools.conf(5), virt-alignment-scan(1), virt-builder(1), virt-builder-repository(1), virt-cat(1), virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1), virt-diff(1), virt-drivers(1), virt-edit(1), virt-filesystems(1), virt-format(1), virt-get-kernel(1), virt-index-validate(1), virt-inspector(1), virt-log(1), virt-ls(1), virt-make-fs(1), virt-rescue(1), virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1), virt-v2v-hacking(1), virt-v2v-in-place(1), virt-v2v-input-vmware(1), virt-v2v-input-xen(1), virt-v2v-inspector(1), virt-v2v-output-local(1), virt-v2v-output-openstack(1), virt-v2v-output-rhv(1), virt-v2v-release-notes-1.42(1), virt-v2v-release-notes-2.0(1), virt-v2v-release-notes-2.2(1), virt-v2v-release-notes-2.4(1), virt-v2v-support(1), virt-win-reg(1).

2024-01-05 libguestfs-1.52.0 Virtualization Support