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       --list-operations
194           List the operations supported by the virt-sysprep program.
195
196           These are listed one per line, with one or more single-space-
197           separated fields, eg:
198
199            $ virt-sysprep --list-operations
200            bash-history * Remove the bash history in the guest
201            cron-spool * Remove user at-jobs and cron-jobs
202            dhcp-client-state * Remove DHCP client leases
203            dhcp-server-state * Remove DHCP server leases
204            [etc]
205
206           The first field is the operation name, which can be supplied to
207           --enable.  The second field is a "*" character if the operation is
208           enabled by default or blank if not.  Subsequent fields on the same
209           line are the description of the operation.
210
211           Before libguestfs 1.17.33 only the first (operation name) field was
212           shown and all operations were enabled by default.
213
214       --mount-options mp:opts[;mp:opts;...]
215           Set the mount options used when libguestfs opens the disk image.
216           Note this has no effect on the guest.  It is used when opening
217           certain guests such as ones using the UFS (BSD) filesystem.
218
219           Use a semicolon-separated list of "mountpoint:options" pairs.  You
220           may need to quote this list to protect it from the shell.
221
222           For example:
223
224            --mount-options "/:noatime"
225
226           will mount the root directory with "notime".  This example:
227
228            --mount-options "/:noatime;/var:rw,nodiratime"
229
230           will do the same, plus mount /var with "rw,nodiratime".
231
232       -q
233       --quiet
234           Don’t print log messages.
235
236           To enable detailed logging of individual file operations, use -x.
237
238       --network
239       --no-network
240           Enable or disable network access from the guest during the
241           installation.
242
243           In virt-sysprep, the network is disabled by default.  You must use
244           --network to enable it, in order that options such as --install or
245           --update will work.
246
247           virt-builder(1) has more information about the security advantages
248           of disabling the network.
249
250       -v
251       --verbose
252           Enable verbose messages for debugging.
253
254       -V
255       --version
256           Display version number and exit.
257
258       -x  Enable tracing of libguestfs API calls.
259
260       --append-line FILE:LINE (see "customize" below)
261           Append a single line of text to the "FILE".  If the file does not
262           already end with a newline, then one is added before the appended
263           line.  Also a newline is added to the end of the "LINE" string
264           automatically.
265
266           For example (assuming ordinary shell quoting) this command:
267
268            --append-line '/etc/hosts:10.0.0.1 foo'
269
270           will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
271           the latter only if the existing file does not already end with a
272           newline.
273
274           "⏎" represents a newline character, which is guessed by looking at
275           the existing content of the file, so this command does the right
276           thing for files using Unix or Windows line endings.  It also works
277           for empty or non-existent files.
278
279           To insert several lines, use the same option several times:
280
281            --append-line '/etc/hosts:10.0.0.1 foo'
282            --append-line '/etc/hosts:10.0.0.2 bar'
283
284           To insert a blank line before the appended line, do:
285
286            --append-line '/etc/hosts:'
287            --append-line '/etc/hosts:10.0.0.1 foo'
288
289       --chmod PERMISSIONS:FILE (see "customize" below)
290           Change the permissions of "FILE" to "PERMISSIONS".
291
292           Note: "PERMISSIONS" by default would be decimal, unless you prefix
293           it with 0 to get octal, ie. use 0700 not 700.
294
295       --commands-from-file FILENAME (see "customize" below)
296           Read the customize commands from a file, one (and its arguments)
297           each line.
298
299           Each line contains a single customization command and its
300           arguments, for example:
301
302            delete /some/file
303            install some-package
304            password some-user:password:its-new-password
305
306           Empty lines are ignored, and lines starting with "#" are comments
307           and are ignored as well.  Furthermore, arguments can be spread
308           across multiple lines, by adding a "\" (continuation character) at
309           the of a line, for example
310
311            edit /some/file:\
312              s/^OPT=.*/OPT=ok/
313
314           The commands are handled in the same order as they are in the file,
315           as if they were specified as --delete /some/file on the command
316           line.
317
318       --copy SOURCE:DEST (see "customize" below)
319           Copy files or directories recursively inside the guest.
320
321           Wildcards cannot be used.
322
323       --copy-in LOCALPATH:REMOTEDIR (see "customize" below)
324           Copy local files or directories recursively into the disk image,
325           placing them in the directory "REMOTEDIR" (which must exist).
326
327           Wildcards cannot be used.
328
329       --delete PATH (see "customize" below)
330           Delete a file from the guest.  Or delete a directory (and all its
331           contents, recursively).
332
333           You can use shell glob characters in the specified path.  Be
334           careful to escape glob characters from the host shell, if that is
335           required.  For example:
336
337            virt-customize --delete '/var/log/*.log'.
338
339           See also: --upload, --scrub.
340
341       --edit FILE:EXPR (see "customize" below)
342           Edit "FILE" using the Perl expression "EXPR".
343
344           Be careful to properly quote the expression to prevent it from
345           being altered by the shell.
346
347           Note that this option is only available when Perl 5 is installed.
348
349           See "NON-INTERACTIVE EDITING" in virt-edit(1).
350
351       --firstboot SCRIPT (see "customize" below)
352           Install "SCRIPT" inside the guest, so that when the guest first
353           boots up, the script runs (as root, late in the boot process).
354
355           The script is automatically chmod +x after installation in the
356           guest.
357
358           The alternative version --firstboot-command is the same, but it
359           conveniently wraps the command up in a single line script for you.
360
361           You can have multiple --firstboot options.  They run in the same
362           order that they appear on the command line.
363
364           Please take a look at "FIRST BOOT SCRIPTS" in virt-builder(1) for
365           more information and caveats about the first boot scripts.
366
367           See also --run.
368
369       --firstboot-command 'CMD+ARGS' (see "customize" below)
370           Run command (and arguments) inside the guest when the guest first
371           boots up (as root, late in the boot process).
372
373           You can have multiple --firstboot options.  They run in the same
374           order that they appear on the command line.
375
376           Please take a look at "FIRST BOOT SCRIPTS" in virt-builder(1) for
377           more information and caveats about the first boot scripts.
378
379           See also --run.
380
381       --firstboot-install PKG,PKG.. (see "customize" below)
382           Install the named packages (a comma-separated list).  These are
383           installed when the guest first boots using the guest’s package
384           manager (eg. apt, yum, etc.) and the guest’s network connection.
385
386           For an overview on the different ways to install packages, see
387           "INSTALLING PACKAGES" in virt-builder(1).
388
389       --hostname HOSTNAME (see "customize" below)
390           Set the hostname of the guest to "HOSTNAME".  You can use a dotted
391           hostname.domainname (FQDN) if you want.
392
393       --install PKG,PKG.. (see "customize" below)
394           Install the named packages (a comma-separated list).  These are
395           installed during the image build using the guest’s package manager
396           (eg. apt, yum, etc.) and the host’s network connection.
397
398           For an overview on the different ways to install packages, see
399           "INSTALLING PACKAGES" in virt-builder(1).
400
401           See also --update, --uninstall.
402
403       --keep-user-accounts USERS (see "user-account" below)
404           The user accounts to be kept in the guest.  The value of this
405           option is a list of user names separated by comma, where specifying
406           an user means it is going to be kept.  For example:
407
408            --keep-user-accounts mary
409
410           would keep the user account "mary".
411
412           This option can be specified multiple times.
413
414       --link TARGET:LINK[:LINK..] (see "customize" below)
415           Create symbolic link(s) in the guest, starting at "LINK" and
416           pointing at "TARGET".
417
418       --mkdir DIR (see "customize" below)
419           Create a directory in the guest.
420
421           This uses "mkdir -p" so any intermediate directories are created,
422           and it also works if the directory already exists.
423
424       --move SOURCE:DEST (see "customize" below)
425           Move files or directories inside the guest.
426
427           Wildcards cannot be used.
428
429       --no-logfile (see "customize" below)
430           Scrub "builder.log" (log file from build commands) from the image
431           after building is complete.  If you don't want to reveal precisely
432           how the image was built, use this option.
433
434           See also: "LOG FILE".
435
436       --password USER:SELECTOR (see "customize" below)
437           Set the password for "USER".  (Note this option does not create the
438           user account).
439
440           See "USERS AND PASSWORDS" in virt-builder(1) for the format of the
441           "SELECTOR" field, and also how to set up user accounts.
442
443       --password-crypto md5|sha256|sha512 (see "customize" below)
444           When the virt tools change or set a password in the guest, this
445           option sets the password encryption of that password to "md5",
446           "sha256" or "sha512".
447
448           "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
449           the guest).
450
451           "md5" will work with relatively old Linux guests (eg. RHEL 3), but
452           is not secure against modern attacks.
453
454           The default is "sha512" unless libguestfs detects an old guest that
455           didn't have support for SHA-512, in which case it will use "md5".
456           You can override libguestfs by specifying this option.
457
458           Note this does not change the default password encryption used by
459           the guest when you create new user accounts inside the guest.  If
460           you want to do that, then you should use the --edit option to
461           modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
462           "/etc/pam.d/common-password" (Debian, Ubuntu).
463
464       --remove-user-accounts USERS (see "user-account" below)
465           The user accounts to be removed from the guest.  The value of this
466           option is a list of user names separated by comma, where specifying
467           an user means it is going to be removed.  For example:
468
469            --remove-user-accounts bob,eve
470
471           would only remove the user accounts "bob" and "eve".
472
473           This option can be specified multiple times.
474
475       --root-password SELECTOR (see "customize" below)
476           Set the root password.
477
478           See "USERS AND PASSWORDS" in virt-builder(1) for the format of the
479           "SELECTOR" field, and also how to set up user accounts.
480
481           Note: In virt-builder, if you don't set --root-password then the
482           guest is given a random root password.
483
484       --run SCRIPT (see "customize" below)
485           Run the shell script (or any program) called "SCRIPT" on the disk
486           image.  The script runs virtualized inside a small appliance,
487           chrooted into the guest filesystem.
488
489           The script is automatically chmod +x.
490
491           If libguestfs supports it then a limited network connection is
492           available but it only allows outgoing network connections.  You can
493           also attach data disks (eg. ISO files) as another way to provide
494           data (eg. software packages) to the script without needing a
495           network connection (--attach).  You can also upload data files
496           (--upload).
497
498           You can have multiple --run options.  They run in the same order
499           that they appear on the command line.
500
501           See also: --firstboot, --attach, --upload.
502
503       --run-command 'CMD+ARGS' (see "customize" below)
504           Run the command and arguments on the disk image.  The command runs
505           virtualized inside a small appliance, chrooted into the guest
506           filesystem.
507
508           If libguestfs supports it then a limited network connection is
509           available but it only allows outgoing network connections.  You can
510           also attach data disks (eg. ISO files) as another way to provide
511           data (eg. software packages) to the script without needing a
512           network connection (--attach).  You can also upload data files
513           (--upload).
514
515           You can have multiple --run-command options.  They run in the same
516           order that they appear on the command line.
517
518           See also: --firstboot, --attach, --upload.
519
520       --script SCRIPT (see "script" below)
521           Run the named "SCRIPT" (a shell script or program) against the
522           guest.  The script can be any program on the host.  The script’s
523           current directory will be the guest’s root directory.
524
525           Note: If the script is not on the $PATH, then you must give the
526           full absolute path to the script.
527
528       --scriptdir SCRIPTDIR (see "script" below)
529           The mount point (an empty directory on the host) used when the
530           "script" operation is enabled and one or more scripts are specified
531           using --script parameter(s).
532
533           Note: "SCRIPTDIR" must be an absolute path.
534
535           If --scriptdir is not specified then a temporary mountpoint will be
536           created.
537
538       --scrub FILE (see "customize" below)
539           Scrub a file from the guest.  This is like --delete except that:
540
541           ·   It scrubs the data so a guest could not recover it.
542
543           ·   It cannot delete directories, only regular files.
544
545       --selinux-relabel (see "customize" below)
546           Relabel files in the guest so that they have the correct SELinux
547           label.
548
549           This will attempt to relabel files immediately, but if the
550           operation fails this will instead touch /.autorelabel on the image
551           to schedule a relabel operation for the next time the image boots.
552
553           You should only use this option for guests which support SELinux.
554
555       --sm-attach SELECTOR (see "customize" below)
556           Attach to a pool using "subscription-manager".
557
558           See "SUBSCRIPTION-MANAGER" in virt-builder(1) for the format of the
559           "SELECTOR" field.
560
561       --sm-credentials SELECTOR (see "customize" below)
562           Set the credentials for "subscription-manager".
563
564           See "SUBSCRIPTION-MANAGER" in virt-builder(1) for the format of the
565           "SELECTOR" field.
566
567       --sm-register (see "customize" below)
568           Register the guest using "subscription-manager".
569
570           This requires credentials being set using --sm-credentials.
571
572       --sm-remove (see "customize" below)
573           Remove all the subscriptions from the guest using
574           "subscription-manager".
575
576       --sm-unregister (see "customize" below)
577           Unregister the guest using "subscription-manager".
578
579       --ssh-inject USER[:SELECTOR] (see "customize" below)
580           Inject an ssh key so the given "USER" will be able to log in over
581           ssh without supplying a password.  The "USER" must exist already in
582           the guest.
583
584           See "SSH KEYS" in virt-builder(1) for the format of the "SELECTOR"
585           field.
586
587           You can have multiple --ssh-inject options, for different users and
588           also for more keys for each user.
589
590       --timezone TIMEZONE (see "customize" below)
591           Set the default timezone of the guest to "TIMEZONE".  Use a
592           location string like "Europe/London"
593
594       --touch FILE (see "customize" below)
595           This command performs a touch(1)-like operation on "FILE".
596
597       --truncate FILE (see "customize" below)
598           This command truncates "FILE" to a zero-length file. The file must
599           exist already.
600
601       --truncate-recursive PATH (see "customize" below)
602           This command recursively truncates all files under "PATH" to zero-
603           length.
604
605       --uninstall PKG,PKG.. (see "customize" below)
606           Uninstall the named packages (a comma-separated list).  These are
607           removed during the image build using the guest’s package manager
608           (eg. apt, yum, etc.).  Dependent packages may also need to be
609           uninstalled to satisfy the request.
610
611           See also --install, --update.
612
613       --update (see "customize" below)
614           Do the equivalent of "yum update", "apt-get upgrade", or whatever
615           command is required to update the packages already installed in the
616           template to their latest versions.
617
618           See also --install, --uninstall.
619
620       --upload FILE:DEST (see "customize" below)
621           Upload local file "FILE" to destination "DEST" in the disk image.
622           File owner and permissions from the original are preserved, so you
623           should set them to what you want them to be in the disk image.
624
625           "DEST" could be the final filename.  This can be used to rename the
626           file on upload.
627
628           If "DEST" is a directory name (which must already exist in the
629           guest) then the file is uploaded into that directory, and it keeps
630           the same name as on the local filesystem.
631
632           See also: --mkdir, --delete, --scrub.
633
634       --write FILE:CONTENT (see "customize" below)
635           Write "CONTENT" to "FILE".
636

