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 [--chown UID:GID:PATH] [--commands-from-file FILENAME]
18 [--copy SOURCE:DEST] [--copy-in LOCALPATH:REMOTEDIR]
19 [--delete PATH] [--edit FILE:EXPR] [--firstboot SCRIPT]
20 [--firstboot-command 'CMD+ARGS'] [--firstboot-install PKG,PKG..]
21 [--hostname HOSTNAME] [--inject-qemu-ga METHOD]
22 [--inject-virtio-win METHOD] [--install PKG,PKG..]
23 [--link TARGET:LINK[:LINK..]] [--mkdir DIR] [--move SOURCE:DEST]
24 [--password USER:SELECTOR] [--root-password SELECTOR]
25 [--run SCRIPT] [--run-command 'CMD+ARGS'] [--scrub FILE]
26 [--sm-attach SELECTOR] [--sm-register] [--sm-remove]
27 [--sm-unregister] [--ssh-inject USER[:SELECTOR]]
28 [--tar-in TARFILE:REMOTEDIR] [--timezone TIMEZONE] [--touch FILE]
29 [--truncate FILE] [--truncate-recursive PATH]
30 [--uninstall PKG,PKG..] [--update] [--upload FILE:DEST]
31 [--write FILE:CONTENT] [--no-logfile]
32 [--password-crypto md5|sha256|sha512] [--no-selinux-relabel]
33 [--selinux-relabel] [--sm-credentials SELECTOR]
34 virt-customize [ -V | --version ]
37
39 Using "virt-customize" on live virtual machines, or concurrently with
40 other disk editing tools, can be dangerous, potentially causing disk
41 corruption. The virtual machine must be shut down before you use this
42 command, and disk images must not be edited concurrently.
43
45 Virt-customize can customize a virtual machine (disk image) by
46 installing packages, editing configuration files, and so on.
47 Virt-customize modifies the guest or disk image in place. The guest
49 must be shut down. If you want to preserve the existing contents of
50 the guest, you must snapshot, copy or clone the disk first.
51 You do not need to run virt-customize as root. In fact we'd generally
53 recommend that you don't.
54 Related tools include: virt-sysprep(1) and virt-builder(1).
56
58 --help
59 Display brief help.
60 -a file
62 --add file
63 Add file which should be a disk image from a virtual machine.
64 The format of the disk image is auto-detected. To override this
66 and force a particular format use the --format option.
67 -a URI
69 --add URI
70 Add a remote disk. The URI format is compatible with guestfish.
71 See "ADDING REMOTE STORAGE" in guestfish(1).
72 --attach ISOFILE
74 The given disk is attached to the libguestfs appliance. This is
75 used to provide extra software repositories or other data for
76 customization.
77 You probably want to ensure the volume(s) or filesystems in the
79 attached disks are labelled (or use an ISO volume name) so that you
80 can mount them by label in your run-scripts:
81 mkdir /tmp/mount
83 mount LABEL=EXTRA /tmp/mount
84 You can have multiple --attach options, and the format can be any
86 disk format (not just an ISO).
87 --attach-format FORMAT
89 Specify the disk format for the next --attach option. The "FORMAT"
90 is usually "raw" or "qcow2". Use "raw" for ISOs.
91 --colors
93 --colours
94 Use ANSI colour sequences to colourize messages. This is the
95 default when the output is a tty. If the output of the program is
96 redirected to a file, ANSI colour sequences are disabled unless you
97 use this option.
98 -c URI
100 --connect URI
101 If using libvirt, connect to the given URI. If omitted, then we
102 connect to the default libvirt hypervisor.
103 If you specify guest block devices directly (-a), then libvirt is
105 not used at all.
106 -d guest
108 --domain guest
109 Add all the disks from the named libvirt guest. Domain UUIDs can
110 be used instead of names.
111 -n
113 --dry-run
114 Perform a read-only "dry run" on the guest. This runs the sysprep
115 operation, but throws away any changes to the disk at the end.
116 --echo-keys
118 When prompting for keys and passphrases, virt-customize normally
119 turns echoing off so you cannot see what you are typing. If you
120 are not worried about Tempest attacks and there is no one else in
121 the room you can specify this flag to see what you are typing.
122 --format raw|qcow2|..
124 --format auto
125 The default for the -a option is to auto-detect the format of the
126 disk image. Using this forces the disk format for -a options which
127 follow on the command line. Using --format auto switches back to
128 auto-detection for subsequent -a options.
129 For example:
131 virt-customize --format raw -a disk.img
133 forces raw format (no auto-detection) for disk.img.
135 virt-customize --format raw -a disk.img --format auto -a another.img
137 forces raw format (no auto-detection) for disk.img and reverts to
139 auto-detection for another.img.
140 If you have untrusted raw-format guest disk images, you should use
142 this option to specify the disk format. This avoids a possible
143 security problem with malicious guests (CVE-2010-3851).
144 --key SELECTOR
146 Specify a key for LUKS, to automatically open a LUKS device when
147 using the inspection.
148 --key NAME:key:KEY_STRING
150 --key UUID:key:KEY_STRING
151 --key all:key:KEY_STRING
152 "NAME" is the libguestfs device name (eg. "/dev/sda1"). "UUID"
153 is the device UUID. "all" means try the key against any
154 encrypted device.
155 Use the specified "KEY_STRING" as passphrase.
157 --key NAME:file:FILENAME
159 --key UUID:file:FILENAME
160 --key all:file:FILENAME
161 Read the passphrase from FILENAME.
162 --key NAME:clevis
164 --key UUID:clevis
165 --key all:clevis
166 Attempt passphrase-less unlocking for the device with Clevis,
167 over the network. Please refer to "ENCRYPTED DISKS" in
168 guestfs(3) for more information on network-bound disk
169 encryption (NBDE).
170 Note that if any such option is present on the command line,
172 QEMU user networking will be automatically enabled for the
173 libguestfs appliance.
174 --keys-from-stdin
176 Read key or passphrase parameters from stdin. The default is to
177 try to read passphrases from the user by opening /dev/tty.
178 If there are multiple encrypted devices then you may need to supply
180 multiple keys on stdin, one per line.
181 -m MB
183 --memsize MB
184 Change the amount of memory allocated to --run scripts. Increase
185 this if you find that --run scripts or the --install option are
186 running out of memory.
187 The default can be found with this command:
189 guestfish get-memsize
191 --network
193 --no-network
194 Enable or disable network access from the guest during the
195 installation.
196 Enabled is the default. Use --no-network to disable access.
198 The network only allows outgoing connections and has other minor
200 limitations. See "NETWORK" in virt-rescue(1).
201 If you use --no-network then certain other options such as
203 --install will not work.
204 This does not affect whether the guest can access the network once
206 it has been booted, because that is controlled by your hypervisor
207 or cloud environment and has nothing to do with virt-customize.
208 Generally speaking you should not use --no-network. But here are
210 some reasons why you might want to:
211 1. Because the libguestfs backend that you are using doesn't
213 support the network. (See: "BACKEND" in guestfs(3)).
214 2. Any software you need to install comes from an attached ISO, so
216 you don't need the network.
217 3. You don’t want untrusted guest code trying to access your host
219 network when running virt-customize. This is particularly an
220 issue when you don't trust the source of the operating system
221 templates. (See "SECURITY" below).
222 4. You don’t have a host network (eg. in secure/restricted
224 environments).
225 -q
227 --quiet
228 Don’t print log messages.
229 To enable detailed logging of individual file operations, use -x.
231 --smp N
233 Enable N ≥ 2 virtual CPUs for --run scripts to use.
234 -v
236 --verbose
237 Enable verbose messages for debugging.
238 -V
240 --version
241 Display version number and exit.
242 --wrap
244 Wrap error, warning, and informative messages. This is the default
245 when the output is a tty. If the output of the program is
246 redirected to a file, wrapping is disabled unless you use this
247 option.
248 -x Enable tracing of libguestfs API calls.
250 Customization options
252 --append-line FILE:LINE
253 Append a single line of text to the "FILE". If the file does not
254 already end with a newline, then one is added before the appended
255 line. Also a newline is added to the end of the "LINE" string
256 automatically.
257 For example (assuming ordinary shell quoting) this command:
259 --append-line '/etc/hosts:10.0.0.1 foo'
261 will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
263 the latter only if the existing file does not already end with a
264 newline.
265 "⏎" represents a newline character, which is guessed by looking at
267 the existing content of the file, so this command does the right
268 thing for files using Unix or Windows line endings. It also works
269 for empty or non-existent files.
270 To insert several lines, use the same option several times:
272 --append-line '/etc/hosts:10.0.0.1 foo'
274 --append-line '/etc/hosts:10.0.0.2 bar'
275 To insert a blank line before the appended line, do:
277 --append-line '/etc/hosts:'
279 --append-line '/etc/hosts:10.0.0.1 foo'
280 --chmod PERMISSIONS:FILE
282 Change the permissions of "FILE" to "PERMISSIONS".
283 Note: "PERMISSIONS" by default would be decimal, unless you prefix
285 it with 0 to get octal, ie. use 0700 not 700.
286 --chown UID:GID:PATH
288 Change the owner user and group ID of a file or directory in the
289 guest. Note:
290 • Only numeric UIDs and GIDs will work, and these may not be the
292 same inside the guest as on the host.
293 • This will not work with Windows guests.
295 For example:
297 virt-customize --chown '0:0:/var/log/audit.log'
299 See also: --upload.
301 --commands-from-file FILENAME
303 Read the customize commands from a file, one (and its arguments)
304 each line.
305 Each line contains a single customization command and its
307 arguments, for example:
308 delete /some/file
310 install some-package
311 password some-user:password:its-new-password
312 Empty lines are ignored, and lines starting with "#" are comments
314 and are ignored as well. Furthermore, arguments can be spread
315 across multiple lines, by adding a "\" (continuation character) at
316 the of a line, for example
317 edit /some/file:\
319 s/^OPT=.*/OPT=ok/
320 The commands are handled in the same order as they are in the file,
322 as if they were specified as --delete /some/file on the command
323 line.
324 --copy SOURCE:DEST
326 Copy files or directories recursively inside the guest.
327 Wildcards cannot be used.
329 --copy-in LOCALPATH:REMOTEDIR
331 Copy local files or directories recursively into the disk image,
332 placing them in the directory "REMOTEDIR" (which must exist).
333 Wildcards cannot be used.
335 --delete PATH
337 Delete a file from the guest. Or delete a directory (and all its
338 contents, recursively).
339 You can use shell glob characters in the specified path. Be
341 careful to escape glob characters from the host shell, if that is
342 required. For example:
343 virt-customize --delete '/var/log/*.log'.
345 See also: --upload, --scrub.
347 --edit FILE:EXPR
349 Edit "FILE" using the Perl expression "EXPR".
350 Be careful to properly quote the expression to prevent it from
352 being altered by the shell.
353 Note that this option is only available when Perl 5 is installed.
355 See "NON-INTERACTIVE EDITING" in virt-edit(1).
357 --firstboot SCRIPT
359 Install "SCRIPT" inside the guest, so that when the guest first
360 boots up, the script runs (as root, late in the boot process).
361 The script is automatically chmod +x after installation in the
363 guest.
364 The alternative version --firstboot-command is the same, but it
366 conveniently wraps the command up in a single line script for you.
367 You can have multiple --firstboot options. They run in the same
369 order that they appear on the command line.
370 Please take a look at "FIRST BOOT SCRIPTS" in virt-builder(1) for
372 more information and caveats about the first boot scripts.
373 See also --run.
375 --firstboot-command 'CMD+ARGS'
377 Run command (and arguments) inside the guest when the guest first
378 boots up (as root, late in the boot process).
379 You can have multiple --firstboot options. They run in the same
381 order that they appear on the command line.
382 Please take a look at "FIRST BOOT SCRIPTS" in virt-builder(1) for
384 more information and caveats about the first boot scripts.
385 See also --run.
387 --firstboot-install PKG,PKG..
389 Install the named packages (a comma-separated list). These are
390 installed when the guest first boots using the guest’s package
391 manager (eg. apt, yum, etc.) and the guest’s network connection.
392 For an overview on the different ways to install packages, see
394 "INSTALLING PACKAGES" in virt-builder(1).
395 --hostname HOSTNAME
397 Set the hostname of the guest to "HOSTNAME". You can use a dotted
398 hostname.domainname (FQDN) if you want.
399 --inject-qemu-ga METHOD
401 Inject the QEMU Guest Agent into a Windows guest. The guest agent
402 communicates with qemu through a socket in order to provide
403 enhanced features (see qemu-ga(8)). This operation also injects a
404 firstboot script so that the Guest Agent is installed when the
405 guest boots.
406 The parameter is the same as used by the --inject-virtio-win
408 operation.
409 Note that to do a full conversion of a Windows guest from a foreign
411 hypervisor like VMware (which involves many other operations) you
412 should use the virt-v2v(1) tool instead of this.
413 --inject-virtio-win METHOD
415 Inject virtio-win drivers into a Windows guest. These drivers add
416 virtio accelerated drivers suitable when running on top of a
417 hypervisor that supports virtio (such as qemu/KVM). The operation
418 also adjusts the Windows Registry so that the drivers are installed
419 when the guest boots.
420 The parameter can be one of:
422 ISO The path to the ISO image containing the virtio-win drivers
424 (eg. /usr/share/virtio-win/virtio-win.iso).
425 DIR The directory containing the unpacked virtio-win drivers (eg.
427 /usr/share/virtio-win).
428 "osinfo"
430 The literal string "osinfo" means to use the libosinfo database
431 to locate the drivers. (See osinfo-query(1).
432 Note that to do a full conversion of a Windows guest from a foreign
434 hypervisor like VMware (which involves many other operations) you
435 should use the virt-v2v(1) tool instead of this.
436 --install PKG,PKG..
438 Install the named packages (a comma-separated list). These are
439 installed during the image build using the guest’s package manager
440 (eg. apt, yum, etc.) and the host’s network connection.
441 For an overview on the different ways to install packages, see
443 "INSTALLING PACKAGES" in virt-builder(1).
444 See also --update, --uninstall.
446 --link TARGET:LINK[:LINK..]
448 Create symbolic link(s) in the guest, starting at "LINK" and
449 pointing at "TARGET".
450 --mkdir DIR
452 Create a directory in the guest.
453 This uses "mkdir -p" so any intermediate directories are created,
455 and it also works if the directory already exists.
456 --move SOURCE:DEST
458 Move files or directories inside the guest.
459 Wildcards cannot be used.
461 --no-logfile
463 Scrub "builder.log" (log file from build commands) from the image
464 after building is complete. If you don't want to reveal precisely
465 how the image was built, use this option.
466 See also: "LOG FILE".
468 --no-selinux-relabel
470 Do not attempt to correct the SELinux labels of files in the guest.
471 In such guests that support SELinux, customization automatically
473 relabels files so that they have the correct SELinux label. (The
474 relabeling is performed immediately, but if the operation fails,
475 customization will instead touch /.autorelabel on the image to
476 schedule a relabel operation for the next time the image boots.)
477 This option disables the automatic relabeling.
478 The option is a no-op for guests that do not support SELinux.
480 --password USER:SELECTOR
482 Set the password for "USER". (Note this option does not create the
483 user account).
484 See "USERS AND PASSWORDS" in virt-builder(1) for the format of the
486 "SELECTOR" field, and also how to set up user accounts.
487 --password-crypto md5|sha256|sha512
489 When the virt tools change or set a password in the guest, this
490 option sets the password encryption of that password to "md5",
491 "sha256" or "sha512".
492 "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
494 the guest).
495 "md5" will work with relatively old Linux guests (eg. RHEL 3), but
497 is not secure against modern attacks.
498 The default is "sha512" unless libguestfs detects an old guest that
500 didn't have support for SHA-512, in which case it will use "md5".
501 You can override libguestfs by specifying this option.
502 Note this does not change the default password encryption used by
504 the guest when you create new user accounts inside the guest. If
505 you want to do that, then you should use the --edit option to
506 modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
507 "/etc/pam.d/common-password" (Debian, Ubuntu).
508 --root-password SELECTOR
510 Set the root password.
511 See "USERS AND PASSWORDS" in virt-builder(1) for the format of the
513 "SELECTOR" field, and also how to set up user accounts.
514 Note: In virt-builder, if you don't set --root-password then the
516 guest is given a random root password.
517 --run SCRIPT
519 Run the shell script (or any program) called "SCRIPT" on the disk
520 image. The script runs virtualized inside a small appliance,
521 chrooted into the guest filesystem.
522 The script is automatically chmod +x.
524 If libguestfs supports it then a limited network connection is
526 available but it only allows outgoing network connections. You can
527 also attach data disks (eg. ISO files) as another way to provide
528 data (eg. software packages) to the script without needing a
529 network connection (--attach). You can also upload data files
530 (--upload).
531 You can have multiple --run options. They run in the same order
533 that they appear on the command line.
534 See also: --firstboot, --attach, --upload.
536 --run-command 'CMD+ARGS'
538 Run the command and arguments on the disk image. The command runs
539 virtualized inside a small appliance, chrooted into the guest
540 filesystem.
541 If libguestfs supports it then a limited network connection is
543 available but it only allows outgoing network connections. You can
544 also attach data disks (eg. ISO files) as another way to provide
545 data (eg. software packages) to the script without needing a
546 network connection (--attach). You can also upload data files
547 (--upload).
548 You can have multiple --run-command options. They run in the same
550 order that they appear on the command line.
551 See also: --firstboot, --attach, --upload.
553 --scrub FILE
555 Scrub a file from the guest. This is like --delete except that:
556 • It scrubs the data so a guest could not recover it.
558 • It cannot delete directories, only regular files.
560 --selinux-relabel
562 This is a compatibility option that does nothing.
563 --sm-attach SELECTOR
565 Attach to a pool using "subscription-manager".
566 See "SUBSCRIPTION-MANAGER" in virt-builder(1) for the format of the
568 "SELECTOR" field.
569 --sm-credentials SELECTOR
571 Set the credentials for "subscription-manager".
572 See "SUBSCRIPTION-MANAGER" in virt-builder(1) for the format of the
574 "SELECTOR" field.
575 --sm-register
577 Register the guest using "subscription-manager".
578 This requires credentials being set using --sm-credentials.
580 --sm-remove
582 Remove all the subscriptions from the guest using
583 "subscription-manager".
584 --sm-unregister
586 Unregister the guest using "subscription-manager".
587 --ssh-inject USER[:SELECTOR]
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 See "SSH KEYS" in virt-builder(1) for the format of the "SELECTOR"
594 field.
595 You can have multiple --ssh-inject options, for different users and
597 also for more keys for each user.
598 --tar-in TARFILE:REMOTEDIR
600 Copy local files or directories from a local tar file called
601 "TARFILE" into the disk image, placing them in the directory
602 "REMOTEDIR" (which must exist). Note that the tar file must be
603 uncompressed (.tar.gz files will not work here)
604 --timezone TIMEZONE
606 Set the default timezone of the guest to "TIMEZONE". Use a
607 location string like "Europe/London"
608 --touch FILE
610 This command performs a touch(1)-like operation on "FILE".
611 --truncate FILE
613 This command truncates "FILE" to a zero-length file. The file must
614 exist already.
615 --truncate-recursive PATH
617 This command recursively truncates all files under "PATH" to zero-
618 length.
619 --uninstall PKG,PKG..
621 Uninstall the named packages (a comma-separated list). These are
622 removed during the image build using the guest’s package manager
623 (eg. apt, yum, etc.). Dependent packages may also need to be
624 uninstalled to satisfy the request.
625 See also --install, --update.
627 --update
629 Do the equivalent of "yum update", "apt-get upgrade", or whatever
630 command is required to update the packages already installed in the
631 template to their latest versions.
632 See also --install, --uninstall.
634 --upload FILE:DEST
636 Upload local file "FILE" to destination "DEST" in the disk image.
637 File owner and permissions from the original are preserved, so you
638 should set them to what you want them to be in the disk image.
639 "DEST" could be the final filename. This can be used to rename the
641 file on upload.
642 If "DEST" is a directory name (which must already exist in the
644 guest) then the file is uploaded into that directory, and it keeps
645 the same name as on the local filesystem.
646 See also: --mkdir, --delete, --scrub.
648 --write FILE:CONTENT
650 Write "CONTENT" to "FILE".
651
653 For guests which make use of SELinux, special handling for them might
654 be needed when using operations which create new files or alter
655 existing ones.
656 For further details, see "SELINUX" in virt-builder(1).
658
660 This program returns 0 on success, or 1 if there was an error.
661
663 "VIRT_TOOLS_DATA_DIR"
664 This can point to the directory containing data files used for
665 Windows firstboot installation.
666 Normally you do not need to set this. If not set, a compiled-in
668 default will be used (something like /usr/share/virt-tools).
669 This directory may contain the following files:
671 rhsrvany.exe
673 This is the RHSrvAny Windows binary, used to install a
674 "firstboot" script in Windows guests. It is required if you
675 intend to use the --firstboot or --firstboot-command options
676 with Windows guests.
677 See also: "https://github.com/rwmjones/rhsrvany"
679 pvvxsvc.exe
681 This is a Windows binary shipped with SUSE VMDP, used to
682 install a "firstboot" script in Windows guests. It is required
683 if you intend to use the --firstboot or --firstboot-command
684 options with Windows guests.
685 For other environment variables, see "ENVIRONMENT VARIABLES" in
687 guestfs(3).
688
690 guestfs(3), guestfish(1), virt-builder(1), virt-clone(1),
691 virt-rescue(1), virt-resize(1), virt-sparsify(1), virt-sysprep(1),
692 virsh(1), lvcreate(8), qemu-img(1), scrub(1), http://libguestfs.org/,
693 http://libvirt.org/.
694
696 Richard W.M. Jones http://people.redhat.com/~rjones/
697
699 Copyright (C) 2011-2023 Red Hat Inc.
700
702 This program is free software; you can redistribute it and/or modify it
703 under the terms of the GNU General Public License as published by the
704 Free Software Foundation; either version 2 of the License, or (at your
705 option) any later version.
706 This program is distributed in the hope that it will be useful, but
708 WITHOUT ANY WARRANTY; without even the implied warranty of
709 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
710 General Public License for more details.
711 You should have received a copy of the GNU General Public License along
713 with this program; if not, write to the Free Software Foundation, Inc.,
714 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
715
717 To get a list of bugs against libguestfs, use this link:
718 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
719 To report a new bug against libguestfs, use this link:
721 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
722 When reporting a bug, please supply:
724 • The version of libguestfs.
726 • Where you got libguestfs (eg. which Linux distro, compiled from
728 source, etc)
729 • Describe the bug accurately and give a way to reproduce it.
731 • Run libguestfs-test-tool(1) and paste the complete, unedited output
733 into the bug report.
734guestfs-tools-1.51.6 2023-12-09 virt-customize(1)