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 You can try comparing this to the results from L<df(1)> inside the
 106 guest, but there are some provisos:
 107
 108 =over 4
 109
 110 =item *
 111
 112 The guest must be idle.
 113
 114 =item *
 115
 116 The guest disks must be synched using L<sync(1)>.
 117
 118 =item *
 119
 120 Any action such as booting the guest will write log files causing the
 121 numbers to change.
 122
 123 =back
 124
 125 We don't guarantee that the numbers will be identical even under these
 126 circumstances.  They should be similar.  It would indicate a bug if
 127 you saw greatly differing numbers.
 128
 129 =head2 Try importing virt-df CSV output into a spreadsheet or database.
 130
 131 Run:
 132
 133  virt-df --csv > /tmp/report.csv
 134
 135 Now try to load this into your favorite spreadsheet or database.  Are
 136 the results reproduced faithfully in the spreadsheet/database?
 137
 138 http://www.postgresql.org/docs/8.1/static/sql-copy.html
 139 http://dev.mysql.com/doc/refman/5.1/en/load-data.html
 140
 141 =head2 B<*> Edit a file in a B<shut off> guest.
 142
 143 L<virt-edit(1)> can edit files in guests.  Try this command on
 144 a RHEL or Fedora guest:
 145
 146  virt-edit LinuxGuest /etc/sysconfig/network
 147
 148 On other Linux guests try editing other files such as:
 149
 150  virt-edit LinuxGuest /etc/motd
 151
 152 Are the changes seen inside the guest when it is booted?
 153
 154 =head2 Display the filesystems / partitions / LVs in a guest.
 155
 156 L<virt-filesystems(1)> can be used to display filesystems in
 157 a guest.  Try this command on any disk image or guest:
 158
 159  virt-filesystems -a /path/to/disk.img --all --long -h
 160
 161 or:
 162
 163  virt-filesystems -d Guest --all --long -h
 164
 165 Do the results match what is seen in the guest?
 166
 167 =head2 Run virt-inspector on all your guests.
 168
 169 Use L<virt-inspector(1)> to get a report on all of your guests or disk
 170 images:
 171
 172  virt-inspector -a /path/to/disk.img | less
 173
 174 or:
 175
 176  virt-inspector -d Guest | less
 177
 178 Do the results match what is actually in the guest?
 179
 180 =head2 Try the auditing features of virt-ls on all your guests.
 181
 182 List all setuid or setgid programs in a Linux virtual machine:
 183
 184  virt-ls -lR -d Guest / | grep '^- [42]'
 185
 186 List all public-writable directories in a Linux virtual machine:
 187
 188  virt-ls -lR -d Guest / | grep '^d ...7'
 189
 190 List all Unix domain sockets in a Linux virtual machine:
 191
 192  virt-ls -lR -d Guest / | grep '^s'
 193
 194 List all regular files with filenames ending in '.png':
 195
 196  virt-ls -lR -d Guest / | grep -i '^-.*\.png$'
 197
 198 Display files larger than 10MB in home directories:
 199
 200  virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'
 201
 202 Find everything modified in the last 7 days:
 203
 204  virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'
 205
 206 Find regular files modified in the last 24 hours:
 207
 208  virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'
 209
 210 Do the results match what is in the guest?
 211
 212 =head2 Create a disk image from a tarball.
 213
 214 Use L<virt-make-fs(1)> to create a disk image from any tarball
 215 that you happen to have:
 216
 217  virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img
 218
 219 Add 'output.img' as a raw disk to an existing guest.  Check the guest
 220 can see the files.  This test is particularly useful if you try it
 221 with a Windows guest.
 222
 223 Try other partitioning schemes, eg. I<--partition=gpt>.
 224
 225 Try other filesystem formats, eg. I<--type=ntfs>, I<--type=ext2>.
 226
 227 =head2 B<*> Run virt-rescue on a B<shut off> disk image or guest.
 228
 229 Use L<virt-rescue(1)> to examine, rescue or repair a B<shut off> guest
 230 or disk image:
 231
 232  virt-rescue -a /path/to/disk.img
 233
 234 or:
 235
 236  virt-rescue -d Guest
 237
 238 Can you use ordinary shell commands to examine the guest?
 239
 240 =head2 B<*> Resize your guests.
 241
 242 Use L<virt-resize(1)> to give a guest some more disk space.  For
 243 example, if you have a disk image that is smaller than 30G, increase
 244 it to 30G by doing:
 245
 246  truncate -s 30G newdisk.img
 247  virt-filesystems -a /path/to/olddisk.img --all --long -h
 248  virt-resize /path/to/olddisk.img newdisk.img --expand /dev/sda1
 249  qemu-kvm -m 1024 -hda newdisk.img
 250
 251 Does the guest still boot?  Try expanding other partitions.
 252
 253 =head2 B<*> Sparsify a guest disk.
 254
 255 Using L<virt-sparsify(1)>, make a disk image more sparse:
 256
 257  virt-sparsify /path/to/olddisk.img newdisk.img
 258
 259 Is C<newdisk.img> still bootable after sparsifying?  Is the resulting
 260 disk image smaller (use C<du> to check)?
 261
 262 =head2 B<*> "sysprep" a B<shut off> Linux guest.
 263
 264 Note that this really will mess up an existing guest, so it's better
 265 to clone the guest before trying this.
 266
 267  virt-sysprep --hostname newhost.example.com -a /path/to/disk.img
 268
 269 Was the sysprep successful?  After booting, what changes were made and
 270 were they successful?
 271
 272 =head2 Dump the Windows Registry from your Windows guests.
 273
 274 Use L<virt-win-reg(1)> to dump out the Windows Registry from
 275 any Windows guests that you have.
 276
 277  virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
 278    less
 279
 280  virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
 281    less
 282
 283 Does the output match running C<regedit> inside the guest?
 284
 285 A recent feature is the ability to dump user registries, so try this,
 286 replacing I<username> with the name of a local user in the guest:
 287
 288  virt-win-reg --unsafe-printable-strings WindowsGuest 'HKEY_USERS\username' |
 289    less
 290
 291 =head1 SEE ALSO
 292
 293 L<guestfs(3)>,
 294 L<guestfish(1)>,
 295 L<guestfs-examples(3)>,
 296 L<http://libguestfs.org/>.
 297
 298 =head1 AUTHORS
 299
 300 Richard W.M. Jones (C<rjones at redhat dot com>)
 301
 302 =head1 COPYRIGHT
 303
 304 Copyright (C) 2011 Red Hat Inc. L<http://libguestfs.org/>
 305
 306 This library is free software; you can redistribute it and/or
 307 modify it under the terms of the GNU Lesser General Public
 308 License as published by the Free Software Foundation; either
 309 version 2 of the License, or (at your option) any later version.
 310
 311 This library is distributed in the hope that it will be useful,
 312 but WITHOUT ANY WARRANTY; without even the implied warranty of
 313 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 314 Lesser General Public License for more details.
 315
 316 You should have received a copy of the GNU Lesser General Public
 317 License along with this library; if not, write to the Free Software
 318 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA