1guestfs-testing(1) Virtualization Support guestfs-testing(1)
2
6 guestfs-testing - manual testing of libguestfs, you can help!
7
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!
12 These tests require libguestfs ≥ 1.14.
14 Tests marked with a * (asterisk) can destroy data if you're not
16 careful. The others are safe and won't modify anything.
17 You can report bugs you find through this link:
19 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
21 or post on the mailing list (registration is not required, but if
23 you're not registered then you'll have to wait for a moderator to
24 manually approve your message):
25 https://www.redhat.com/mailman/listinfo/libguestfs
27
29 Run libguestfs-test-tool
30 Run:
31 libguestfs-test-tool
33 This command does a very simple, non-destructive test that basic
35 libguestfs is functioning. You don't need to run it as root.
36 If it doesn't print "===== TEST FINISHED OK =====", report it as a bug.
38 It is very important that you include the complete, unedited output of
39 "libguestfs-test-tool" in your bug report. See the "BUGS" section at
40 the end of this page.
41 Check KVM acceleration is being used.
43 If your host has hardware virt acceleration, then with a hot cache
44 libguestfs should be able to start up in a few seconds. Run the
45 following command a few times:
46 time guestfish -a /dev/null run
48 After a few runs, the time should settle down to a few seconds (under 5
50 seconds on fast 64 bit hardware).
51 How to check for hardware virt:
53 http://virt-tools.org/learning/check-hardware-virt/
55 If the command above does not work at all, use libguestfs-test-tool(1).
57 Run virt-alignment-scan on all your guests.
59 Run virt-alignment-scan(1) on guests or disk images:
60 virt-alignment-scan -a /path/to/disk.img
62 or:
64 virt-alignment-scan -d Guest
66 Does the alignment report match how the guest partitions are aligned?
68 Run virt-cat on some files in guests.
70 virt-cat(1) can display files from guests. For a Linux guest, try:
71 virt-cat LinuxGuest /etc/passwd
73 A recent feature is support for Windows paths, for example:
75 virt-cat WindowsGuest 'c:\windows\win.ini'
77 An even better test is if you have a Windows guest with multiple
79 drives. Do "D:", "E:" etc paths work correctly?
80 * Copy some files into a shut off guest.
82 virt-copy-in(1) can recursively copy files and directories into a guest
83 or disk image.
84 virt-copy-in -d Guest /etc /tmp
86 This should copy local directory "/etc" to "/tmp/etc" in the guest
88 (recursively). If you boot the guest, can you see all of the copied
89 files and directories?
90 Shut the guest down and try copying multiple files and directories:
92 virt-copy-in -d Guest /home /etc/issue /tmp
94 Copy some files out of a guest.
96 virt-copy-out(1) can recursively copy files and directories out of a
97 guest or disk image.
98 virt-copy-out -d Guest /home .
100 Note the final space and period in the command is not a typo.
102 This should copy "/home" from the guest into the current directory.
104 Run virt-df.
106 virt-df(1) lists disk space. Run:
107 virt-df
109 You can try comparing this to the results from df(1) inside the guest,
111 but there are some provisos:
112 · The guest must be idle.
114 · The guest disks must be synched using sync(1).
116 · Any action such as booting the guest will write log files causing
118 the numbers to change.
119 We don't guarantee that the numbers will be identical even under these
121 circumstances. They should be similar. It would indicate a bug if you
122 saw greatly differing numbers.
123 Try importing virt-df CSV output into a spreadsheet or database.
125 Run:
126 virt-df --csv > /tmp/report.csv
128 Now try to load this into your favorite spreadsheet or database. Are
130 the results reproduced faithfully in the spreadsheet/database?
131 http://www.postgresql.org/docs/8.1/static/sql-copy.html
133 http://dev.mysql.com/doc/refman/5.1/en/load-data.html
134 * Edit a file in a shut off guest.
136 virt-edit(1) can edit files in guests. Try this command on a RHEL or
137 Fedora guest:
138 virt-edit LinuxGuest /etc/sysconfig/network
140 On other Linux guests try editing other files such as:
142 virt-edit LinuxGuest /etc/motd
144 Are the changes seen inside the guest when it is booted?
146 Display the filesystems / partitions / LVs in a guest.
148 virt-filesystems(1) can be used to display filesystems in a guest. Try
149 this command on any disk image or guest:
150 virt-filesystems -a /path/to/disk.img --all --long -h
152 or:
154 virt-filesystems -d Guest --all --long -h
156 Do the results match what is seen in the guest?
158 Run virt-inspector on all your guests.
160 Use virt-inspector(1) to get a report on all of your guests or disk
161 images:
162 virt-inspector -a /path/to/disk.img | less
164 or:
166 virt-inspector -d Guest | less
168 Do the results match what is actually in the guest?
170 Try the auditing features of virt-ls on all your guests.
172 List all setuid or setgid programs in a Linux virtual machine:
173 virt-ls -lR -d Guest / | grep '^- [42]'
175 List all public-writable directories in a Linux virtual machine:
177 virt-ls -lR -d Guest / | grep '^d ...7'
179 List all Unix domain sockets in a Linux virtual machine:
181 virt-ls -lR -d Guest / | grep '^s'
183 List all regular files with filenames ending in '.png':
185 virt-ls -lR -d Guest / | grep -i '^-.*\.png$'
187 Display files larger than 10MB in home directories:
189 virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'
191 Find everything modified in the last 7 days:
193 virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'
195 Find regular files modified in the last 24 hours:
197 virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'
199 Do the results match what is in the guest?
201 Create a disk image from a tarball.
203 Use virt-make-fs(1) to create a disk image from any tarball that you
204 happen to have:
205 virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img
207 Add 'output.img' as a raw disk to an existing guest. Check the guest
209 can see the files. This test is particularly useful if you try it with
210 a Windows guest.
211 Try other partitioning schemes, eg. --partition=gpt.
213 Try other filesystem formats, eg. --type=ntfs, --type=ext2.
215 * Run virt-rescue on a shut off disk image or guest.
217 Use virt-rescue(1) to examine, rescue or repair a shut off guest or
218 disk image:
219 virt-rescue -a /path/to/disk.img
221 or:
223 virt-rescue -d Guest
225 Can you use ordinary shell commands to examine the guest?
227 * Resize your guests.
229 Use virt-resize(1) to give a guest some more disk space. For example,
230 if you have a disk image that is smaller than 30G, increase it to 30G
231 by doing:
232 truncate -s 30G newdisk.img
234 virt-filesystems -a /path/to/olddisk.img --all --long -h
235 virt-resize /path/to/olddisk.img newdisk.img --expand /dev/sda1
236 qemu-kvm -m 1024 -hda newdisk.img
237 Does the guest still boot? Try expanding other partitions.
239 * Sparsify a guest disk.
241 Using virt-sparsify(1), make a disk image more sparse:
242 virt-sparsify /path/to/olddisk.img newdisk.img
244 Is "newdisk.img" still bootable after sparsifying? Is the resulting
246 disk image smaller (use "du" to check)?
247 * "sysprep" a shut off Linux guest.
249 Note that this really will mess up an existing guest, so it's better to
250 clone the guest before trying this.
251 virt-sysprep --hostname newhost.example.com -a /path/to/disk.img
253 Was the sysprep successful? After booting, what changes were made and
255 were they successful?
256 Dump the Windows Registry from your Windows guests.
258 Use virt-win-reg(1) to dump out the Windows Registry from any Windows
259 guests that you have.
260 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
262 less
263 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
265 less
266 Does the output match running "regedit" inside the guest?
268 A recent feature is the ability to dump user registries, so try this,
270 replacing username with the name of a local user in the guest:
271 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKEY_USERS\username' |
273 less
274
276 guestfs(3), guestfish(1), guestfs-examples(3), http://libguestfs.org/.
277
279 Richard W.M. Jones ("rjones at redhat dot com")
280
282 Copyright (C) 2011-2012 Red Hat Inc.
283
285 This library is free software; you can redistribute it and/or modify it
286 under the terms of the GNU Lesser General Public License as published
287 by the Free Software Foundation; either version 2 of the License, or
288 (at your option) any later version.
289 This library is distributed in the hope that it will be useful, but
291 WITHOUT ANY WARRANTY; without even the implied warranty of
292 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
293 Lesser General Public License for more details.
294 You should have received a copy of the GNU Lesser General Public
296 License along with this library; if not, write to the Free Software
297 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
298 02110-1301 USA
299
301 To get a list of bugs against libguestfs, use this link:
302 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
303 To report a new bug against libguestfs, use this link:
305 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
306 When reporting a bug, please supply:
308 · The version of libguestfs.
310 · Where you got libguestfs (eg. which Linux distro, compiled from
312 source, etc)
313 · Describe the bug accurately and give a way to reproduce it.
315 · Run libguestfs-test-tool(1) and paste the complete, unedited output
317 into the bug report.
318libguestfs-1.20.11 2013-08-27 guestfs-testing(1)