examples/guestfs-testing.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 guestfs-testing - manual testing of libguestfs, you can help!
   6
   7 =head1 DESCRIPTION
   8
   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 These tests require libguestfs E<ge> 1.14.
  14
  15 Tests marked with a B<*> (asterisk) can B<destroy data> if you're not
  16 careful.  The others are safe and won't modify anything.
  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 B<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
  28 =head1 TESTS
  29
  30 =head2 Check KVM acceleration is being used.
  31
  32 If your host has hardware virt acceleration, then with a hot cache
  33 libguestfs should be able to start up in a few seconds.  Run the
  34 following command a few times:
  35
  36  time guestfish -a /dev/null run
  37
  38 After a few runs, the time should settle down to a few seconds (under
  39 5 seconds on fast 64 bit hardware).
  40
  41 How to check for hardware virt:
  42
  43 http://virt-tools.org/learning/check-hardware-virt/
  44
  45 If the command above does not work at all, use
  46 L<libguestfs-test-tool(1)>.
  47
  48 =head2 Run virt-alignment-scan on all your guests.
  49
  50 Run L<virt-alignment-scan(1)> on guests or disk images:
  51
  52  virt-alignment-scan -a /path/to/disk.img
  53
  54 or:
  55
  56  virt-alignment-scan -d Guest
  57
  58 Does the alignment report match how the guest partitions are aligned?
  59
  60 =head2 Run virt-cat on some files in guests.
  61
  62 L<virt-cat(1)> can display files from guests.  For a Linux guest, try:
  63
  64  virt-cat LinuxGuest /etc/passwd
  65
  66 A recent feature is support for Windows paths, for example:
  67
  68  virt-cat WindowsGuest 'c:\windows\win.ini'
  69
  70 An even better test is if you have a Windows guest with multiple
  71 drives.  Do C<D:>, C<E:> etc paths work correctly?
  72
  73 =head2 B<*> Copy some files into a B<shut off> guest.
  74
  75 L<virt-copy-in(1)> can recursively copy files and directories
  76 into a guest or disk image.
  77
  78  virt-copy-in -d Guest /etc /tmp
  79
  80 This should copy local directory C</etc> to C</tmp/etc> in the guest
  81 (recursively).  If you boot the guest, can you see all of the copied
  82 files and directories?
  83
  84 Shut the guest down and try copying multiple files and directories:
  85
  86  virt-copy-in -d Guest /home /etc/issue /tmp
  87
  88 =head2 Copy some files out of a guest.
  89
  90 L<virt-copy-out(1)> can recursively copy files and directories
  91 out of a guest or disk image.
  92
  93  virt-copy-out -d Guest /home .
  94
  95 Note the final space and period in the command is not a typo.
  96
  97 This should copy C</home> from the guest into the current directory.
  98
  99 =head2 Run virt-df.
 100
 101 L<virt-df(1)> lists disk space.  Run:
 102
 103  virt-df
 104
 105 Do the results match what's reported inside the guests?
 106
 107 =head2 Try importing virt-df CSV output into a spreadsheet or database.
 108
 109 Run:
 110
 111  virt-df --csv > /tmp/report.csv
 112
 113 Now try to load this into your favorite spreadsheet or database.  Are
 114 the results reproduced faithfully in the spreadsheet/database?
 115
 116 http://www.postgresql.org/docs/8.1/static/sql-copy.html
 117 http://dev.mysql.com/doc/refman/5.1/en/load-data.html
 118
 119 =head2 B<*> Edit a file in a B<shut off> guest.
 120
 121 L<virt-edit(1)> can edit files in guests.  Try this command on
 122 a RHEL or Fedora guest:
 123
 124  virt-edit LinuxGuest /etc/sysconfig/network
 125
 126 On other Linux guests try editing other files such as:
 127
 128  virt-edit LinuxGuest /etc/motd
 129
 130 Are the changes seen inside the guest when it is booted?
 131
 132 =head2 Display the filesystems / partitions / LVs in a guest.
 133
 134 L<virt-filesystems(1)> can be used to display filesystems in
 135 a guest.  Try this command on any disk image or guest:
 136
 137  virt-filesystems -a /path/to/disk.img --all --long -h
 138
 139 or:
 140
 141  virt-filesystems -d Guest --all --long -h
 142
 143 Do the results match what is seen in the guest?
 144
 145 =head2 Run virt-inspector on all your guests.
 146
 147 Use L<virt-inspector(1)> to get a report on all of your guests or disk
 148 images:
 149
 150  virt-inspector -a /path/to/disk.img | less
 151
 152 or:
 153
 154  virt-inspector -d Guest | less
 155
 156 Do the results match what is actually in the guest?
 157
 158 =head2 Try the auditing features of virt-ls on all your guests.
 159
 160 List all setuid or setgid programs in a Linux virtual machine:
 161
 162  virt-ls -lR -d Guest / | grep '^- [42]'
 163
 164 List all public-writable directories in a Linux virtual machine:
 165
 166  virt-ls -lR -d Guest / | grep '^d ...7'
 167
 168 List all Unix domain sockets in a Linux virtual machine:
 169
 170  virt-ls -lR -d Guest / | grep '^s'
 171
 172 List all regular files with filenames ending in '.png':
 173
 174  virt-ls -lR -d Guest / | grep -i '^-.*\.png$'
 175
 176 Display files larger than 10MB in home directories:
 177
 178  virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'
 179
 180 Find everything modified in the last 7 days:
 181
 182  virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'
 183
 184 Find regular files modified in the last 24 hours:
 185
 186  virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'
 187
 188 Do the results match what is in the guest?
 189
 190 =head2 Create a disk image from a tarball.
 191
 192 Use L<virt-make-fs(1)> to create a disk image from any tarball
 193 that you happen to have:
 194
 195  virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img
 196
 197 Add 'output.img' as a raw disk to an existing guest.  Check the guest
 198 can see the files.  This test is particularly useful if you try it
 199 with a Windows guest.
 200
 201 Try other partitioning schemes, eg. I<--partition=gpt>.
 202
 203 Try other filesystem formats, eg. I<--type=ntfs>, I<--type=ext2>.
 204
 205 =head2 B<*> Run virt-rescue on a B<shut off> disk image or guest.
 206
 207 Use L<virt-rescue(1)> to examine, rescue or repair a B<shut off> guest
 208 or disk image:
 209
 210  virt-rescue -a /path/to/disk.img
 211
 212 or:
 213
 214  virt-rescue -d Guest
 215
 216 Can you use ordinary shell commands to examine the guest?
 217
 218 =head2 B<*> Resize your guests.
 219
 220 Use L<virt-resize(1)> to give a guest some more disk space.  For
 221 example, if you have a disk image that is smaller than 30G, increase
 222 it to 30G by doing:
 223
 224  truncate -s 30G newdisk.img
 225  virt-filesystems -a /path/to/olddisk.img --all --long -h
 226  virt-resize /path/to/olddisk.img newdisk.img --expand /dev/sda1
 227  qemu-kvm -m 1024 -hda newdisk.img
 228
 229 Does the guest still boot?  Try expanding other partitions.
 230
 231 =head2 B<*> Sparsify a guest disk.
 232
 233 Using L<virt-sparsify(1)>, make a disk image more sparse:
 234
 235  virt-sparsify /path/to/olddisk.img newdisk.img
 236
 237 Is C<newdisk.img> still bootable after sparsifying?  Is the resulting
 238 disk image smaller (use C<du> to check)?
 239
 240 =head2 B<*> "sysprep" a B<shut off> Linux guest.
 241
 242 Note that this really will mess up an existing guest, so it's better
 243 to clone the guest before trying this.
 244
 245  virt-sysprep --hostname newhost.example.com -a /path/to/disk.img
 246
 247 Was the sysprep successful?  After booting, what changes were made and
 248 were they successful?
 249
 250 =head2 Dump the Windows Registry from your Windows guests.
 251
 252 Use L<virt-win-reg(1)> to dump out the Windows Registry from
 253 any Windows guests that you have.
 254
 255  virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
 256    less
 257
 258  virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
 259    less
 260
 261 Does the output match running C<regedit> inside the guest?
 262
 263 A recent feature is the ability to dump user registries, so try this,
 264 replacing I<username> with the name of a local user in the guest:
 265
 266  virt-win-reg --unsafe-printable-strings WindowsGuest 'HKEY_USERS\username' |
 267    less
 268
 269 =head1 SEE ALSO
 270
 271 L<guestfs(3)>,
 272 L<guestfish(1)>,
 273 L<guestfs-examples(3)>,
 274 L<http://libguestfs.org/>.
 275
 276 =head1 AUTHORS
 277
 278 Richard W.M. Jones (C<rjones at redhat dot com>)
 279
 280 =head1 COPYRIGHT
 281
 282 Copyright (C) 2011 Red Hat Inc. L<http://libguestfs.org/>
 283
 284 This library is free software; you can redistribute it and/or
 285 modify it under the terms of the GNU Lesser General Public
 286 License as published by the Free Software Foundation; either
 287 version 2 of the License, or (at your option) any later version.
 288
 289 This library is distributed in the hope that it will be useful,
 290 but WITHOUT ANY WARRANTY; without even the implied warranty of
 291 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 292 Lesser General Public License for more details.
 293
 294 You should have received a copy of the GNU Lesser General Public
 295 License along with this library; if not, write to the Free Software
 296 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA