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