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