OPERATIONS

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

COPYING AND CLONING

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

FIRSTBOOT VS SCRIPT

1216       The two options --firstboot and --script both supply shell scripts that
1217       are run against the guest.  However these two options are significantly
1218       different.
1219
1220       --firstboot script uploads the file "script" into the guest and
1221       arranges that it will run, in the guest, when the guest is next booted.
1222       (The script will only run once, at the "first boot").
1223
1224       --script script runs the shell "script" on the host, with its current
1225       directory inside the guest filesystem.
1226
1227       If you needed, for example, to "yum install" new packages, then you
1228       must not use --script for this, since that would (a) run the "yum"
1229       command on the host and (b) wouldn't have access to the same resources
1230       (repositories, keys, etc.) as the guest.  Any command that needs to run
1231       on the guest must be run via --firstboot.
1232
1233       On the other hand if you need to make adjustments to the guest
1234       filesystem (eg. copying in files), then --script is ideal since (a) it
1235       has access to the host filesystem and (b) you will get immediate
1236       feedback on errors.
1237
1238       Either or both options can be used multiple times on the command line.
1239

SECURITY

1241       Although virt-sysprep removes some sensitive information from the
1242       guest, it does not pretend to remove all of it.  You should examine the
1243       "OPERATIONS" above and the guest afterwards.
1244
1245       Sensitive files are simply removed.  The data they contained may still
1246       exist on the disk, easily recovered with a hex editor or undelete tool.
1247       The --scrub option can be used to scrub files instead of just deleting
1248       them.  virt-sparsify(1) is another way to remove this content.  See
1249       also the scrub(1) command to get rid of deleted content in directory
1250       entries and inodes.
1251
1252   RANDOM SEED
1253       (This section applies to Linux guests only)
1254
1255       For supported guests, virt-sysprep writes a few bytes of randomness
1256       from the host into the guest’s random seed file.
1257
1258       If this is just done once and the guest is cloned from the same
1259       template, then each guest will start with the same entropy, and things
1260       like SSH host keys and TCP sequence numbers may be predictable.
1261
1262       Therefore you should arrange to add more randomness after cloning from
1263       a template too, which can be done by enabling just the customize
1264       module:
1265
1266        cp template.img newguest.img
1267        virt-sysprep --enable customize -a newguest.img
1268

