1virt-customize(1) Virtualization Support virt-customize(1)
2
6 virt-customize - Customize a virtual machine
7
9 virt-customize
10 [ -a disk.img [ -a disk.img ... ] | -d domname ]
11 [--attach ISOFILE] [--attach-format FORMAT]
12 [ -c URI | --connect URI ] [ -n | --dry-run ]
13 [ --format FORMAT] [ -m MB | --memsize MB ]
14 [ --network | --no-network ]
15 [ -q | --quiet ] [--smp N] [ -v | --verbose ] [-x]
16 [--append-line FILE:LINE] [--chmod PERMISSIONS:FILE]
17 [--commands-from-file FILENAME] [--copy SOURCE:DEST]
18 [--copy-in LOCALPATH:REMOTEDIR] [--delete PATH] [--edit FILE:EXPR]
19 [--firstboot SCRIPT] [--firstboot-command 'CMD+ARGS']
20 [--firstboot-install PKG,PKG..] [--hostname HOSTNAME]
21 [--inject-qemu-ga METHOD] [--inject-virtio-win METHOD]
22 [--install PKG,PKG..] [--link TARGET:LINK[:LINK..]] [--mkdir DIR]
23 [--move SOURCE:DEST] [--password USER:SELECTOR]
24 [--root-password SELECTOR] [--run SCRIPT]
25 [--run-command 'CMD+ARGS'] [--scrub FILE] [--sm-attach SELECTOR]
26 [--sm-register] [--sm-remove] [--sm-unregister]
27 [--ssh-inject USER[:SELECTOR]] [--truncate FILE]
28 [--truncate-recursive PATH] [--timezone TIMEZONE] [--touch FILE]
29 [--uninstall PKG,PKG..] [--update] [--upload FILE:DEST]
30 [--write FILE:CONTENT] [--no-logfile]
31 [--password-crypto md5|sha256|sha512] [--no-selinux-relabel]
32 [--selinux-relabel] [--sm-credentials SELECTOR]
33 virt-customize [ -V | --version ]
36
38 Using "virt-customize" on live virtual machines, or concurrently with
39 other disk editing tools, can be dangerous, potentially causing disk
40 corruption. The virtual machine must be shut down before you use this
41 command, and disk images must not be edited concurrently.
42
44 Virt-customize can customize a virtual machine (disk image) by
45 installing packages, editing configuration files, and so on.
46 Virt-customize modifies the guest or disk image in place. The guest
48 must be shut down. If you want to preserve the existing contents of
49 the guest, you must snapshot, copy or clone the disk first.
50 You do not need to run virt-customize as root. In fact we'd generally
52 recommend that you don't.
53 Related tools include: virt-sysprep(1) and virt-builder(1).
55
57 --help
58 Display brief help.
59 -a file
61 --add file
62 Add file which should be a disk image from a virtual machine.
63 The format of the disk image is auto-detected. To override this
65 and force a particular format use the --format option.
66 -a URI
68 --add URI
69 Add a remote disk. The URI format is compatible with guestfish.
70 See "ADDING REMOTE STORAGE" in guestfish(1).
71 --attach ISOFILE
73 The given disk is attached to the libguestfs appliance. This is
74 used to provide extra software repositories or other data for
75 customization.
76 You probably want to ensure the volume(s) or filesystems in the
78 attached disks are labelled (or use an ISO volume name) so that you
79 can mount them by label in your run-scripts:
80 mkdir /tmp/mount
82 mount LABEL=EXTRA /tmp/mount
83 You can have multiple --attach options, and the format can be any
85 disk format (not just an ISO).
86 --attach-format FORMAT
88 Specify the disk format for the next --attach option. The "FORMAT"
89 is usually "raw" or "qcow2". Use "raw" for ISOs.
90 --colors
92 --colours
93 Use ANSI colour sequences to colourize messages. This is the
94 default when the output is a tty. If the output of the program is
95 redirected to a file, ANSI colour sequences are disabled unless you
96 use this option.
97 -c URI
99 --connect URI
100 If using libvirt, connect to the given URI. If omitted, then we
101 connect to the default libvirt hypervisor.
102 If you specify guest block devices directly (-a), then libvirt is
104 not used at all.
105 -d guest
107 --domain guest
108 Add all the disks from the named libvirt guest. Domain UUIDs can
109 be used instead of names.
110 -n
112 --dry-run
113 Perform a read-only "dry run" on the guest. This runs the sysprep
114 operation, but throws away any changes to the disk at the end.
115 --echo-keys
117 When prompting for keys and passphrases, virt-customize normally
118 turns echoing off so you cannot see what you are typing. If you
119 are not worried about Tempest attacks and there is no one else in
120 the room you can specify this flag to see what you are typing.
121 --format raw|qcow2|..
123 --format auto
124 The default for the -a option is to auto-detect the format of the
125 disk image. Using this forces the disk format for -a options which
126 follow on the command line. Using --format auto switches back to
127 auto-detection for subsequent -a options.
128 For example:
130 virt-customize --format raw -a disk.img
132 forces raw format (no auto-detection) for disk.img.
134 virt-customize --format raw -a disk.img --format auto -a another.img
136 forces raw format (no auto-detection) for disk.img and reverts to
138 auto-detection for another.img.
139 If you have untrusted raw-format guest disk images, you should use
141 this option to specify the disk format. This avoids a possible
142 security problem with malicious guests (CVE-2010-3851).
143 --key SELECTOR
145 Specify a key for LUKS, to automatically open a LUKS device when
146 using the inspection. "ID" can be either the libguestfs device
147 name, or the UUID of the LUKS device.
148 --key "ID":key:KEY_STRING
150 Use the specified "KEY_STRING" as passphrase.
151 --key "ID":file:FILENAME
153 Read the passphrase from FILENAME.
154 --key "ID":clevis
156 Attempt passphrase-less unlocking for "ID" with Clevis, over
157 the network. Please refer to "ENCRYPTED DISKS" in guestfs(3)
158 for more information on network-bound disk encryption (NBDE).
159 Note that if any such option is present on the command line,
161 QEMU user networking will be automatically enabled for the
162 libguestfs appliance.
163 --keys-from-stdin
165 Read key or passphrase parameters from stdin. The default is to
166 try to read passphrases from the user by opening /dev/tty.
167 If there are multiple encrypted devices then you may need to supply
169 multiple keys on stdin, one per line.
170 -m MB
172 --memsize MB
173 Change the amount of memory allocated to --run scripts. Increase
174 this if you find that --run scripts or the --install option are
175 running out of memory.
176 The default can be found with this command:
178 guestfish get-memsize
180 --network
182 --no-network
183 Enable or disable network access from the guest during the
184 installation.
185 Enabled is the default. Use --no-network to disable access.
187 The network only allows outgoing connections and has other minor
189 limitations. See "NETWORK" in virt-rescue(1).
190 If you use --no-network then certain other options such as
192 --install will not work.
193 This does not affect whether the guest can access the network once
195 it has been booted, because that is controlled by your hypervisor
196 or cloud environment and has nothing to do with virt-customize.
197 Generally speaking you should not use --no-network. But here are
199 some reasons why you might want to:
200 1. Because the libguestfs backend that you are using doesn't
202 support the network. (See: "BACKEND" in guestfs(3)).
203 2. Any software you need to install comes from an attached ISO, so
205 you don't need the network.
206 3. You don’t want untrusted guest code trying to access your host
208 network when running virt-customize. This is particularly an
209 issue when you don't trust the source of the operating system
210 templates. (See "SECURITY" below).
211 4. You don’t have a host network (eg. in secure/restricted
213 environments).
214 -q
216 --quiet
217 Don’t print log messages.
218 To enable detailed logging of individual file operations, use -x.
220 --smp N
222 Enable N ≥ 2 virtual CPUs for --run scripts to use.
223 -v
225 --verbose
226 Enable verbose messages for debugging.
227 -V
229 --version
230 Display version number and exit.
231 --wrap
233 Wrap error, warning, and informative messages. This is the default
234 when the output is a tty. If the output of the program is
235 redirected to a file, wrapping is disabled unless you use this
236 option.
237 -x Enable tracing of libguestfs API calls.
239 Customization options
241 --append-line FILE:LINE
242 Append a single line of text to the "FILE". If the file does not
243 already end with a newline, then one is added before the appended
244 line. Also a newline is added to the end of the "LINE" string
245 automatically.
246 For example (assuming ordinary shell quoting) this command:
248 --append-line '/etc/hosts:10.0.0.1 foo'
250 will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
252 the latter only if the existing file does not already end with a
253 newline.
254 "⏎" represents a newline character, which is guessed by looking at
256 the existing content of the file, so this command does the right
257 thing for files using Unix or Windows line endings. It also works
258 for empty or non-existent files.
259 To insert several lines, use the same option several times:
261 --append-line '/etc/hosts:10.0.0.1 foo'
263 --append-line '/etc/hosts:10.0.0.2 bar'
264 To insert a blank line before the appended line, do:
266 --append-line '/etc/hosts:'
268 --append-line '/etc/hosts:10.0.0.1 foo'
269 --chmod PERMISSIONS:FILE
271 Change the permissions of "FILE" to "PERMISSIONS".
272 Note: "PERMISSIONS" by default would be decimal, unless you prefix
274 it with 0 to get octal, ie. use 0700 not 700.
275 --commands-from-file FILENAME
277 Read the customize commands from a file, one (and its arguments)
278 each line.
279 Each line contains a single customization command and its
281 arguments, for example:
282 delete /some/file
284 install some-package
285 password some-user:password:its-new-password
286 Empty lines are ignored, and lines starting with "#" are comments
288 and are ignored as well. Furthermore, arguments can be spread
289 across multiple lines, by adding a "\" (continuation character) at
290 the of a line, for example
291 edit /some/file:\
293 s/^OPT=.*/OPT=ok/
294 The commands are handled in the same order as they are in the file,
296 as if they were specified as --delete /some/file on the command
297 line.
298 --copy SOURCE:DEST
300 Copy files or directories recursively inside the guest.
301 Wildcards cannot be used.
303 --copy-in LOCALPATH:REMOTEDIR
305 Copy local files or directories recursively into the disk image,
306 placing them in the directory "REMOTEDIR" (which must exist).
307 Wildcards cannot be used.
309 --delete PATH
311 Delete a file from the guest. Or delete a directory (and all its
312 contents, recursively).
313 You can use shell glob characters in the specified path. Be
315 careful to escape glob characters from the host shell, if that is
316 required. For example:
317 virt-customize --delete '/var/log/*.log'.
319 See also: --upload, --scrub.
321 --edit FILE:EXPR
323 Edit "FILE" using the Perl expression "EXPR".
324 Be careful to properly quote the expression to prevent it from
326 being altered by the shell.
327 Note that this option is only available when Perl 5 is installed.
329 See "NON-INTERACTIVE EDITING" in virt-edit(1).
331 --firstboot SCRIPT
333 Install "SCRIPT" inside the guest, so that when the guest first
334 boots up, the script runs (as root, late in the boot process).
335 The script is automatically chmod +x after installation in the
337 guest.
338 The alternative version --firstboot-command is the same, but it
340 conveniently wraps the command up in a single line script for you.
341 You can have multiple --firstboot options. They run in the same
343 order that they appear on the command line.
344 Please take a look at "FIRST BOOT SCRIPTS" in virt-builder(1) for
346 more information and caveats about the first boot scripts.
347 See also --run.
349 --firstboot-command 'CMD+ARGS'
351 Run command (and arguments) inside the guest when the guest first
352 boots up (as root, late in the boot process).
353 You can have multiple --firstboot options. They run in the same
355 order that they appear on the command line.
356 Please take a look at "FIRST BOOT SCRIPTS" in virt-builder(1) for
358 more information and caveats about the first boot scripts.
359 See also --run.
361 --firstboot-install PKG,PKG..
363 Install the named packages (a comma-separated list). These are
364 installed when the guest first boots using the guest’s package
365 manager (eg. apt, yum, etc.) and the guest’s network connection.
366 For an overview on the different ways to install packages, see
368 "INSTALLING PACKAGES" in virt-builder(1).
369 --hostname HOSTNAME
371 Set the hostname of the guest to "HOSTNAME". You can use a dotted
372 hostname.domainname (FQDN) if you want.
373 --inject-qemu-ga METHOD
375 Inject the QEMU Guest Agent into a Windows guest. The guest agent
376 communicates with qemu through a socket in order to provide
377 enhanced features (see qemu-ga(8)). This operation also injects a
378 firstboot script so that the Guest Agent is installed when the
379 guest boots.
380 The parameter is the same as used by the --inject-virtio-win
382 operation.
383 Note that to do a full conversion of a Windows guest from a foreign
385 hypervisor like VMware (which involves many other operations) you
386 should use the virt-v2v(1) tool instead of this.
387 --inject-virtio-win METHOD
389 Inject virtio-win drivers into a Windows guest. These drivers add
390 virtio accelerated drivers suitable when running on top of a
391 hypervisor that supports virtio (such as qemu/KVM). The operation
392 also adjusts the Windows Registry so that the drivers are installed
393 when the guest boots.
394 The parameter can be one of:
396 ISO The path to the ISO image containing the virtio-win drivers
398 (eg. /usr/share/virtio-win/virtio-win.iso).
399 DIR The directory containing the unpacked virtio-win drivers (eg.
401 /usr/share/virtio-win).
402 "osinfo"
404 The literal string "osinfo" means to use the libosinfo database
405 to locate the drivers. (See osinfo-query(1).
406 Note that to do a full conversion of a Windows guest from a foreign
408 hypervisor like VMware (which involves many other operations) you
409 should use the virt-v2v(1) tool instead of this.
410 --install PKG,PKG..
412 Install the named packages (a comma-separated list). These are
413 installed during the image build using the guest’s package manager
414 (eg. apt, yum, etc.) and the host’s network connection.
415 For an overview on the different ways to install packages, see
417 "INSTALLING PACKAGES" in virt-builder(1).
418 See also --update, --uninstall.
420 --link TARGET:LINK[:LINK..]
422 Create symbolic link(s) in the guest, starting at "LINK" and
423 pointing at "TARGET".
424 --mkdir DIR
426 Create a directory in the guest.
427 This uses "mkdir -p" so any intermediate directories are created,
429 and it also works if the directory already exists.
430 --move SOURCE:DEST
432 Move files or directories inside the guest.
433 Wildcards cannot be used.
435 --no-logfile
437 Scrub "builder.log" (log file from build commands) from the image
438 after building is complete. If you don't want to reveal precisely
439 how the image was built, use this option.
440 See also: "LOG FILE".
442 --no-selinux-relabel
444 Do not attempt to correct the SELinux labels of files in the guest.
445 In such guests that support SELinux, customization automatically
447 relabels files so that they have the correct SELinux label. (The
448 relabeling is performed immediately, but if the operation fails,
449 customization will instead touch /.autorelabel on the image to
450 schedule a relabel operation for the next time the image boots.)
451 This option disables the automatic relabeling.
452 The option is a no-op for guests that do not support SELinux.
454 --password USER:SELECTOR
456 Set the password for "USER". (Note this option does not create the
457 user account).
458 See "USERS AND PASSWORDS" in virt-builder(1) for the format of the
460 "SELECTOR" field, and also how to set up user accounts.
461 --password-crypto md5|sha256|sha512
463 When the virt tools change or set a password in the guest, this
464 option sets the password encryption of that password to "md5",
465 "sha256" or "sha512".
466 "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
468 the guest).
469 "md5" will work with relatively old Linux guests (eg. RHEL 3), but
471 is not secure against modern attacks.
472 The default is "sha512" unless libguestfs detects an old guest that
474 didn't have support for SHA-512, in which case it will use "md5".
475 You can override libguestfs by specifying this option.
476 Note this does not change the default password encryption used by
478 the guest when you create new user accounts inside the guest. If
479 you want to do that, then you should use the --edit option to
480 modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
481 "/etc/pam.d/common-password" (Debian, Ubuntu).
482 --root-password SELECTOR
484 Set the root password.
485 See "USERS AND PASSWORDS" in virt-builder(1) for the format of the
487 "SELECTOR" field, and also how to set up user accounts.
488 Note: In virt-builder, if you don't set --root-password then the
490 guest is given a random root password.
491 --run SCRIPT
493 Run the shell script (or any program) called "SCRIPT" on the disk
494 image. The script runs virtualized inside a small appliance,
495 chrooted into the guest filesystem.
496 The script is automatically chmod +x.
498 If libguestfs supports it then a limited network connection is
500 available but it only allows outgoing network connections. You can
501 also attach data disks (eg. ISO files) as another way to provide
502 data (eg. software packages) to the script without needing a
503 network connection (--attach). You can also upload data files
504 (--upload).
505 You can have multiple --run options. They run in the same order
507 that they appear on the command line.
508 See also: --firstboot, --attach, --upload.
510 --run-command 'CMD+ARGS'
512 Run the command and arguments on the disk image. The command runs
513 virtualized inside a small appliance, chrooted into the guest
514 filesystem.
515 If libguestfs supports it then a limited network connection is
517 available but it only allows outgoing network connections. You can
518 also attach data disks (eg. ISO files) as another way to provide
519 data (eg. software packages) to the script without needing a
520 network connection (--attach). You can also upload data files
521 (--upload).
522 You can have multiple --run-command options. They run in the same
524 order that they appear on the command line.
525 See also: --firstboot, --attach, --upload.
527 --scrub FILE
529 Scrub a file from the guest. This is like --delete except that:
530 • It scrubs the data so a guest could not recover it.
532 • It cannot delete directories, only regular files.
534 --selinux-relabel
536 This is a compatibility option that does nothing.
537 --sm-attach SELECTOR
539 Attach to a pool using "subscription-manager".
540 See "SUBSCRIPTION-MANAGER" in virt-builder(1) for the format of the
542 "SELECTOR" field.
543 --sm-credentials SELECTOR
545 Set the credentials for "subscription-manager".
546 See "SUBSCRIPTION-MANAGER" in virt-builder(1) for the format of the
548 "SELECTOR" field.
549 --sm-register
551 Register the guest using "subscription-manager".
552 This requires credentials being set using --sm-credentials.
554 --sm-remove
556 Remove all the subscriptions from the guest using
557 "subscription-manager".
558 --sm-unregister
560 Unregister the guest using "subscription-manager".
561 --ssh-inject USER[:SELECTOR]
563 Inject an ssh key so the given "USER" will be able to log in over
564 ssh without supplying a password. The "USER" must exist already in
565 the guest.
566 See "SSH KEYS" in virt-builder(1) for the format of the "SELECTOR"
568 field.
569 You can have multiple --ssh-inject options, for different users and
571 also for more keys for each user.
572 --timezone TIMEZONE
574 Set the default timezone of the guest to "TIMEZONE". Use a
575 location string like "Europe/London"
576 --touch FILE
578 This command performs a touch(1)-like operation on "FILE".
579 --truncate FILE
581 This command truncates "FILE" to a zero-length file. The file must
582 exist already.
583 --truncate-recursive PATH
585 This command recursively truncates all files under "PATH" to zero-
586 length.
587 --uninstall PKG,PKG..
589 Uninstall the named packages (a comma-separated list). These are
590 removed during the image build using the guest’s package manager
591 (eg. apt, yum, etc.). Dependent packages may also need to be
592 uninstalled to satisfy the request.
593 See also --install, --update.
595 --update
597 Do the equivalent of "yum update", "apt-get upgrade", or whatever
598 command is required to update the packages already installed in the
599 template to their latest versions.
600 See also --install, --uninstall.
602 --upload FILE:DEST
604 Upload local file "FILE" to destination "DEST" in the disk image.
605 File owner and permissions from the original are preserved, so you
606 should set them to what you want them to be in the disk image.
607 "DEST" could be the final filename. This can be used to rename the
609 file on upload.
610 If "DEST" is a directory name (which must already exist in the
612 guest) then the file is uploaded into that directory, and it keeps
613 the same name as on the local filesystem.
614 See also: --mkdir, --delete, --scrub.
616 --write FILE:CONTENT
618 Write "CONTENT" to "FILE".
619
621 For guests which make use of SELinux, special handling for them might
622 be needed when using operations which create new files or alter
623 existing ones.
624 For further details, see "SELINUX" in virt-builder(1).
626
628 This program returns 0 on success, or 1 if there was an error.
629
631 "VIRT_TOOLS_DATA_DIR"
632 This can point to the directory containing data files used for
633 Windows firstboot installation.
634 Normally you do not need to set this. If not set, a compiled-in
636 default will be used (something like /usr/share/virt-tools).
637 This directory may contain the following files:
639 rhsrvany.exe
641 This is the RHSrvAny Windows binary, used to install a
642 "firstboot" script in Windows guests. It is required if you
643 intend to use the --firstboot or --firstboot-command options
644 with Windows guests.
645 See also: "https://github.com/rwmjones/rhsrvany"
647 pvvxsvc.exe
649 This is a Windows binary shipped with SUSE VMDP, used to
650 install a "firstboot" script in Windows guests. It is required
651 if you intend to use the --firstboot or --firstboot-command
652 options with Windows guests.
653 For other environment variables, see "ENVIRONMENT VARIABLES" in
655 guestfs(3).
656
658 guestfs(3), guestfish(1), virt-builder(1), virt-clone(1),
659 virt-rescue(1), virt-resize(1), virt-sparsify(1), virt-sysprep(1),
660 virsh(1), lvcreate(8), qemu-img(1), scrub(1), http://libguestfs.org/,
661 http://libvirt.org/.
662
664 Richard W.M. Jones http://people.redhat.com/~rjones/
665
667 Copyright (C) 2011-2023 Red Hat Inc.
668
670 This program is free software; you can redistribute it and/or modify it
671 under the terms of the GNU General Public License as published by the
672 Free Software Foundation; either version 2 of the License, or (at your
673 option) any later version.
674 This program is distributed in the hope that it will be useful, but
676 WITHOUT ANY WARRANTY; without even the implied warranty of
677 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
678 General Public License for more details.
679 You should have received a copy of the GNU General Public License along
681 with this program; if not, write to the Free Software Foundation, Inc.,
682 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
683
685 To get a list of bugs against libguestfs, use this link:
686 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
687 To report a new bug against libguestfs, use this link:
689 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
690 When reporting a bug, please supply:
692 • The version of libguestfs.
694 • Where you got libguestfs (eg. which Linux distro, compiled from
696 source, etc)
697 • Describe the bug accurately and give a way to reproduce it.
699 • Run libguestfs-test-tool(1) and paste the complete, unedited output
701 into the bug report.
702guestfs-tools-1.50.1 2023-04-06 virt-customize(1)