.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "guestfs-testing 1"
.TH guestfs-testing 1 "2013-12-07" "libguestfs-1.18.1" "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
guestfs\-testing \- manual testing of libguestfs, you can help!
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This page has manual tests you can try on libguestfs.  Everyone has a
slightly different combination of platform, hardware and guests, so
this testing is very valuable.  Thanks for helping out!
.PP
These tests require libguestfs ≥ 1.14.
.PP
Tests marked with a \fB*\fR (asterisk) can \fBdestroy data\fR if you're not
careful.  The others are safe and won't modify anything.
.PP
You can report bugs you find through this link:
.PP
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
or post on the mailing list (registration is \fBnot\fR required, but if
you're not registered then you'll have to wait for a moderator to
manually approve your message):
.PP
https://www.redhat.com/mailman/listinfo/libguestfs
.SH "TESTS"
.IX Header "TESTS"
.SS "Check \s-1KVM\s0 acceleration is being used."
.IX Subsection "Check KVM acceleration is being used."
If your host has hardware virt acceleration, then with a hot cache
libguestfs should be able to start up in a few seconds.  Run the
following command a few times:
.PP
.Vb 1
\& time guestfish \-a /dev/null run
.Ve
.PP
After a few runs, the time should settle down to a few seconds (under
5 seconds on fast 64 bit hardware).
.PP
How to check for hardware virt:
.PP
http://virt\-tools.org/learning/check\-hardware\-virt/
.PP
If the command above does not work at all, use
\&\fIlibguestfs\-test\-tool\fR\|(1).
.SS "Run virt-alignment-scan on all your guests."
.IX Subsection "Run virt-alignment-scan on all your guests."
Run \fIvirt\-alignment\-scan\fR\|(1) on guests or disk images:
.PP
.Vb 1
\& virt\-alignment\-scan \-a /path/to/disk.img
.Ve
.PP
or:
.PP
.Vb 1
\& virt\-alignment\-scan \-d Guest
.Ve
.PP
Does the alignment report match how the guest partitions are aligned?
.SS "Run virt-cat on some files in guests."
.IX Subsection "Run virt-cat on some files in guests."
\&\fIvirt\-cat\fR\|(1) can display files from guests.  For a Linux guest, try:
.PP
.Vb 1
\& virt\-cat LinuxGuest /etc/passwd
.Ve
.PP
A recent feature is support for Windows paths, for example:
.PP
.Vb 1
\& virt\-cat WindowsGuest \*(Aqc:\ewindows\ewin.ini\*(Aq
.Ve
.PP
An even better test is if you have a Windows guest with multiple
drives.  Do \f(CW\*(C`D:\*(C'\fR, \f(CW\*(C`E:\*(C'\fR etc paths work correctly?
.SS "\fB*\fP Copy some files into a \fBshut off\fP guest."
.IX Subsection "* Copy some files into a shut off guest."
\&\fIvirt\-copy\-in\fR\|(1) can recursively copy files and directories
into a guest or disk image.
.PP
.Vb 1
\& virt\-copy\-in \-d Guest /etc /tmp
.Ve
.PP
This should copy local directory \f(CW\*(C`/etc\*(C'\fR to \f(CW\*(C`/tmp/etc\*(C'\fR in the guest
(recursively).  If you boot the guest, can you see all of the copied
files and directories?
.PP
Shut the guest down and try copying multiple files and directories:
.PP
.Vb 1
\& virt\-copy\-in \-d Guest /home /etc/issue /tmp
.Ve
.SS "Copy some files out of a guest."
.IX Subsection "Copy some files out of a guest."
\&\fIvirt\-copy\-out\fR\|(1) can recursively copy files and directories
out of a guest or disk image.
.PP
.Vb 1
\& virt\-copy\-out \-d Guest /home .
.Ve
.PP
Note the final space and period in the command is not a typo.
.PP
This should copy \f(CW\*(C`/home\*(C'\fR from the guest into the current directory.
.SS "Run virt-df."
.IX Subsection "Run virt-df."
\&\fIvirt\-df\fR\|(1) lists disk space.  Run:
.PP
.Vb 1
\& virt\-df
.Ve
.PP
You can try comparing this to the results from \fIdf\fR\|(1) inside the
guest, but there are some provisos:
.IP "\(bu" 4
The guest must be idle.
.IP "\(bu" 4
The guest disks must be synched using \fIsync\fR\|(1).
.IP "\(bu" 4
Any action such as booting the guest will write log files causing the
numbers to change.
.PP
We don't guarantee that the numbers will be identical even under these
circumstances.  They should be similar.  It would indicate a bug if
you saw greatly differing numbers.
.SS "Try importing virt-df \s-1CSV\s0 output into a spreadsheet or database."
.IX Subsection "Try importing virt-df CSV output into a spreadsheet or database."
Run:
.PP
.Vb 1
\& virt\-df \-\-csv > /tmp/report.csv
.Ve
.PP
Now try to load this into your favorite spreadsheet or database.  Are
the results reproduced faithfully in the spreadsheet/database?
.PP
http://www.postgresql.org/docs/8.1/static/sql\-copy.html
http://dev.mysql.com/doc/refman/5.1/en/load\-data.html
.SS "\fB*\fP Edit a file in a \fBshut off\fP guest."
.IX Subsection "* Edit a file in a shut off guest."
\&\fIvirt\-edit\fR\|(1) can edit files in guests.  Try this command on
a \s-1RHEL\s0 or Fedora guest:
.PP
.Vb 1
\& virt\-edit LinuxGuest /etc/sysconfig/network
.Ve
.PP
On other Linux guests try editing other files such as:
.PP
.Vb 1
\& virt\-edit LinuxGuest /etc/motd
.Ve
.PP
Are the changes seen inside the guest when it is booted?
.SS "Display the filesystems / partitions / LVs in a guest."
.IX Subsection "Display the filesystems / partitions / LVs in a guest."
\&\fIvirt\-filesystems\fR\|(1) can be used to display filesystems in
a guest.  Try this command on any disk image or guest:
.PP
.Vb 1
\& virt\-filesystems \-a /path/to/disk.img \-\-all \-\-long \-h
.Ve
.PP
or:
.PP
.Vb 1
\& virt\-filesystems \-d Guest \-\-all \-\-long \-h
.Ve
.PP
Do the results match what is seen in the guest?
.SS "Run virt-inspector on all your guests."
.IX Subsection "Run virt-inspector on all your guests."
Use \fIvirt\-inspector\fR\|(1) to get a report on all of your guests or disk
images:
.PP
.Vb 1
\& virt\-inspector \-a /path/to/disk.img | less
.Ve
.PP
or:
.PP
.Vb 1
\& virt\-inspector \-d Guest | less
.Ve
.PP
Do the results match what is actually in the guest?
.SS "Try the auditing features of virt-ls on all your guests."
.IX Subsection "Try the auditing features of virt-ls on all your guests."
List all setuid or setgid programs in a Linux virtual machine:
.PP
.Vb 1
\& virt\-ls \-lR \-d Guest / | grep \*(Aq^\- [42]\*(Aq
.Ve
.PP
List all public-writable directories in a Linux virtual machine:
.PP
.Vb 1
\& virt\-ls \-lR \-d Guest / | grep \*(Aq^d ...7\*(Aq
.Ve
.PP
List all Unix domain sockets in a Linux virtual machine:
.PP
.Vb 1
\& virt\-ls \-lR \-d Guest / | grep \*(Aq^s\*(Aq
.Ve
.PP
List all regular files with filenames ending in '.png':
.PP
.Vb 1
\& virt\-ls \-lR \-d Guest / | grep \-i \*(Aq^\-.*\e.png$\*(Aq
.Ve
.PP
Display files larger than 10MB in home directories:
.PP
.Vb 1
\& virt\-ls \-lR \-d Guest /home | awk \*(Aq$3 > 10*1024*1024\*(Aq
.Ve
.PP
Find everything modified in the last 7 days:
.PP
.Vb 1
\& virt\-ls \-lR \-d Guest \-\-time\-days / | awk \*(Aq$6 <= 7\*(Aq
.Ve
.PP
Find regular files modified in the last 24 hours:
.PP
.Vb 1
\& virt\-ls \-lR \-d Guest \-\-time\-days / | grep \*(Aq^\-\*(Aq | awk \*(Aq$6 < 1\*(Aq
.Ve
.PP
Do the results match what is in the guest?
.SS "Create a disk image from a tarball."
.IX Subsection "Create a disk image from a tarball."
Use \fIvirt\-make\-fs\fR\|(1) to create a disk image from any tarball
that you happen to have:
.PP
.Vb 1
\& virt\-make\-fs \-\-partition=mbr \-\-type=vfat /any/tarball.tar.gz output.img
.Ve
.PP
Add 'output.img' as a raw disk to an existing guest.  Check the guest
can see the files.  This test is particularly useful if you try it
with a Windows guest.
.PP
Try other partitioning schemes, eg. \fI\-\-partition=gpt\fR.
.PP
Try other filesystem formats, eg. \fI\-\-type=ntfs\fR, \fI\-\-type=ext2\fR.
.SS "\fB*\fP Run virt-rescue on a \fBshut off\fP disk image or guest."
.IX Subsection "* Run virt-rescue on a shut off disk image or guest."
Use \fIvirt\-rescue\fR\|(1) to examine, rescue or repair a \fBshut off\fR guest
or disk image:
.PP
.Vb 1
\& virt\-rescue \-a /path/to/disk.img
.Ve
.PP
or:
.PP
.Vb 1
\& virt\-rescue \-d Guest
.Ve
.PP
Can you use ordinary shell commands to examine the guest?
.SS "\fB*\fP Resize your guests."
.IX Subsection "* Resize your guests."
Use \fIvirt\-resize\fR\|(1) to give a guest some more disk space.  For
example, if you have a disk image that is smaller than 30G, increase
it to 30G by doing:
.PP
.Vb 4
\& truncate \-s 30G newdisk.img
\& virt\-filesystems \-a /path/to/olddisk.img \-\-all \-\-long \-h
\& virt\-resize /path/to/olddisk.img newdisk.img \-\-expand /dev/sda1
\& qemu\-kvm \-m 1024 \-hda newdisk.img
.Ve
.PP
Does the guest still boot?  Try expanding other partitions.
.SS "\fB*\fP Sparsify a guest disk."
.IX Subsection "* Sparsify a guest disk."
Using \fIvirt\-sparsify\fR\|(1), make a disk image more sparse:
.PP
.Vb 1
\& virt\-sparsify /path/to/olddisk.img newdisk.img
.Ve
.PP
Is \f(CW\*(C`newdisk.img\*(C'\fR still bootable after sparsifying?  Is the resulting
disk image smaller (use \f(CW\*(C`du\*(C'\fR to check)?
.ie n .SS "\fB*\fP ""sysprep"" a \fBshut off\fP Linux guest."
.el .SS "\fB*\fP ``sysprep'' a \fBshut off\fP Linux guest."
.IX Subsection "* sysprep a shut off Linux guest."
Note that this really will mess up an existing guest, so it's better
to clone the guest before trying this.
.PP
.Vb 1
\& virt\-sysprep \-\-hostname newhost.example.com \-a /path/to/disk.img
.Ve
.PP
Was the sysprep successful?  After booting, what changes were made and
were they successful?
.SS "Dump the Windows Registry from your Windows guests."
.IX Subsection "Dump the Windows Registry from your Windows guests."
Use \fIvirt\-win\-reg\fR\|(1) to dump out the Windows Registry from
any Windows guests that you have.
.PP
.Vb 2
\& virt\-win\-reg \-\-unsafe\-printable\-strings WindowsGuest \*(AqHKLM\eSoftware\*(Aq |
\&   less
\&
\& virt\-win\-reg \-\-unsafe\-printable\-strings WindowsGuest \*(AqHKLM\eSystem\*(Aq |
\&   less
.Ve
.PP
Does the output match running \f(CW\*(C`regedit\*(C'\fR inside the guest?
.PP
A recent feature is the ability to dump user registries, so try this,
replacing \fIusername\fR with the name of a local user in the guest:
.PP
.Vb 2
\& virt\-win\-reg \-\-unsafe\-printable\-strings WindowsGuest \*(AqHKEY_USERS\eusername\*(Aq |
\&   less
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIguestfs\fR\|(3),
\&\fIguestfish\fR\|(1),
\&\fIguestfs\-examples\fR\|(3),
<http://libguestfs.org/>.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2011 Red Hat Inc. <http://libguestfs.org/>
.PP
This library is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
.PP
This library is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0
Lesser General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0 02110\-1301 \s-1USA\s0