1virt-builder(1) Virtualization Support virt-builder(1)
2
6 virt-builder - Build virtual machine images quickly
7
9 virt-builder os-version
10 [-o|--output DISKIMAGE] [--size SIZE] [--format raw|qcow2]
11 [--arch ARCHITECTURE] [--attach ISOFILE]
12 [--append-line FILE:LINE] [--chmod PERMISSIONS:FILE]
13 [--chown UID:GID:PATH] [--commands-from-file FILENAME]
14 [--copy SOURCE:DEST] [--copy-in LOCALPATH:REMOTEDIR]
15 [--delete PATH] [--edit FILE:EXPR] [--firstboot SCRIPT]
16 [--firstboot-command 'CMD+ARGS'] [--firstboot-install PKG,PKG..]
17 [--hostname HOSTNAME] [--inject-qemu-ga METHOD]
18 [--inject-virtio-win METHOD] [--install PKG,PKG..]
19 [--link TARGET:LINK[:LINK..]] [--mkdir DIR] [--move SOURCE:DEST]
20 [--password USER:SELECTOR] [--root-password SELECTOR]
21 [--run SCRIPT] [--run-command 'CMD+ARGS'] [--scrub FILE]
22 [--sm-attach SELECTOR] [--sm-register] [--sm-remove]
23 [--sm-unregister] [--ssh-inject USER[:SELECTOR]]
24 [--tar-in TARFILE:REMOTEDIR] [--timezone TIMEZONE] [--touch FILE]
25 [--truncate FILE] [--truncate-recursive PATH]
26 [--uninstall PKG,PKG..] [--update] [--upload FILE:DEST]
27 [--write FILE:CONTENT] [--no-logfile]
28 [--password-crypto md5|sha256|sha512] [--no-selinux-relabel]
29 [--selinux-relabel] [--sm-credentials SELECTOR]
30 virt-builder -l|--list [--long] [--list-format short|long|json] [os-version]
33 virt-builder --notes os-version
35 virt-builder --print-cache
37 virt-builder --cache-all-templates
39 virt-builder --delete-cache
41 virt-builder --get-kernel DISKIMAGE
43 [--format raw|qcow2] [--output OUTPUTDIR]
44
46 Virt-builder is a tool for quickly building new virtual machines. You
47 can build a variety of VMs for local or cloud use, usually within a few
48 minutes or less. Virt-builder also has many ways to customize these
49 VMs. Everything is run from the command line and nothing requires root
50 privileges, so automation and scripting is simple.
51 Note that virt-builder does not install guests from scratch. It takes
53 cleanly prepared, digitally signed OS templates and customizes them.
54 This approach is used because it is much faster, but if you need to do
55 fresh installs you may want to look at virt-install(1) and
56 oz-install(1).
57 The easiest way to get started is by looking at the examples in the
59 next section.
60
62 List the virtual machines available
63 virt-builder --list
64 will list out the operating systems available to install. A selection
66 of freely redistributable OSes is available as standard. You can add
67 your own too (see below).
68 After choosing a guest from the list, you may want to see if there are
70 any installation notes:
71 virt-builder --notes fedora-27
73 Build a virtual machine
75 virt-builder fedora-27
76 will build a Fedora 25 image for the same architecture as virt-builder
78 (so running it from an i686 installation will try to build an i686
79 image, if available). This will have all default configuration
80 (minimal size, no user accounts, random root password, only the bare
81 minimum installed software, etc.).
82 You do not need to run this command as root.
84 The first time this runs it has to download the template over the
86 network, but this gets cached (see "CACHING").
87 The name of the output file is derived from the template name, so above
89 it will be fedora-27.img. You can change the output filename using the
90 -o option:
91 virt-builder fedora-27 -o mydisk.img
93 You can also use the -o option to write to existing devices or logical
95 volumes.
96 virt-builder fedora-27 --format qcow2
98 As above, but write the output in qcow2 format to fedora-27.qcow2.
100 virt-builder fedora-27 --size 20G
102 As above, but the output size will be 20 GB. The guest OS is resized
104 as it is copied to the output (automatically, using virt-resize(1)).
105 virt-builder fedora-27 --arch i686
107 As above, but using an i686 template, if available.
109 Setting the root password
111 virt-builder fedora-27 --root-password file:/tmp/rootpw
112 Create a Fedora 25 image. The root password is taken from the file
114 /tmp/rootpw.
115 Note if you don’t set --root-password then the guest is given a random
117 root password which is printed on stdout.
118 You can also create user accounts. See "USERS AND PASSWORDS" below.
120 Set the hostname
122 virt-builder fedora-27 --hostname virt.example.com
123 Set the hostname to "virt.example.com".
125 Installing software
127 To install packages from the ordinary (guest) software repository (eg.
128 dnf or apt):
129 virt-builder fedora-27 --install "inkscape,@Xfce Desktop"
131 (In Fedora, "@" is used to install groups of packages. On Debian you
133 would install a meta-package instead.)
134 To update the installed packages to the latest version:
136 virt-builder debian-7 --update
138 Customizing the installation
140 There are many options that let you customize the installation. These
141 include: --run/--run-command, which run a shell script or command while
142 the disk image is being generated and lets you add or edit files that
143 go into the disk image. --firstboot/--firstboot-command, which let you
144 add scripts/commands that are run the first time the guest boots.
145 --edit to edit files. --upload to upload files.
146 For example:
148 cat <<'EOF' > /tmp/dnf-update.sh
150 dnf -y --best update
151 EOF
152 virt-builder fedora-27 --firstboot /tmp/dnf-update.sh
154 or simply:
156 virt-builder fedora-27 --firstboot-command 'dnf -y --best update'
158 which makes the dnf(8) "update" command run once the first time the
160 guest boots.
161 Or:
163 virt-builder fedora-27 \
165 --edit '/etc/dnf/dnf.conf:
166 s/gpgcheck=1/gpgcheck=0/'
167 which edits /etc/dnf/dnf.conf inside the disk image (during disk image
169 creation, long before boot).
170 You can combine these options, and have multiple options of all types.
172
174 --help
175 Display help.
176 --arch ARCHITECTURE
178 Use the specified architecture for the output image. This means
179 there must be sources providing the requested template for the
180 requested architecture.
181 See also "ARCHITECTURE".
183 --attach ISOFILE
185 During the customization phase, the given disk is attached to the
186 libguestfs appliance. This is used to provide extra software
187 repositories or other data for customization.
188 You probably want to ensure the volume(s) or filesystems in the
190 attached disks are labelled (or use an ISO volume name) so that you
191 can mount them by label in your run-scripts:
192 mkdir /tmp/mount
194 mount LABEL=EXTRA /tmp/mount
195 You can have multiple --attach options, and the format can be any
197 disk format (not just an ISO).
198 See also: --run, "Installing packages at build time from a side
200 repository", genisoimage(1), virt-make-fs(1).
201 --attach-format FORMAT
203 Specify the disk format for the next --attach option. The "FORMAT"
204 is usually "raw" or "qcow2". Use "raw" for ISOs.
205 --cache DIR
207 --no-cache
208 --cache DIR sets the directory to use/check for cached template
209 files. If not set, defaults to either
210 $XDG_CACHE_HOME/virt-builder/ or $HOME/.cache/virt-builder/.
211 --no-cache disables template caching.
213 --cache-all-templates
215 Download all templates to the cache and then exit. See "CACHING".
216 Note this doesn't cache everything. More templates might be
218 uploaded. Also this doesn't cache packages (the --install,
219 --update options).
220 --check-signature
222 --no-check-signature
223 Check/don’t check the digital signature of the OS template. The
224 default is to check the signature and exit if it is not correct.
225 Using --no-check-signature bypasses this check.
226 See also --fingerprint.
228 --colors
230 --colours
231 Use ANSI colour sequences to colourize messages. This is the
232 default when the output is a tty. If the output of the program is
233 redirected to a file, ANSI colour sequences are disabled unless you
234 use this option.
235 --curl CURL
237 Specify an alternate curl(1) binary. You can also use this to add
238 curl parameters, for example to disable https certificate checks:
239 virt-builder --curl "curl --insecure" [...]
241 --delete-cache
243 Delete the template cache. See "CACHING".
244 --no-delete-on-failure
246 Don’t delete the output file on failure to build. You can use this
247 to debug failures to run scripts. See "DEBUGGING BUILDS" for ways
248 to debug images.
249 The default is to delete the output file if virt-builder fails (or,
251 for example, some script that it runs fails).
252 --fingerprint 'AAAA BBBB ...'
254 Check that the index and templates are signed by the key with the
255 given fingerprint. (The fingerprint is a long string, usually
256 written as 10 groups of 4 hexadecimal digits).
257 You can give this option multiple times. If you have multiple
259 source URLs, then you can have either no fingerprint, one
260 fingerprint or multiple fingerprints. If you have multiple, then
261 each must correspond 1-1 with a source URL.
262 --format qcow2
264 --format raw
265 For ordinary builds, this selects the output format. The default
266 is raw.
267 With --get-kernel this specifies the input format.
269 To create an old-style qcow2 file (for compatibility with RHEL 6 or
271 very old qemu < 1.1), after running virt-builder, use this command:
272 qemu-img amend -f qcow2 -o compat=0.10 output.qcow2
274 --get-kernel IMAGE
276 This option extracts the kernel and initramfs from a previously
277 built disk image called "IMAGE" (in fact it works for any VM disk
278 image, not just ones built using virt-builder).
279 Note this method is deprecated: there is a separate tool for this,
281 virt-get-kernel(1), which has more options for the file extraction.
282 The kernel and initramfs are written to the current directory,
284 unless you also specify the --output "outputdir" directory name.
285 The format of the disk image is automatically detected unless you
287 specify it by using the --format option.
288 In the case where the guest contains multiple kernels, the one with
290 the highest version number is chosen. To extract arbitrary kernels
291 from the disk image, see guestfish(1). To extract the entire /boot
292 directory of a guest, see virt-copy-out(1).
293 --gpg GPG
295 Specify an alternate gpg(1) (GNU Privacy Guard) binary. By default
296 virt-builder looks for either "gpg2" or "gpg" in the $PATH.
297 You can also use this to add gpg parameters, for example to specify
299 an alternate home directory:
300 virt-builder --gpg "gpg --homedir /tmp" [...]
302 -l [os-version]
304 --list [os-version]
305 --list --list-format format [os-version]
306 --list --long [os-version]
307 List all the available templates if no guest is specified, or only
308 for the specified one.
309 It is possible to choose with --list-format the output format for
311 the list templates:
312 short
314 The default format, prints only the template identifier and,
315 next to it, its short description.
316 long
318 Prints a textual list with the details of the available
319 sources, followed by the details of the available templates.
320 json
322 Prints a JSON object with the details of the available sources
323 and the details of the available templates.
324 The "version" key in the main object represents the
326 "compatibility version", and it is bumped every time the
327 resulting JSON output is incompatible with the previous
328 versions (for example the structure has changed, or non-
329 optional keys are no more present).
330 --long is a shorthand for the "long" format.
332 See also: --source, --notes, "SOURCES OF TEMPLATES".
334 --machine-readable
336 --machine-readable=format
337 This option is used to make the output more machine friendly when
338 being parsed by other programs. See "MACHINE READABLE OUTPUT"
339 below.
340 -m MB
342 --memsize MB
343 Change the amount of memory allocated to --run scripts. Increase
344 this if you find that --run scripts or the --install option are
345 running out of memory.
346 The default can be found with this command:
348 guestfish get-memsize
350 --network
352 --no-network
353 Enable or disable network access from the guest during the
354 installation.
355 Enabled is the default. Use --no-network to disable access.
357 The network only allows outgoing connections and has other minor
359 limitations. See "NETWORK" in virt-rescue(1).
360 If you use --no-network then certain other options such as
362 --install will not work.
363 This does not affect whether the guest can access the network once
365 it has been booted, because that is controlled by your hypervisor
366 or cloud environment and has nothing to do with virt-builder.
367 Generally speaking you should not use --no-network. But here are
369 some reasons why you might want to:
370 1. Because the libguestfs backend that you are using doesn't
372 support the network. (See: "BACKEND" in guestfs(3)).
373 2. Any software you need to install comes from an attached ISO, so
375 you don't need the network.
376 3. You don’t want untrusted guest code trying to access your host
378 network when running virt-builder. This is particularly an
379 issue when you don't trust the source of the operating system
380 templates. (See "SECURITY" below).
381 4. You don’t have a host network (eg. in secure/restricted
383 environments).
384 --no-sync
386 Do not sync the output file on exit.
387 Virt-builder "fsync"s the output file or disk image when it exits.
389 The reason is that qemu/KVM’s default caching mode is "none" or
391 "directsync", both of which bypass the host page cache. Therefore
392 these would not work correctly if you immediately started the guest
393 after running virt-builder - they would not see the complete output
394 file. (Note that you should not use these caching modes - they are
395 fundamentally broken for this and other reasons.)
396 If you are not using these broken caching modes, you can use
398 --no-sync to avoid this unnecessary sync and gain considerable
399 extra performance.
400 --notes os-version
402 List any notes associated with this guest, then exit (this does not
403 do the install).
404 -o filename
406 --output filename
407 Write the output to filename. If you don’t specify this option,
408 then the output filename is generated by taking the "os-version"
409 string and adding ".img" (for raw format) or ".qcow2" (for qcow2
410 format).
411 Note that the output filename could be a device, partition or
413 logical volume.
414 When used with --get-kernel, this option specifies the output
416 directory.
417 --print-cache
419 Print information about the template cache. See "CACHING".
420 -q
422 --quiet
423 Don’t print ordinary progress messages.
424 --size SIZE
426 Select the size of the output disk, where the size can be specified
427 using common names such as "32G" (32 gigabytes) etc.
428 Virt-builder will resize filesystems inside the disk image
430 automatically.
431 If the size is not specified, then one of two things happens. If
433 the output is a file, then the size is the same as the template.
434 If the output is a device, partition, etc then the size of that
435 device is used.
436 To specify size in bytes, the number must be followed by the
438 lowercase letter b, eg: "--size 10737418240b".
439 --smp N
441 Enable N ≥ 2 virtual CPUs for --run scripts to use.
442 --source URL
444 Set the source URL to look for indexes.
445 You can give this option multiple times to specify multiple
447 sources.
448 See also "SOURCES OF TEMPLATES" below.
450 Note that you should not point --source to sources that you don’t
452 trust (unless the source is signed by someone you do trust). See
453 also the --no-network option.
454 --no-warn-if-partition
456 Do not emit a warning if the output device is a partition. This
457 warning avoids a common user error when writing to a USB key or
458 external drive, when you should normally write to the whole device
459 (--output /dev/sdX), not to a partition on the device
460 (--output /dev/sdX1). Use this option to suppress this warning.
461 -v
463 --verbose
464 Enable debug messages and/or produce verbose output.
465 When reporting bugs, use this option and attach the complete output
467 to your bug report.
468 -V
470 --version
471 Display version number and exit.
472 --wrap
474 Wrap error, warning, and informative messages. This is the default
475 when the output is a tty. If the output of the program is
476 redirected to a file, wrapping is disabled unless you use this
477 option.
478 -x Enable tracing of libguestfs API calls.
480 Customization options
482 --append-line FILE:LINE
483 Append a single line of text to the "FILE". If the file does not
484 already end with a newline, then one is added before the appended
485 line. Also a newline is added to the end of the "LINE" string
486 automatically.
487 For example (assuming ordinary shell quoting) this command:
489 --append-line '/etc/hosts:10.0.0.1 foo'
491 will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
493 the latter only if the existing file does not already end with a
494 newline.
495 "⏎" represents a newline character, which is guessed by looking at
497 the existing content of the file, so this command does the right
498 thing for files using Unix or Windows line endings. It also works
499 for empty or non-existent files.
500 To insert several lines, use the same option several times:
502 --append-line '/etc/hosts:10.0.0.1 foo'
504 --append-line '/etc/hosts:10.0.0.2 bar'
505 To insert a blank line before the appended line, do:
507 --append-line '/etc/hosts:'
509 --append-line '/etc/hosts:10.0.0.1 foo'
510 --chmod PERMISSIONS:FILE
512 Change the permissions of "FILE" to "PERMISSIONS".
513 Note: "PERMISSIONS" by default would be decimal, unless you prefix
515 it with 0 to get octal, ie. use 0700 not 700.
516 --chown UID:GID:PATH
518 Change the owner user and group ID of a file or directory in the
519 guest. Note:
520 • Only numeric UIDs and GIDs will work, and these may not be the
522 same inside the guest as on the host.
523 • This will not work with Windows guests.
525 For example:
527 virt-customize --chown '0:0:/var/log/audit.log'
529 See also: --upload.
531 --commands-from-file FILENAME
533 Read the customize commands from a file, one (and its arguments)
534 each line.
535 Each line contains a single customization command and its
537 arguments, for example:
538 delete /some/file
540 install some-package
541 password some-user:password:its-new-password
542 Empty lines are ignored, and lines starting with "#" are comments
544 and are ignored as well. Furthermore, arguments can be spread
545 across multiple lines, by adding a "\" (continuation character) at
546 the of a line, for example
547 edit /some/file:\
549 s/^OPT=.*/OPT=ok/
550 The commands are handled in the same order as they are in the file,
552 as if they were specified as --delete /some/file on the command
553 line.
554 --copy SOURCE:DEST
556 Copy files or directories recursively inside the guest.
557 Wildcards cannot be used.
559 --copy-in LOCALPATH:REMOTEDIR
561 Copy local files or directories recursively into the disk image,
562 placing them in the directory "REMOTEDIR" (which must exist).
563 Wildcards cannot be used.
565 --delete PATH
567 Delete a file from the guest. Or delete a directory (and all its
568 contents, recursively).
569 You can use shell glob characters in the specified path. Be
571 careful to escape glob characters from the host shell, if that is
572 required. For example:
573 virt-customize --delete '/var/log/*.log'.
575 See also: --upload, --scrub.
577 --edit FILE:EXPR
579 Edit "FILE" using the Perl expression "EXPR".
580 Be careful to properly quote the expression to prevent it from
582 being altered by the shell.
583 Note that this option is only available when Perl 5 is installed.
585 See "NON-INTERACTIVE EDITING" in virt-edit(1).
587 --firstboot SCRIPT
589 Install "SCRIPT" inside the guest, so that when the guest first
590 boots up, the script runs (as root, late in the boot process).
591 The script is automatically chmod +x after installation in the
593 guest.
594 The alternative version --firstboot-command is the same, but it
596 conveniently wraps the command up in a single line script for you.
597 You can have multiple --firstboot options. They run in the same
599 order that they appear on the command line.
600 Please take a look at "FIRST BOOT SCRIPTS" for more information and
602 caveats about the first boot scripts.
603 See also --run.
605 --firstboot-command 'CMD+ARGS'
607 Run command (and arguments) inside the guest when the guest first
608 boots up (as root, late in the boot process).
609 You can have multiple --firstboot options. They run in the same
611 order that they appear on the command line.
612 Please take a look at "FIRST BOOT SCRIPTS" for more information and
614 caveats about the first boot scripts.
615 See also --run.
617 --firstboot-install PKG,PKG..
619 Install the named packages (a comma-separated list). These are
620 installed when the guest first boots using the guest’s package
621 manager (eg. apt, yum, etc.) and the guest’s network connection.
622 For an overview on the different ways to install packages, see
624 "INSTALLING PACKAGES".
625 --hostname HOSTNAME
627 Set the hostname of the guest to "HOSTNAME". You can use a dotted
628 hostname.domainname (FQDN) if you want.
629 --inject-qemu-ga METHOD
631 Inject the QEMU Guest Agent into a Windows guest. The guest agent
632 communicates with qemu through a socket in order to provide
633 enhanced features (see qemu-ga(8)). This operation also injects a
634 firstboot script so that the Guest Agent is installed when the
635 guest boots.
636 The parameter is the same as used by the --inject-virtio-win
638 operation.
639 Note that to do a full conversion of a Windows guest from a foreign
641 hypervisor like VMware (which involves many other operations) you
642 should use the virt-v2v(1) tool instead of this.
643 --inject-virtio-win METHOD
645 Inject virtio-win drivers into a Windows guest. These drivers add
646 virtio accelerated drivers suitable when running on top of a
647 hypervisor that supports virtio (such as qemu/KVM). The operation
648 also adjusts the Windows Registry so that the drivers are installed
649 when the guest boots.
650 The parameter can be one of:
652 ISO The path to the ISO image containing the virtio-win drivers
654 (eg. /usr/share/virtio-win/virtio-win.iso).
655 DIR The directory containing the unpacked virtio-win drivers (eg.
657 /usr/share/virtio-win).
658 "osinfo"
660 The literal string "osinfo" means to use the libosinfo database
661 to locate the drivers. (See osinfo-query(1).
662 Note that to do a full conversion of a Windows guest from a foreign
664 hypervisor like VMware (which involves many other operations) you
665 should use the virt-v2v(1) tool instead of this.
666 --install PKG,PKG..
668 Install the named packages (a comma-separated list). These are
669 installed during the image build using the guest’s package manager
670 (eg. apt, yum, etc.) and the host’s network connection.
671 For an overview on the different ways to install packages, see
673 "INSTALLING PACKAGES".
674 See also --update, --uninstall.
676 --link TARGET:LINK[:LINK..]
678 Create symbolic link(s) in the guest, starting at "LINK" and
679 pointing at "TARGET".
680 --mkdir DIR
682 Create a directory in the guest.
683 This uses "mkdir -p" so any intermediate directories are created,
685 and it also works if the directory already exists.
686 --move SOURCE:DEST
688 Move files or directories inside the guest.
689 Wildcards cannot be used.
691 --no-logfile
693 Scrub "builder.log" (log file from build commands) from the image
694 after building is complete. If you don't want to reveal precisely
695 how the image was built, use this option.
696 See also: "LOG FILE".
698 --no-selinux-relabel
700 Do not attempt to correct the SELinux labels of files in the guest.
701 In such guests that support SELinux, customization automatically
703 relabels files so that they have the correct SELinux label. (The
704 relabeling is performed immediately, but if the operation fails,
705 customization will instead touch /.autorelabel on the image to
706 schedule a relabel operation for the next time the image boots.)
707 This option disables the automatic relabeling.
708 The option is a no-op for guests that do not support SELinux.
710 --password USER:SELECTOR
712 Set the password for "USER". (Note this option does not create the
713 user account).
714 See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
716 and also how to set up user accounts.
717 --password-crypto md5|sha256|sha512
719 When the virt tools change or set a password in the guest, this
720 option sets the password encryption of that password to "md5",
721 "sha256" or "sha512".
722 "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
724 the guest).
725 "md5" will work with relatively old Linux guests (eg. RHEL 3), but
727 is not secure against modern attacks.
728 The default is "sha512" unless libguestfs detects an old guest that
730 didn't have support for SHA-512, in which case it will use "md5".
731 You can override libguestfs by specifying this option.
732 Note this does not change the default password encryption used by
734 the guest when you create new user accounts inside the guest. If
735 you want to do that, then you should use the --edit option to
736 modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
737 "/etc/pam.d/common-password" (Debian, Ubuntu).
738 --root-password SELECTOR
740 Set the root password.
741 See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
743 and also how to set up user accounts.
744 Note: In virt-builder, if you don't set --root-password then the
746 guest is given a random root password.
747 --run SCRIPT
749 Run the shell script (or any program) called "SCRIPT" on the disk
750 image. The script runs virtualized inside a small appliance,
751 chrooted into the guest filesystem.
752 The script is automatically chmod +x.
754 If libguestfs supports it then a limited network connection is
756 available but it only allows outgoing network connections. You can
757 also attach data disks (eg. ISO files) as another way to provide
758 data (eg. software packages) to the script without needing a
759 network connection (--attach). You can also upload data files
760 (--upload).
761 You can have multiple --run options. They run in the same order
763 that they appear on the command line.
764 See also: --firstboot, --attach, --upload.
766 --run-command 'CMD+ARGS'
768 Run the command and arguments on the disk image. The command runs
769 virtualized inside a small appliance, chrooted into the guest
770 filesystem.
771 If libguestfs supports it then a limited network connection is
773 available but it only allows outgoing network connections. You can
774 also attach data disks (eg. ISO files) as another way to provide
775 data (eg. software packages) to the script without needing a
776 network connection (--attach). You can also upload data files
777 (--upload).
778 You can have multiple --run-command options. They run in the same
780 order that they appear on the command line.
781 See also: --firstboot, --attach, --upload.
783 --scrub FILE
785 Scrub a file from the guest. This is like --delete except that:
786 • It scrubs the data so a guest could not recover it.
788 • It cannot delete directories, only regular files.
790 --selinux-relabel
792 This is a compatibility option that does nothing.
793 --sm-attach SELECTOR
795 Attach to a pool using "subscription-manager".
796 See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
798 --sm-credentials SELECTOR
800 Set the credentials for "subscription-manager".
801 See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
803 --sm-register
805 Register the guest using "subscription-manager".
806 This requires credentials being set using --sm-credentials.
808 --sm-remove
810 Remove all the subscriptions from the guest using
811 "subscription-manager".
812 --sm-unregister
814 Unregister the guest using "subscription-manager".
815 --ssh-inject USER[:SELECTOR]
817 Inject an ssh key so the given "USER" will be able to log in over
818 ssh without supplying a password. The "USER" must exist already in
819 the guest.
820 See "SSH KEYS" for the format of the "SELECTOR" field.
822 You can have multiple --ssh-inject options, for different users and
824 also for more keys for each user.
825 --tar-in TARFILE:REMOTEDIR
827 Copy local files or directories from a local tar file called
828 "TARFILE" into the disk image, placing them in the directory
829 "REMOTEDIR" (which must exist). Note that the tar file must be
830 uncompressed (.tar.gz files will not work here)
831 --timezone TIMEZONE
833 Set the default timezone of the guest to "TIMEZONE". Use a
834 location string like "Europe/London"
835 --touch FILE
837 This command performs a touch(1)-like operation on "FILE".
838 --truncate FILE
840 This command truncates "FILE" to a zero-length file. The file must
841 exist already.
842 --truncate-recursive PATH
844 This command recursively truncates all files under "PATH" to zero-
845 length.
846 --uninstall PKG,PKG..
848 Uninstall the named packages (a comma-separated list). These are
849 removed during the image build using the guest’s package manager
850 (eg. apt, yum, etc.). Dependent packages may also need to be
851 uninstalled to satisfy the request.
852 See also --install, --update.
854 --update
856 Do the equivalent of "yum update", "apt-get upgrade", or whatever
857 command is required to update the packages already installed in the
858 template to their latest versions.
859 See also --install, --uninstall.
861 --upload FILE:DEST
863 Upload local file "FILE" to destination "DEST" in the disk image.
864 File owner and permissions from the original are preserved, so you
865 should set them to what you want them to be in the disk image.
866 "DEST" could be the final filename. This can be used to rename the
868 file on upload.
869 If "DEST" is a directory name (which must already exist in the
871 guest) then the file is uploaded into that directory, and it keeps
872 the same name as on the local filesystem.
873 See also: --mkdir, --delete, --scrub.
875 --write FILE:CONTENT
877 Write "CONTENT" to "FILE".
878
880 INSTALLING PACKAGES
881 There are several approaches to installing packages or applications in
882 the guest which have different trade-offs.
883 Installing packages at build time
885 If the guest OS you are installing is similar to the host OS (eg. both
887 are Linux), and if libguestfs supports network connections, then you
888 can use --install to install packages like this:
889 virt-builder fedora-27 --install inkscape
891 This uses the guest’s package manager and the host’s network
893 connection.
894 Updating packages at build time
896 To update the installed packages in the template at build time:
898 virt-builder fedora-27 --update
900 Most of the templates that ship with virt-builder come with a very
902 minimal selection of packages (known as a "JEOS" or "Just Enough
903 Operating System"), which are up to date at the time the template is
904 created, but could be out of date by the time you come to install an OS
905 from the template. This option updates those template packages.
906 Installing packages at first boot
908 Another option is to install the packages when the guest first boots:
910 virt-builder fedora-27 --firstboot-install inkscape
912 This uses the guest’s package manager and the guest’s network
914 connection.
915 The downsides are that it will take the guest a lot longer to boot
917 first time, and there’s nothing much you can do if package installation
918 fails (eg. if a network problem means the guest can't reach the package
919 repositories).
920 Installing packages at build time from a side repository
922 If the software you want to install is not available in the main
924 package repository of the guest, then you can add a side repository.
925 Usually this is presented as an ISO (CD disk image) file containing
926 extra packages.
927 You can create the disk image using either genisoimage(1) or
929 virt-make-fs(1). For genisoimage, use a command like this:
930 genisoimage -o extra-packages.iso -R -J -V EXTRA cdcontents/
932 Create a script that mounts the ISO and sets up the repository. For
934 dnf, create /tmp/install.sh containing:
935 mkdir /tmp/mount
937 mount LABEL=EXTRA /tmp/mount
938 cat <<'EOF' > /etc/yum.repos.d/extra.repo
940 [extra]
941 name=extra
942 baseurl=file:///tmp/mount
943 enabled=1
944 EOF
945 dnf -y install famousdatabase
947 For apt, create /tmp/install.sh containing:
949 mkdir /tmp/mount
951 mount LABEL=EXTRA /tmp/mount
952 apt-cdrom -d=/tmp/mount add
954 apt-get -y install famousdatabase
955 Use the --attach option to attach the CD / disk image and the --run
957 option to run the script:
958 virt-builder fedora-27 \
960 --attach extra-packages.iso \
961 --run /tmp/install.sh
962 USERS AND PASSWORDS
964 The --root-password option is used to change the root password
965 (otherwise a random password is used). This option takes a password
966 "SELECTOR" in one of the following formats:
967 --root-password file:FILENAME
969 Read the root password from "FILENAME". The whole first line of
970 this file is the replacement password. Any other lines are
971 ignored. You should create the file with mode 0600 to ensure no
972 one else can read it.
973 --root-password password:PASSWORD
975 Set the root password to the literal string "PASSWORD".
976 Note: this is not secure since any user on the same machine can see
978 the cleartext password using ps(1).
979 --root-password random
981 Choose a random password, which is printed on stdout. The password
982 has approximately 120 bits of randomness.
983 This is the default.
985 --root-password disabled
987 The root account password is disabled. This is like putting "*" in
988 the password field.
989 --root-password locked:file:FILENAME
991 --root-password locked:password:PASSWORD
992 --root-password locked:random
993 The root account is locked, but a password is placed on the
994 account. If first unlocked (using "passwd -u") then logins will
995 use the given password.
996 --root-password locked
998 --root-password locked:disabled
999 The root account is locked and password is disabled.
1000 Creating user accounts
1002 To create user accounts, use the useradd(8) command with
1004 --firstboot-command like this:
1005 virt-builder --firstboot-command \
1007 'useradd -m -p "" rjones ; chage -d 0 rjones'
1008 The above command will create an "rjones" account with no password, and
1010 force the user to set a password when they first log in. There are
1011 other ways to manage passwords, see useradd(8) for details.
1012 KEYBOARD LAYOUT
1014 Because there are so many different ways to set the keyboard layout in
1015 Linux distributions, virt-builder does not yet attempt to have a simple
1016 command line option. This section describes how to set the keyboard
1017 for some common Linux distributions.
1018 Keyboard layout with systemd
1020 For distros that use systemd "localectl", use a command like this:
1022 virt-builder fedora-27 \
1024 --firstboot-command 'localectl set-keymap uk'
1025 See localectl(1) and
1027 https://www.happyassassin.net/2013/11/23/keyboard-layouts-in-fedora-20-and-previously/
1028 for more details.
1029 Keyboard layout using /etc/sysconfig/keyboard
1031 For RHEL ≤ 6, Fedora ≤ 18 and similar, upload or modify the keyboard
1033 configuration file using the --upload, --write or --edit options. For
1034 example:
1035 virt-builder centos-6 \
1037 --edit '/etc/sysconfig/keyboard: s/^KEYTABLE=.*/KEYTABLE="uk"/'
1038 The format of this file can be found documented in many places online.
1040 Keyboard layout with Debian-derived distros
1042 For Debian-derived distros using /etc/default/keyboard, upload or
1044 modify the keyboard file using the --upload, --write or --edit options.
1045 For example:
1046 virt-builder debian-8 \
1048 --edit '/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/'
1049 See https://wiki.debian.org/Keyboard.
1051 LANGUAGE
1053 Most Linux distributions support multiple locale settings so that you
1054 can have guest messages printed in another language such as Russian.
1055 However there is no single setting which controls this, since extra
1057 packages may need to be installed to support console and X fonts, and
1058 keyboard input methods. The packages required, and their configuration
1059 is highly distro-specific, and it is outside the scope of virt-builder
1060 to do this.
1061 This section contains examples for some common Linux distributions.
1063 Setting Japanese in Fedora 25
1065 virt-builder fedora-27 \
1067 --size 20G \
1068 --update \
1069 --install @japanese-support \
1070 --install @xfce \
1071 --install xorg-x11-server-Xorg,xorg-x11-drivers,rsyslog \
1072 --link /usr/lib/systemd/system/graphical.target:/etc/systemd/system/default.target \
1073 --firstboot-command 'localectl set-locale LANG=ja_JP.utf8' \
1074 --firstboot-command 'localectl set-keymap jp' \
1075 --firstboot-command 'systemctl isolate graphical.target'
1076 Setting Japanese in Debian 8 (Jessie)
1078 Note that although this enables Japanese in the text console too, it is
1080 unlikely that you will see properly rendered Japanese there. However
1081 Japanese is properly rendered in X applications and terminals.
1082 pkgs=locales,xfce4,\
1084 ibus,ibus-anthy,\
1085 fonts-ipafont-gothic,fonts-ipafont-mincho,\
1086 fonts-takao-mincho,\
1087 xfonts-intl-japanese,xfonts-intl-japanese-big,\
1088 iceweasel-l10n-ja,manpages-ja
1089 virt-builder debian-8 \
1091 --size 20G \
1092 --install $pkgs \
1093 --edit '/etc/locale.gen: s,^#\s*ja,ja,' \
1094 --write '/etc/default/locale:LANG="ja_JP.UTF-8"' \
1095 --run-command "locale-gen"
1096 LOG FILE
1098 Scripts and package installation that runs at build time (--run,
1099 --run-command, --install, --update, but not firstboot) is logged in one
1100 of the following locations:
1101 /tmp/builder.log
1103 On Linux, BSD, and other non-Windows guests.
1104 C:\Temp\builder.log
1106 On Windows, DOS guests.
1107 /builder.log
1109 If /tmp or C:\Temp is missing.
1110 If you don’t want the log file to appear in the final image, then use
1112 the --no-logfile command line option.
1113 SSH KEYS
1115 The --ssh-inject option is used to inject ssh keys for users in the
1116 guest, so they can login without supplying a password.
1117 The "SELECTOR" part of the option value is optional; in this case,
1119 --ssh-inject "USER" means that we look in the current user’s ~/.ssh
1120 directory to find the default public ID file. That key is uploaded.
1121 "default public ID" is the default_ID_file file described in
1122 ssh-copy-id(1).
1123 If specified, the "SELECTOR" can be in one of the following formats:
1125 --ssh-inject USER:file:FILENAME
1127 Read the ssh key from FILENAME. FILENAME is usually a .pub file.
1128 --ssh-inject USER:string:KEY_STRING
1130 Use the specified "KEY_STRING". "KEY_STRING" is usually a public
1131 string like ssh-rsa AAAA.... user@localhost.
1132 In any case, the ~USER/.ssh directory and the
1134 ~USER/.ssh/authorized_keys file will be created if not existing
1135 already.
1136 FIRST BOOT SCRIPTS
1138 The --firstboot and --firstboot-command options allow you to execute
1139 commands at the first boot of the guest. To do so, an init script for
1140 the guest init system is installed, which takes care of running all the
1141 added scripts and commands.
1142 Supported operating systems are:
1144 Linux
1146 Init systems supported are: systemd, System-V init (known also as
1147 sysvinit), and Upstart (using the System-V scripts).
1148 Note that usually init scripts run as root, but with a more limited
1150 environment than what could be available from a normal shell: for
1151 example, $HOME may be unset or empty.
1152 The output of the first boot scripts is available in the guest as
1154 ~root/virt-sysprep-firstboot.log.
1155 Windows
1157 rhsrvany.exe, available from sources at
1158 https://github.com/rwmjones/rhsrvany, or pvvxsvc.exe, available
1159 with SUSE VMDP is installed to run the first boot scripts. It is
1160 required, and the setup of first boot scripts will fail if it is
1161 not present.
1162 rhsrvany.exe or pvvxsvc.exe is copied from the location pointed to
1164 by the "VIRT_TOOLS_DATA_DIR" environment variable; if not set, a
1165 compiled-in default will be used (something like
1166 /usr/share/virt-tools).
1167 The output of the first boot scripts is available in the guest as
1169 C:\Program Files\Guestfs\Firstboot\log.txt.
1170 SUBSCRIPTION-MANAGER
1172 It is possible to automate the registration and attaching of the system
1173 using "subscription-manager". This is typical on Red Hat Enterprise
1174 Linux guests. There are few options which ease this process, avoid
1175 executing commands manually and exposing passwords on command line.
1176 --sm-register starts the registration process, and requires
1178 --sm-credentials to be specified; the format of the "SELECTOR" of
1179 --sm-credentials is one of the following formats:
1180 --sm-credentials USER:file:FILENAME
1182 Read the password for the specified "USER" from FILENAME.
1183 --sm-credentials USER:password:PASSWORD
1185 Use the literal string "PASSWORD" for the specified "USER".
1186 --sm-attach attaches the system to subscriptions; the format of its
1188 "SELECTOR" is one of the following:
1189 --sm-attach auto
1191 "subscription-manager" attaches to the best-fitting subscriptions
1192 for the system.
1193 --sm-attach file:FILENAME
1195 Read the pool ID from FILENAME.
1196 --sm-attach pool:POOL
1198 Use the literal string "POOL" as pool ID.
1199 --sm-remove removes all the subscriptions from the guest, while
1201 --sm-unregister completely unregister the system.
1202 INSTALLATION PROCESS
1204 When you invoke virt-builder, installation proceeds as follows:
1205 • The template image is downloaded.
1207 If the template image is present in the cache, the cached version
1209 is used instead. (See "CACHING").
1210 • The template signature is checked.
1212 • The template is uncompressed to a tmp file.
1214 • The template image is resized into the destination, using
1216 virt-resize(1).
1217 • Extra disks are attached (--attach).
1219 • A new random seed is generated for the guest.
1221 • Guest customization is performed, in the order specified on the
1223 command line.
1224 • SELinux relabelling is done unless disabled with
1226 --no-selinux-relabel.
1227 IMPORTING THE DISK IMAGE
1229 Importing into libvirt
1230 Import the disk image into libvirt using virt-install(1) --import
1232 option.
1233 virt-install --import \
1235 --name guest --ram 2048 \
1236 --disk path=disk.img,format=raw --os-variant fedora27
1237 Notes:
1239 1. You must specify the correct format. The format is "raw" unless
1241 you used virt-builder’s --format option.
1242 2. --os-variant is highly recommended, because it will present optimum
1244 devices to enable the guest to run most efficiently. To get a list
1245 of all variants, do:
1246 osinfo-query os
1248 The above tool is provided by libosinfo package.
1250 3. You can run virt-install as root or non-root. Each works slightly
1252 differently because libvirt manages a different set of virtual
1253 machines for each user. In particular virt-manager normally shows
1254 the root-owned VMs, whereas Boxes shows the user-owned VMs, and
1255 other tools probably work differently as well.
1256 Importing into OpenStack
1258 Import the image into Glance (the OpenStack image store) by doing:
1260 glance image-create --name fedora-27-image --file fedora-27.img \
1262 --disk-format raw --container-format bare \
1263 --is-public True
1264 The --file parameter is the virt-builder-generated disk image. It
1266 should match virt-builder’s --output option. The --disk-format
1267 parameter should match virt-builder’s --format option (or "raw" if you
1268 didn't use that option). The --container-format should always be
1269 "bare" since virt-builder doesn't put images into containers.
1270 You can use the "glance image-show fedora-27-image" command to display
1272 the properties of the image.
1273 To boot up an instance of your image on a Nova compute node, do:
1275 nova boot fedora-27-server --image fedora-27-image \
1277 --flavor m1.medium
1278 Use "nova flavor-list" to list possible machine flavors. Use
1280 "nova list" to list running instances.
1281 Booting directly using qemu or KVM
1283 The qemu command line is not very stable or easy to use, hence libvirt
1285 should be used if possible. However a command line similar to the
1286 following could be used to boot the virtual machine:
1287 qemu-system-x86_64 \
1289 -machine accel=kvm:tcg \
1290 -cpu host \
1291 -m 2048 \
1292 -drive file=disk.img,format=raw,if=virtio
1293 As with libvirt, it is very important that the correct format is
1295 chosen. It will be "raw" unless the --format option was used.
1296 CONFIGURATION MANAGEMENT
1298 Puppet
1299 To enable the Puppet agent in a guest, install the package, point the
1301 configuration at your Puppetmaster, and ensure the agent runs at boot.
1302 A typical virt-builder command would be:
1304 virt-builder fedora-27 \
1306 --hostname client.example.com \
1307 --update \
1308 --install puppet \
1309 --append-line '/etc/puppet/puppet.conf:[agent]' \
1310 --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
1311 --run-command 'systemctl enable puppet'
1312 The precise instructions vary according to the Linux distro. For
1314 further information see:
1315 https://docs.puppet.com/puppet/latest/install_pre.html
1316 DEBUGGING BUILDS
1318 If virt-builder itself fails, then enable debugging (-v) and report a
1319 bug (see "BUGS" below).
1320 If virt-builder fails because some script or package it is installing
1322 fails, try using --no-delete-on-failure to preserve the output file,
1323 and continue reading this section.
1324 If virt-builder is successful but the image doesn't work, here are some
1326 things to try:
1327 Use virt-rescue
1329 Run virt-rescue(1) on the disk image:
1330 virt-rescue -a disk.img
1332 This gives you a rescue shell. You can mount the filesystems from
1334 the disk image on /sysroot and examine them using ordinary Linux
1335 commands. You can also chroot into the guest to reinstall the
1336 bootloader. The virt-rescue man page has a lot more information
1337 and examples.
1338 Use guestfish
1340 Run guestfish(1) on the disk image:
1341 guestfish -a disk.img -i
1343 Use guestfish commands like "ll /directory" and "cat /file" to
1345 examine directories and files.
1346 Use guestmount
1348 Mount the disk image safely on the host using FUSE and
1349 guestmount(1):
1350 mkdir /tmp/mp
1352 guestmount -a disk.img -i /tmp/mp
1353 cd /tmp/mp
1354 To unmount the disk image do:
1356 fusermount -u /tmp/mp
1358 Add a serial console
1360 If the guest hangs during boot, it can be helpful to add a serial
1361 console to the guest, and direct kernel messages to the serial
1362 console. Adding the serial console will involve looking at the
1363 documentation for your hypervisor. To direct kernel messages to
1364 the serial console, add the following on the kernel command line:
1365 console=tty0 console=ttyS0,115200
1367 SOURCES OF TEMPLATES
1369 virt-builder reads the available sources from configuration files, with
1370 the .conf extension and located in the following paths:
1371 • $XDG_CONFIG_HOME/virt-builder/repos.d/ ($XDG_CONFIG_HOME is
1373 $HOME/.config if not set).
1374 • $VIRT_BUILDER_DIRS/virt-builder/repos.d/ (where $VIRT_BUILDER_DIRS
1376 means any of the directories in that environment variable, or just
1377 /etc if not set).
1378 Each .conf file in those paths has a simple text format like the
1380 following:
1381 [libguestfs.org]
1383 uri=http://libguestfs.org/download/builder/index.asc
1384 gpgkey=file:///etc/xdg/virt-builder/repos.d/libguestfs.gpg
1385 The part in square brackets is the repository identifier, which is used
1387 as unique identifier.
1388 The following fields can appear:
1390 "uri=URI"
1392 The URI of the index file which this repository refers to.
1393 This field is required.
1395 "gpgkey=URI"
1397 This optional field represents the URI (although only file:// URIs
1398 are accepted) of the key used to sign the index file. If not
1399 present, the index file referred by uri=.. is not signed.
1400 "proxy=MODE"
1402 This optional field specifies the proxy mode, to be used when
1403 downloading the index file of this repository. The possible values
1404 are:
1405 no, off
1407 No proxy is being used at all, even overriding the system
1408 configuration.
1409 system
1411 The proxy used is the system one.
1412 anything else
1414 Specifies the actual proxy configuration to be used, overriding
1415 the system configuration.
1416 If not present, the assumed value is to respect the proxy settings
1418 of the system (i.e. as if system would be specified).
1419 "format=FORMAT"
1421 This optional field specifies the format of the repository. The
1422 possible values are:
1423 native
1425 The native format of the "virt-builder" repository. See also
1426 "Creating and signing the index file" below.
1427 simplestreams
1429 The URI represents the root of a Simple Streams v1.0 tree of
1430 metadata.
1431 For more information about Simple Streams, see also
1433 https://launchpad.net/simplestreams.
1434 If not present, the assumed value is "native".
1436 For serious virt-builder use, you may want to create your own
1438 repository of templates.
1439 Libguestfs.org repository
1441 Out of the box, virt-builder downloads the file
1443 http://libguestfs.org/download/builder/index.asc which is an index of
1444 available templates plus some information about each one, wrapped up in
1445 a digital signature. The command "virt-builder --list" lists out the
1446 information in this index file.
1447 The templates hosted on libguestfs.org were created using shell
1449 scripts, kickstart files and preseed files which can be found in the
1450 libguestfs source tree, in "builder/templates".
1451 Setting up the repository
1453 You can set up your own site containing an index file and some
1455 templates, and then point virt-builder at the site by creating a .conf
1456 file pointing to it.
1457 Note that if your index is signed, you will need to properly fill
1459 gpgkey=.. in your .conf file, making sure to deploy also the GPG key
1460 file.
1461 virt-builder --source https://example.com/builder/index.asc \
1463 --fingerprint 'AAAA BBBB ...' \
1464 --list
1465 You can host this on any web or FTP server, or a local or network
1467 filesystem.
1468 Setting up a GPG key
1470 If you don’t have a GnuPG key, you will need to set one up. (Strictly
1472 speaking this is optional, but if your index and template files are not
1473 signed then virt-builder users will have to use the
1474 --no-check-signature flag every time they use virt-builder.)
1475 To create a key, see the GPG manual
1477 http://www.gnupg.org/gph/en/manual.html.
1478 Export your GPG public key:
1480 gpg --export -a "you@example.com" > pubkey
1482 Create the templates
1484 There are many ways to create the templates. For example you could
1486 clone existing guests (see virt-sysprep(1)), or you could install a
1487 guest by hand (virt-install(1)). To see how the templates were created
1488 for virt-builder, look at the scripts in "builder/templates"
1489 Virt-builder supports any image format (e.g. raw, qcow2, etc) as
1491 template, both as-is, and compressed as XZ. This way, existing images
1492 (e.g. cleaned using virt-sysprep(1)) can be used as templates.
1493 For best results when compressing the templates, use the following xz
1495 options (see nbdkit-xz-plugin(1) for further explanation):
1496 xz --best --block-size=16777216 disk
1498 Creating and signing the index file
1500 The index file has a simple text format (shown here without the digital
1502 signature):
1503 [fedora-18]
1505 name=Fedora® 18
1506 osinfo=fedora18
1507 arch=x86_64
1508 file=fedora-18.xz
1509 checksum[sha512]=...
1510 format=raw
1511 size=6442450944
1512 compressed_size=148947524
1513 expand=/dev/sda3
1514 [fedora-19]
1516 name=Fedora® 19
1517 osinfo=fedora19
1518 arch=x86_64
1519 file=fedora-19.xz
1520 checksum[sha512]=...
1521 revision=3
1522 format=raw
1523 size=4294967296
1524 compressed_size=172190964
1525 expand=/dev/sda3
1526 The part in square brackets is the "os-version", which is the same
1528 string that is used on the virt-builder command line to build that OS.
1529 The index file creation and signature can be eased with the
1531 virt-builder-repository(1) tool.
1532 After preparing the "index" file in the correct format, clearsign it
1534 using the following command:
1535 gpg --clearsign --armor index
1537 This will create the final file called index.asc which can be uploaded
1539 to the server (and is the uri=.. URL). As noted above, signing the
1540 index file is optional, but recommended.
1541 The following fields can appear:
1543 "name=NAME"
1545 The user-friendly name of this template. This is displayed in the
1546 --list output but is otherwise not significant.
1547 "osinfo=ID"
1549 This optional field maps the operating system to the associated
1550 libosinfo ID. Virt-builder does not use it (yet).
1551 "arch=ARCH"
1553 The architecture of the operating system installed within the
1554 template. This field is required.
1555 "file=PATH"
1557 The path (relative to the index) of the xz-compressed template.
1558 Note that absolute paths or URIs are not permitted here. This is
1560 because virt-builder has a "same origin" policy for templates so
1561 they cannot come from other servers.
1562 "sig=PATH"
1564 This option is deprecated. Use the checksum field instead.
1565 The path (relative to the index) of the GPG detached signature of
1567 the xz file.
1568 Note that absolute paths or URIs are not permitted here. This is
1570 because virt-builder has a "same origin" policy for templates so
1571 they cannot come from other servers.
1572 The file can be created as follows:
1574 gpg --detach-sign --armor -o disk.xz.sig disk.xz
1576 "checksum[sha512]=7b882fe9b82eb0fef..."
1578 The SHA-512 checksum of the file specified in file=.. is checked
1579 after it is downloaded. To work out the signature, do:
1580 sha512sum disk.xz
1582 Note if you use this, you don’t need to sign the file, ie. don’t
1584 use "sig". This option overrides "sig".
1585 "checksum=7b882fe9b82eb0fef..."
1587 "checksum" is an alias for "checksum[sha512]".
1588 If you need to interoperate with virt-builder = 1.24.0 then you
1590 have to use "checksum" because that version would give a parse
1591 error with square brackets and numbers in the key of a field. This
1592 is fixed in virt-builder ≥ 1.24.1.
1593 "revision=N"
1595 The revision is an integer which is used to control the template
1596 cache. Increasing the revision number causes clients to download
1597 the template again even if they have a copy in the cache.
1598 The revision number is optional. If omitted it defaults to 1.
1600 "format=raw"
1602 "format=qcow2"
1603 Specify the format of the disk image; in case it is compressed,
1604 that is the format before the compression. If not given, the
1605 format is autodetected, but generally it is better to be explicit
1606 about the intended format.
1607 Note this is the source format, which is different from the
1609 --format option (requested output format). Virt-builder does on-
1610 the-fly conversion from the source format to the requested output
1611 format.
1612 "size=NNN"
1614 The virtual size of the image in bytes. This is the size of the
1615 image when uncompressed. If using a non-raw format such as qcow2
1616 then it means the virtual disk size, not the size of the qcow2
1617 file.
1618 This field is required.
1620 Virt-builder also uses this as the minimum size that users can
1622 request via the --size option, or as the default size if there is
1623 no --size option.
1624 "compressed_size=NNN"
1626 The actual size of the disk image in bytes, i.e. what was specified
1627 in file=... This is just used for information (when using "long",
1628 and "json" formats of --list).
1629 "expand=/dev/sdaX"
1631 When expanding the image to its final size, instruct virt-resize(1)
1632 to expand the named partition in the guest image to fill up all
1633 available space. This works like the virt-resize --expand option.
1634 You should usually put the device name of the guest’s root
1636 filesystem here.
1637 It’s a good idea to use this, but not required. If the field is
1639 omitted then virt-resize will create an extra partition at the end
1640 of the disk to cover the free space, which is much less user-
1641 friendly.
1642 "lvexpand=/dev/VolGroup/LogVol"
1644 When expanding the image to its final size, instruct virt-resize(1)
1645 to expand the named logical volume in the guest image to fill up
1646 all available space. This works like the virt-resize --lv-expand
1647 option.
1648 If the guest uses LVM2 you should usually put the LV of the guest’s
1650 root filesystem here. If the guest does not use LVM2 or its root
1651 filesystem is not on an LV, don't use this option.
1652 "notes=NOTES"
1654 Any notes that go with this image, especially notes describing what
1655 packages are in the image, how the image was prepared, and
1656 licensing information.
1657 This information is shown in the --notes and --list --long modes.
1659 You can use multi-line notes here by indenting each new line with
1661 at least one character of whitespace (even on blank lines):
1662 notes=This image was prepared using
1664 the following kickstart script:
1665 <-- one space at beginning of line
1666 part /boot --fstype ext3
1667 ...
1668 "hidden=true"
1670 Using the hidden flag prevents the template from being listed by
1671 the --list option (but it is still installable). This is used for
1672 test images.
1673 "aliases=ALIAS1 ALIAS2 ..."
1675 This optional field specifies a list of aliases, separated by
1676 spaces, for the image. For example, an alias could be used to
1677 always point to the latest version of a certain image, leaving the
1678 old versions available in the index instead of updating the same
1679 image (see the "revision" field).
1680 Running virt-builder against multiple sources
1682 It is possible to use multiple sources with virt-builder. The
1684 recommended way is to deploy .conf files pointing to the index files.
1685 Another way is to specify the sources using multiple --source and/or
1686 --fingerprint options:
1687 virt-builder \
1689 --source http://example.com/s1/index.asc \
1690 --source http://example.com/s2/index.asc
1691 You can provide N or 1 fingerprints. In the case where you provide N
1693 fingerprints, N = number of sources and there is a 1-1 correspondence
1694 between each source and each fingerprint:
1695 virt-builder \
1697 --source http://example.com/s1/index.asc --fingerprint '0123 ...' \
1698 --source http://example.com/s2/index.asc --fingerprint '9876 ...'
1699 In the case where you provide 1 fingerprint, the same fingerprint is
1701 used for all sources.
1702 You "must" provide at least 1 fingerprint.
1704 Licensing of templates
1706 You should be aware of the licensing of images that you distribute.
1708 For open source guests, provide a link to the source code in the
1709 "notes" field and comply with other requirements (eg. around
1710 trademarks).
1711 Formal specification of the index file
1713 The index file format has a formal specification defined by the flex
1715 scanner and bison parser used to parse the file. This can be found in
1716 the following files in the libguestfs source tree:
1717 builder/index-scan.l
1719 builder/index-parse.y
1720 A tool called virt-index-validate(1) is available to validate the index
1722 file to ensure it is correct.
1723 Note that the parser and tool can work on either the signed or unsigned
1725 index file (ie. index or index.asc).
1726 The index is always encoded in UTF-8.
1728 CACHING
1730 Caching templates
1731 Since the templates are usually very large, downloaded templates are
1733 cached in the user’s home directory.
1734 The location of the cache is $XDG_CACHE_HOME/virt-builder/ or
1736 $HOME/.cache/virt-builder.
1737 You can print out information about the cache directory, including
1739 which guests are currently cached, by doing:
1740 virt-builder --print-cache
1742 The cache can be deleted if you want to save space by doing:
1744 virt-builder --delete-cache
1746 You can download all (current) templates to the local cache by doing:
1748 virt-builder --cache-all-templates
1750 To disable the template cache, use --no-cache.
1752 Only templates are cached. The index and detached digital signatures
1754 are not cached.
1755 Caching packages
1757 Virt-builder uses curl(1) to download files and it also uses the
1759 current "http_proxy" (etc) settings when installing packages
1760 (--install, --update).
1761 You may therefore want to set those environment variables in order to
1763 maximize the amount of local caching that happens. See "ENVIRONMENT
1764 VARIABLES" and curl(1).
1765 Local mirrors
1767 To increase both speed and reliability of installing packages, you can
1769 set up a local mirror of the target distribution, and point the guest
1770 package manager at that.
1771 Using a local mirror with Fedora
1773 To install a Fedora guest using a local mirror:
1775 virt-builder fedora-27 \
1777 --edit '/etc/yum.repos.d/fedora.repo:
1778 s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
1779 s{.*metalink=.*}{};
1780 ' \
1781 --edit '/etc/yum.repos.d/fedora-updates.repo:
1782 s{.*baseurl=.*}{baseurl=http://example.com/mirror-updates/};
1783 s{.*metalink=.*}{};
1784 ' \
1785 --run-command 'dnf -y update' \
1786 --install 'pkg1,pkg2,...'
1787 Using a local mirror with Debian
1789 Assuming that you are using "apt-proxy" to mirror the repository, you
1791 should create a new sources.list file to point to your proxy (see
1792 https://help.ubuntu.com/community/AptProxy) and then do:
1793 virt-builder debian-8 \
1795 --upload sources.list:/etc/apt/sources.list \
1796 --run-command 'apt-get -y update' \
1797 --install 'pkg1,pkg2,...'
1798 DIGITAL SIGNATURES
1800 Virt-builder uses GNU Privacy Guard (GnuPG or gpg) to verify that the
1801 index and templates have not been tampered with.
1802 The source points to an index file, which is optionally signed.
1804 Virt-builder downloads the index and checks that the signature is valid
1806 and the signer’s fingerprint matches the specified fingerprint (ie. the
1807 one specified in gpgkey=.. in the .conf, or with --fingerprint, in that
1808 order).
1809 For checking against the built-in public key/fingerprint, this requires
1811 importing the public key into the user’s local gpg keyring (that’s just
1812 the way that gpg works).
1813 When a template is downloaded, its signature is checked in the same
1815 way.
1816 Although the signatures are optional, if you don’t have them then virt-
1818 builder users will have to use --no-check-signature on the command
1819 line. This prevents an attacker from replacing the signed index file
1820 with an unsigned index file and having virt-builder silently work
1821 without checking the signature. In any case it is highly recommended
1822 that you always create signed index and templates.
1823 ARCHITECTURE
1825 Virt-builder can build a guest for any architecture no matter what the
1826 host architecture is. For example an x86-64 guest on an ARM host.
1827 However certain options may not work, specifically options that require
1829 running commands in the guest during the build process: --install,
1830 --update, --run, --run-command. You may need to replace these with
1831 their firstboot-equivalents.
1832 An x86-64 host building 32 bit i686 guests should work without any
1834 special steps.
1835 SECURITY
1837 Virt-builder does not need to run as root (in fact, should not be run
1838 as root), and doesn't use setuid, "sudo" or any similar mechanism.
1839 --install, --update, --run and --run-command are implemented using an
1841 appliance (a small virtual machine) so these commands do not run on the
1842 host. If you are using the libguestfs libvirt backend and have SELinux
1843 enabled then the virtual machine is additionally encapsulated in an
1844 SELinux container (sVirt).
1845 However these options will have access to the host’s network and since
1847 the template may contain untrusted code, the code might try to access
1848 host network resources which it should not. You can use --no-network
1849 to prevent this.
1850 Firstboot commands run in the context of the guest when it is booted,
1852 and so the security of your hypervisor / cloud should be considered.
1853 Virt-builder injects a random seed into every guest which it builds.
1855 This helps to ensure that TCP sequence numbers, UUIDs, ssh host keys
1856 etc are truly random when the guest boots.
1857 You should check digital signatures and not ignore any signing errors.
1859 CLONES
1861 If you wish to create many new guests of the same type, it is tempting
1862 to run virt-builder once and then copy the output file. You should not
1863 do this. You should run virt-builder once for each new guest you need.
1864 The reason is that each clone needs to have (at least) a separate
1866 random seed, and possibly other unique features (such as filesystem
1867 UUIDs) in future versions of virt-builder.
1868 Another thing you should not do is to boot the guest, then clone the
1870 booted disk image. The reason is that some guests create unique
1871 machine IDs, SSH host keys and so on at first boot, and you would not
1872 want clones to have duplicate identities.
1873 See also: virt-sysprep(1).
1875 PERFORMANCE
1877 The most important aspect of getting good performance is caching.
1878 Templates gets downloaded into the cache the first time they are used,
1879 or if you use the --cache-all-templates option. See "CACHING" above
1880 for further information.
1881 Packages required for the --install and --update options are downloaded
1883 using the host network connection. Setting the "http_proxy",
1884 "https_proxy" and "ftp_proxy" environment variables to point to a local
1885 web cache may ensure they only need to be downloaded once. You can
1886 also try using a local package repository, although this can be complex
1887 to set up and varies according to which Linux distro you are trying to
1888 install.
1889 Using --no-sync
1891 Use --no-sync. However read the caveats in the "OPTIONS" section
1893 above, since this can cause disk corruption if not used correctly.
1894 Skipping virt-resize
1896 Virt-builder can skip the virt-resize step under certain conditions.
1898 This makes virt-builder much faster. The conditions are:
1899 • the output must be a regular file (not a block device), and
1901 • the user did not use the --size option, and
1903 • the output format is the same as the template format (usually raw).
1905 pxzcat
1907 Virt-builder uses an internal implementation of pxzcat (parallel xzcat)
1909 if liblzma was found at build time. If liblzma was not found at build
1910 time, regular "xzcat" is used which is single-threaded.
1911 SELINUX
1913 Guests which use SELinux (such as Fedora and Red Hat Enterprise Linux)
1914 require that each file has a correct SELinux label.
1915 Virt-builder does not know how to give new files a label, so there are
1917 two possible strategies it can use to ensure correct labelling:
1918 Automatic relabeling
1920 This runs setfiles(8) just before finalizing the guest, which sets
1921 SELinux labels correctly in the disk image.
1922 This is the recommended method.
1924 Using --no-selinux-relabel --touch /.autorelabel
1926 Guest templates may already contain a file called /.autorelabel or
1927 you may touch it.
1928 For guests that use SELinux, this causes restorecon(8) to run at
1930 first boot. Guests will reboot themselves once the first time you
1931 use them, which is normal and harmless.
1932
1934 The --machine-readable option can be used to make the output more
1935 machine friendly, which is useful when calling virt-builder from other
1936 programs, GUIs etc.
1937 Use the option on its own to query the capabilities of the virt-builder
1939 binary. Typical output looks like this:
1940 $ virt-builder --machine-readable
1942 virt-builder
1943 arch
1944 config-file
1945 customize
1946 json-list
1947 pxzcat
1948 A list of features is printed, one per line, and the program exits with
1950 status 0.
1951 It is possible to specify a format string for controlling the output;
1953 see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
1954
1956 For other environment variables which affect all libguestfs programs,
1957 see "ENVIRONMENT VARIABLES" in guestfs(3).
1958 "http_proxy"
1960 "https_proxy"
1961 "no_proxy"
1962 Set the proxy for downloads. These environment variables (and
1963 more) are actually interpreted by curl(1), not virt-builder.
1964 "HOME"
1966 Used to determine the location of the template cache, and the
1967 location of the user' sources. See "CACHING" and "SOURCES OF
1968 TEMPLATES".
1969 "VIRT_TOOLS_DATA_DIR"
1971 This can point to the directory containing data files used for
1972 Windows firstboot installation.
1973 Normally you do not need to set this. If not set, a compiled-in
1975 default will be used (something like /usr/share/virt-tools).
1976 This directory may contain the following files:
1978 rhsrvany.exe
1980 This is the RHSrvAny Windows binary, used to install a
1981 "firstboot" script in Windows guests. It is required if you
1982 intend to use the --firstboot or --firstboot-command options
1983 with Windows guests.
1984 See also: "https://github.com/rwmjones/rhsrvany"
1986 pvvxsvc.exe
1988 This is a Windows binary shipped with SUSE VMDP, used to
1989 install a "firstboot" script in Windows guests. It is required
1990 if you intend to use the --firstboot or --firstboot-command
1991 options with Windows guests.
1992 "XDG_CACHE_HOME"
1994 Used to determine the location of the template cache. See
1995 "CACHING".
1996 "XDG_CONFIG_HOME"
1998 Used to determine the location of the user' sources. See "SOURCES
1999 OF TEMPLATES".
2000 "VIRT_BUILDER_DIRS"
2002 Used to determine the location of the system sources. See "SOURCES
2003 OF TEMPLATES".
2004
2006 This program returns 0 if successful, or non-zero if there was an
2007 error.
2008
2010 guestfs(3), guestfish(1), guestmount(1), virt-builder-repository(1),
2011 virt-copy-out(1), virt-customize(1), virt-get-kernel(1),
2012 virt-install(1), virt-rescue(1), virt-resize(1), virt-sysprep(1),
2013 oz-install(1), gpg(1), gpg2(1), curl(1), virt-make-fs(1),
2014 genisoimage(1), http://libguestfs.org/.
2015
2017 Richard W.M. Jones http://people.redhat.com/~rjones/
2018
2020 Copyright (C) 2013 Red Hat Inc.
2021
2023 This program is free software; you can redistribute it and/or modify it
2024 under the terms of the GNU General Public License as published by the
2025 Free Software Foundation; either version 2 of the License, or (at your
2026 option) any later version.
2027 This program is distributed in the hope that it will be useful, but
2029 WITHOUT ANY WARRANTY; without even the implied warranty of
2030 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
2031 General Public License for more details.
2032 You should have received a copy of the GNU General Public License along
2034 with this program; if not, write to the Free Software Foundation, Inc.,
2035 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
2036
2038 To get a list of bugs against libguestfs, use this link:
2039 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
2040 To report a new bug against libguestfs, use this link:
2042 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
2043 When reporting a bug, please supply:
2045 • The version of libguestfs.
2047 • Where you got libguestfs (eg. which Linux distro, compiled from
2049 source, etc)
2050 • Describe the bug accurately and give a way to reproduce it.
2052 • Run libguestfs-test-tool(1) and paste the complete, unedited output
2054 into the bug report.
2055guestfs-tools-1.51.6 2023-12-09 virt-builder(1)