test-tool/libguestfs-test-tool.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 libguestfs-test-tool - Diagnostics for libguestfs
   6
   7 =head1 SYNOPSIS
   8
   9  libguestfs-test-tool [--options]
  10
  11 =head1 DESCRIPTION
  12
  13 libguestfs-test-tool is a test program shipped with libguestfs to
  14 allow you to check basic libguestfs functionality is working.  This is
  15 needed because libguestfs occasionally breaks for reasons beyond our
  16 control: usually because of changes in the underlying qemu or kernel
  17 packages, or the host environment.
  18
  19 If you suspect a problem in libguestfs, then just run:
  20
  21  libguestfs-test-tool
  22
  23 It will print lots of diagnostic messages.
  24
  25 If it runs to completion successfully, you will see this near the end:
  26
  27  ===== TEST FINISHED OK =====
  28
  29 and the test tool will exit with code 0.
  30
  31 If it fails (and/or exits with non-zero error code), please paste the
  32 I<complete, unedited> output of the test tool into a bug report.  More
  33 information about reporting bugs can be found on the
  34 L<http://libguestfs.org/> website.
  35
  36 =head1 OPTIONS
  37
  38 =over 4
  39
  40 =item B<--help>
  41
  42 Display short usage information and exit.
  43
  44 =item B<--qemu qemu_binary>
  45
  46 If you have downloaded another qemu binary, point this option at the
  47 full path of the binary to try it.
  48
  49 =item B<--qemudir qemu_source_dir>
  50
  51 If you have compiled qemu from source, point this option at the source
  52 directory to try it.
  53
  54 =item B<-t N>
  55
  56 =item B<--timeout N>
  57
  58 Set the launch timeout to C<N> seconds.  The default is 600 seconds
  59 (10 minutes) which does not usually need to be adjusted.
  60
  61 =back
  62
  63 =head1 TRYING OUT A DIFFERENT VERSION OF QEMU
  64
  65 If you have compiled another version of qemu from source and would
  66 like to try that, then you can use the I<--qemudir> option to point to
  67 the qemu source directory.
  68
  69 If you have downloaded a qemu binary from somewhere, use the I<--qemu>
  70 option to point to the binary.
  71
  72 Note when using these options, you can ignore the business of qemu
  73 wrapper scripts (L<guestfs(3)/QEMU WRAPPERS>), since
  74 libguestfs-test-tool writes a wrapper script for you if one is needed.
  75
  76 =head1 TRYING OUT A DIFFERENT KERNEL
  77
  78 If you are using febootstrap E<ge> 3.8 then you can select which
  79 kernel libguestfs tries.  You do this by setting the environment
  80 variables C<FEBOOTSTRAP_KERNEL> and/or C<FEBOOTSTRAP_MODULES>.
  81
  82 Refer to L<febootstrap-supermin-helper(8)/ENVIRONMENT VARIABLES>
  83 for further information.
  84
  85 =head1 SELF-DIAGNOSIS
  86
  87 Refer to L<guestfs(3)/APPLIANCE BOOT PROCESS> to understand the
  88 messages produced by libguestfs-test-tool and/or possible errors.
  89
  90 =head1 EXIT STATUS
  91
  92 libguestfs-test-tool returns I<0> if the tests completed without
  93 error, or I<1> if there was an error.
  94
  95 =head1 ENVIRONMENT VARIABLES
  96
  97 For the full list of environment variables which may affect
  98 libguestfs, please see the L<guestfs(3)> manual page.
  99
 100 =head1 SEE ALSO
 101
 102 L<guestfs(3)>,
 103 L<http://libguestfs.org/>,
 104 L<http://qemu.org/>.
 105
 106 =head1 AUTHORS
 107
 108 Richard W.M. Jones (C<rjones at redhat dot com>)
 109
 110 =head1 COPYRIGHT
 111
 112 Copyright (C) 2009-2011 Red Hat Inc.
 113 L<http://libguestfs.org/>
 114
 115 This program is free software; you can redistribute it and/or modify
 116 it under the terms of the GNU General Public License as published by
 117 the Free Software Foundation; either version 2 of the License, or
 118 (at your option) any later version.
 119
 120 This program is distributed in the hope that it will be useful,
 121 but WITHOUT ANY WARRANTY; without even the implied warranty of
 122 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 123 GNU General Public License for more details.
 124
 125 You should have received a copy of the GNU General Public License
 126 along with this program; if not, write to the Free Software
 127 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.