mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-21 22:53:37 +00:00
195 lines
5.0 KiB
Plaintext
195 lines
5.0 KiB
Plaintext
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
libguestfs-test-tool - Diagnostics for libguestfs
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
libguestfs-test-tool [--options]
|
|
|
|
=head1 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
|
|
I<complete, unedited> output of the test tool into a bug report. More
|
|
information about reporting bugs can be found on the
|
|
L<http://libguestfs.org/> website.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<--help>
|
|
|
|
Display short usage information and exit.
|
|
|
|
=item B<--qemu qemu_binary>
|
|
|
|
If you have downloaded another qemu binary, point this option at the
|
|
full path of the binary to try it.
|
|
|
|
=item B<--qemudir qemu_source_dir>
|
|
|
|
If you have compiled qemu from source, point this option at the source
|
|
directory to try it.
|
|
|
|
=item B<-t N>
|
|
|
|
=item B<--timeout N>
|
|
|
|
Set the launch timeout to C<N> seconds. The default is 600 seconds
|
|
(10 minutes) which does not usually need to be adjusted.
|
|
|
|
=item B<-V>
|
|
|
|
=item B<--version>
|
|
|
|
Display the libguestfs version number and exit.
|
|
|
|
=back
|
|
|
|
=head1 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 I<--qemudir> option to point to
|
|
the qemu source directory.
|
|
|
|
If you have downloaded a qemu binary from somewhere, use the I<--qemu>
|
|
option to point to the binary.
|
|
|
|
Note when using these options, you can ignore the business of qemu
|
|
wrapper scripts (L<guestfs(3)/QEMU WRAPPERS>), since
|
|
libguestfs-test-tool writes a wrapper script for you if one is needed.
|
|
|
|
=head1 TRYING OUT A DIFFERENT KERNEL
|
|
|
|
If you are using supermin / febootstrap E<ge> 3.8 then you can select
|
|
which kernel libguestfs tries. You do this by setting the environment
|
|
variables C<SUPERMIN_KERNEL> and/or C<SUPERMIN_MODULES>
|
|
(C<FEBOOTSTRAP_KERNEL> and C<FEBOOTSTRAP_MODULES> if still using the
|
|
old febootstrap 3.21 program).
|
|
|
|
Refer to L<supermin(1)/ENVIRONMENT VARIABLES> for further information.
|
|
|
|
=head1 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
|
|
(I<not> as root):
|
|
|
|
killall libvirtd lt-libvirtd
|
|
~/path/to/libvirt/run libguestfs-test-tool
|
|
|
|
The first command kills any session C<libvirtd> process(es) that may
|
|
be running on the machine. The second command uses libvirt's C<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.
|
|
|
|
=head1 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
|
|
L<libvirt URI|http://libvirt.org/uri.html>:
|
|
|
|
export LIBGUESTFS_BACKEND=libvirt:qemu:///session
|
|
|
|
=head1 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 L<audit2allow(1)>. For more information, see the "Security
|
|
Enhanced Linux User Guide".
|
|
|
|
To reenable SELinux and sVirt, do:
|
|
|
|
setenforce Enforcing
|
|
|
|
=head1 SELF-DIAGNOSIS
|
|
|
|
Refer to L<guestfs(3)/APPLIANCE BOOT PROCESS> to understand the
|
|
messages produced by libguestfs-test-tool and/or possible errors.
|
|
|
|
=head1 EXIT STATUS
|
|
|
|
libguestfs-test-tool returns I<0> if the tests completed without
|
|
error, or I<1> if there was an error.
|
|
|
|
=head1 ENVIRONMENT VARIABLES
|
|
|
|
For the full list of environment variables which may affect
|
|
libguestfs, please see the L<guestfs(3)> manual page.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<guestfs(3)>,
|
|
L<http://libguestfs.org/>,
|
|
L<http://qemu.org/>.
|
|
|
|
=head1 AUTHORS
|
|
|
|
Richard W.M. Jones (C<rjones at redhat dot com>)
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (C) 2009-2014 Red Hat Inc.
|