libguestfs-test-tool(1)

📦
version 1.61.3 · 14 versions
, in centos-stream 10

💅 libguestfs-test-tool — the diagnostics bestie for libguestfs

okay so this is libguestfs-test-tool(1), living its best life in the Virtualization Support section of the manual. Think of it as the vibe-check tool for your libguestfs setup 🩺✨

🌸 NAME 🌸

libguestfs-test-tool — diagnostics for libguestfs, aka the "is my install actually okay??" checker.

✨ SYNOPSIS ✨

libguestfs-test-tool [--options]

💖 DESCRIPTION 💖

okay so libguestfs-test-tool is a test program that ships with libguestfs, and its whole job is letting you check that basic libguestfs functionality is actually working. lowkey necessary because libguestfs occasionally breaks for reasons completely beyond our control 😭 — usually because of changes in the underlying qemu or kernel packages, or the host environment. not us, not you, just... the ecosystem.

so if you suspect a problem in libguestfs, just run:

libguestfs-test-tool

and it will print lots of diagnostic messages. like, a lot a lot. it's giving main character energy with the output volume, ngl.

if it runs all the way to completion successfully, you'll see this near the end:

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

and the test tool exits with code 0. slay 🎉

if it fails (and/or exits with a non-zero error code), please paste the complete, unedited output of the test tool into a bug report. fr fr, don't trim it, don't summarize it, give us the whole thing. more info about reporting bugs lives on the http://libguestfs.org/ website 🫶

🎀 OPTIONS 🎀

  • --help — displays short usage information and exits. it's giving "just tell me the basics and go".
  • --qemu qemu_binary — if you downloaded another qemu binary, point this option at the full path of the binary so it tries that one instead. 💅
  • --qemudir qemu_source_dir — if you compiled qemu from source, point this option at the source directory to try it.
  • -t N, --timeout N — sets the launch timeout to N seconds. the default is 600 seconds (that's 10 minutes, bestie) and honestly you usually don't need to adjust it. lowkey leave it alone unless you know.
  • -V, --version — displays the libguestfs version number and exits.

🦋 TRYING OUT A DIFFERENT VERSION OF QEMU 🦋

so if you compiled another version of qemu from source and you're like "ooh let me try that one", you can use the --qemudir option to point at the qemu source directory.

and if you downloaded a qemu binary from somewhere, use the --qemu option to point at the binary. easy.

note: when using these options, you can ignore the whole business of qemu wrapper scripts (that's "QEMU WRAPPERS" in guestfs(3)), because libguestfs-test-tool writes a wrapper script for you if one is needed. it's got you, no cap 💜

⭐ 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. iykyk 🌈

🧚 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're using the libvirt backend, then you can try out a different (eg. upstream) version of libvirt by running these commands (not as root, bestie, we're being responsible):

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. iconic behavior honestly ✨

🍓 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're using the libvirt backend, you can try without it (ie. libguestfs directly launching qemu) by doing:

export LIBGUESTFS_BACKEND=direct

or if you're 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

pick your fighter 💀

💜 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're 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". ngl that guide is a whole journey but it's worth it 📚

to re-enable SELinux and sVirt, do:

setenforce Enforcing

(put it back, bestie, we don't leave it in permissive forever 🙈)

🔥 SELF-DIAGNOSIS 🔥

refer to "APPLIANCE BOOT PROCESS" in guestfs(3) to understand the messages produced by libguestfs-test-tool and/or possible errors. that's the decoder ring for all the output you're about to see.

🌟 EXIT STATUS 🌟

libguestfs-test-tool returns 0 if the tests completed without error, or 1 if there was an error. simple as that. no in-between, no "it's complicated" 👑

🌈 ENVIRONMENT VARIABLES 🌈

for the full list of environment variables which may affect libguestfs, please see the guestfs(3) manual page. there are a lot and they all live over there.

👑 SEE ALSO 👑

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

🎀 AUTHORS 🎀

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

Copyright (C) 2009-2025 Red Hat Inc.

📜 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:

  • 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. (yes, the whole thing — the unedited part is not a suggestion 💀)

and that's the whole page, bestie 🫶 this was libguestfs-1.61.3, dated 2026-09-16, and you were reading the libguestfs-test-tool(1) man page. go forth and check your libguestfs install, you got this 💅✨

📦 where this page comes from