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 all sysprep operations
 159 in the list below are enabled, although some are skipped depending on
 160 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 =head2 dhcp-client-state
 171
 172 Remove DHCP client leases.
 173
 174 =head2 dhcp-server-state
 175
 176 Remove DHCP server leases.
 177
 178 =head2 hostname
 179
 180 Changes the hostname of the guest to the value given in the
 181 I<--hostname> parameter.
 182
 183 If the I<--hostname> parameter is not given, then the hostname is
 184 changed to C<localhost.localdomain>.
 185
 186 =head2 logfiles
 187
 188 Remove many log files.
 189
 190 =head2 net-hwaddr
 191
 192 Remove HWADDR (hard-coded MAC address) configuration.  For Fedora and
 193 Red Hat Enterprise Linux, this is removed from C<ifcfg-*> files.
 194
 195 =head2 random-seed
 196
 197 Write some random bytes from the host into the random seed file of
 198 the guest.
 199
 200 See C</RANDOM SEED> below.
 201
 202 =head2 smolt-uuid
 203
 204 Remove the Smolt hardware UUID.
 205
 206 =head2 ssh-hostkeys
 207
 208 Remove the SSH host keys in the guest.
 209
 210 The SSH host keys are regenerated (differently) next time the guest is
 211 booted.
 212
 213 If, after cloning, the guest gets the same IP address, ssh will give
 214 you a stark warning about the host key changing:
 215
 216  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 217  @    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
 218  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 219  IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
 220
 221 =head2 udev-persistent-net
 222
 223 Remove udev persistent net rules which map the guest's existing MAC
 224 address to a fixed ethernet device (eg. eth0).
 225
 226 After a guest is cloned, the MAC address usually changes.  Since the
 227 old MAC address occupies the old name (eg. eth0), this means the fresh
 228 MAC address is assigned to a new name (eg. eth1) and this is usually
 229 undesirable.  Erasing the udev persistent net rules avoids this.
 230
 231 =head2 yum-uuid
 232
 233 Remove the yum UUID.
 234
 235 yum creates a fresh UUID the next time it runs when it notices that
 236 the original UUID has been erased.
 237
 238 =head1 COPYING AND CLONING
 239
 240 Virt-sysprep can be used as part of a process of cloning guests, or to
 241 prepare a template from which guests can be cloned.  There are many
 242 different ways to achieve this using the virt tools, and this section
 243 is just an introduction.
 244
 245 A virtual machine (when switched off) consists of two parts:
 246
 247 =over 4
 248
 249 =item I<configuration>
 250
 251 The configuration or description of the guest.  eg. The libvirt
 252 XML (see C<virsh dumpxml>), the running configuration of the guest,
 253 or another external format like OVF.
 254
 255 Some configuration items that might need to be changed:
 256
 257 =over 4
 258
 259 =item *
 260
 261 name
 262
 263 =item *
 264
 265 UUID
 266
 267 =item *
 268
 269 path to block device(s)
 270
 271 =item *
 272
 273 network card MAC address
 274
 275 =back
 276
 277 =item I<block device(s)>
 278
 279 One or more hard disk images, themselves containing files,
 280 directories, applications, kernels, configuration, etc.
 281
 282 Some things inside the block devices that might need to be changed:
 283
 284 =over 4
 285
 286 =item *
 287
 288 hostname and other net configuration
 289
 290 =item *
 291
 292 UUID
 293
 294 =item *
 295
 296 SSH host keys
 297
 298 =item *
 299
 300 Windows unique security ID (SID)
 301
 302 =item *
 303
 304 Puppet registration
 305
 306 =back
 307
 308 =back
 309
 310 =head2 COPYING THE BLOCK DEVICE
 311
 312 Starting with an original guest, you probably wish to copy the guest
 313 block device and its configuration to make a template.  Then once you
 314 are happy with the template, you will want to make many clones from
 315 it.
 316
 317                         virt-sysprep
 318                              |
 319                              v
 320  original guest --------> template ---------->
 321                                       \------> cloned
 322                                        \-----> guests
 323                                         \---->
 324
 325 You can, of course, just copy the block device on the host using
 326 L<cp(1)> or L<dd(1)>.
 327
 328                    dd                 dd
 329  original guest --------> template ---------->
 330                                       \------> cloned
 331                                        \-----> guests
 332                                         \---->
 333
 334 There are some smarter (and faster) ways too:
 335
 336 =over 4
 337
 338 =item *
 339
 340                           snapshot
 341                 template ---------->
 342                             \------> cloned
 343                              \-----> guests
 344                               \---->
 345
 346 Use the block device as a backing file and create a snapshot on top
 347 for each guest.  The advantage is that you don't need to copy the
 348 block device (very fast) and only changes are stored (less storage
 349 required).
 350
 351 Note that writing to the backing file once you have created guests on
 352 top of it is not possible: you will corrupt the guests.
 353
 354 Tools that can do this include:
 355 L<qemu-img(1)> (with the I<create -f qcow2 -o backing_file> option),
 356 L<lvcreate(8)> (I<--snapshot> option).  Some filesystems (such as
 357 btrfs) and most Network Attached Storage devices can also create cheap
 358 snapshots from files or LUNs.
 359
 360 =item *
 361
 362 Get your NAS to snapshot and/or duplicate the LUN.
 363
 364 =item *
 365
 366 Prepare your template using L<virt-sparsify(1)>.  See below.
 367
 368 =back
 369
 370 =head2 VIRT-CLONE
 371
 372 A separate tool, L<virt-clone(1)>, can be used to duplicate the block
 373 device and/or modify the external libvirt configuration of a guest.
 374 It will reset the name, UUID and MAC address of the guest in the
 375 libvirt XML.
 376
 377 L<virt-clone(1)> does not use libguestfs and cannot look inside the
 378 disk image.  This was the original motivation to write virt-sysprep.
 379
 380 =head2 SPARSIFY
 381
 382               virt-sparsify
 383  original guest --------> template
 384
 385 L<virt-sparsify(1)> can be used to make the cloning template smaller,
 386 making it easier to compress and/or faster to copy.
 387
 388 Notice that since virt-sparsify also copies the image, you can use it
 389 to make the initial copy (instead of C<dd>).
 390
 391 =head2 RESIZE
 392
 393                          virt-resize
 394                 template ---------->
 395                             \------> cloned
 396                              \-----> guests
 397                               \---->
 398
 399 If you want to give people cloned guests, but let them pick the size
 400 of the guest themselves (eg. depending on how much they are prepared
 401 to pay for disk space), then instead of copying the template, you can
 402 run L<virt-resize(1)>.  Virt-resize performs a copy and resize, and
 403 thus is ideal for cloning guests from a template.
 404
 405 =head1 SECURITY
 406
 407 Although virt-sysprep removes some sensitive information from
 408 the guest, it does not pretend to remove all of it.  You should
 409 examine the L</OPERATIONS> above, and the implementation of
 410 the operations in the shell script.
 411
 412 You should also examine the guest afterwards.
 413
 414 Sensitive files are simply removed.  The data they contained may still
 415 exist on the disk, easily recovered with a hex editor or undelete
 416 tool.  Use L<virt-sparsify(1)> as one way to remove this content.  See
 417 also the L<scrub(1)> command to get rid of deleted content in
 418 directory entries and inodes.
 419
 420 =head2 RANDOM SEED
 421
 422 I<(This section applies to Linux guests only)>
 423
 424 The virt-sysprep C<random-seed> operation writes a few bytes of
 425 randomness from the host into the guest's random seed file.
 426
 427 If this is just done once and the guest is cloned from the same
 428 template, then each guest will start with the same entropy, and things
 429 like SSH host keys and TCP sequence numbers may be predictable.
 430
 431 Therefore you should arrange to add more randomness I<after> cloning
 432 from a template too, which can be done by just enabling the
 433 C<random-seed> operation:
 434
 435  cp template.img newguest.img
 436  virt-sysprep --enable=random-seed -a newguest.img
 437
 438 =head2 SELINUX RELABELLING
 439
 440 I<(This section applies to Linux guests using SELinux only)>
 441
 442 If any new files are created by virt-sysprep, then virt-sysprep
 443 touches C</.autorelabel> so that these will be correctly labelled by
 444 SELinux the next time the guest is booted.  This process interrupts
 445 boot and can take some time.
 446
 447 You can force relabelling for all guests by supplying the
 448 I<--selinux-relabel> option.
 449
 450 You can disable relabelling entirely by supplying the
 451 I<--no-selinux-relabel> option.
 452
 453 =head1 SHELL QUOTING
 454
 455 Libvirt guest names can contain arbitrary characters, some of which
 456 have meaning to the shell such as C<#> and space.  You may need to
 457 quote or escape these characters on the command line.  See the shell
 458 manual page L<sh(1)> for details.
 459
 460 =head1 EXIT STATUS
 461
 462 This program returns 0 on success, or 1 if there was an error.
 463
 464 =head1 SEE ALSO
 465
 466 L<guestfs(3)>,
 467 L<guestfish(1)>,
 468 L<virt-clone(1)>,
 469 L<virt-rescue(1)>,
 470 L<virt-resize(1)>,
 471 L<virt-sparsify(1)>,
 472 L<virsh(1)>,
 473 L<lvcreate(8)>,
 474 L<qemu-img(1)>,
 475 L<scrub(1)>,
 476 L<http://libguestfs.org/>,
 477 L<http://libvirt.org/>.
 478
 479 =head1 AUTHOR
 480
 481 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 482
 483 =head1 COPYRIGHT
 484
 485 Copyright (C) 2011 Red Hat Inc.
 486
 487 This program is free software; you can redistribute it and/or modify
 488 it under the terms of the GNU General Public License as published by
 489 the Free Software Foundation; either version 2 of the License, or
 490 (at your option) any later version.
 491
 492 This program is distributed in the hope that it will be useful,
 493 but WITHOUT ANY WARRANTY; without even the implied warranty of
 494 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 495 GNU General Public License for more details.
 496
 497 You should have received a copy of the GNU General Public License
 498 along with this program; if not, write to the Free Software
 499 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.