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://lists.libguestfs.org
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 Try to open a remote guest image with guestfish.
96 You may also have to disable libvirt by setting this:
97 export LIBGUESTFS_BACKEND=direct
99 If you have a disk image available over HTTP/FTP, try to open it.
101 guestfish --ro -i --format=raw -a http://www.example.com/disk.img
103 For SSH you will need to make sure that ssh-agent is set up so you
105 don't need a password to log in to the remote machine. Then a command
106 similar to this should work:
107 guestfish --ro -i --format=raw \
109 -a ssh://remote.example.com/path/to/disk.img
110 If you get an error, try enabling debugging (add "-v" to the command
112 line). Also make sure that libguestfs-test-tool(1) succeeds.
113 Run virt-alignment-scan on all your guests.
115 Run virt-alignment-scan(1) on guests or disk images:
116 virt-alignment-scan -a /path/to/disk.img
118 or:
120 virt-alignment-scan -d Guest
122 Does the alignment report match how the guest partitions are aligned?
124 Run virt-cat on some files in guests.
126 virt-cat(1) can display files from guests. For a Linux guest, try:
127 virt-cat LinuxGuest /etc/passwd
129 A recent feature is support for Windows paths, for example:
131 virt-cat WindowsGuest 'c:\windows\win.ini'
133 An even better test is if you have a Windows guest with multiple
135 drives. Do "D:", "E:" etc paths work correctly?
136 * Copy some files into a shut off guest.
138 virt-copy-in(1) can recursively copy files and directories into a guest
139 or disk image.
140 virt-copy-in -d Guest /etc /tmp
142 This should copy local directory /etc to /tmp/etc in the guest
144 (recursively). If you boot the guest, can you see all of the copied
145 files and directories?
146 Shut the guest down and try copying multiple files and directories:
148 virt-copy-in -d Guest /home /etc/issue /tmp
150 Copy some files out of a guest.
152 virt-copy-out(1) can recursively copy files and directories out of a
153 guest or disk image.
154 virt-copy-out -d Guest /home .
156 Note the final space and period in the command is not a typo.
158 This should copy /home from the guest into the current directory.
160 Run virt-df.
162 virt-df(1) lists disk space. Run:
163 virt-df
165 You can try comparing this to the results from df(1) inside the guest,
167 but there are some provisos:
168 • The guest must be idle.
170 • The guest disks must be synched using sync(1).
172 • Any action such as booting the guest will write log files causing
174 the numbers to change.
175 We don’t guarantee that the numbers will be identical even under these
177 circumstances. They should be similar. It would indicate a bug if you
178 saw greatly differing numbers.
179 Try importing virt-df CSV output into a spreadsheet or database.
181 Run:
182 virt-df --csv > /tmp/report.csv
184 Now try to load this into your favorite spreadsheet or database. Are
186 the results reproduced faithfully in the spreadsheet/database?
187 http://www.postgresql.org/docs/8.1/static/sql-copy.html
189 http://dev.mysql.com/doc/refman/5.1/en/load-data.html
190 * Edit a file in a shut off guest.
192 virt-edit(1) can edit files in guests. Try this command on a RHEL or
193 Fedora guest:
194 virt-edit LinuxGuest /etc/sysconfig/network
196 On other Linux guests try editing other files such as:
198 virt-edit LinuxGuest /etc/motd
200 Are the changes seen inside the guest when it is booted?
202 Display the filesystems / partitions / LVs in a guest.
204 virt-filesystems(1) can be used to display filesystems in a guest. Try
205 this command on any disk image or guest:
206 virt-filesystems -a /path/to/disk.img --all --long -h
208 or:
210 virt-filesystems -d Guest --all --long -h
212 Do the results match what is seen in the guest?
214 Run virt-inspector on all your guests.
216 Use virt-inspector(1) to get a report on all of your guests or disk
217 images:
218 virt-inspector -a /path/to/disk.img | less
220 or:
222 virt-inspector -d Guest | less
224 Do the results match what is actually in the guest?
226 If you have an unusual guest (a rare Linux distro, a very new version
228 of Windows), does virt-inspector recognize it? If not, then it's
229 probably a bug.
230 Try the auditing features of virt-ls on all your guests.
232 List all setuid or setgid programs in a Linux virtual machine:
233 virt-ls -lR -d Guest / | grep '^- [42]'
235 List all public-writable directories in a Linux virtual machine:
237 virt-ls -lR -d Guest / | grep '^d ...7'
239 List all Unix domain sockets in a Linux virtual machine:
241 virt-ls -lR -d Guest / | grep '^s'
243 List all regular files with filenames ending in ‘.png’:
245 virt-ls -lR -d Guest / | grep -i '^-.*\.png$'
247 Display files larger than 10MB in home directories:
249 virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'
251 Find everything modified in the last 7 days:
253 virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'
255 Find regular files modified in the last 24 hours:
257 virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'
259 Do the results match what is in the guest?
261 Create a disk image from a tarball.
263 Use virt-make-fs(1) to create a disk image from any tarball that you
264 happen to have:
265 virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img
267 Add ‘output.img’ as a raw disk to an existing guest. Check the guest
269 can see the files. This test is particularly useful if you try it with
270 a Windows guest.
271 Try other partitioning schemes, eg. --partition=gpt.
273 Try other filesystem formats, eg. --type=ntfs, --type=ext2.
275 * Run virt-rescue on a shut off disk image or guest.
277 Use virt-rescue(1) to examine, rescue or repair a shut off guest or
278 disk image:
279 virt-rescue -a /path/to/disk.img
281 or:
283 virt-rescue -d Guest
285 Can you use ordinary shell commands to examine the guest?
287 * Resize your guests.
289 Use virt-resize(1) to give a guest some more disk space. For example,
290 if you have a disk image that is smaller than 30G, increase it to 30G
291 by doing:
292 truncate -s 30G newdisk.img
294 virt-filesystems -a /path/to/olddisk.img --all --long -h
295 virt-resize /path/to/olddisk.img newdisk.img --expand /dev/sda1
296 qemu-kvm -m 1024 -hda newdisk.img
297 Does the guest still boot? Try expanding other partitions.
299 * Sparsify a guest disk.
301 Using virt-sparsify(1), make a disk image more sparse:
302 virt-sparsify /path/to/olddisk.img newdisk.img
304 Is newdisk.img still bootable after sparsifying? Is the resulting disk
306 image smaller (use "du" to check)?
307 Build and boot a guest
309 Using virt-builder(1), choose a guest from the list:
310 virt-builder -l
312 build it:
314 virt-builder -o disk.img [os-version from list above]
316 and boot it:
318 qemu-kvm -cpu host -m 2048 -drive file=disk.img,format=raw
320 Does it boot?
322 * "Sysprep" a shut off Linux guest.
324 Note that this really will mess up an existing guest, so it's better to
325 clone the guest before trying this.
326 virt-sysprep --hostname newhost.example.com -a /path/to/disk.img
328 Was the sysprep successful? After booting, what changes were made and
330 were they successful?
331 Dump the Windows Registry from your Windows guests.
333 Use virt-win-reg(1) to dump out the Windows Registry from any Windows
334 guests that you have.
335 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
337 less
338 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
340 less
341 Does the output match running "regedit" inside the guest?
343 A recent feature is the ability to dump user registries, so try this,
345 replacing username with the name of a local user in the guest:
346 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKEY_USERS\username' |
348 less
349
351 guestfs(3), guestfish(1), guestfs-examples(3), http://libguestfs.org/.
352
354 Richard W.M. Jones ("rjones at redhat dot com")
355
357 Copyright (C) 2011-2023 Red Hat Inc.
358
360 This library is free software; you can redistribute it and/or modify it
361 under the terms of the GNU Lesser General Public License as published
362 by the Free Software Foundation; either version 2 of the License, or
363 (at your option) any later version.
364 This library is distributed in the hope that it will be useful, but
366 WITHOUT ANY WARRANTY; without even the implied warranty of
367 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
368 Lesser General Public License for more details.
369 You should have received a copy of the GNU Lesser General Public
371 License along with this library; if not, write to the Free Software
372 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
373 02110-1301 USA
374
376 To get a list of bugs against libguestfs, use this link:
377 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
378 To report a new bug against libguestfs, use this link:
380 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
381 When reporting a bug, please supply:
383 • The version of libguestfs.
385 • Where you got libguestfs (eg. which Linux distro, compiled from
387 source, etc)
388 • Describe the bug accurately and give a way to reproduce it.
390 • Run libguestfs-test-tool(1) and paste the complete, unedited output
392 into the bug report.
393libguestfs-1.51.9 2023-12-09 guestfs-testing(1)