clone/virt-sysprep.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 virt-sysprep - Reset or unconfigure a virtual machine so clones can be made
   6
   7 =head1 SYNOPSIS
   8
   9  virt-sysprep [--options] -d domname
  10
  11  virt-sysprep [--options] -a disk.img [-a disk.img ...]
  12
  13 =head1 DESCRIPTION
  14
  15 Virt-sysprep "resets" or "unconfigures" a virtual machine so that
  16 clones can be made from it.  Steps in this process include removing
  17 SSH host keys, removing persistent network MAC configuration, and
  18 removing user accounts.  Each step can be enabled or disabled as
  19 required.
  20
  21 Virt-sysprep is a simple shell script, allowing easy inspection or
  22 customization by the system administrator.
  23
  24 Virt-sysprep modifies the guest or disk image I<in place>.  The guest
  25 must be shut down.  If you want to preserve the existing contents of
  26 the guest, you I<must copy or clone the disk first>.
  27 See L</COPYING AND CLONING> below.
  28
  29 You do I<not> need to run virt-sysprep as root.  In fact we'd
  30 generally recommend that you don't.  The time you might want to run it
  31 as root is when you need root in order to access the disk image, but
  32 even in this case it would be better to change the permissions on the
  33 disk image to be writable as the non-root user running virt-sysprep.
  34
  35 "Sysprep" stands for "system preparation" tool.  The name comes from
  36 the Microsoft program C<sysprep.exe> which is used to unconfigure
  37 Windows machines in preparation for cloning them.  Having said that,
  38 virt-sysprep does I<not> currently work on Microsoft Windows guests.
  39 We plan to support Windows sysprepping in a future version, and we
  40 already have code to do it.
  41
  42 =head1 OPTIONS
  43
  44 =over 4
  45
  46 =item B<--help>
  47
  48 Display brief help.
  49
  50 =item B<-a> file
  51
  52 =item B<--add> file
  53
  54 Add I<file> which should be a disk image from a virtual machine.
  55
  56 The format of the disk image is auto-detected.  To override this and
  57 force a particular format use the I<--format=..> option.
  58
  59 =item B<-c> URI
  60
  61 =item B<--connect> URI
  62
  63 If using libvirt, connect to the given I<URI>.  If omitted, then we
  64 connect to the default libvirt hypervisor.
  65
  66 If you specify guest block devices directly (I<-a>), then libvirt is
  67 not used at all.
  68
  69 =item B<-d> guest
  70
  71 =item B<--domain> guest
  72
  73 Add all the disks from the named libvirt guest.  Domain UUIDs can be
  74 used instead of names.
  75
  76 =item B<--enable=...>
  77
  78 Choose which sysprep operations to perform.  Give a comma-separated
  79 list of operations, for example:
  80
  81  --enable=ssh-hostkeys,udev-persistent-net
  82
  83 would enable ONLY C<ssh-hostkeys> and C<udev-persistent-net> operations.
  84
  85 If the I<--enable> option is not given, then we default to trying all
  86 possible sysprep operations.  But some sysprep operations are skipped
  87 for some guest types.
  88
  89 Use I<--list-operations> to list operations supported by a particular
  90 version of virt-sysprep.
  91
  92 See L</OPERATIONS> below for a list and an explanation of each
  93 operation.
  94
  95 =item B<--format=raw|qcow2|..>
  96
  97 =item B<--format>
  98
  99 The default for the I<-a> option is to auto-detect the format of the
 100 disk image.  Using this forces the disk format for I<-a> options which
 101 follow on the command line.  Using I<--format> with no argument
 102 switches back to auto-detection for subsequent I<-a> options.
 103
 104 For example:
 105
 106  virt-sysprep --format=raw -a disk.img
 107
 108 forces raw format (no auto-detection) for C<disk.img>.
 109
 110  virt-sysprep --format=raw -a disk.img --format -a another.img
 111
 112 forces raw format (no auto-detection) for C<disk.img> and reverts to
 113 auto-detection for C<another.img>.
 114
 115 If you have untrusted raw-format guest disk images, you should use
 116 this option to specify the disk format.  This avoids a possible
 117 security problem with malicious guests (CVE-2010-3851).
 118
 119 =item B<--hostname> newhostname
 120
 121 Change the hostname.  See the L</hostname> operation below.
 122 If not given, defaults to C<localhost.localdomain>.
 123
 124 =item B<--list-operations>
 125
 126 List the operations supported by the virt-sysprep program.
 127
 128 =item B<--selinux-relabel>
 129
 130 =item B<--no-selinux-relabel>
 131
 132 I<--selinux-relabel> forces SELinux relabelling next time the guest
 133 boots.  I<--no-selinux-relabel> disables relabelling.
 134
 135 The default is to try to detect if SELinux relabelling is required.
 136 See L</SELINUX RELABELLING> below for more details.
 137
 138 =item B<-v>
 139
 140 =item B<--verbose>
 141
 142 Enable verbose messages for debugging.
 143
 144 =item B<-V>
 145
 146 =item B<--version>
 147
 148 Display version number and exit.
 149
 150 =item B<-x>
 151
 152 Enable tracing of libguestfs API calls.
 153
 154 =back
 155
 156 =head1 OPERATIONS
 157
 158 If the I<--enable> option is I<not> given, then
 159 I<all sysprep operations are enabled>, although some are skipped
 160 depending on the type of guest.
 161
 162 Operations can be individually enabled using the I<--enable> option.
 163 Use a comma-separated list, for example:
 164
 165  virt-sysprep --enable=ssh-hostkeys,udev-persistent-net [etc..]
 166
 167 To list the operations supported by the current version of
 168 virt-sysprep, use I<--list-operations>.
 169
 170 Future versions of virt-sysprep may add more operations.  If you are
 171 using virt-sysprep and want predictable behaviour, specify only the
 172 operations that you want to have enabled.
 173
 174 =head2 cron-spool
 175
 176 Remove user at-jobs and cron-jobs.
 177
 178 =head2 dhcp-client-state
 179
 180 Remove DHCP client leases.
 181
 182 =head2 dhcp-server-state
 183
 184 Remove DHCP server leases.
 185
 186 =head2 hostname
 187
 188 Changes the hostname of the guest to the value given in the
 189 I<--hostname> parameter.
 190
 191 If the I<--hostname> parameter is not given, then the hostname is
 192 changed to C<localhost.localdomain>.
 193
 194 =head2 logfiles
 195
 196 Remove many log files.
 197
 198 =head2 mail-spool
 199
 200 Remove email from the local mail spool directory.
 201
 202 =head2 net-hwaddr
 203
 204 Remove HWADDR (hard-coded MAC address) configuration.  For Fedora and
 205 Red Hat Enterprise Linux, this is removed from C<ifcfg-*> files.
 206
 207 =head2 random-seed
 208
 209 Write some random bytes from the host into the random seed file of
 210 the guest.
 211
 212 See L</RANDOM SEED> below.
 213
 214 =head2 rhn-systemid
 215
 216 Remove the RHN system ID.
 217
 218 =head2 smolt-uuid
 219
 220 Remove the Smolt hardware UUID.
 221
 222 =head2 ssh-hostkeys
 223
 224 Remove the SSH host keys in the guest.
 225
 226 The SSH host keys are regenerated (differently) next time the guest is
 227 booted.
 228
 229 If, after cloning, the guest gets the same IP address, ssh will give
 230 you a stark warning about the host key changing:
 231
 232  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 233  @    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
 234  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 235  IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
 236
 237 =head2 udev-persistent-net
 238
 239 Remove udev persistent net rules which map the guest's existing MAC
 240 address to a fixed ethernet device (eg. eth0).
 241
 242 After a guest is cloned, the MAC address usually changes.  Since the
 243 old MAC address occupies the old name (eg. eth0), this means the fresh
 244 MAC address is assigned to a new name (eg. eth1) and this is usually
 245 undesirable.  Erasing the udev persistent net rules avoids this.
 246
 247 =head2 utmp
 248
 249 Remove the utmp file.
 250
 251 This records who is currently logged in on a machine.  In modern Linux
 252 distros it is stored in a ramdisk and hence not part of the virtual
 253 machine's disk, but it was stored on disk in older distros.
 254
 255 =head2 yum-uuid
 256
 257 Remove the yum UUID.
 258
 259 Yum creates a fresh UUID the next time it runs when it notices that
 260 the original UUID has been erased.
 261
 262 =head1 COPYING AND CLONING
 263
 264 Virt-sysprep can be used as part of a process of cloning guests, or to
 265 prepare a template from which guests can be cloned.  There are many
 266 different ways to achieve this using the virt tools, and this section
 267 is just an introduction.
 268
 269 A virtual machine (when switched off) consists of two parts:
 270
 271 =over 4
 272
 273 =item I<configuration>
 274
 275 The configuration or description of the guest.  eg. The libvirt
 276 XML (see C<virsh dumpxml>), the running configuration of the guest,
 277 or another external format like OVF.
 278
 279 Some configuration items that might need to be changed:
 280
 281 =over 4
 282
 283 =item *
 284
 285 name
 286
 287 =item *
 288
 289 UUID
 290
 291 =item *
 292
 293 path to block device(s)
 294
 295 =item *
 296
 297 network card MAC address
 298
 299 =back
 300
 301 =item I<block device(s)>
 302
 303 One or more hard disk images, themselves containing files,
 304 directories, applications, kernels, configuration, etc.
 305
 306 Some things inside the block devices that might need to be changed:
 307
 308 =over 4
 309
 310 =item *
 311
 312 hostname and other net configuration
 313
 314 =item *
 315
 316 UUID
 317
 318 =item *
 319
 320 SSH host keys
 321
 322 =item *
 323
 324 Windows unique security ID (SID)
 325
 326 =item *
 327
 328 Puppet registration
 329
 330 =back
 331
 332 =back
 333
 334 =head2 COPYING THE BLOCK DEVICE
 335
 336 Starting with an original guest, you probably wish to copy the guest
 337 block device and its configuration to make a template.  Then once you
 338 are happy with the template, you will want to make many clones from
 339 it.
 340
 341                         virt-sysprep
 342                              |
 343                              v
 344  original guest --------> template ---------->
 345                                       \------> cloned
 346                                        \-----> guests
 347                                         \---->
 348
 349 You can, of course, just copy the block device on the host using
 350 L<cp(1)> or L<dd(1)>.
 351
 352                    dd                 dd
 353  original guest --------> template ---------->
 354                                       \------> cloned
 355                                        \-----> guests
 356                                         \---->
 357
 358 There are some smarter (and faster) ways too:
 359
 360 =over 4
 361
 362 =item *
 363
 364                           snapshot
 365                 template ---------->
 366                             \------> cloned
 367                              \-----> guests
 368                               \---->
 369
 370 Use the block device as a backing file and create a snapshot on top
 371 for each guest.  The advantage is that you don't need to copy the
 372 block device (very fast) and only changes are stored (less storage
 373 required).
 374
 375 Note that writing to the backing file once you have created guests on
 376 top of it is not possible: you will corrupt the guests.
 377
 378 Tools that can do this include:
 379 L<qemu-img(1)> (with the I<create -f qcow2 -o backing_file> option),
 380 L<lvcreate(8)> (I<--snapshot> option).  Some filesystems (such as
 381 btrfs) and most Network Attached Storage devices can also create cheap
 382 snapshots from files or LUNs.
 383
 384 =item *
 385
 386 Get your NAS to snapshot and/or duplicate the LUN.
 387
 388 =item *
 389
 390 Prepare your template using L<virt-sparsify(1)>.  See below.
 391
 392 =back
 393
 394 =head2 VIRT-CLONE
 395
 396 A separate tool, L<virt-clone(1)>, can be used to duplicate the block
 397 device and/or modify the external libvirt configuration of a guest.
 398 It will reset the name, UUID and MAC address of the guest in the
 399 libvirt XML.
 400
 401 L<virt-clone(1)> does not use libguestfs and cannot look inside the
 402 disk image.  This was the original motivation to write virt-sysprep.
 403
 404 =head2 SPARSIFY
 405
 406               virt-sparsify
 407  original guest --------> template
 408
 409 L<virt-sparsify(1)> can be used to make the cloning template smaller,
 410 making it easier to compress and/or faster to copy.
 411
 412 Notice that since virt-sparsify also copies the image, you can use it
 413 to make the initial copy (instead of C<dd>).
 414
 415 =head2 RESIZE
 416
 417                          virt-resize
 418                 template ---------->
 419                             \------> cloned
 420                              \-----> guests
 421                               \---->
 422
 423 If you want to give people cloned guests, but let them pick the size
 424 of the guest themselves (eg. depending on how much they are prepared
 425 to pay for disk space), then instead of copying the template, you can
 426 run L<virt-resize(1)>.  Virt-resize performs a copy and resize, and
 427 thus is ideal for cloning guests from a template.
 428
 429 =head1 SECURITY
 430
 431 Although virt-sysprep removes some sensitive information from the
 432 guest, it does not pretend to remove all of it.  You should examine
 433 the L</OPERATIONS> above, and the implementation of the operations in
 434 the shell script.  You should also examine the guest afterwards.
 435
 436 Sensitive files are simply removed.  The data they contained may still
 437 exist on the disk, easily recovered with a hex editor or undelete
 438 tool.  Use L<virt-sparsify(1)> as one way to remove this content.  See
 439 also the L<scrub(1)> command to get rid of deleted content in
 440 directory entries and inodes.
 441
 442 =head2 RANDOM SEED
 443
 444 I<(This section applies to Linux guests only)>
 445
 446 The virt-sysprep C<random-seed> operation writes a few bytes of
 447 randomness from the host into the guest's random seed file.
 448
 449 If this is just done once and the guest is cloned from the same
 450 template, then each guest will start with the same entropy, and things
 451 like SSH host keys and TCP sequence numbers may be predictable.
 452
 453 Therefore you should arrange to add more randomness I<after> cloning
 454 from a template too, which can be done by just enabling the
 455 C<random-seed> operation:
 456
 457  cp template.img newguest.img
 458  virt-sysprep --enable=random-seed -a newguest.img
 459
 460 =head2 SELINUX RELABELLING
 461
 462 I<(This section applies to Linux guests using SELinux only)>
 463
 464 If any new files are created by virt-sysprep, then virt-sysprep
 465 touches C</.autorelabel> so that these will be correctly labelled by
 466 SELinux the next time the guest is booted.  This process interrupts
 467 boot and can take some time.
 468
 469 You can force relabelling for all guests by supplying the
 470 I<--selinux-relabel> option.
 471
 472 You can disable relabelling entirely by supplying the
 473 I<--no-selinux-relabel> option.
 474
 475 =head1 SHELL QUOTING
 476
 477 Libvirt guest names can contain arbitrary characters, some of which
 478 have meaning to the shell such as C<#> and space.  You may need to
 479 quote or escape these characters on the command line.  See the shell
 480 manual page L<sh(1)> for details.
 481
 482 =head1 EXIT STATUS
 483
 484 This program returns 0 on success, or 1 if there was an error.
 485
 486 =head1 SEE ALSO
 487
 488 L<guestfs(3)>,
 489 L<guestfish(1)>,
 490 L<virt-clone(1)>,
 491 L<virt-rescue(1)>,
 492 L<virt-resize(1)>,
 493 L<virt-sparsify(1)>,
 494 L<virsh(1)>,
 495 L<lvcreate(8)>,
 496 L<qemu-img(1)>,
 497 L<scrub(1)>,
 498 L<http://libguestfs.org/>,
 499 L<http://libvirt.org/>.
 500
 501 =head1 AUTHOR
 502
 503 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 504
 505 =head1 COPYRIGHT
 506
 507 Copyright (C) 2011 Red Hat Inc.
 508
 509 This program is free software; you can redistribute it and/or modify
 510 it under the terms of the GNU General Public License as published by
 511 the Free Software Foundation; either version 2 of the License, or
 512 (at your option) any later version.
 513
 514 This program is distributed in the hope that it will be useful,
 515 but WITHOUT ANY WARRANTY; without even the implied warranty of
 516 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 517 GNU General Public License for more details.
 518
 519 You should have received a copy of the GNU General Public License
 520 along with this program; if not, write to the Free Software
 521 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.