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