SELINUX

1270       For guests which make use of SELinux, special handling for them might
1271       be needed when using operations which create new files or alter
1272       existing ones.
1273
1274       For further details, see "SELINUX" in virt-builder(1).
1275

WINDOWS 8

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

EXIT STATUS

1281       This program returns 0 on success, or 1 if there was an error.
1282

ENVIRONMENT VARIABLES

1284       "VIRT_TOOLS_DATA_DIR"
1285           This can point to the directory containing data files used for
1286           Windows firstboot installation.
1287
1288           Normally you do not need to set this.  If not set, a compiled-in
1289           default will be used (something like /usr/share/virt-tools).
1290
1291           This directory may contain the following files:
1292
1293           rhsrvany.exe
1294               This is the RHSrvAny Windows binary, used to install a
1295               "firstboot" script in Windows guests.  It is required if you
1296               intend to use the --firstboot or --firstboot-command options
1297               with Windows guests.
1298
1299               See also: "https://github.com/rwmjones/rhsrvany"
1300
1301           pvvxsvc.exe
1302               This is a Windows binary shipped with SUSE VMDP, used to
1303               install a "firstboot" script in Windows guests.  It is required
1304               if you intend to use the --firstboot or --firstboot-command
1305               options with Windows guests.
1306
1307       For other environment variables, see "ENVIRONMENT VARIABLES" in
1308       guestfs(3).
1309

