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 You can try comparing this to the results from L<df(1)> inside the
106 guest, but there are some provisos:
112 The guest must be idle.
116 The guest disks must be synched using L<sync(1)>.
120 Any action such as booting the guest will write log files causing the
125 We don't guarantee that the numbers will be identical even under these
126 circumstances. They should be similar. It would indicate a bug if
127 you saw greatly differing numbers.
129 =head2 Try importing virt-df CSV output into a spreadsheet or database.
133 virt-df --csv > /tmp/report.csv
135 Now try to load this into your favorite spreadsheet or database. Are
136 the results reproduced faithfully in the spreadsheet/database?
138 http://www.postgresql.org/docs/8.1/static/sql-copy.html
139 http://dev.mysql.com/doc/refman/5.1/en/load-data.html
141 =head2 B<*> Edit a file in a B<shut off> guest.
143 L<virt-edit(1)> can edit files in guests. Try this command on
144 a RHEL or Fedora guest:
146 virt-edit LinuxGuest /etc/sysconfig/network
148 On other Linux guests try editing other files such as:
150 virt-edit LinuxGuest /etc/motd
152 Are the changes seen inside the guest when it is booted?
154 =head2 Display the filesystems / partitions / LVs in a guest.
156 L<virt-filesystems(1)> can be used to display filesystems in
157 a guest. Try this command on any disk image or guest:
159 virt-filesystems -a /path/to/disk.img --all --long -h
163 virt-filesystems -d Guest --all --long -h
165 Do the results match what is seen in the guest?
167 =head2 Run virt-inspector on all your guests.
169 Use L<virt-inspector(1)> to get a report on all of your guests or disk
172 virt-inspector -a /path/to/disk.img | less
176 virt-inspector -d Guest | less
178 Do the results match what is actually in the guest?
180 =head2 Try the auditing features of virt-ls on all your guests.
182 List all setuid or setgid programs in a Linux virtual machine:
184 virt-ls -lR -d Guest / | grep '^- [42]'
186 List all public-writable directories in a Linux virtual machine:
188 virt-ls -lR -d Guest / | grep '^d ...7'
190 List all Unix domain sockets in a Linux virtual machine:
192 virt-ls -lR -d Guest / | grep '^s'
194 List all regular files with filenames ending in '.png':
196 virt-ls -lR -d Guest / | grep -i '^-.*\.png$'
198 Display files larger than 10MB in home directories:
200 virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'
202 Find everything modified in the last 7 days:
204 virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'
206 Find regular files modified in the last 24 hours:
208 virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'
210 Do the results match what is in the guest?
212 =head2 Create a disk image from a tarball.
214 Use L<virt-make-fs(1)> to create a disk image from any tarball
215 that you happen to have:
217 virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img
219 Add 'output.img' as a raw disk to an existing guest. Check the guest
220 can see the files. This test is particularly useful if you try it
221 with a Windows guest.
223 Try other partitioning schemes, eg. I<--partition=gpt>.
225 Try other filesystem formats, eg. I<--type=ntfs>, I<--type=ext2>.
227 =head2 B<*> Run virt-rescue on a B<shut off> disk image or guest.
229 Use L<virt-rescue(1)> to examine, rescue or repair a B<shut off> guest
232 virt-rescue -a /path/to/disk.img
238 Can you use ordinary shell commands to examine the guest?
240 =head2 B<*> Resize your guests.
242 Use L<virt-resize(1)> to give a guest some more disk space. For
243 example, if you have a disk image that is smaller than 30G, increase
246 truncate -s 30G newdisk.img
247 virt-filesystems -a /path/to/olddisk.img --all --long -h
248 virt-resize /path/to/olddisk.img newdisk.img --expand /dev/sda1
249 qemu-kvm -m 1024 -hda newdisk.img
251 Does the guest still boot? Try expanding other partitions.
253 =head2 B<*> Sparsify a guest disk.
255 Using L<virt-sparsify(1)>, make a disk image more sparse:
257 virt-sparsify /path/to/olddisk.img newdisk.img
259 Is C<newdisk.img> still bootable after sparsifying? Is the resulting
260 disk image smaller (use C<du> to check)?
262 =head2 B<*> "sysprep" a B<shut off> Linux guest.
264 Note that this really will mess up an existing guest, so it's better
265 to clone the guest before trying this.
267 virt-sysprep --hostname newhost.example.com -a /path/to/disk.img
269 Was the sysprep successful? After booting, what changes were made and
270 were they successful?
272 =head2 Dump the Windows Registry from your Windows guests.
274 Use L<virt-win-reg(1)> to dump out the Windows Registry from
275 any Windows guests that you have.
277 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
280 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
283 Does the output match running C<regedit> inside the guest?
285 A recent feature is the ability to dump user registries, so try this,
286 replacing I<username> with the name of a local user in the guest:
288 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKEY_USERS\username' |
295 L<guestfs-examples(3)>,
296 L<http://libguestfs.org/>.
300 Richard W.M. Jones (C<rjones at redhat dot com>)
304 Copyright (C) 2011 Red Hat Inc. L<http://libguestfs.org/>
306 This library is free software; you can redistribute it and/or
307 modify it under the terms of the GNU Lesser General Public
308 License as published by the Free Software Foundation; either
309 version 2 of the License, or (at your option) any later version.
311 This library is distributed in the hope that it will be useful,
312 but WITHOUT ANY WARRANTY; without even the implied warranty of
313 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
314 Lesser General Public License for more details.
316 You should have received a copy of the GNU Lesser General Public
317 License along with this library; if not, write to the Free Software
318 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA