5 guestfs-testing - manual testing of libguestfs, you can help!
9 This page has manual tests you can try on libguestfs. Everyone has a
10 slightly different combination of platform, hardware and guests, so
11 this testing is very valuable. Thanks for helping out!
13 These tests require libguestfs E<ge> 1.14.
15 Tests marked with a B<*> (asterisk) can B<destroy data> if you're not
16 careful. The others are safe and won't modify anything.
18 You can report bugs you find through this link:
20 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
22 or post on the mailing list (registration is B<not> required, but if
23 you're not registered then you'll have to wait for a moderator to
24 manually approve your message):
26 https://www.redhat.com/mailman/listinfo/libguestfs
30 =head2 Check KVM acceleration is being used.
32 If your host has hardware virt acceleration, then with a hot cache
33 libguestfs should be able to start up in a few seconds. Run the
34 following command a few times:
36 time guestfish -a /dev/null run
38 After a few runs, the time should settle down to a few seconds (under
39 5 seconds on fast 64 bit hardware).
41 How to check for hardware virt:
43 http://virt-tools.org/learning/check-hardware-virt/
45 If the command above does not work at all, use
46 L<libguestfs-test-tool(1)>.
48 =head2 Run virt-alignment-scan on all your guests.
50 Run L<virt-alignment-scan(1)> on guests or disk images:
52 virt-alignment-scan -a /path/to/disk.img
56 virt-alignment-scan -d Guest
58 Does the alignment report match how the guest partitions are aligned?
60 =head2 Run virt-cat on some files in guests.
62 L<virt-cat(1)> can display files from guests. For a Linux guest, try:
64 virt-cat LinuxGuest /etc/passwd
66 A recent feature is support for Windows paths, for example:
68 virt-cat WindowsGuest 'c:\windows\win.ini'
70 An even better test is if you have a Windows guest with multiple
71 drives. Do C<D:>, C<E:> etc paths work correctly?
73 =head2 B<*> Copy some files into a B<shut off> guest.
75 L<virt-copy-in(1)> can recursively copy files and directories
76 into a guest or disk image.
78 virt-copy-in -d Guest /etc /tmp
80 This should copy local directory C</etc> to C</tmp/etc> in the guest
81 (recursively). If you boot the guest, can you see all of the copied
82 files and directories?
84 Shut the guest down and try copying multiple files and directories:
86 virt-copy-in -d Guest /home /etc/issue /tmp
88 =head2 Copy some files out of a guest.
90 L<virt-copy-out(1)> can recursively copy files and directories
91 out of a guest or disk image.
93 virt-copy-out -d Guest /home .
95 Note the final space and period in the command is not a typo.
97 This should copy C</home> from the guest into the current directory.
101 L<virt-df(1)> lists disk space. Run:
105 Do the results match what's reported inside the guests?
107 =head2 Try importing virt-df CSV output into a spreadsheet or database.
111 virt-df --csv > /tmp/report.csv
113 Now try to load this into your favorite spreadsheet or database. Are
114 the results reproduced faithfully in the spreadsheet/database?
116 http://www.postgresql.org/docs/8.1/static/sql-copy.html
117 http://dev.mysql.com/doc/refman/5.1/en/load-data.html
119 =head2 B<*> Edit a file in a B<shut off> guest.
121 L<virt-edit(1)> can edit files in guests. Try this command on
122 a RHEL or Fedora guest:
124 virt-edit LinuxGuest /etc/sysconfig/network
126 On other Linux guests try editing other files such as:
128 virt-edit LinuxGuest /etc/motd
130 Are the changes seen inside the guest when it is booted?
132 =head2 Display the filesystems / partitions / LVs in a guest.
134 L<virt-filesystems(1)> can be used to display filesystems in
135 a guest. Try this command on any disk image or guest:
137 virt-filesystems -a /path/to/disk.img --all --long -h
141 virt-filesystems -d Guest --all --long -h
143 Do the results match what is seen in the guest?
145 =head2 Run virt-inspector on all your guests.
147 Use L<virt-inspector(1)> to get a report on all of your guests or disk
150 virt-inspector -a /path/to/disk.img | less
154 virt-inspector -d Guest | less
156 Do the results match what is actually in the guest?
158 =head2 Try the auditing features of virt-ls on all your guests.
160 List all setuid or setgid programs in a Linux virtual machine:
162 virt-ls -lR -d Guest / | grep '^- [42]'
164 List all public-writable directories in a Linux virtual machine:
166 virt-ls -lR -d Guest / | grep '^d ...7'
168 List all Unix domain sockets in a Linux virtual machine:
170 virt-ls -lR -d Guest / | grep '^s'
172 List all regular files with filenames ending in '.png':
174 virt-ls -lR -d Guest / | grep -i '^-.*\.png$'
176 Display files larger than 10MB in home directories:
178 virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'
180 Find everything modified in the last 7 days:
182 virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'
184 Find regular files modified in the last 24 hours:
186 virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'
188 Do the results match what is in the guest?
190 =head2 Create a disk image from a tarball.
192 Use L<virt-make-fs(1)> to create a disk image from any tarball
193 that you happen to have:
195 virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img
197 Add 'output.img' as a raw disk to an existing guest. Check the guest
198 can see the files. This test is particularly useful if you try it
199 with a Windows guest.
201 Try other partitioning schemes, eg. I<--partition=gpt>.
203 Try other filesystem formats, eg. I<--type=ntfs>, I<--type=ext2>.
205 =head2 B<*> Run virt-rescue on a B<shut off> disk image or guest.
207 Use L<virt-rescue(1)> to examine, rescue or repair a B<shut off> guest
210 virt-rescue -a /path/to/disk.img
216 Can you use ordinary shell commands to examine the guest?
218 =head2 B<*> Resize your guests.
220 Use L<virt-resize(1)> to give a guest some more disk space. For
221 example, if you have a disk image that is smaller than 30G, increase
224 truncate -s 30G newdisk.img
225 virt-filesystems -a /path/to/olddisk.img --all --long -h
226 virt-resize /path/to/olddisk.img newdisk.img --expand /dev/sda1
227 qemu-kvm -m 1024 -hda newdisk.img
229 Does the guest still boot? Try expanding other partitions.
231 =head2 B<*> Sparsify a guest disk.
233 Using L<virt-sparsify(1)>, make a disk image more sparse:
235 virt-sparsify /path/to/olddisk.img newdisk.img
237 Is C<newdisk.img> still bootable after sparsifying? Is the resulting
238 disk image smaller (use C<du> to check)?
240 =head2 B<*> "sysprep" a B<shut off> Linux guest.
242 Note that this really will mess up an existing guest, so it's better
243 to clone the guest before trying this.
245 virt-sysprep --hostname newhost.example.com -a /path/to/disk.img
247 Was the sysprep successful? After booting, what changes were made and
248 were they successful?
250 =head2 Dump the Windows Registry from your Windows guests.
252 Use L<virt-win-reg(1)> to dump out the Windows Registry from
253 any Windows guests that you have.
255 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
258 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
261 Does the output match running C<regedit> inside the guest?
263 A recent feature is the ability to dump user registries, so try this,
264 replacing I<username> with the name of a local user in the guest:
266 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKEY_USERS\username' |
273 L<guestfs-examples(3)>,
274 L<http://libguestfs.org/>.
278 Richard W.M. Jones (C<rjones at redhat dot com>)
282 Copyright (C) 2011 Red Hat Inc. L<http://libguestfs.org/>
284 This library is free software; you can redistribute it and/or
285 modify it under the terms of the GNU Lesser General Public
286 License as published by the Free Software Foundation; either
287 version 2 of the License, or (at your option) any later version.
289 This library is distributed in the hope that it will be useful,
290 but WITHOUT ANY WARRANTY; without even the implied warranty of
291 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
292 Lesser General Public License for more details.
294 You should have received a copy of the GNU Lesser General Public
295 License along with this library; if not, write to the Free Software
296 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA