1virt-sysprep(1)             Virtualization Support             virt-sysprep(1)
2
3
4

NAME

6       virt-sysprep - Reset, unconfigure or customize a virtual machine so
7       clones can be made
8

SYNOPSIS

10        virt-sysprep [--options] -d domname
11
12        virt-sysprep [--options] -a disk.img [-a disk.img ...]
13

WARNING

15       Using "virt-sysprep" on live virtual machines, or concurrently with
16       other disk editing tools, can be dangerous, potentially causing disk
17       corruption.  The virtual machine must be shut down before you use this
18       command, and disk images must not be edited concurrently.
19

DESCRIPTION

21       Virt-sysprep can reset or unconfigure a virtual machine so that clones
22       can be made from it.  Steps in this process include removing SSH host
23       keys, removing persistent network MAC configuration, and removing user
24       accounts.  Virt-sysprep can also customize a virtual machine, for
25       instance by adding SSH keys, users or logos.  Each step can be enabled
26       or disabled as required.
27
28       Virt-sysprep modifies the guest or disk image in place.  The guest must
29       be shut down.  If you want to preserve the existing contents of the
30       guest, you must snapshot, copy or clone the disk first.  See "COPYING
31       AND CLONING" below.
32
33       You do not need to run virt-sysprep as root.  In fact we'd generally
34       recommend that you don't.  The time you might want to run it as root is
35       when you need root in order to access the disk image, but even in this
36       case it would be better to change the permissions on the disk image to
37       be writable as the non-root user running virt-sysprep.
38
39       "Sysprep" stands for "system preparation" tool.  The name comes from
40       the Microsoft program sysprep.exe which is used to unconfigure Windows
41       machines in preparation for cloning them.  Having said that, virt-
42       sysprep does not currently work on Microsoft Windows guests.  We plan
43       to support Windows sysprepping in a future version, and we already have
44       code to do it.
45

OPTIONS

47       --help
48           Display brief help.
49
50       -a file
51       --add file
52           Add file which should be a disk image from a virtual machine.
53
54           The format of the disk image is auto-detected.  To override this
55           and force a particular format use the --format option.
56
57       -a URI
58       --add URI
59           Add a remote disk.  The URI format is compatible with guestfish.
60           See "ADDING REMOTE STORAGE" in guestfish(1).
61
62       --colors
63       --colours
64           Use ANSI colour sequences to colourize messages.  This is the
65           default when the output is a tty.  If the output of the program is
66           redirected to a file, ANSI colour sequences are disabled unless you
67           use this option.
68
69       -c URI
70       --connect URI
71           If using libvirt, connect to the given URI.  If omitted, then we
72           connect to the default libvirt hypervisor.
73
74           If you specify guest block devices directly (-a), then libvirt is
75           not used at all.
76
77       -d guest
78       --domain guest
79           Add all the disks from the named libvirt guest.  Domain UUIDs can
80           be used instead of names.
81
82       -n
83       --dry-run
84           Perform a read-only "dry run" on the guest.  This runs the sysprep
85           operation, but throws away any changes to the disk at the end.
86
87       --enable operations
88           Choose which sysprep operations to perform.  Give a comma-separated
89           list of operations, for example:
90
91            --enable ssh-hostkeys,udev-persistent-net
92
93           would enable ONLY "ssh-hostkeys" and "udev-persistent-net"
94           operations.
95
96           If the --enable option is not given, then we default to trying most
97           sysprep operations (see --list-operations to show which are
98           enabled).
99
100           Regardless of the --enable option, sysprep operations are skipped
101           for some guest types.
102
103           Use --list-operations to list operations supported by a particular
104           version of virt-sysprep.
105
106           See "OPERATIONS" below for a list and an explanation of each
107           operation.
108
109       --operation operations
110       --operations operations
111           Choose which sysprep operations to perform.  Give a comma-separated
112           list of operations, for example:
113
114            --operations ssh-hostkeys,udev-persistent-net
115
116           would enable ONLY "ssh-hostkeys" and "udev-persistent-net"
117           operations.
118
119           --operations allows you to enable and disable any operation,
120           including the default ones (which would be tried when specifying
121           neither --operations nor --enable) and all the available ones;
122           prepending a "-" in front of an operation name removes it from the
123           list of enabled operations, while the meta-names "defaults" and
124           "all" represent respectively the operations enabled by default and
125           all the available ones.  For example:
126
127            --operations firewall-rules,defaults,-tmp-files
128
129           would enable the "firewall-rules" operation (regardless whether it
130           is enabled by default), all the default ones, and disable the
131           "tmp-files" operation.
132
133           --operations can be specified multiple times; the first time the
134           set of enabled operations is empty, while any further --operations
135           affects the operations enabled so far.
136
137           If the --operations option is not given, then we default to trying
138           most sysprep operations (see --list-operations to show which are
139           enabled).
140
141           Regardless of the --operations option, sysprep operations are
142           skipped for some guest types.
143
144           Use --list-operations to list operations supported by a particular
145           version of virt-sysprep.
146
147           See "OPERATIONS" below for a list and an explanation of each
148           operation.
149
150       --echo-keys
151           When prompting for keys and passphrases, virt-sysprep normally
152           turns echoing off so you cannot see what you are typing.  If you
153           are not worried about Tempest attacks and there is no one else in
154           the room you can specify this flag to see what you are typing.
155
156       --format raw|qcow2|..
157       --format auto
158           The default for the -a option is to auto-detect the format of the
159           disk image.  Using this forces the disk format for -a options which
160           follow on the command line.  Using --format auto switches back to
161           auto-detection for subsequent -a options.
162
163           For example:
164
165            virt-sysprep --format raw -a disk.img
166
167           forces raw format (no auto-detection) for disk.img.
168
169            virt-sysprep --format raw -a disk.img --format auto -a another.img
170
171           forces raw format (no auto-detection) for disk.img and reverts to
172           auto-detection for another.img.
173
174           If you have untrusted raw-format guest disk images, you should use
175           this option to specify the disk format.  This avoids a possible
176           security problem with malicious guests (CVE-2010-3851).
177
178       --key SELECTOR
179           Specify a key for LUKS, to automatically open a LUKS device when
180           using the inspection.  "ID" can be either the libguestfs device
181           name, or the UUID of the LUKS device.
182
183           --key "ID":key:KEY_STRING
184               Use the specified "KEY_STRING" as passphrase.
185
186           --key "ID":file:FILENAME
187               Read the passphrase from FILENAME.
188
189       --keys-from-stdin
190           Read key or passphrase parameters from stdin.  The default is to
191           try to read passphrases from the user by opening /dev/tty.
192
193           If there are multiple encrypted devices then you may need to supply
194           multiple keys on stdin, one per line.
195
196       --list-operations
197           List the operations supported by the virt-sysprep program.
198
199           These are listed one per line, with one or more single-space-
200           separated fields, eg:
201
202            $ virt-sysprep --list-operations
203            bash-history * Remove the bash history in the guest
204            cron-spool * Remove user at-jobs and cron-jobs
205            dhcp-client-state * Remove DHCP client leases
206            dhcp-server-state * Remove DHCP server leases
207            [etc]
208
209           The first field is the operation name, which can be supplied to
210           --enable.  The second field is a "*" character if the operation is
211           enabled by default or blank if not.  Subsequent fields on the same
212           line are the description of the operation.
213
214           Before libguestfs 1.17.33 only the first (operation name) field was
215           shown and all operations were enabled by default.
216
217       --mount-options mp:opts[;mp:opts;...]
218           Set the mount options used when libguestfs opens the disk image.
219           Note this has no effect on the guest.  It is used when opening
220           certain guests such as ones using the UFS (BSD) filesystem.
221
222           Use a semicolon-separated list of "mountpoint:options" pairs.  You
223           may need to quote this list to protect it from the shell.
224
225           For example:
226
227            --mount-options "/:noatime"
228
229           will mount the root directory with "notime".  This example:
230
231            --mount-options "/:noatime;/var:rw,nodiratime"
232
233           will do the same, plus mount /var with "rw,nodiratime".
234
235       -q
236       --quiet
237           Don’t print log messages.
238
239           To enable detailed logging of individual file operations, use -x.
240
241       --network
242       --no-network
243           Enable or disable network access from the guest during the
244           installation.
245
246           In virt-sysprep, the network is disabled by default.  You must use
247           --network to enable it, in order that options such as --install or
248           --update will work.
249
250           virt-builder(1) has more information about the security advantages
251           of disabling the network.
252
253       -v
254       --verbose
255           Enable verbose messages for debugging.
256
257       -V
258       --version
259           Display version number and exit.
260
261       --wrap
262           Wrap error, warning, and informative messages.  This is the default
263           when the output is a tty.  If the output of the program is
264           redirected to a file, wrapping is disabled unless you use this
265           option.
266
267       -x  Enable tracing of libguestfs API calls.
268
269       --append-line FILE:LINE (see "customize" below)
270           Append a single line of text to the "FILE".  If the file does not
271           already end with a newline, then one is added before the appended
272           line.  Also a newline is added to the end of the "LINE" string
273           automatically.
274
275           For example (assuming ordinary shell quoting) this command:
276
277            --append-line '/etc/hosts:10.0.0.1 foo'
278
279           will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
280           the latter only if the existing file does not already end with a
281           newline.
282
283           "⏎" represents a newline character, which is guessed by looking at
284           the existing content of the file, so this command does the right
285           thing for files using Unix or Windows line endings.  It also works
286           for empty or non-existent files.
287
288           To insert several lines, use the same option several times:
289
290            --append-line '/etc/hosts:10.0.0.1 foo'
291            --append-line '/etc/hosts:10.0.0.2 bar'
292
293           To insert a blank line before the appended line, do:
294
295            --append-line '/etc/hosts:'
296            --append-line '/etc/hosts:10.0.0.1 foo'
297
298       --chmod PERMISSIONS:FILE (see "customize" below)
299           Change the permissions of "FILE" to "PERMISSIONS".
300
301           Note: "PERMISSIONS" by default would be decimal, unless you prefix
302           it with 0 to get octal, ie. use 0700 not 700.
303
304       --commands-from-file FILENAME (see "customize" below)
305           Read the customize commands from a file, one (and its arguments)
306           each line.
307
308           Each line contains a single customization command and its
309           arguments, for example:
310
311            delete /some/file
312            install some-package
313            password some-user:password:its-new-password
314
315           Empty lines are ignored, and lines starting with "#" are comments
316           and are ignored as well.  Furthermore, arguments can be spread
317           across multiple lines, by adding a "\" (continuation character) at
318           the of a line, for example
319
320            edit /some/file:\
321              s/^OPT=.*/OPT=ok/
322
323           The commands are handled in the same order as they are in the file,
324           as if they were specified as --delete /some/file on the command
325           line.
326
327       --copy SOURCE:DEST (see "customize" below)
328           Copy files or directories recursively inside the guest.
329
330           Wildcards cannot be used.
331
332       --copy-in LOCALPATH:REMOTEDIR (see "customize" below)
333           Copy local files or directories recursively into the disk image,
334           placing them in the directory "REMOTEDIR" (which must exist).
335
336           Wildcards cannot be used.
337
338       --delete PATH (see "customize" below)
339           Delete a file from the guest.  Or delete a directory (and all its
340           contents, recursively).
341
342           You can use shell glob characters in the specified path.  Be
343           careful to escape glob characters from the host shell, if that is
344           required.  For example:
345
346            virt-customize --delete '/var/log/*.log'.
347
348           See also: --upload, --scrub.
349
350       --edit FILE:EXPR (see "customize" below)
351           Edit "FILE" using the Perl expression "EXPR".
352
353           Be careful to properly quote the expression to prevent it from
354           being altered by the shell.
355
356           Note that this option is only available when Perl 5 is installed.
357
358           See "NON-INTERACTIVE EDITING" in virt-edit(1).
359
360       --firstboot SCRIPT (see "customize" below)
361           Install "SCRIPT" inside the guest, so that when the guest first
362           boots up, the script runs (as root, late in the boot process).
363
364           The script is automatically chmod +x after installation in the
365           guest.
366
367           The alternative version --firstboot-command is the same, but it
368           conveniently wraps the command up in a single line script for you.
369
370           You can have multiple --firstboot options.  They run in the same
371           order that they appear on the command line.
372
373           Please take a look at "FIRST BOOT SCRIPTS" in virt-builder(1) for
374           more information and caveats about the first boot scripts.
375
376           See also --run.
377
378       --firstboot-command 'CMD+ARGS' (see "customize" below)
379           Run command (and arguments) inside the guest when the guest first
380           boots up (as root, late in the boot process).
381
382           You can have multiple --firstboot options.  They run in the same
383           order that they appear on the command line.
384
385           Please take a look at "FIRST BOOT SCRIPTS" in virt-builder(1) for
386           more information and caveats about the first boot scripts.
387
388           See also --run.
389
390       --firstboot-install PKG,PKG.. (see "customize" below)
391           Install the named packages (a comma-separated list).  These are
392           installed when the guest first boots using the guest’s package
393           manager (eg. apt, yum, etc.) and the guest’s network connection.
394
395           For an overview on the different ways to install packages, see
396           "INSTALLING PACKAGES" in virt-builder(1).
397
398       --hostname HOSTNAME (see "customize" below)
399           Set the hostname of the guest to "HOSTNAME".  You can use a dotted
400           hostname.domainname (FQDN) if you want.
401
402       --install PKG,PKG.. (see "customize" below)
403           Install the named packages (a comma-separated list).  These are
404           installed during the image build using the guest’s package manager
405           (eg. apt, yum, etc.) and the host’s network connection.
406
407           For an overview on the different ways to install packages, see
408           "INSTALLING PACKAGES" in virt-builder(1).
409
410           See also --update, --uninstall.
411
412       --keep-user-accounts USERS (see "user-account" below)
413           The user accounts to be kept in the guest.  The value of this
414           option is a list of user names separated by comma, where specifying
415           an user means it is going to be kept.  For example:
416
417            --keep-user-accounts mary
418
419           would keep the user account "mary".
420
421           This option can be specified multiple times.
422
423       --link TARGET:LINK[:LINK..] (see "customize" below)
424           Create symbolic link(s) in the guest, starting at "LINK" and
425           pointing at "TARGET".
426
427       --mkdir DIR (see "customize" below)
428           Create a directory in the guest.
429
430           This uses "mkdir -p" so any intermediate directories are created,
431           and it also works if the directory already exists.
432
433       --move SOURCE:DEST (see "customize" below)
434           Move files or directories inside the guest.
435
436           Wildcards cannot be used.
437
438       --no-logfile (see "customize" below)
439           Scrub "builder.log" (log file from build commands) from the image
440           after building is complete.  If you don't want to reveal precisely
441           how the image was built, use this option.
442
443           See also: "LOG FILE".
444
445       --password USER:SELECTOR (see "customize" below)
446           Set the password for "USER".  (Note this option does not create the
447           user account).
448
449           See "USERS AND PASSWORDS" in virt-builder(1) for the format of the
450           "SELECTOR" field, and also how to set up user accounts.
451
452       --password-crypto md5|sha256|sha512 (see "customize" below)
453           When the virt tools change or set a password in the guest, this
454           option sets the password encryption of that password to "md5",
455           "sha256" or "sha512".
456
457           "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
458           the guest).
459
460           "md5" will work with relatively old Linux guests (eg. RHEL 3), but
461           is not secure against modern attacks.
462
463           The default is "sha512" unless libguestfs detects an old guest that
464           didn't have support for SHA-512, in which case it will use "md5".
465           You can override libguestfs by specifying this option.
466
467           Note this does not change the default password encryption used by
468           the guest when you create new user accounts inside the guest.  If
469           you want to do that, then you should use the --edit option to
470           modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
471           "/etc/pam.d/common-password" (Debian, Ubuntu).
472
473       --remove-user-accounts USERS (see "user-account" below)
474           The user accounts to be removed from the guest.  The value of this
475           option is a list of user names separated by comma, where specifying
476           an user means it is going to be removed.  For example:
477
478            --remove-user-accounts bob,eve
479
480           would only remove the user accounts "bob" and "eve".
481
482           This option can be specified multiple times.
483
484       --root-password SELECTOR (see "customize" below)
485           Set the root password.
486
487           See "USERS AND PASSWORDS" in virt-builder(1) for the format of the
488           "SELECTOR" field, and also how to set up user accounts.
489
490           Note: In virt-builder, if you don't set --root-password then the
491           guest is given a random root password.
492
493       --run SCRIPT (see "customize" below)
494           Run the shell script (or any program) called "SCRIPT" on the disk
495           image.  The script runs virtualized inside a small appliance,
496           chrooted into the guest filesystem.
497
498           The script is automatically chmod +x.
499
500           If libguestfs supports it then a limited network connection is
501           available but it only allows outgoing network connections.  You can
502           also attach data disks (eg. ISO files) as another way to provide
503           data (eg. software packages) to the script without needing a
504           network connection (--attach).  You can also upload data files
505           (--upload).
506
507           You can have multiple --run options.  They run in the same order
508           that they appear on the command line.
509
510           See also: --firstboot, --attach, --upload.
511
512       --run-command 'CMD+ARGS' (see "customize" below)
513           Run the command and arguments on the disk image.  The command runs
514           virtualized inside a small appliance, chrooted into the guest
515           filesystem.
516
517           If libguestfs supports it then a limited network connection is
518           available but it only allows outgoing network connections.  You can
519           also attach data disks (eg. ISO files) as another way to provide
520           data (eg. software packages) to the script without needing a
521           network connection (--attach).  You can also upload data files
522           (--upload).
523
524           You can have multiple --run-command options.  They run in the same
525           order that they appear on the command line.
526
527           See also: --firstboot, --attach, --upload.
528
529       --script SCRIPT (see "script" below)
530           Run the named "SCRIPT" (a shell script or program) against the
531           guest.  The script can be any program on the host.  The script’s
532           current directory will be the guest’s root directory.
533
534           Note: If the script is not on the $PATH, then you must give the
535           full absolute path to the script.
536
537       --scriptdir SCRIPTDIR (see "script" below)
538           The mount point (an empty directory on the host) used when the
539           "script" operation is enabled and one or more scripts are specified
540           using --script parameter(s).
541
542           Note: "SCRIPTDIR" must be an absolute path.
543
544           If --scriptdir is not specified then a temporary mountpoint will be
545           created.
546
547       --scrub FILE (see "customize" below)
548           Scrub a file from the guest.  This is like --delete except that:
549
550           •   It scrubs the data so a guest could not recover it.
551
552           •   It cannot delete directories, only regular files.
553
554       --selinux-relabel (see "customize" below)
555           Relabel files in the guest so that they have the correct SELinux
556           label.
557
558           This will attempt to relabel files immediately, but if the
559           operation fails this will instead touch /.autorelabel on the image
560           to schedule a relabel operation for the next time the image boots.
561
562           You should only use this option for guests which support SELinux.
563
564       --sm-attach SELECTOR (see "customize" below)
565           Attach to a pool using "subscription-manager".
566
567           See "SUBSCRIPTION-MANAGER" in virt-builder(1) for the format of the
568           "SELECTOR" field.
569
570       --sm-credentials SELECTOR (see "customize" below)
571           Set the credentials for "subscription-manager".
572
573           See "SUBSCRIPTION-MANAGER" in virt-builder(1) for the format of the
574           "SELECTOR" field.
575
576       --sm-register (see "customize" below)
577           Register the guest using "subscription-manager".
578
579           This requires credentials being set using --sm-credentials.
580
581       --sm-remove (see "customize" below)
582           Remove all the subscriptions from the guest using
583           "subscription-manager".
584
585       --sm-unregister (see "customize" below)
586           Unregister the guest using "subscription-manager".
587
588       --ssh-inject USER[:SELECTOR] (see "customize" below)
589           Inject an ssh key so the given "USER" will be able to log in over
590           ssh without supplying a password.  The "USER" must exist already in
591           the guest.
592
593           See "SSH KEYS" in virt-builder(1) for the format of the "SELECTOR"
594           field.
595
596           You can have multiple --ssh-inject options, for different users and
597           also for more keys for each user.
598
599       --timezone TIMEZONE (see "customize" below)
600           Set the default timezone of the guest to "TIMEZONE".  Use a
601           location string like "Europe/London"
602
603       --touch FILE (see "customize" below)
604           This command performs a touch(1)-like operation on "FILE".
605
606       --truncate FILE (see "customize" below)
607           This command truncates "FILE" to a zero-length file. The file must
608           exist already.
609
610       --truncate-recursive PATH (see "customize" below)
611           This command recursively truncates all files under "PATH" to zero-
612           length.
613
614       --uninstall PKG,PKG.. (see "customize" below)
615           Uninstall the named packages (a comma-separated list).  These are
616           removed during the image build using the guest’s package manager
617           (eg. apt, yum, etc.).  Dependent packages may also need to be
618           uninstalled to satisfy the request.
619
620           See also --install, --update.
621
622       --update (see "customize" below)
623           Do the equivalent of "yum update", "apt-get upgrade", or whatever
624           command is required to update the packages already installed in the
625           template to their latest versions.
626
627           See also --install, --uninstall.
628
629       --upload FILE:DEST (see "customize" below)
630           Upload local file "FILE" to destination "DEST" in the disk image.
631           File owner and permissions from the original are preserved, so you
632           should set them to what you want them to be in the disk image.
633
634           "DEST" could be the final filename.  This can be used to rename the
635           file on upload.
636
637           If "DEST" is a directory name (which must already exist in the
638           guest) then the file is uploaded into that directory, and it keeps
639           the same name as on the local filesystem.
640
641           See also: --mkdir, --delete, --scrub.
642
643       --write FILE:CONTENT (see "customize" below)
644           Write "CONTENT" to "FILE".
645

