1libguestfs-test-tool(1)     Virtualization Support     libguestfs-test-tool(1)
2
3
4

NAME

6       libguestfs-test-tool - Diagnostics for libguestfs
7

SYNOPSIS

9        libguestfs-test-tool [--options]
10

DESCRIPTION

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
18       If you suspect a problem in libguestfs, then just run:
19
20        libguestfs-test-tool
21
22       It will print lots of diagnostic messages.
23
24       If it runs to completion successfully, you will see this near the end:
25
26        ===== TEST FINISHED OK =====
27
28       and the test tool will exit with code 0.
29
30       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

OPTIONS

36       --help
37           Display short usage information and exit.
38
39       --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
43       --qemudir qemu_source_dir
44           If you have compiled qemu from source, point this option at the
45           source directory to try it.
46
47       -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
52       -V
53       --version
54           Display the libguestfs version number and exit.
55

TRYING OUT A DIFFERENT VERSION OF QEMU

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
61       If you have downloaded a qemu binary from somewhere, use the --qemu
62       option to point to the binary.
63
64       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

TRYING OUT A DIFFERENT KERNEL

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
73       Refer to "ENVIRONMENT VARIABLES" in supermin(1) for further
74       information.
75

TRYING OUT A DIFFERENT VERSION OF LIBVIRT

77       To find out which backend is the default in your libguestfs package,
78       do:
79
80        unset LIBGUESTFS_BACKEND
81        guestfish get-backend
82
83       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
87        killall libvirtd lt-libvirtd
88        ~/path/to/libvirt/run libguestfs-test-tool
89
90       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

TRYING OUT WITH / WITHOUT LIBVIRT

97       To find out which backend is the default in your libguestfs package,
98       do:
99
100        unset LIBGUESTFS_BACKEND
101        guestfish get-backend
102
103       If you are using the libvirt backend, you can try without (ie.
104       libguestfs directly launching qemu) by doing:
105
106        export LIBGUESTFS_BACKEND=direct
107
108       Or if you are using the default (direct) backend, then you can try
109       libvirt:
110
111        export LIBGUESTFS_BACKEND=libvirt
112
113       or with libvirt and a specific libvirt URI:
114
115        export LIBGUESTFS_BACKEND=libvirt:qemu:///session
116

TRYING OUT DIFFERENT SELINUX SETTINGS

118       To find out which backend is the default in your libguestfs package,
119       do:
120
121        unset LIBGUESTFS_BACKEND
122        guestfish get-backend
123
124       To find out if SELinux is being used, do:
125
126        getenforce
127
128       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
132        setenforce Permissive
133
134       If this makes a difference, look in the audit logs for recent failures
135       ("AVCs"):
136
137        ausearch -m avc -ts recent
138
139       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
143       To reenable SELinux and sVirt, do:
144
145        setenforce Enforcing
146

SELF-DIAGNOSIS

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

EXIT STATUS

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

ENVIRONMENT VARIABLES

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

SEE ALSO

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

AUTHORS

163       Richard W.M. Jones ("rjones at redhat dot com")
164
166       Copyright (C) 2009-2023 Red Hat Inc.
167

LICENSE

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
174       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
179       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

BUGS

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
187       To report a new bug against libguestfs, use this link:
188       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
189
190       When reporting a bug, please supply:
191
192       •   The version of libguestfs.
193
194       •   Where you got libguestfs (eg. which Linux distro, compiled from
195           source, etc)
196
197       •   Describe the bug accurately and give a way to reproduce it.
198
199       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
200           into the bug report.
201
202
203
204libguestfs-1.51.9                 2023-12-09           libguestfs-test-tool(1)
Impressum