SEE ALSO

1311       guestfs(3), guestfish(1), virt-builder(1), virt-clone(1),
1312       virt-customize(1), virt-rescue(1), virt-resize(1), virt-sparsify(1),
1313       virsh(1), lvcreate(8), qemu-img(1), scrub(1), http://libguestfs.org/,
1314       http://libvirt.org/.
1315

AUTHORS

1317       Richard W.M. Jones http://people.redhat.com/~rjones/
1318
1319       Wanlong Gao, Fujitsu Ltd.
1320
1322       Copyright (C) 2011-2020 Red Hat Inc.
1323
1324       Copyright (C) 2012 Fujitsu Ltd.
1325

LICENSE

1327       This program is free software; you can redistribute it and/or modify it
1328       under the terms of the GNU General Public License as published by the
1329       Free Software Foundation; either version 2 of the License, or (at your
1330       option) any later version.
1331
1332       This program is distributed in the hope that it will be useful, but
1333       WITHOUT ANY WARRANTY; without even the implied warranty of
1334       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1335       General Public License for more details.
1336
1337       You should have received a copy of the GNU General Public License along
1338       with this program; if not, write to the Free Software Foundation, Inc.,
1339       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
1340

BUGS

1342       To get a list of bugs against libguestfs, use this link:
1343       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
1344
1345       To report a new bug against libguestfs, use this link:
1346       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1347
1348       When reporting a bug, please supply:
1349
1350       ·   The version of libguestfs.
1351
1352       ·   Where you got libguestfs (eg. which Linux distro, compiled from
1353           source, etc)
1354
1355       ·   Describe the bug accurately and give a way to reproduce it.
1356
1357       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
1358           into the bug report.
1359
1360
1361
1362libguestfs-1.42.0                 2020-03-09                   virt-sysprep(1)
Impressum