OPERATIONS

647       If the --enable/--operations option is not given, then most sysprep
648       operations are enabled.
649
650       Use "virt-sysprep --list-operations" to list all operations for your
651       virt-sysprep binary.  The ones which are enabled by default are marked
652       with a "*" character.  Regardless of the --enable/--operations options,
653       sysprep operations are skipped for some guest types.
654
655       Operations can be individually enabled using the --enable/--operations
656       options.  Use a comma-separated list, for example:
657
658        virt-sysprep --operations ssh-hostkeys,udev-persistent-net [etc..]
659
660       Future versions of virt-sysprep may add more operations.  If you are
661       using virt-sysprep and want predictable behaviour, specify only the
662       operations that you want to have enabled.
663
664       "*" = enabled by default when no --enable/--operations option is given.
665
666   abrt-data *
667       Remove the crash data generated by ABRT.
668
669       Remove the automatically generated ABRT crash data in
670       "/var/spool/abrt/".
671
672   backup-files *
673       Remove editor backup files from the guest.
674
675       The following files are removed from anywhere in the guest filesystem:
676
677       ·   *.bak
678
679       ·   *~
680
681       On Linux and Unix operating systems, only the following filesystems
682       will be examined:
683
684       ·   /etc
685
686       ·   /root
687
688       ·   /srv
689
690       ·   /tmp
691
692       ·   /var
693
694   bash-history *
695       Remove the bash history in the guest.
696
697       Remove the bash history of user "root" and any other users who have a
698       ".bash_history" file in their home directory.
699
700       Notes on bash-history
701
702       Currently this only looks in "/root" and "/home/*" for home
703       directories, so users with home directories in other locations won't
704       have the bash history removed.
705
706   blkid-tab *
707       Remove blkid tab in the guest.
708
709   ca-certificates
710       Remove CA certificates in the guest.
711
712       In case any certificate is removed, the system CA store is updated.
713
714   crash-data *
715       Remove the crash data generated by kexec-tools.
716
717       Remove the automatically generated kdump kernel crash data.
718
719   cron-spool *
720       Remove user at-jobs and cron-jobs.
721
722   customize *
723       Customize the guest.
724
725       Customize the guest by providing virt-customize(1) options for
726       installing packages, editing files and so on.
727
728   dhcp-client-state *
729       Remove DHCP client leases.
730
731   dhcp-server-state *
732       Remove DHCP server leases.
733
734   dovecot-data *
735       Remove Dovecot (mail server) data.
736
737   firewall-rules
738       Remove the firewall rules.
739
740       This removes custom firewall rules by removing
741       "/etc/sysconfig/iptables" or custom firewalld configuration in
742       "/etc/firewalld/*/*".
743
744       Note this is not enabled by default since it may expose guests to
745       exploits.  Use with care.
746
747   flag-reconfiguration
748       Flag the system for reconfiguration.
749
750       For Linux guests, this touches "/.unconfigured", which causes the first
751       boot to interactively query the user for settings such as the root
752       password and timezone.
753
754   fs-uuids
755       Change filesystem UUIDs.
756
757       On guests and filesystem types where this is supported, new random
758       UUIDs are generated and assigned to filesystems.
759
760       Notes on fs-uuids
761
762       The fs-uuids operation is disabled by default because it does not yet
763       find and update all the places in the guest that use the UUIDs.  For
764       example "/etc/fstab" or the bootloader.  Enabling this operation is
765       more likely than not to make your guest unbootable.
766
767       See: https://bugzilla.redhat.com/show_bug.cgi?id=991641
768
769   ipa-client *
770       Remove the IPA files.
771
772       Remove all the files related to an IPA (Identity, Policy, Audit)
773       system.  This effectively unenrolls the guest from an IPA server
774       without interacting with it.
775
776       This operation does not run "ipa-client".
777
778   kerberos-data
779       Remove Kerberos data in the guest.
780
781   kerberos-hostkeytab *
782       Remove the Kerberos host keytab file in the guest.
783
784   logfiles *
785       Remove many log files from the guest.
786
787       On Linux the following files are removed:
788
789       ·   /etc/Pegasus/*.cnf
790
791       ·   /etc/Pegasus/*.crt
792
793       ·   /etc/Pegasus/*.csr
794
795       ·   /etc/Pegasus/*.pem
796
797       ·   /etc/Pegasus/*.srl
798
799       ·   /root/anaconda-ks.cfg
800
801       ·   /root/anaconda-post.log
802
803       ·   /root/initial-setup-ks.cfg
804
805       ·   /root/install.log
806
807       ·   /root/install.log.syslog
808
809       ·   /root/original-ks.cfg
810
811       ·   /var/cache/fontconfig/*
812
813       ·   /var/cache/gdm/*
814
815       ·   /var/cache/man/*
816
817       ·   /var/lib/AccountService/users/*
818
819       ·   /var/lib/fprint/*
820
821       ·   /var/lib/logrotate.status
822
823       ·   /var/log/*.log*
824
825       ·   /var/log/BackupPC/LOG
826
827       ·   /var/log/ConsoleKit/*
828
829       ·   /var/log/anaconda.syslog
830
831       ·   /var/log/anaconda/*
832
833       ·   /var/log/apache2/*_log
834
835       ·   /var/log/apache2/*_log-*
836
837       ·   /var/log/apt/*
838
839       ·   /var/log/aptitude*
840
841       ·   /var/log/audit/*
842
843       ·   /var/log/btmp*
844
845       ·   /var/log/ceph/*.log
846
847       ·   /var/log/chrony/*.log
848
849       ·   /var/log/cron*
850
851       ·   /var/log/cups/*_log*
852
853       ·   /var/log/debug*
854
855       ·   /var/log/dmesg*
856
857       ·   /var/log/exim4/*
858
859       ·   /var/log/faillog*
860
861       ·   /var/log/firewalld*
862
863       ·   /var/log/gdm/*
864
865       ·   /var/log/glusterfs/*glusterd.vol.log
866
867       ·   /var/log/glusterfs/glusterfs.log
868
869       ·   /var/log/grubby*
870
871       ·   /var/log/httpd/*log
872
873       ·   /var/log/installer/*
874
875       ·   /var/log/jetty/jetty-console.log
876
877       ·   /var/log/journal/*
878
879       ·   /var/log/lastlog*
880
881       ·   /var/log/libvirt/libvirtd.log
882
883       ·   /var/log/libvirt/libxl/*.log
884
885       ·   /var/log/libvirt/lxc/*.log
886
887       ·   /var/log/libvirt/qemu/*.log
888
889       ·   /var/log/libvirt/uml/*.log
890
891       ·   /var/log/lightdm/*
892
893       ·   /var/log/mail/*
894
895       ·   /var/log/maillog*
896
897       ·   /var/log/messages*
898
899       ·   /var/log/ntp
900
901       ·   /var/log/ntpstats/*
902
903       ·   /var/log/ppp/connect-errors
904
905       ·   /var/log/rhsm/*
906
907       ·   /var/log/sa/*
908
909       ·   /var/log/secure*
910
911       ·   /var/log/setroubleshoot/*.log
912
913       ·   /var/log/spooler*
914
915       ·   /var/log/squid/*.log
916
917       ·   /var/log/syslog*
918
919       ·   /var/log/tallylog*
920
921       ·   /var/log/tuned/tuned.log
922
923       ·   /var/log/wtmp*
924
925       ·   /var/log/xferlog*
926
927       ·   /var/named/data/named.run
928
929   lvm-uuids *
930       Change LVM2 PV and VG UUIDs.
931
932       On Linux guests that have LVM2 physical volumes (PVs) or volume groups
933       (VGs), new random UUIDs are generated and assigned to those PVs and
934       VGs.
935
936   machine-id *
937       Remove the local machine ID.
938
939       The machine ID is usually generated from a random source during system
940       installation and stays constant for all subsequent boots.  Optionally,
941       for stateless systems it is generated during runtime at boot if it is
942       found to be empty.
943
944   mail-spool *
945       Remove email from the local mail spool directory.
946
947   net-hostname *
948       Remove HOSTNAME and DHCP_HOSTNAME in network interface configuration.
949
950       For Fedora and Red Hat Enterprise Linux, this is removed from "ifcfg-*"
951       files.
952
953   net-hwaddr *
954       Remove HWADDR (hard-coded MAC address) configuration.
955
956       For Fedora and Red Hat Enterprise Linux, this is removed from "ifcfg-*"
957       files.
958
959   net-nmconn *
960       Remove system-local NetworkManager connection profiles (keyfiles).
961
962       On Fedora and Red Hat Enterprise Linux, remove the
963       "/etc/NetworkManager/system-connections/*.nmconnection" files.
964
965   pacct-log *
966       Remove the process accounting log files.
967
968       The system wide process accounting will store to the pacct log files if
969       the process accounting is on.
970
971   package-manager-cache *
972       Remove package manager cache.
973
974   pam-data *
975       Remove the PAM data in the guest.
976
977   passwd-backups *
978       Remove /etc/passwd- and similar backup files.
979
980       On Linux the following files are removed:
981
982       ·   /etc/group-
983
984       ·   /etc/gshadow-
985
986       ·   /etc/passwd-
987
988       ·   /etc/shadow-
989
990       ·   /etc/subgid-
991
992       ·   /etc/subuid-
993
994   puppet-data-log *
995       Remove the data and log files of puppet.
996
997   rh-subscription-manager *
998       Remove the RH subscription manager files.
999
1000   rhn-systemid *
1001       Remove the RHN system ID.
1002
1003   rpm-db *
1004       Remove host-specific RPM database files.
1005
1006       Remove host-specific RPM database files and locks.  RPM will recreate
1007       these files automatically if needed.
1008
1009   samba-db-log *
1010       Remove the database and log files of Samba.
1011
1012   script *
1013       Run arbitrary scripts against the guest.
1014
1015       The "script" module lets you run arbitrary shell scripts or programs
1016       against the guest.
1017
1018       Note this feature requires FUSE support.  You may have to enable this
1019       in your host, for example by adding the current user to the "fuse"
1020       group, or by loading a kernel module.
1021
1022       Use one or more --script parameters to specify scripts or programs that
1023       will be run against the guest.
1024
1025       The script or program is run with its current directory being the
1026       guest’s root directory, so relative paths should be used.  For example:
1027       "rm etc/resolv.conf" in the script would remove a Linux guest’s DNS
1028       configuration file, but "rm /etc/resolv.conf" would (try to) remove the
1029       host’s file.
1030
1031       Normally a temporary mount point for the guest is used, but you can
1032       choose a specific one by using the --scriptdir parameter.
1033
1034       Note: This is different from --firstboot scripts (which run in the
1035       context of the guest when it is booting first time).  --script scripts
1036       run on the host, not in the guest.
1037
1038   smolt-uuid *
1039       Remove the Smolt hardware UUID.
1040
1041   ssh-hostkeys *
1042       Remove the SSH host keys in the guest.
1043
1044       The SSH host keys are regenerated (differently) next time the guest is
1045       booted.
1046
1047       If, after cloning, the guest gets the same IP address, ssh will give
1048       you a stark warning about the host key changing:
1049
1050        @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
1051        @    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
1052        @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
1053        IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
1054
1055   ssh-userdir *
1056       Remove ".ssh" directories in the guest.
1057
1058       Remove the ".ssh" directory of user "root" and any other users who have
1059       a ".ssh" directory in their home directory.
1060
1061       Notes on ssh-userdir
1062
1063       Currently this only looks in "/root" and "/home/*" for home
1064       directories, so users with home directories in other locations won't
1065       have the ssh files removed.
1066
1067   sssd-db-log *
1068       Remove the database and log files of sssd.
1069
1070   tmp-files *
1071       Remove temporary files.
1072
1073       This removes temporary files under "/tmp" and "/var/tmp".
1074
1075   udev-persistent-net *
1076       Remove udev persistent net rules.
1077
1078       Remove udev persistent net rules which map the guest’s existing MAC
1079       address to a fixed ethernet device (eg. eth0).
1080
1081       After a guest is cloned, the MAC address usually changes.  Since the
1082       old MAC address occupies the old name (eg. eth0), this means the fresh
1083       MAC address is assigned to a new name (eg. eth1) and this is usually
1084       undesirable.  Erasing the udev persistent net rules avoids this.
1085
1086   user-account
1087       Remove the user accounts in the guest.
1088
1089       By default remove all the user accounts and their home directories.
1090       The "root" account is not removed.
1091
1092       See the --remove-user-accounts parameter for a way to specify how to
1093       remove only some users, or to not remove some others.
1094
1095   utmp *
1096       Remove the utmp file.
1097
1098       This file records who is currently logged in on a machine.  In modern
1099       Linux distros it is stored in a ramdisk and hence not part of the
1100       virtual machine’s disk, but it was stored on disk in older distros.
1101
1102   yum-uuid *
1103       Remove the yum UUID.
1104
1105       Yum creates a fresh UUID the next time it runs when it notices that the
1106       original UUID has been erased.
1107

COPYING AND CLONING

1109       Virt-sysprep can be used as part of a process of cloning guests, or to
1110       prepare a template from which guests can be cloned.  There are many
1111       different ways to achieve this using the virt tools, and this section
1112       is just an introduction.
1113
1114       A virtual machine (when switched off) consists of two parts:
1115
1116       configuration
1117           The configuration or description of the guest.  eg. The libvirt XML
1118           (see "virsh dumpxml"), the running configuration of the guest, or
1119           another external format like OVF.
1120
1121           Some configuration items that might need to be changed:
1122
1123           •   name
1124
1125           •   UUID
1126
1127           •   path to block device(s)
1128
1129           •   network card MAC address
1130
1131       block device(s)
1132           One or more hard disk images, themselves containing files,
1133           directories, applications, kernels, configuration, etc.
1134
1135           Some things inside the block devices that might need to be changed:
1136
1137           •   hostname and other net configuration
1138
1139           •   UUID
1140
1141           •   SSH host keys
1142
1143           •   Windows unique security ID (SID)
1144
1145           •   Puppet registration
1146
1147   COPYING THE BLOCK DEVICE
1148       Starting with an original guest, you probably wish to copy the guest
1149       block device and its configuration to make a template.  Then once you
1150       are happy with the template, you will want to make many clones from it.
1151
1152                               virt-sysprep
1153                                    |
1154                                    v
1155        original guest --------> template ---------->
1156                                             \------> cloned
1157                                              \-----> guests
1158                                               \---->
1159
1160       You can, of course, just copy the block device on the host using cp(1)
1161       or dd(1).
1162
1163                          dd                 dd
1164        original guest --------> template ---------->
1165                                             \------> cloned
1166                                              \-----> guests
1167                                               \---->
1168
1169       There are some smarter (and faster) ways too:
1170
1171                                 snapshot
1172                       template ---------->
1173                                   \------> cloned
1174                                    \-----> guests
1175                                     \---->
1176
1177       You may want to run virt-sysprep twice, once to reset the guest (to
1178       make a template) and a second time to customize the guest for a
1179       specific user:
1180
1181                           virt-sysprep        virt-sysprep
1182                             (reset)      (add user, keys, logos)
1183                                |                   |
1184                        dd      v          dd       v
1185        original guest ----> template ---------> copied ------> custom
1186                                                 template       guest
1187
1188       •   Create a snapshot using qemu-img:
1189
1190            qemu-img create -f qcow2 -o backing_file=original snapshot.qcow
1191
1192           The advantage is that you don’t need to copy the original (very
1193           fast) and only changes are stored (less storage required).
1194
1195           Note that writing to the backing file once you have created guests
1196           on top of it is not possible: you will corrupt the guests.
1197
1198       •   Create a snapshot using "lvcreate --snapshot".
1199
1200       •   Other ways to create snapshots include using filesystems-level
1201           tools (for filesystems such as btrfs).
1202
1203           Most Network Attached Storage (NAS) devices can also create cheap
1204           snapshots from files or LUNs.
1205
1206       •   Get your NAS to duplicate the LUN.  Most NAS devices can also
1207           duplicate LUNs very cheaply (they copy them on-demand in the
1208           background).
1209
1210       •   Prepare your template using virt-sparsify(1).  See below.
1211
1212   VIRT-CLONE
1213       A separate tool, virt-clone(1), can be used to duplicate the block
1214       device and/or modify the external libvirt configuration of a guest.  It
1215       will reset the name, UUID and MAC address of the guest in the libvirt
1216       XML.
1217
1218       virt-clone(1) does not use libguestfs and cannot look inside the disk
1219       image.  This was the original motivation to write virt-sysprep.
1220
1221   SPARSIFY
1222                     virt-sparsify
1223        original guest --------> template
1224
1225       virt-sparsify(1) can be used to make the cloning template smaller,
1226       making it easier to compress and/or faster to copy.
1227
1228       Notice that since virt-sparsify also copies the image, you can use it
1229       to make the initial copy (instead of "dd").
1230
1231   RESIZE
1232                                virt-resize
1233                       template ---------->
1234                                   \------> cloned
1235                                    \-----> guests
1236                                     \---->
1237
1238       If you want to give people cloned guests, but let them pick the size of
1239       the guest themselves (eg. depending on how much they are prepared to
1240       pay for disk space), then instead of copying the template, you can run
1241       virt-resize(1).  Virt-resize performs a copy and resize, and thus is
1242       ideal for cloning guests from a template.
1243

FIRSTBOOT VS SCRIPT

1245       The two options --firstboot and --script both supply shell scripts that
1246       are run against the guest.  However these two options are significantly
1247       different.
1248
1249       --firstboot script uploads the file "script" into the guest and
1250       arranges that it will run, in the guest, when the guest is next booted.
1251       (The script will only run once, at the "first boot").
1252
1253       --script script runs the shell "script" on the host, with its current
1254       directory inside the guest filesystem.
1255
1256       If you needed, for example, to "yum install" new packages, then you
1257       must not use --script for this, since that would (a) run the "yum"
1258       command on the host and (b) wouldn't have access to the same resources
1259       (repositories, keys, etc.) as the guest.  Any command that needs to run
1260       on the guest must be run via --firstboot.
1261
1262       On the other hand if you need to make adjustments to the guest
1263       filesystem (eg. copying in files), then --script is ideal since (a) it
1264       has access to the host filesystem and (b) you will get immediate
1265       feedback on errors.
1266
1267       Either or both options can be used multiple times on the command line.
1268

SECURITY

1270       Although virt-sysprep removes some sensitive information from the
1271       guest, it does not pretend to remove all of it.  You should examine the
1272       "OPERATIONS" above and the guest afterwards.
1273
1274       Sensitive files are simply removed.  The data they contained may still
1275       exist on the disk, easily recovered with a hex editor or undelete tool.
1276       The --scrub option can be used to scrub files instead of just deleting
1277       them.  virt-sparsify(1) is another way to remove this content.  See
1278       also the scrub(1) command to get rid of deleted content in directory
1279       entries and inodes.
1280
1281   RANDOM SEED
1282       (This section applies to Linux guests only)
1283
1284       For supported guests, virt-sysprep writes a few bytes of randomness
1285       from the host into the guest’s random seed file.
1286
1287       If this is just done once and the guest is cloned from the same
1288       template, then each guest will start with the same entropy, and things
1289       like SSH host keys and TCP sequence numbers may be predictable.
1290
1291       Therefore you should arrange to add more randomness after cloning from
1292       a template too, which can be done by enabling just the customize
1293       module:
1294
1295        cp template.img newguest.img
1296        virt-sysprep --enable customize -a newguest.img
1297

SELINUX

1299       For guests which make use of SELinux, special handling for them might
1300       be needed when using operations which create new files or alter
1301       existing ones.
1302
1303       For further details, see "SELINUX" in virt-builder(1).
1304

WINDOWS 8

1306       Windows 8 "fast startup" can prevent virt-sysprep from working.  See
1307       "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in guestfs(3).
1308

EXIT STATUS

1310       This program returns 0 on success, or 1 if there was an error.
1311

ENVIRONMENT VARIABLES

1313       "VIRT_TOOLS_DATA_DIR"
1314           This can point to the directory containing data files used for
1315           Windows firstboot installation.
1316
1317           Normally you do not need to set this.  If not set, a compiled-in
1318           default will be used (something like /usr/share/virt-tools).
1319
1320           This directory may contain the following files:
1321
1322           rhsrvany.exe
1323               This is the RHSrvAny Windows binary, used to install a
1324               "firstboot" script in Windows guests.  It is required if you
1325               intend to use the --firstboot or --firstboot-command options
1326               with Windows guests.
1327
1328               See also: "https://github.com/rwmjones/rhsrvany"
1329
1330           pvvxsvc.exe
1331               This is a Windows binary shipped with SUSE VMDP, used to
1332               install a "firstboot" script in Windows guests.  It is required
1333               if you intend to use the --firstboot or --firstboot-command
1334               options with Windows guests.
1335
1336       For other environment variables, see "ENVIRONMENT VARIABLES" in
1337       guestfs(3).
1338

SEE ALSO

1340       guestfs(3), guestfish(1), virt-builder(1), virt-clone(1),
1341       virt-customize(1), virt-rescue(1), virt-resize(1), virt-sparsify(1),
1342       virsh(1), lvcreate(8), qemu-img(1), scrub(1), http://libguestfs.org/,
1343       http://libvirt.org/.
1344

AUTHORS

1346       Richard W.M. Jones http://people.redhat.com/~rjones/
1347
1348       Wanlong Gao, Fujitsu Ltd.
1349
1351       Copyright (C) 2011-2020 Red Hat Inc.
1352
1353       Copyright (C) 2012 Fujitsu Ltd.
1354

LICENSE

1356       This program is free software; you can redistribute it and/or modify it
1357       under the terms of the GNU General Public License as published by the
1358       Free Software Foundation; either version 2 of the License, or (at your
1359       option) any later version.
1360
1361       This program is distributed in the hope that it will be useful, but
1362       WITHOUT ANY WARRANTY; without even the implied warranty of
1363       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1364       General Public License for more details.
1365
1366       You should have received a copy of the GNU General Public License along
1367       with this program; if not, write to the Free Software Foundation, Inc.,
1368       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
1369

BUGS

1371       To get a list of bugs against libguestfs, use this link:
1372       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
1373
1374       To report a new bug against libguestfs, use this link:
1375       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1376
1377       When reporting a bug, please supply:
1378
1379       •   The version of libguestfs.
1380
1381       •   Where you got libguestfs (eg. which Linux distro, compiled from
1382           source, etc)
1383
1384       •   Describe the bug accurately and give a way to reproduce it.
1385
1386       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
1387           into the bug report.
1388
1389
1390
1391guestfs-tools-1.48.2              2022-05-26                   virt-sysprep(1)
Impressum