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 Tests marked with a * (asterisk) can destroy data if you're not
14 careful. The others are safe and won't modify anything.
15 These tests require libguestfs ≥ 1.22.
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 3
50 seconds on fast 64 bit hardware).
51 If the command above does not work at all, use libguestfs-test-tool(1).
53 Check which version of libguestfs, qemu, libvirt, etc is being used.
55 Look at the output of "libguestfs-test-tool" and check:
56 · Which version of libguestfs is being used? Near the beginning of
58 the output you'll see a line like:
59 library version: 1.22.0fedora=19,release=1.fc19,libvirt
61 · Is libvirt being used? You can tell the difference by looking for
63 the backend:
64 guestfs_get_backend: direct
66 or:
68 guestfs_get_backend: libvirt
70 · Which version of qemu is being used? It may be printed out:
72 libguestfs: qemu version 1.5
74 · Which kernel is being used? supermin(1) will try to pick the
76 latest kernel installed on your machine. You can see the version
77 in the appliance output, eg:
78 [ 0.000000] Linux version 3.9.2-200.fc18.x86_64 [...]
80 Try to open a local guest image with guestfish.
82 You can use any guest disk image for this test. Make sure you use the
83 "--ro" flag so that guestfish(1) will open the disk image read-only.
84 guestfish --ro -a /path/to/disk.img -i
86 If the command is successful, it should print out the guest operating
88 system name and put you at the guestfish "><fs>" prompt. You can use
89 guestfish commands like "ll /" to look inside the disk image. To exit,
90 type "exit".
91 If you get an error, try enabling debugging (add "-v" to the command
93 line). Also make sure that libguestfs-test-tool(1) succeeds.
94 Run virt-alignment-scan on all your guests.
96 Run virt-alignment-scan(1) on guests or disk images:
97 virt-alignment-scan -a /path/to/disk.img
99 or:
101 virt-alignment-scan -d Guest
103 Does the alignment report match how the guest partitions are aligned?
105 Run virt-cat on some files in guests.
107 virt-cat(1) can display files from guests. For a Linux guest, try:
108 virt-cat LinuxGuest /etc/passwd
110 A recent feature is support for Windows paths, for example:
112 virt-cat WindowsGuest 'c:\windows\win.ini'
114 An even better test is if you have a Windows guest with multiple
116 drives. Do "D:", "E:" etc paths work correctly?
117 * Copy some files into a shut off guest.
119 virt-copy-in(1) can recursively copy files and directories into a guest
120 or disk image.
121 virt-copy-in -d Guest /etc /tmp
123 This should copy local directory /etc to /tmp/etc in the guest
125 (recursively). If you boot the guest, can you see all of the copied
126 files and directories?
127 Shut the guest down and try copying multiple files and directories:
129 virt-copy-in -d Guest /home /etc/issue /tmp
131 Copy some files out of a guest.
133 virt-copy-out(1) can recursively copy files and directories out of a
134 guest or disk image.
135 virt-copy-out -d Guest /home .
137 Note the final space and period in the command is not a typo.
139 This should copy /home from the guest into the current directory.
141 Run virt-df.
143 virt-df(1) lists disk space. Run:
144 virt-df
146 You can try comparing this to the results from df(1) inside the guest,
148 but there are some provisos:
149 · The guest must be idle.
151 · The guest disks must be synched using sync(1).
153 · Any action such as booting the guest will write log files causing
155 the numbers to change.
156 We don’t guarantee that the numbers will be identical even under these
158 circumstances. They should be similar. It would indicate a bug if you
159 saw greatly differing numbers.
160 Try importing virt-df CSV output into a spreadsheet or database.
162 Run:
163 virt-df --csv > /tmp/report.csv
165 Now try to load this into your favorite spreadsheet or database. Are
167 the results reproduced faithfully in the spreadsheet/database?
168 http://www.postgresql.org/docs/8.1/static/sql-copy.html
170 http://dev.mysql.com/doc/refman/5.1/en/load-data.html
171 * Edit a file in a shut off guest.
173 virt-edit(1) can edit files in guests. Try this command on a RHEL or
174 Fedora guest:
175 virt-edit LinuxGuest /etc/sysconfig/network
177 On other Linux guests try editing other files such as:
179 virt-edit LinuxGuest /etc/motd
181 Are the changes seen inside the guest when it is booted?
183 Display the filesystems / partitions / LVs in a guest.
185 virt-filesystems(1) can be used to display filesystems in a guest. Try
186 this command on any disk image or guest:
187 virt-filesystems -a /path/to/disk.img --all --long -h
189 or:
191 virt-filesystems -d Guest --all --long -h
193 Do the results match what is seen in the guest?
195 Run virt-inspector on all your guests.
197 Use virt-inspector(1) to get a report on all of your guests or disk
198 images:
199 virt-inspector -a /path/to/disk.img | less
201 or:
203 virt-inspector -d Guest | less
205 Do the results match what is actually in the guest?
207 If you have an unusual guest (a rare Linux distro, a very new version
209 of Windows), does virt-inspector recognize it? If not, then it's
210 probably a bug.
211 Try the auditing features of virt-ls on all your guests.
213 List all setuid or setgid programs in a Linux virtual machine:
214 virt-ls -lR -d Guest / | grep '^- [42]'
216 List all public-writable directories in a Linux virtual machine:
218 virt-ls -lR -d Guest / | grep '^d ...7'
220 List all Unix domain sockets in a Linux virtual machine:
222 virt-ls -lR -d Guest / | grep '^s'
224 List all regular files with filenames ending in ‘.png’:
226 virt-ls -lR -d Guest / | grep -i '^-.*\.png$'
228 Display files larger than 10MB in home directories:
230 virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'
232 Find everything modified in the last 7 days:
234 virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'
236 Find regular files modified in the last 24 hours:
238 virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'
240 Do the results match what is in the guest?
242 Create a disk image from a tarball.
244 Use virt-make-fs(1) to create a disk image from any tarball that you
245 happen to have:
246 virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img
248 Add ‘output.img’ as a raw disk to an existing guest. Check the guest
250 can see the files. This test is particularly useful if you try it with
251 a Windows guest.
252 Try other partitioning schemes, eg. --partition=gpt.
254 Try other filesystem formats, eg. --type=ntfs, --type=ext2.
256 * Run virt-rescue on a shut off disk image or guest.
258 Use virt-rescue(1) to examine, rescue or repair a shut off guest or
259 disk image:
260 virt-rescue -a /path/to/disk.img
262 or:
264 virt-rescue -d Guest
266 Can you use ordinary shell commands to examine the guest?
268 * Resize your guests.
270 Use virt-resize(1) to give a guest some more disk space. For example,
271 if you have a disk image that is smaller than 30G, increase it to 30G
272 by doing:
273 truncate -s 30G newdisk.img
275 virt-filesystems -a /path/to/olddisk.img --all --long -h
276 virt-resize /path/to/olddisk.img newdisk.img --expand /dev/sda1
277 qemu-kvm -m 1024 -hda newdisk.img
278 Does the guest still boot? Try expanding other partitions.
280 * Sparsify a guest disk.
282 Using virt-sparsify(1), make a disk image more sparse:
283 virt-sparsify /path/to/olddisk.img newdisk.img
285 Is newdisk.img still bootable after sparsifying? Is the resulting disk
287 image smaller (use "du" to check)?
288 Build and boot a guest
290 Using virt-builder(1), choose a guest from the list:
291 virt-builder -l
293 build it:
295 virt-builder -o disk.img [os-version from list above]
297 and boot it:
299 qemu-kvm -cpu host -m 2048 -drive file=disk.img,format=raw
301 Does it boot?
303 * "Sysprep" a shut off Linux guest.
305 Note that this really will mess up an existing guest, so it's better to
306 clone the guest before trying this.
307 virt-sysprep --hostname newhost.example.com -a /path/to/disk.img
309 Was the sysprep successful? After booting, what changes were made and
311 were they successful?
312 Dump the Windows Registry from your Windows guests.
314 Use virt-win-reg(1) to dump out the Windows Registry from any Windows
315 guests that you have.
316 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
318 less
319 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
321 less
322 Does the output match running "regedit" inside the guest?
324 A recent feature is the ability to dump user registries, so try this,
326 replacing username with the name of a local user in the guest:
327 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKEY_USERS\username' |
329 less
330
332 guestfs(3), guestfish(1), guestfs-examples(3), http://libguestfs.org/.
333
335 Richard W.M. Jones ("rjones at redhat dot com")
336
338 Copyright (C) 2011-2012 Red Hat Inc.
339
341 This library is free software; you can redistribute it and/or modify it
342 under the terms of the GNU Lesser General Public License as published
343 by the Free Software Foundation; either version 2 of the License, or
344 (at your option) any later version.
345 This library is distributed in the hope that it will be useful, but
347 WITHOUT ANY WARRANTY; without even the implied warranty of
348 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
349 Lesser General Public License for more details.
350 You should have received a copy of the GNU Lesser General Public
352 License along with this library; if not, write to the Free Software
353 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
354 02110-1301 USA
355
357 To get a list of bugs against libguestfs, use this link:
358 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
359 To report a new bug against libguestfs, use this link:
361 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
362 When reporting a bug, please supply:
364 · The version of libguestfs.
366 · Where you got libguestfs (eg. which Linux distro, compiled from
368 source, etc)
369 · Describe the bug accurately and give a way to reproduce it.
371 · Run libguestfs-test-tool(1) and paste the complete, unedited output
373 into the bug report.
374libguestfs-1.38.2 2018-05-15 guestfs-testing(1)