1libguestfs-test-tool(1) Virtualization Support libguestfs-test-tool(1)
2
6 libguestfs-test-tool - Diagnostics for libguestfs
7
9 libguestfs-test-tool [--options]
10
12 libguestfs-test-tool is a test program shipped with libguestfs to allow
13 you to check basic libguestfs functionality is working. This is needed
14 because libguestfs occasionally breaks for reasons beyond our control:
15 usually because of changes in the underlying qemu or kernel packages,
16 or the host environment.
17 If you suspect a problem in libguestfs, then just run:
19 libguestfs-test-tool
21 It will print lots of diagnostic messages.
23 If it runs to completion successfully, you will see this near the end:
25 ===== TEST FINISHED OK =====
27 and the test tool will exit with code 0.
29 If it fails (and/or exits with non-zero error code), please paste the
31 complete, unedited output of the test tool into a bug report. More
32 information about reporting bugs can be found on the
33 http://libguestfs.org/ website.
34
36 --help
37 Display short usage information and exit.
38 --qemu qemu_binary
40 If you have downloaded another qemu binary, point this option at
41 the full path of the binary to try it.
42 --qemudir qemu_source_dir
44 If you have compiled qemu from source, point this option at the
45 source directory to try it.
46 -t N
48 --timeout N
49 Set the launch timeout to "N" seconds. The default is 600 seconds
50 (10 minutes) which does not usually need to be adjusted.
51 -V
53 --version
54 Display the libguestfs version number and exit.
55
57 If you have compiled another version of qemu from source and would like
58 to try that, then you can use the --qemudir option to point to the qemu
59 source directory.
60 If you have downloaded a qemu binary from somewhere, use the --qemu
62 option to point to the binary.
63 Note when using these options, you can ignore the business of qemu
65 wrapper scripts ("QEMU WRAPPERS" in guestfs(3)), since libguestfs-test-
66 tool writes a wrapper script for you if one is needed.
67
69 You can tell supermin to try a different kernel. You do this by
70 setting the environment variables "SUPERMIN_KERNEL",
71 "SUPERMIN_KERNEL_VERSION" and/or "SUPERMIN_MODULES".
72 Refer to "ENVIRONMENT VARIABLES" in supermin(1) for further
74 information.
75
77 To find out which backend is the default in your libguestfs package,
78 do:
79 unset LIBGUESTFS_BACKEND
81 guestfish get-backend
82 If you are using the libvirt backend, then you can try out a different
84 (eg. upstream) version of libvirt by running these commands (not as
85 root):
86 killall libvirtd lt-libvirtd
88 ~/path/to/libvirt/run libguestfs-test-tool
89 The first command kills any session "libvirtd" process(es) that may be
91 running on the machine. The second command uses libvirt’s "run" script
92 (in the top-level libvirt build directory) to set some environment
93 variables so that the alternate version of libvirt is used to run the
94 program.
95
97 To find out which backend is the default in your libguestfs package,
98 do:
99 unset LIBGUESTFS_BACKEND
101 guestfish get-backend
102 If you are using the libvirt backend, you can try without (ie.
104 libguestfs directly launching qemu) by doing:
105 export LIBGUESTFS_BACKEND=direct
107 Or if you are using the default (direct) backend, then you can try
109 libvirt:
110 export LIBGUESTFS_BACKEND=libvirt
112 or with libvirt and a specific libvirt URI:
114 export LIBGUESTFS_BACKEND=libvirt:qemu:///session
116
118 To find out which backend is the default in your libguestfs package,
119 do:
120 unset LIBGUESTFS_BACKEND
122 guestfish get-backend
123 To find out if SELinux is being used, do:
125 getenforce
127 If you are using libvirt, SELinux and sVirt, then you can try to see if
129 changing SELinux to "permissive" mode makes any difference. Use this
130 command as root:
131 setenforce Permissive
133 If this makes a difference, look in the audit logs for recent failures
135 ("AVCs"):
136 ausearch -m avc -ts recent
138 You can convert AVCs into suggested SELinux policy rules using tools
140 like audit2allow(1). For more information, see the "Security Enhanced
141 Linux User Guide".
142 To reenable SELinux and sVirt, do:
144 setenforce Enforcing
146
148 Refer to "APPLIANCE BOOT PROCESS" in guestfs(3) to understand the
149 messages produced by libguestfs-test-tool and/or possible errors.
150
152 libguestfs-test-tool returns 0 if the tests completed without error, or
153 1 if there was an error.
154
156 For the full list of environment variables which may affect libguestfs,
157 please see the guestfs(3) manual page.
158
160 guestfs(3), http://libguestfs.org/, http://qemu.org/.
161
163 Richard W.M. Jones ("rjones at redhat dot com")
164
166 Copyright (C) 2009-2023 Red Hat Inc.
167
169 This program is free software; you can redistribute it and/or modify it
170 under the terms of the GNU General Public License as published by the
171 Free Software Foundation; either version 2 of the License, or (at your
172 option) any later version.
173 This program is distributed in the hope that it will be useful, but
175 WITHOUT ANY WARRANTY; without even the implied warranty of
176 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
177 General Public License for more details.
178 You should have received a copy of the GNU General Public License along
180 with this program; if not, write to the Free Software Foundation, Inc.,
181 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
182
184 To get a list of bugs against libguestfs, use this link:
185 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
186 To report a new bug against libguestfs, use this link:
188 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
189 When reporting a bug, please supply:
191 • The version of libguestfs.
193 • Where you got libguestfs (eg. which Linux distro, compiled from
195 source, etc)
196 • Describe the bug accurately and give a way to reproduce it.
198 • Run libguestfs-test-tool(1) and paste the complete, unedited output
200 into the bug report.
201libguestfs-1.51.9 2023-12-09 libguestfs-test-tool(1)