1guestfs-testing(1)          Virtualization Support          guestfs-testing(1)
2
3
4

NAME

6       guestfs-testing - manual testing of libguestfs, you can help!
7

DESCRIPTION

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

TESTS

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

SEE ALSO

351       guestfs(3), guestfish(1), guestfs-examples(3), http://libguestfs.org/.
352

AUTHORS

354       Richard W.M. Jones ("rjones at redhat dot com")
355
357       Copyright (C) 2011-2023 Red Hat Inc.
358

LICENSE

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

BUGS

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.50.1                 2023-02-21                guestfs-testing(1)
Impressum