1guestfs-testing(1) Virtualization Support guestfs-testing(1)
2
3
4
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
13 Tests marked with a * (asterisk) can destroy data if you're not
14 careful. The others are safe and won't modify anything.
15
16 These tests require libguestfs ≥ 1.22.
17
18 You can report bugs you find through this link:
19
20 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
21
22 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
26 https://www.redhat.com/mailman/listinfo/libguestfs
27
29 Run libguestfs-test-tool
30 Run:
31
32 libguestfs-test-tool
33
34 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
37 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
42 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
47 time guestfish -a /dev/null run
48
49 After a few runs, the time should settle down to a few seconds (under 3
50 seconds on fast 64 bit hardware).
51
52 If the command above does not work at all, use libguestfs-test-tool(1).
53
54 Check which version of libguestfs, qemu, libvirt, etc is being used.
55 Look at the output of "libguestfs-test-tool" and check:
56
57 · Which version of libguestfs is being used? Near the beginning of
58 the output you'll see a line like:
59
60 library version: 1.22.0fedora=19,release=1.fc19,libvirt
61
62 · Is libvirt being used? You can tell the difference by looking for
63 the backend:
64
65 guestfs_get_backend: direct
66
67 or:
68
69 guestfs_get_backend: libvirt
70
71 · Which version of qemu is being used? It may be printed out:
72
73 libguestfs: qemu version 1.5
74
75 · 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
79 [ 0.000000] Linux version 3.9.2-200.fc18.x86_64 [...]
80
81 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
85 guestfish --ro -a /path/to/disk.img -i
86
87 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
92 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
95 Try to open a remote guest image with guestfish.
96 You may also have to disable libvirt by setting this:
97
98 export LIBGUESTFS_BACKEND=direct
99
100 If you have a disk image available over HTTP/FTP, try to open it.
101
102 guestfish --ro -i --format=raw -a http://www.example.com/disk.img
103
104 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
108 guestfish --ro -i --format=raw \
109 -a ssh://remote.example.com/path/to/disk.img
110
111 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
114 Run virt-alignment-scan on all your guests.
115 Run virt-alignment-scan(1) on guests or disk images:
116
117 virt-alignment-scan -a /path/to/disk.img
118
119 or:
120
121 virt-alignment-scan -d Guest
122
123 Does the alignment report match how the guest partitions are aligned?
124
125 Run virt-cat on some files in guests.
126 virt-cat(1) can display files from guests. For a Linux guest, try:
127
128 virt-cat LinuxGuest /etc/passwd
129
130 A recent feature is support for Windows paths, for example:
131
132 virt-cat WindowsGuest 'c:\windows\win.ini'
133
134 An even better test is if you have a Windows guest with multiple
135 drives. Do "D:", "E:" etc paths work correctly?
136
137 * 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
141 virt-copy-in -d Guest /etc /tmp
142
143 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
147 Shut the guest down and try copying multiple files and directories:
148
149 virt-copy-in -d Guest /home /etc/issue /tmp
150
151 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
155 virt-copy-out -d Guest /home .
156
157 Note the final space and period in the command is not a typo.
158
159 This should copy /home from the guest into the current directory.
160
161 Run virt-df.
162 virt-df(1) lists disk space. Run:
163
164 virt-df
165
166 You can try comparing this to the results from df(1) inside the guest,
167 but there are some provisos:
168
169 · The guest must be idle.
170
171 · The guest disks must be synched using sync(1).
172
173 · Any action such as booting the guest will write log files causing
174 the numbers to change.
175
176 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
180 Try importing virt-df CSV output into a spreadsheet or database.
181 Run:
182
183 virt-df --csv > /tmp/report.csv
184
185 Now try to load this into your favorite spreadsheet or database. Are
186 the results reproduced faithfully in the spreadsheet/database?
187
188 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
191 * 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
195 virt-edit LinuxGuest /etc/sysconfig/network
196
197 On other Linux guests try editing other files such as:
198
199 virt-edit LinuxGuest /etc/motd
200
201 Are the changes seen inside the guest when it is booted?
202
203 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
207 virt-filesystems -a /path/to/disk.img --all --long -h
208
209 or:
210
211 virt-filesystems -d Guest --all --long -h
212
213 Do the results match what is seen in the guest?
214
215 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
219 virt-inspector -a /path/to/disk.img | less
220
221 or:
222
223 virt-inspector -d Guest | less
224
225 Do the results match what is actually in the guest?
226
227 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
231 Try the auditing features of virt-ls on all your guests.
232 List all setuid or setgid programs in a Linux virtual machine:
233
234 virt-ls -lR -d Guest / | grep '^- [42]'
235
236 List all public-writable directories in a Linux virtual machine:
237
238 virt-ls -lR -d Guest / | grep '^d ...7'
239
240 List all Unix domain sockets in a Linux virtual machine:
241
242 virt-ls -lR -d Guest / | grep '^s'
243
244 List all regular files with filenames ending in ‘.png’:
245
246 virt-ls -lR -d Guest / | grep -i '^-.*\.png$'
247
248 Display files larger than 10MB in home directories:
249
250 virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'
251
252 Find everything modified in the last 7 days:
253
254 virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'
255
256 Find regular files modified in the last 24 hours:
257
258 virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'
259
260 Do the results match what is in the guest?
261
262 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
266 virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img
267
268 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
272 Try other partitioning schemes, eg. --partition=gpt.
273
274 Try other filesystem formats, eg. --type=ntfs, --type=ext2.
275
276 * 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
280 virt-rescue -a /path/to/disk.img
281
282 or:
283
284 virt-rescue -d Guest
285
286 Can you use ordinary shell commands to examine the guest?
287
288 * 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
293 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
298 Does the guest still boot? Try expanding other partitions.
299
300 * Sparsify a guest disk.
301 Using virt-sparsify(1), make a disk image more sparse:
302
303 virt-sparsify /path/to/olddisk.img newdisk.img
304
305 Is newdisk.img still bootable after sparsifying? Is the resulting disk
306 image smaller (use "du" to check)?
307
308 Build and boot a guest
309 Using virt-builder(1), choose a guest from the list:
310
311 virt-builder -l
312
313 build it:
314
315 virt-builder -o disk.img [os-version from list above]
316
317 and boot it:
318
319 qemu-kvm -cpu host -m 2048 -drive file=disk.img,format=raw
320
321 Does it boot?
322
323 * "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
327 virt-sysprep --hostname newhost.example.com -a /path/to/disk.img
328
329 Was the sysprep successful? After booting, what changes were made and
330 were they successful?
331
332 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
336 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
337 less
338
339 virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
340 less
341
342 Does the output match running "regedit" inside the guest?
343
344 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
347 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-2012 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
365 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
370 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
379 To report a new bug against libguestfs, use this link:
380 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
381
382 When reporting a bug, please supply:
383
384 · The version of libguestfs.
385
386 · Where you got libguestfs (eg. which Linux distro, compiled from
387 source, etc)
388
389 · Describe the bug accurately and give a way to reproduce it.
390
391 · Run libguestfs-test-tool(1) and paste the complete, unedited output
392 into the bug report.
393
394
395
396libguestfs-1.44.0 2021-01-05 guestfs-testing(1)