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 [--commands-from-file FILENAME] [--copy SOURCE:DEST]
14 [--copy-in LOCALPATH:REMOTEDIR] [--delete PATH] [--edit FILE:EXPR]
15 [--firstboot SCRIPT] [--firstboot-command 'CMD+ARGS']
16 [--firstboot-install PKG,PKG..] [--hostname HOSTNAME]
17 [--install PKG,PKG..] [--link TARGET:LINK[:LINK..]] [--mkdir DIR]
18 [--move SOURCE:DEST] [--password USER:SELECTOR]
19 [--root-password SELECTOR] [--run SCRIPT]
20 [--run-command 'CMD+ARGS'] [--scrub FILE] [--sm-attach SELECTOR]
21 [--sm-register] [--sm-remove] [--sm-unregister]
22 [--ssh-inject USER[:SELECTOR]] [--truncate FILE]
23 [--truncate-recursive PATH] [--timezone TIMEZONE] [--touch FILE]
24 [--uninstall PKG,PKG..] [--update] [--upload FILE:DEST]
25 [--write FILE:CONTENT] [--no-logfile]
26 [--password-crypto md5|sha256|sha512] [--no-selinux-relabel]
27 [--selinux-relabel] [--sm-credentials SELECTOR]
28 virt-builder -l|--list [--long] [--list-format short|long|json] [os-version]
31 virt-builder --notes os-version
33 virt-builder --print-cache
35 virt-builder --cache-all-templates
37 virt-builder --delete-cache
39 virt-builder --get-kernel DISKIMAGE
41 [--format raw|qcow2] [--output OUTPUTDIR]
42
44 Virt-builder is a tool for quickly building new virtual machines. You
45 can build a variety of VMs for local or cloud use, usually within a few
46 minutes or less. Virt-builder also has many ways to customize these
47 VMs. Everything is run from the command line and nothing requires root
48 privileges, so automation and scripting is simple.
49 Note that virt-builder does not install guests from scratch. It takes
51 cleanly prepared, digitally signed OS templates and customizes them.
52 This approach is used because it is much faster, but if you need to do
53 fresh installs you may want to look at virt-install(1) and
54 oz-install(1).
55 The easiest way to get started is by looking at the examples in the
57 next section.
58
60 List the virtual machines available
61 virt-builder --list
62 will list out the operating systems available to install. A selection
64 of freely redistributable OSes is available as standard. You can add
65 your own too (see below).
66 After choosing a guest from the list, you may want to see if there are
68 any installation notes:
69 virt-builder --notes fedora-27
71 Build a virtual machine
73 virt-builder fedora-27
74 will build a Fedora 25 image for the same architecture as virt-builder
76 (so running it from an i686 installation will try to build an i686
77 image, if available). This will have all default configuration
78 (minimal size, no user accounts, random root password, only the bare
79 minimum installed software, etc.).
80 You do not need to run this command as root.
82 The first time this runs it has to download the template over the
84 network, but this gets cached (see "CACHING").
85 The name of the output file is derived from the template name, so above
87 it will be fedora-27.img. You can change the output filename using the
88 -o option:
89 virt-builder fedora-27 -o mydisk.img
91 You can also use the -o option to write to existing devices or logical
93 volumes.
94 virt-builder fedora-27 --format qcow2
96 As above, but write the output in qcow2 format to fedora-27.qcow2.
98 virt-builder fedora-27 --size 20G
100 As above, but the output size will be 20 GB. The guest OS is resized
102 as it is copied to the output (automatically, using virt-resize(1)).
103 virt-builder fedora-27 --arch i686
105 As above, but using an i686 template, if available.
107 Setting the root password
109 virt-builder fedora-27 --root-password file:/tmp/rootpw
110 Create a Fedora 25 image. The root password is taken from the file
112 /tmp/rootpw.
113 Note if you don’t set --root-password then the guest is given a random
115 root password which is printed on stdout.
116 You can also create user accounts. See "USERS AND PASSWORDS" below.
118 Set the hostname
120 virt-builder fedora-27 --hostname virt.example.com
121 Set the hostname to "virt.example.com".
123 Installing software
125 To install packages from the ordinary (guest) software repository (eg.
126 dnf or apt):
127 virt-builder fedora-27 --install "inkscape,@Xfce Desktop"
129 (In Fedora, "@" is used to install groups of packages. On Debian you
131 would install a meta-package instead.)
132 To update the installed packages to the latest version:
134 virt-builder debian-7 --update
136 Customizing the installation
138 There are many options that let you customize the installation. These
139 include: --run/--run-command, which run a shell script or command while
140 the disk image is being generated and lets you add or edit files that
141 go into the disk image. --firstboot/--firstboot-command, which let you
142 add scripts/commands that are run the first time the guest boots.
143 --edit to edit files. --upload to upload files.
144 For example:
146 cat <<'EOF' > /tmp/dnf-update.sh
148 dnf -y --best update
149 EOF
150 virt-builder fedora-27 --firstboot /tmp/dnf-update.sh
152 or simply:
154 virt-builder fedora-27 --firstboot-command 'dnf -y --best update'
156 which makes the dnf(8) "update" command run once the first time the
158 guest boots.
159 Or:
161 virt-builder fedora-27 \
163 --edit '/etc/dnf/dnf.conf:
164 s/gpgcheck=1/gpgcheck=0/'
165 which edits /etc/dnf/dnf.conf inside the disk image (during disk image
167 creation, long before boot).
168 You can combine these options, and have multiple options of all types.
170
172 --help
173 Display help.
174 --arch ARCHITECTURE
176 Use the specified architecture for the output image. This means
177 there must be sources providing the requested template for the
178 requested architecture.
179 See also "ARCHITECTURE".
181 --attach ISOFILE
183 During the customization phase, the given disk is attached to the
184 libguestfs appliance. This is used to provide extra software
185 repositories or other data for customization.
186 You probably want to ensure the volume(s) or filesystems in the
188 attached disks are labelled (or use an ISO volume name) so that you
189 can mount them by label in your run-scripts:
190 mkdir /tmp/mount
192 mount LABEL=EXTRA /tmp/mount
193 You can have multiple --attach options, and the format can be any
195 disk format (not just an ISO).
196 See also: --run, "Installing packages at build time from a side
198 repository", genisoimage(1), virt-make-fs(1).
199 --attach-format FORMAT
201 Specify the disk format for the next --attach option. The "FORMAT"
202 is usually "raw" or "qcow2". Use "raw" for ISOs.
203 --cache DIR
205 --no-cache
206 --cache DIR sets the directory to use/check for cached template
207 files. If not set, defaults to either
208 $XDG_CACHE_HOME/virt-builder/ or $HOME/.cache/virt-builder/.
209 --no-cache disables template caching.
211 --cache-all-templates
213 Download all templates to the cache and then exit. See "CACHING".
214 Note this doesn't cache everything. More templates might be
216 uploaded. Also this doesn't cache packages (the --install,
217 --update options).
218 --check-signature
220 --no-check-signature
221 Check/don’t check the digital signature of the OS template. The
222 default is to check the signature and exit if it is not correct.
223 Using --no-check-signature bypasses this check.
224 See also --fingerprint.
226 --colors
228 --colours
229 Use ANSI colour sequences to colourize messages. This is the
230 default when the output is a tty. If the output of the program is
231 redirected to a file, ANSI colour sequences are disabled unless you
232 use this option.
233 --curl CURL
235 Specify an alternate curl(1) binary. You can also use this to add
236 curl parameters, for example to disable https certificate checks:
237 virt-builder --curl "curl --insecure" [...]
239 --delete-cache
241 Delete the template cache. See "CACHING".
242 --no-delete-on-failure
244 Don’t delete the output file on failure to build. You can use this
245 to debug failures to run scripts. See "DEBUGGING BUILDS" for ways
246 to debug images.
247 The default is to delete the output file if virt-builder fails (or,
249 for example, some script that it runs fails).
250 --fingerprint 'AAAA BBBB ...'
252 Check that the index and templates are signed by the key with the
253 given fingerprint. (The fingerprint is a long string, usually
254 written as 10 groups of 4 hexadecimal digits).
255 You can give this option multiple times. If you have multiple
257 source URLs, then you can have either no fingerprint, one
258 fingerprint or multiple fingerprints. If you have multiple, then
259 each must correspond 1-1 with a source URL.
260 --format qcow2
262 --format raw
263 For ordinary builds, this selects the output format. The default
264 is raw.
265 With --get-kernel this specifies the input format.
267 To create an old-style qcow2 file (for compatibility with RHEL 6 or
269 very old qemu < 1.1), after running virt-builder, use this command:
270 qemu-img amend -f qcow2 -o compat=0.10 output.qcow2
272 --get-kernel IMAGE
274 This option extracts the kernel and initramfs from a previously
275 built disk image called "IMAGE" (in fact it works for any VM disk
276 image, not just ones built using virt-builder).
277 Note this method is deprecated: there is a separate tool for this,
279 virt-get-kernel(1), which has more options for the file extraction.
280 The kernel and initramfs are written to the current directory,
282 unless you also specify the --output "outputdir" directory name.
283 The format of the disk image is automatically detected unless you
285 specify it by using the --format option.
286 In the case where the guest contains multiple kernels, the one with
288 the highest version number is chosen. To extract arbitrary kernels
289 from the disk image, see guestfish(1). To extract the entire /boot
290 directory of a guest, see virt-copy-out(1).
291 --gpg GPG
293 Specify an alternate gpg(1) (GNU Privacy Guard) binary. By default
294 virt-builder looks for either "gpg2" or "gpg" in the $PATH.
295 You can also use this to add gpg parameters, for example to specify
297 an alternate home directory:
298 virt-builder --gpg "gpg --homedir /tmp" [...]
300 -l [os-version]
302 --list [os-version]
303 --list --list-format format [os-version]
304 --list --long [os-version]
305 List all the available templates if no guest is specified, or only
306 for the specified one.
307 It is possible to choose with --list-format the output format for
309 the list templates:
310 short
312 The default format, prints only the template identifier and,
313 next to it, its short description.
314 long
316 Prints a textual list with the details of the available
317 sources, followed by the details of the available templates.
318 json
320 Prints a JSON object with the details of the available sources
321 and the details of the available templates.
322 The "version" key in the main object represents the
324 "compatibility version", and it is bumped every time the
325 resulting JSON output is incompatible with the previous
326 versions (for example the structure has changed, or non-
327 optional keys are no more present).
328 --long is a shorthand for the "long" format.
330 See also: --source, --notes, "SOURCES OF TEMPLATES".
332 --machine-readable
334 --machine-readable=format
335 This option is used to make the output more machine friendly when
336 being parsed by other programs. See "MACHINE READABLE OUTPUT"
337 below.
338 -m MB
340 --memsize MB
341 Change the amount of memory allocated to --run scripts. Increase
342 this if you find that --run scripts or the --install option are
343 running out of memory.
344 The default can be found with this command:
346 guestfish get-memsize
348 --network
350 --no-network
351 Enable or disable network access from the guest during the
352 installation.
353 Enabled is the default. Use --no-network to disable access.
355 The network only allows outgoing connections and has other minor
357 limitations. See "NETWORK" in virt-rescue(1).
358 If you use --no-network then certain other options such as
360 --install will not work.
361 This does not affect whether the guest can access the network once
363 it has been booted, because that is controlled by your hypervisor
364 or cloud environment and has nothing to do with virt-builder.
365 Generally speaking you should not use --no-network. But here are
367 some reasons why you might want to:
368 1. Because the libguestfs backend that you are using doesn't
370 support the network. (See: "BACKEND" in guestfs(3)).
371 2. Any software you need to install comes from an attached ISO, so
373 you don't need the network.
374 3. You don’t want untrusted guest code trying to access your host
376 network when running virt-builder. This is particularly an
377 issue when you don't trust the source of the operating system
378 templates. (See "SECURITY" below).
379 4. You don’t have a host network (eg. in secure/restricted
381 environments).
382 --no-sync
384 Do not sync the output file on exit.
385 Virt-builder "fsync"s the output file or disk image when it exits.
387 The reason is that qemu/KVM’s default caching mode is "none" or
389 "directsync", both of which bypass the host page cache. Therefore
390 these would not work correctly if you immediately started the guest
391 after running virt-builder - they would not see the complete output
392 file. (Note that you should not use these caching modes - they are
393 fundamentally broken for this and other reasons.)
394 If you are not using these broken caching modes, you can use
396 --no-sync to avoid this unnecessary sync and gain considerable
397 extra performance.
398 --notes os-version
400 List any notes associated with this guest, then exit (this does not
401 do the install).
402 -o filename
404 --output filename
405 Write the output to filename. If you don’t specify this option,
406 then the output filename is generated by taking the "os-version"
407 string and adding ".img" (for raw format) or ".qcow2" (for qcow2
408 format).
409 Note that the output filename could be a device, partition or
411 logical volume.
412 When used with --get-kernel, this option specifies the output
414 directory.
415 --print-cache
417 Print information about the template cache. See "CACHING".
418 -q
420 --quiet
421 Don’t print ordinary progress messages.
422 --size SIZE
424 Select the size of the output disk, where the size can be specified
425 using common names such as "32G" (32 gigabytes) etc.
426 Virt-builder will resize filesystems inside the disk image
428 automatically.
429 If the size is not specified, then one of two things happens. If
431 the output is a file, then the size is the same as the template.
432 If the output is a device, partition, etc then the size of that
433 device is used.
434 To specify size in bytes, the number must be followed by the
436 lowercase letter b, eg: "--size 10737418240b".
437 --smp N
439 Enable N ≥ 2 virtual CPUs for --run scripts to use.
440 --source URL
442 Set the source URL to look for indexes.
443 You can give this option multiple times to specify multiple
445 sources.
446 See also "SOURCES OF TEMPLATES" below.
448 Note that you should not point --source to sources that you don’t
450 trust (unless the source is signed by someone you do trust). See
451 also the --no-network option.
452 --no-warn-if-partition
454 Do not emit a warning if the output device is a partition. This
455 warning avoids a common user error when writing to a USB key or
456 external drive, when you should normally write to the whole device
457 (--output /dev/sdX), not to a partition on the device
458 (--output /dev/sdX1). Use this option to suppress this warning.
459 -v
461 --verbose
462 Enable debug messages and/or produce verbose output.
463 When reporting bugs, use this option and attach the complete output
465 to your bug report.
466 -V
468 --version
469 Display version number and exit.
470 --wrap
472 Wrap error, warning, and informative messages. This is the default
473 when the output is a tty. If the output of the program is
474 redirected to a file, wrapping is disabled unless you use this
475 option.
476 -x Enable tracing of libguestfs API calls.
478 Customization options
480 --append-line FILE:LINE
481 Append a single line of text to the "FILE". If the file does not
482 already end with a newline, then one is added before the appended
483 line. Also a newline is added to the end of the "LINE" string
484 automatically.
485 For example (assuming ordinary shell quoting) this command:
487 --append-line '/etc/hosts:10.0.0.1 foo'
489 will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
491 the latter only if the existing file does not already end with a
492 newline.
493 "⏎" represents a newline character, which is guessed by looking at
495 the existing content of the file, so this command does the right
496 thing for files using Unix or Windows line endings. It also works
497 for empty or non-existent files.
498 To insert several lines, use the same option several times:
500 --append-line '/etc/hosts:10.0.0.1 foo'
502 --append-line '/etc/hosts:10.0.0.2 bar'
503 To insert a blank line before the appended line, do:
505 --append-line '/etc/hosts:'
507 --append-line '/etc/hosts:10.0.0.1 foo'
508 --chmod PERMISSIONS:FILE
510 Change the permissions of "FILE" to "PERMISSIONS".
511 Note: "PERMISSIONS" by default would be decimal, unless you prefix
513 it with 0 to get octal, ie. use 0700 not 700.
514 --commands-from-file FILENAME
516 Read the customize commands from a file, one (and its arguments)
517 each line.
518 Each line contains a single customization command and its
520 arguments, for example:
521 delete /some/file
523 install some-package
524 password some-user:password:its-new-password
525 Empty lines are ignored, and lines starting with "#" are comments
527 and are ignored as well. Furthermore, arguments can be spread
528 across multiple lines, by adding a "\" (continuation character) at
529 the of a line, for example
530 edit /some/file:\
532 s/^OPT=.*/OPT=ok/
533 The commands are handled in the same order as they are in the file,
535 as if they were specified as --delete /some/file on the command
536 line.
537 --copy SOURCE:DEST
539 Copy files or directories recursively inside the guest.
540 Wildcards cannot be used.
542 --copy-in LOCALPATH:REMOTEDIR
544 Copy local files or directories recursively into the disk image,
545 placing them in the directory "REMOTEDIR" (which must exist).
546 Wildcards cannot be used.
548 --delete PATH
550 Delete a file from the guest. Or delete a directory (and all its
551 contents, recursively).
552 You can use shell glob characters in the specified path. Be
554 careful to escape glob characters from the host shell, if that is
555 required. For example:
556 virt-customize --delete '/var/log/*.log'.
558 See also: --upload, --scrub.
560 --edit FILE:EXPR
562 Edit "FILE" using the Perl expression "EXPR".
563 Be careful to properly quote the expression to prevent it from
565 being altered by the shell.
566 Note that this option is only available when Perl 5 is installed.
568 See "NON-INTERACTIVE EDITING" in virt-edit(1).
570 --firstboot SCRIPT
572 Install "SCRIPT" inside the guest, so that when the guest first
573 boots up, the script runs (as root, late in the boot process).
574 The script is automatically chmod +x after installation in the
576 guest.
577 The alternative version --firstboot-command is the same, but it
579 conveniently wraps the command up in a single line script for you.
580 You can have multiple --firstboot options. They run in the same
582 order that they appear on the command line.
583 Please take a look at "FIRST BOOT SCRIPTS" for more information and
585 caveats about the first boot scripts.
586 See also --run.
588 --firstboot-command 'CMD+ARGS'
590 Run command (and arguments) inside the guest when the guest first
591 boots up (as root, late in the boot process).
592 You can have multiple --firstboot options. They run in the same
594 order that they appear on the command line.
595 Please take a look at "FIRST BOOT SCRIPTS" for more information and
597 caveats about the first boot scripts.
598 See also --run.
600 --firstboot-install PKG,PKG..
602 Install the named packages (a comma-separated list). These are
603 installed when the guest first boots using the guest’s package
604 manager (eg. apt, yum, etc.) and the guest’s network connection.
605 For an overview on the different ways to install packages, see
607 "INSTALLING PACKAGES".
608 --hostname HOSTNAME
610 Set the hostname of the guest to "HOSTNAME". You can use a dotted
611 hostname.domainname (FQDN) if you want.
612 --install PKG,PKG..
614 Install the named packages (a comma-separated list). These are
615 installed during the image build using the guest’s package manager
616 (eg. apt, yum, etc.) and the host’s network connection.
617 For an overview on the different ways to install packages, see
619 "INSTALLING PACKAGES".
620 See also --update, --uninstall.
622 --link TARGET:LINK[:LINK..]
624 Create symbolic link(s) in the guest, starting at "LINK" and
625 pointing at "TARGET".
626 --mkdir DIR
628 Create a directory in the guest.
629 This uses "mkdir -p" so any intermediate directories are created,
631 and it also works if the directory already exists.
632 --move SOURCE:DEST
634 Move files or directories inside the guest.
635 Wildcards cannot be used.
637 --no-logfile
639 Scrub "builder.log" (log file from build commands) from the image
640 after building is complete. If you don't want to reveal precisely
641 how the image was built, use this option.
642 See also: "LOG FILE".
644 --no-selinux-relabel
646 Do not attempt to correct the SELinux labels of files in the guest.
647 In such guests that support SELinux, customization automatically
649 relabels files so that they have the correct SELinux label. (The
650 relabeling is performed immediately, but if the operation fails,
651 customization will instead touch /.autorelabel on the image to
652 schedule a relabel operation for the next time the image boots.)
653 This option disables the automatic relabeling.
654 The option is a no-op for guests that do not support SELinux.
656 --password USER:SELECTOR
658 Set the password for "USER". (Note this option does not create the
659 user account).
660 See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
662 and also how to set up user accounts.
663 --password-crypto md5|sha256|sha512
665 When the virt tools change or set a password in the guest, this
666 option sets the password encryption of that password to "md5",
667 "sha256" or "sha512".
668 "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
670 the guest).
671 "md5" will work with relatively old Linux guests (eg. RHEL 3), but
673 is not secure against modern attacks.
674 The default is "sha512" unless libguestfs detects an old guest that
676 didn't have support for SHA-512, in which case it will use "md5".
677 You can override libguestfs by specifying this option.
678 Note this does not change the default password encryption used by
680 the guest when you create new user accounts inside the guest. If
681 you want to do that, then you should use the --edit option to
682 modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
683 "/etc/pam.d/common-password" (Debian, Ubuntu).
684 --root-password SELECTOR
686 Set the root password.
687 See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
689 and also how to set up user accounts.
690 Note: In virt-builder, if you don't set --root-password then the
692 guest is given a random root password.
693 --run SCRIPT
695 Run the shell script (or any program) called "SCRIPT" on the disk
696 image. The script runs virtualized inside a small appliance,
697 chrooted into the guest filesystem.
698 The script is automatically chmod +x.
700 If libguestfs supports it then a limited network connection is
702 available but it only allows outgoing network connections. You can
703 also attach data disks (eg. ISO files) as another way to provide
704 data (eg. software packages) to the script without needing a
705 network connection (--attach). You can also upload data files
706 (--upload).
707 You can have multiple --run options. They run in the same order
709 that they appear on the command line.
710 See also: --firstboot, --attach, --upload.
712 --run-command 'CMD+ARGS'
714 Run the command and arguments on the disk image. The command runs
715 virtualized inside a small appliance, chrooted into the guest
716 filesystem.
717 If libguestfs supports it then a limited network connection is
719 available but it only allows outgoing network connections. You can
720 also attach data disks (eg. ISO files) as another way to provide
721 data (eg. software packages) to the script without needing a
722 network connection (--attach). You can also upload data files
723 (--upload).
724 You can have multiple --run-command options. They run in the same
726 order that they appear on the command line.
727 See also: --firstboot, --attach, --upload.
729 --scrub FILE
731 Scrub a file from the guest. This is like --delete except that:
732 • It scrubs the data so a guest could not recover it.
734 • It cannot delete directories, only regular files.
736 --selinux-relabel
738 This is a compatibility option that does nothing.
739 --sm-attach SELECTOR
741 Attach to a pool using "subscription-manager".
742 See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
744 --sm-credentials SELECTOR
746 Set the credentials for "subscription-manager".
747 See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
749 --sm-register
751 Register the guest using "subscription-manager".
752 This requires credentials being set using --sm-credentials.
754 --sm-remove
756 Remove all the subscriptions from the guest using
757 "subscription-manager".
758 --sm-unregister
760 Unregister the guest using "subscription-manager".
761 --ssh-inject USER[:SELECTOR]
763 Inject an ssh key so the given "USER" will be able to log in over
764 ssh without supplying a password. The "USER" must exist already in
765 the guest.
766 See "SSH KEYS" for the format of the "SELECTOR" field.
768 You can have multiple --ssh-inject options, for different users and
770 also for more keys for each user.
771 --timezone TIMEZONE
773 Set the default timezone of the guest to "TIMEZONE". Use a
774 location string like "Europe/London"
775 --touch FILE
777 This command performs a touch(1)-like operation on "FILE".
778 --truncate FILE
780 This command truncates "FILE" to a zero-length file. The file must
781 exist already.
782 --truncate-recursive PATH
784 This command recursively truncates all files under "PATH" to zero-
785 length.
786 --uninstall PKG,PKG..
788 Uninstall the named packages (a comma-separated list). These are
789 removed during the image build using the guest’s package manager
790 (eg. apt, yum, etc.). Dependent packages may also need to be
791 uninstalled to satisfy the request.
792 See also --install, --update.
794 --update
796 Do the equivalent of "yum update", "apt-get upgrade", or whatever
797 command is required to update the packages already installed in the
798 template to their latest versions.
799 See also --install, --uninstall.
801 --upload FILE:DEST
803 Upload local file "FILE" to destination "DEST" in the disk image.
804 File owner and permissions from the original are preserved, so you
805 should set them to what you want them to be in the disk image.
806 "DEST" could be the final filename. This can be used to rename the
808 file on upload.
809 If "DEST" is a directory name (which must already exist in the
811 guest) then the file is uploaded into that directory, and it keeps
812 the same name as on the local filesystem.
813 See also: --mkdir, --delete, --scrub.
815 --write FILE:CONTENT
817 Write "CONTENT" to "FILE".
818
820 INSTALLING PACKAGES
821 There are several approaches to installing packages or applications in
822 the guest which have different trade-offs.
823 Installing packages at build time
825 If the guest OS you are installing is similar to the host OS (eg. both
827 are Linux), and if libguestfs supports network connections, then you
828 can use --install to install packages like this:
829 virt-builder fedora-27 --install inkscape
831 This uses the guest’s package manager and the host’s network
833 connection.
834 Updating packages at build time
836 To update the installed packages in the template at build time:
838 virt-builder fedora-27 --update
840 Most of the templates that ship with virt-builder come with a very
842 minimal selection of packages (known as a "JEOS" or "Just Enough
843 Operating System"), which are up to date at the time the template is
844 created, but could be out of date by the time you come to install an OS
845 from the template. This option updates those template packages.
846 Installing packages at first boot
848 Another option is to install the packages when the guest first boots:
850 virt-builder fedora-27 --firstboot-install inkscape
852 This uses the guest’s package manager and the guest’s network
854 connection.
855 The downsides are that it will take the guest a lot longer to boot
857 first time, and there’s nothing much you can do if package installation
858 fails (eg. if a network problem means the guest can't reach the package
859 repositories).
860 Installing packages at build time from a side repository
862 If the software you want to install is not available in the main
864 package repository of the guest, then you can add a side repository.
865 Usually this is presented as an ISO (CD disk image) file containing
866 extra packages.
867 You can create the disk image using either genisoimage(1) or
869 virt-make-fs(1). For genisoimage, use a command like this:
870 genisoimage -o extra-packages.iso -R -J -V EXTRA cdcontents/
872 Create a script that mounts the ISO and sets up the repository. For
874 dnf, create /tmp/install.sh containing:
875 mkdir /tmp/mount
877 mount LABEL=EXTRA /tmp/mount
878 cat <<'EOF' > /etc/yum.repos.d/extra.repo
880 [extra]
881 name=extra
882 baseurl=file:///tmp/mount
883 enabled=1
884 EOF
885 dnf -y install famousdatabase
887 For apt, create /tmp/install.sh containing:
889 mkdir /tmp/mount
891 mount LABEL=EXTRA /tmp/mount
892 apt-cdrom -d=/tmp/mount add
894 apt-get -y install famousdatabase
895 Use the --attach option to attach the CD / disk image and the --run
897 option to run the script:
898 virt-builder fedora-27 \
900 --attach extra-packages.iso \
901 --run /tmp/install.sh
902 USERS AND PASSWORDS
904 The --root-password option is used to change the root password
905 (otherwise a random password is used). This option takes a password
906 "SELECTOR" in one of the following formats:
907 --root-password file:FILENAME
909 Read the root password from "FILENAME". The whole first line of
910 this file is the replacement password. Any other lines are
911 ignored. You should create the file with mode 0600 to ensure no
912 one else can read it.
913 --root-password password:PASSWORD
915 Set the root password to the literal string "PASSWORD".
916 Note: this is not secure since any user on the same machine can see
918 the cleartext password using ps(1).
919 --root-password random
921 Choose a random password, which is printed on stdout. The password
922 has approximately 120 bits of randomness.
923 This is the default.
925 --root-password disabled
927 The root account password is disabled. This is like putting "*" in
928 the password field.
929 --root-password locked:file:FILENAME
931 --root-password locked:password:PASSWORD
932 --root-password locked:random
933 The root account is locked, but a password is placed on the
934 account. If first unlocked (using "passwd -u") then logins will
935 use the given password.
936 --root-password locked
938 --root-password locked:disabled
939 The root account is locked and password is disabled.
940 Creating user accounts
942 To create user accounts, use the useradd(8) command with
944 --firstboot-command like this:
945 virt-builder --firstboot-command \
947 'useradd -m -p "" rjones ; chage -d 0 rjones'
948 The above command will create an "rjones" account with no password, and
950 force the user to set a password when they first log in. There are
951 other ways to manage passwords, see useradd(8) for details.
952 KEYBOARD LAYOUT
954 Because there are so many different ways to set the keyboard layout in
955 Linux distributions, virt-builder does not yet attempt to have a simple
956 command line option. This section describes how to set the keyboard
957 for some common Linux distributions.
958 Keyboard layout with systemd
960 For distros that use systemd "localectl", use a command like this:
962 virt-builder fedora-27 \
964 --firstboot-command 'localectl set-keymap uk'
965 See localectl(1) and
967 https://www.happyassassin.net/2013/11/23/keyboard-layouts-in-fedora-20-and-previously/
968 for more details.
969 Keyboard layout using /etc/sysconfig/keyboard
971 For RHEL ≤ 6, Fedora ≤ 18 and similar, upload or modify the keyboard
973 configuration file using the --upload, --write or --edit options. For
974 example:
975 virt-builder centos-6 \
977 --edit '/etc/sysconfig/keyboard: s/^KEYTABLE=.*/KEYTABLE="uk"/'
978 The format of this file can be found documented in many places online.
980 Keyboard layout with Debian-derived distros
982 For Debian-derived distros using /etc/default/keyboard, upload or
984 modify the keyboard file using the --upload, --write or --edit options.
985 For example:
986 virt-builder debian-8 \
988 --edit '/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/'
989 See https://wiki.debian.org/Keyboard.
991 LANGUAGE
993 Most Linux distributions support multiple locale settings so that you
994 can have guest messages printed in another language such as Russian.
995 However there is no single setting which controls this, since extra
997 packages may need to be installed to support console and X fonts, and
998 keyboard input methods. The packages required, and their configuration
999 is highly distro-specific, and it is outside the scope of virt-builder
1000 to do this.
1001 This section contains examples for some common Linux distributions.
1003 Setting Japanese in Fedora 25
1005 virt-builder fedora-27 \
1007 --size 20G \
1008 --update \
1009 --install @japanese-support \
1010 --install @xfce \
1011 --install xorg-x11-server-Xorg,xorg-x11-drivers,rsyslog \
1012 --link /usr/lib/systemd/system/graphical.target:/etc/systemd/system/default.target \
1013 --firstboot-command 'localectl set-locale LANG=ja_JP.utf8' \
1014 --firstboot-command 'localectl set-keymap jp' \
1015 --firstboot-command 'systemctl isolate graphical.target'
1016 Setting Japanese in Debian 8 (Jessie)
1018 Note that although this enables Japanese in the text console too, it is
1020 unlikely that you will see properly rendered Japanese there. However
1021 Japanese is properly rendered in X applications and terminals.
1022 pkgs=locales,xfce4,\
1024 ibus,ibus-anthy,\
1025 fonts-ipafont-gothic,fonts-ipafont-mincho,\
1026 fonts-takao-mincho,\
1027 xfonts-intl-japanese,xfonts-intl-japanese-big,\
1028 iceweasel-l10n-ja,manpages-ja
1029 virt-builder debian-8 \
1031 --size 20G \
1032 --install $pkgs \
1033 --edit '/etc/locale.gen: s,^#\s*ja,ja,' \
1034 --write '/etc/default/locale:LANG="ja_JP.UTF-8"' \
1035 --run-command "locale-gen"
1036 LOG FILE
1038 Scripts and package installation that runs at build time (--run,
1039 --run-command, --install, --update, but not firstboot) is logged in one
1040 of the following locations:
1041 /tmp/builder.log
1043 On Linux, BSD, and other non-Windows guests.
1044 C:\Temp\builder.log
1046 On Windows, DOS guests.
1047 /builder.log
1049 If /tmp or C:\Temp is missing.
1050 If you don’t want the log file to appear in the final image, then use
1052 the --no-logfile command line option.
1053 SSH KEYS
1055 The --ssh-inject option is used to inject ssh keys for users in the
1056 guest, so they can login without supplying a password.
1057 The "SELECTOR" part of the option value is optional; in this case,
1059 --ssh-inject "USER" means that we look in the current user’s ~/.ssh
1060 directory to find the default public ID file. That key is uploaded.
1061 "default public ID" is the default_ID_file file described in
1062 ssh-copy-id(1).
1063 If specified, the "SELECTOR" can be in one of the following formats:
1065 --ssh-inject USER:file:FILENAME
1067 Read the ssh key from FILENAME. FILENAME is usually a .pub file.
1068 --ssh-inject USER:string:KEY_STRING
1070 Use the specified "KEY_STRING". "KEY_STRING" is usually a public
1071 string like ssh-rsa AAAA.... user@localhost.
1072 In any case, the ~USER/.ssh directory and the
1074 ~USER/.ssh/authorized_keys file will be created if not existing
1075 already.
1076 FIRST BOOT SCRIPTS
1078 The --firstboot and --firstboot-command options allow you to execute
1079 commands at the first boot of the guest. To do so, an init script for
1080 the guest init system is installed, which takes care of running all the
1081 added scripts and commands.
1082 Supported operating systems are:
1084 Linux
1086 Init systems supported are: systemd, System-V init (known also as
1087 sysvinit), and Upstart (using the System-V scripts).
1088 Note that usually init scripts run as root, but with a more limited
1090 environment than what could be available from a normal shell: for
1091 example, $HOME may be unset or empty.
1092 The output of the first boot scripts is available in the guest as
1094 ~root/virt-sysprep-firstboot.log.
1095 Windows
1097 rhsrvany.exe, available from sources at
1098 https://github.com/rwmjones/rhsrvany, or pvvxsvc.exe, available
1099 with SUSE VMDP is installed to run the first boot scripts. It is
1100 required, and the setup of first boot scripts will fail if it is
1101 not present.
1102 rhsrvany.exe or pvvxsvc.exe is copied from the location pointed to
1104 by the "VIRT_TOOLS_DATA_DIR" environment variable; if not set, a
1105 compiled-in default will be used (something like
1106 /usr/share/virt-tools).
1107 The output of the first boot scripts is available in the guest as
1109 C:\Program Files\Guestfs\Firstboot\log.txt.
1110 SUBSCRIPTION-MANAGER
1112 It is possible to automate the registration and attaching of the system
1113 using "subscription-manager". This is typical on Red Hat Enterprise
1114 Linux guests. There are few options which ease this process, avoid
1115 executing commands manually and exposing passwords on command line.
1116 --sm-register starts the registration process, and requires
1118 --sm-credentials to be specified; the format of the "SELECTOR" of
1119 --sm-credentials is one of the following formats:
1120 --sm-credentials USER:file:FILENAME
1122 Read the password for the specified "USER" from FILENAME.
1123 --sm-credentials USER:password:PASSWORD
1125 Use the literal string "PASSWORD" for the specified "USER".
1126 --sm-attach attaches the system to subscriptions; the format of its
1128 "SELECTOR" is one of the following:
1129 --sm-attach auto
1131 "subscription-manager" attaches to the best-fitting subscriptions
1132 for the system.
1133 --sm-attach file:FILENAME
1135 Read the pool ID from FILENAME.
1136 --sm-attach pool:POOL
1138 Use the literal string "POOL" as pool ID.
1139 --sm-remove removes all the subscriptions from the guest, while
1141 --sm-unregister completely unregister the system.
1142 INSTALLATION PROCESS
1144 When you invoke virt-builder, installation proceeds as follows:
1145 • The template image is downloaded.
1147 If the template image is present in the cache, the cached version
1149 is used instead. (See "CACHING").
1150 • The template signature is checked.
1152 • The template is uncompressed to a tmp file.
1154 • The template image is resized into the destination, using
1156 virt-resize(1).
1157 • Extra disks are attached (--attach).
1159 • A new random seed is generated for the guest.
1161 • Guest customization is performed, in the order specified on the
1163 command line.
1164 • SELinux relabelling is done unless disabled with
1166 --no-selinux-relabel.
1167 IMPORTING THE DISK IMAGE
1169 Importing into libvirt
1170 Import the disk image into libvirt using virt-install(1) --import
1172 option.
1173 virt-install --import \
1175 --name guest --ram 2048 \
1176 --disk path=disk.img,format=raw --os-variant fedora27
1177 Notes:
1179 1. You must specify the correct format. The format is "raw" unless
1181 you used virt-builder’s --format option.
1182 2. --os-variant is highly recommended, because it will present optimum
1184 devices to enable the guest to run most efficiently. To get a list
1185 of all variants, do:
1186 osinfo-query os
1188 The above tool is provided by libosinfo package.
1190 3. You can run virt-install as root or non-root. Each works slightly
1192 differently because libvirt manages a different set of virtual
1193 machines for each user. In particular virt-manager normally shows
1194 the root-owned VMs, whereas Boxes shows the user-owned VMs, and
1195 other tools probably work differently as well.
1196 Importing into OpenStack
1198 Import the image into Glance (the OpenStack image store) by doing:
1200 glance image-create --name fedora-27-image --file fedora-27.img \
1202 --disk-format raw --container-format bare \
1203 --is-public True
1204 The --file parameter is the virt-builder-generated disk image. It
1206 should match virt-builder’s --output option. The --disk-format
1207 parameter should match virt-builder’s --format option (or "raw" if you
1208 didn't use that option). The --container-format should always be
1209 "bare" since virt-builder doesn't put images into containers.
1210 You can use the "glance image-show fedora-27-image" command to display
1212 the properties of the image.
1213 To boot up an instance of your image on a Nova compute node, do:
1215 nova boot fedora-27-server --image fedora-27-image \
1217 --flavor m1.medium
1218 Use "nova flavor-list" to list possible machine flavors. Use
1220 "nova list" to list running instances.
1221 Booting directly using qemu or KVM
1223 The qemu command line is not very stable or easy to use, hence libvirt
1225 should be used if possible. However a command line similar to the
1226 following could be used to boot the virtual machine:
1227 qemu-system-x86_64 \
1229 -machine accel=kvm:tcg \
1230 -cpu host \
1231 -m 2048 \
1232 -drive file=disk.img,format=raw,if=virtio
1233 As with libvirt, it is very important that the correct format is
1235 chosen. It will be "raw" unless the --format option was used.
1236 CONFIGURATION MANAGEMENT
1238 Puppet
1239 To enable the Puppet agent in a guest, install the package, point the
1241 configuration at your Puppetmaster, and ensure the agent runs at boot.
1242 A typical virt-builder command would be:
1244 virt-builder fedora-27 \
1246 --hostname client.example.com \
1247 --update \
1248 --install puppet \
1249 --append-line '/etc/puppet/puppet.conf:[agent]' \
1250 --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
1251 --run-command 'systemctl enable puppet'
1252 The precise instructions vary according to the Linux distro. For
1254 further information see:
1255 https://docs.puppet.com/puppet/latest/install_pre.html
1256 DEBUGGING BUILDS
1258 If virt-builder itself fails, then enable debugging (-v) and report a
1259 bug (see "BUGS" below).
1260 If virt-builder fails because some script or package it is installing
1262 fails, try using --no-delete-on-failure to preserve the output file,
1263 and continue reading this section.
1264 If virt-builder is successful but the image doesn't work, here are some
1266 things to try:
1267 Use virt-rescue
1269 Run virt-rescue(1) on the disk image:
1270 virt-rescue -a disk.img
1272 This gives you a rescue shell. You can mount the filesystems from
1274 the disk image on /sysroot and examine them using ordinary Linux
1275 commands. You can also chroot into the guest to reinstall the
1276 bootloader. The virt-rescue man page has a lot more information
1277 and examples.
1278 Use guestfish
1280 Run guestfish(1) on the disk image:
1281 guestfish -a disk.img -i
1283 Use guestfish commands like "ll /directory" and "cat /file" to
1285 examine directories and files.
1286 Use guestmount
1288 Mount the disk image safely on the host using FUSE and
1289 guestmount(1):
1290 mkdir /tmp/mp
1292 guestmount -a disk.img -i /tmp/mp
1293 cd /tmp/mp
1294 To unmount the disk image do:
1296 fusermount -u /tmp/mp
1298 Add a serial console
1300 If the guest hangs during boot, it can be helpful to add a serial
1301 console to the guest, and direct kernel messages to the serial
1302 console. Adding the serial console will involve looking at the
1303 documentation for your hypervisor. To direct kernel messages to
1304 the serial console, add the following on the kernel command line:
1305 console=tty0 console=ttyS0,115200
1307 SOURCES OF TEMPLATES
1309 virt-builder reads the available sources from configuration files, with
1310 the .conf extension and located in the following paths:
1311 • $XDG_CONFIG_HOME/virt-builder/repos.d/ ($XDG_CONFIG_HOME is
1313 $HOME/.config if not set).
1314 • $VIRT_BUILDER_DIRS/virt-builder/repos.d/ (where $VIRT_BUILDER_DIRS
1316 means any of the directories in that environment variable, or just
1317 /etc if not set).
1318 Each .conf file in those paths has a simple text format like the
1320 following:
1321 [libguestfs.org]
1323 uri=http://libguestfs.org/download/builder/index.asc
1324 gpgkey=file:///etc/xdg/virt-builder/repos.d/libguestfs.gpg
1325 The part in square brackets is the repository identifier, which is used
1327 as unique identifier.
1328 The following fields can appear:
1330 "uri=URI"
1332 The URI of the index file which this repository refers to.
1333 This field is required.
1335 "gpgkey=URI"
1337 This optional field represents the URI (although only file:// URIs
1338 are accepted) of the key used to sign the index file. If not
1339 present, the index file referred by uri=.. is not signed.
1340 "proxy=MODE"
1342 This optional field specifies the proxy mode, to be used when
1343 downloading the index file of this repository. The possible values
1344 are:
1345 no, off
1347 No proxy is being used at all, even overriding the system
1348 configuration.
1349 system
1351 The proxy used is the system one.
1352 anything else
1354 Specifies the actual proxy configuration to be used, overriding
1355 the system configuration.
1356 If not present, the assumed value is to respect the proxy settings
1358 of the system (i.e. as if system would be specified).
1359 "format=FORMAT"
1361 This optional field specifies the format of the repository. The
1362 possible values are:
1363 native
1365 The native format of the "virt-builder" repository. See also
1366 "Creating and signing the index file" below.
1367 simplestreams
1369 The URI represents the root of a Simple Streams v1.0 tree of
1370 metadata.
1371 For more information about Simple Streams, see also
1373 https://launchpad.net/simplestreams.
1374 If not present, the assumed value is "native".
1376 For serious virt-builder use, you may want to create your own
1378 repository of templates.
1379 Libguestfs.org repository
1381 Out of the box, virt-builder downloads the file
1383 http://libguestfs.org/download/builder/index.asc which is an index of
1384 available templates plus some information about each one, wrapped up in
1385 a digital signature. The command "virt-builder --list" lists out the
1386 information in this index file.
1387 The templates hosted on libguestfs.org were created using shell
1389 scripts, kickstart files and preseed files which can be found in the
1390 libguestfs source tree, in "builder/templates".
1391 Setting up the repository
1393 You can set up your own site containing an index file and some
1395 templates, and then point virt-builder at the site by creating a .conf
1396 file pointing to it.
1397 Note that if your index is signed, you will need to properly fill
1399 gpgkey=.. in your .conf file, making sure to deploy also the GPG key
1400 file.
1401 virt-builder --source https://example.com/builder/index.asc \
1403 --fingerprint 'AAAA BBBB ...' \
1404 --list
1405 You can host this on any web or FTP server, or a local or network
1407 filesystem.
1408 Setting up a GPG key
1410 If you don’t have a GnuPG key, you will need to set one up. (Strictly
1412 speaking this is optional, but if your index and template files are not
1413 signed then virt-builder users will have to use the
1414 --no-check-signature flag every time they use virt-builder.)
1415 To create a key, see the GPG manual
1417 http://www.gnupg.org/gph/en/manual.html.
1418 Export your GPG public key:
1420 gpg --export -a "you@example.com" > pubkey
1422 Create the templates
1424 There are many ways to create the templates. For example you could
1426 clone existing guests (see virt-sysprep(1)), or you could install a
1427 guest by hand (virt-install(1)). To see how the templates were created
1428 for virt-builder, look at the scripts in "builder/templates"
1429 Virt-builder supports any image format (e.g. raw, qcow2, etc) as
1431 template, both as-is, and compressed as XZ. This way, existing images
1432 (e.g. cleaned using virt-sysprep(1)) can be used as templates.
1433 For best results when compressing the templates, use the following xz
1435 options (see nbdkit-xz-plugin(1) for further explanation):
1436 xz --best --block-size=16777216 disk
1438 Creating and signing the index file
1440 The index file has a simple text format (shown here without the digital
1442 signature):
1443 [fedora-18]
1445 name=Fedora® 18
1446 osinfo=fedora18
1447 arch=x86_64
1448 file=fedora-18.xz
1449 checksum[sha512]=...
1450 format=raw
1451 size=6442450944
1452 compressed_size=148947524
1453 expand=/dev/sda3
1454 [fedora-19]
1456 name=Fedora® 19
1457 osinfo=fedora19
1458 arch=x86_64
1459 file=fedora-19.xz
1460 checksum[sha512]=...
1461 revision=3
1462 format=raw
1463 size=4294967296
1464 compressed_size=172190964
1465 expand=/dev/sda3
1466 The part in square brackets is the "os-version", which is the same
1468 string that is used on the virt-builder command line to build that OS.
1469 The index file creation and signature can be eased with the
1471 virt-builder-repository(1) tool.
1472 After preparing the "index" file in the correct format, clearsign it
1474 using the following command:
1475 gpg --clearsign --armor index
1477 This will create the final file called index.asc which can be uploaded
1479 to the server (and is the uri=.. URL). As noted above, signing the
1480 index file is optional, but recommended.
1481 The following fields can appear:
1483 "name=NAME"
1485 The user-friendly name of this template. This is displayed in the
1486 --list output but is otherwise not significant.
1487 "osinfo=ID"
1489 This optional field maps the operating system to the associated
1490 libosinfo ID. Virt-builder does not use it (yet).
1491 "arch=ARCH"
1493 The architecture of the operating system installed within the
1494 template. This field is required.
1495 "file=PATH"
1497 The path (relative to the index) of the xz-compressed template.
1498 Note that absolute paths or URIs are not permitted here. This is
1500 because virt-builder has a "same origin" policy for templates so
1501 they cannot come from other servers.
1502 "sig=PATH"
1504 This option is deprecated. Use the checksum field instead.
1505 The path (relative to the index) of the GPG detached signature of
1507 the xz file.
1508 Note that absolute paths or URIs are not permitted here. This is
1510 because virt-builder has a "same origin" policy for templates so
1511 they cannot come from other servers.
1512 The file can be created as follows:
1514 gpg --detach-sign --armor -o disk.xz.sig disk.xz
1516 "checksum[sha512]=7b882fe9b82eb0fef..."
1518 The SHA-512 checksum of the file specified in file=.. is checked
1519 after it is downloaded. To work out the signature, do:
1520 sha512sum disk.xz
1522 Note if you use this, you don’t need to sign the file, ie. don’t
1524 use "sig". This option overrides "sig".
1525 "checksum=7b882fe9b82eb0fef..."
1527 "checksum" is an alias for "checksum[sha512]".
1528 If you need to interoperate with virt-builder = 1.24.0 then you
1530 have to use "checksum" because that version would give a parse
1531 error with square brackets and numbers in the key of a field. This
1532 is fixed in virt-builder ≥ 1.24.1.
1533 "revision=N"
1535 The revision is an integer which is used to control the template
1536 cache. Increasing the revision number causes clients to download
1537 the template again even if they have a copy in the cache.
1538 The revision number is optional. If omitted it defaults to 1.
1540 "format=raw"
1542 "format=qcow2"
1543 Specify the format of the disk image; in case it is compressed,
1544 that is the format before the compression. If not given, the
1545 format is autodetected, but generally it is better to be explicit
1546 about the intended format.
1547 Note this is the source format, which is different from the
1549 --format option (requested output format). Virt-builder does on-
1550 the-fly conversion from the source format to the requested output
1551 format.
1552 "size=NNN"
1554 The virtual size of the image in bytes. This is the size of the
1555 image when uncompressed. If using a non-raw format such as qcow2
1556 then it means the virtual disk size, not the size of the qcow2
1557 file.
1558 This field is required.
1560 Virt-builder also uses this as the minimum size that users can
1562 request via the --size option, or as the default size if there is
1563 no --size option.
1564 "compressed_size=NNN"
1566 The actual size of the disk image in bytes, i.e. what was specified
1567 in file=... This is just used for information (when using "long",
1568 and "json" formats of --list).
1569 "expand=/dev/sdaX"
1571 When expanding the image to its final size, instruct virt-resize(1)
1572 to expand the named partition in the guest image to fill up all
1573 available space. This works like the virt-resize --expand option.
1574 You should usually put the device name of the guest’s root
1576 filesystem here.
1577 It’s a good idea to use this, but not required. If the field is
1579 omitted then virt-resize will create an extra partition at the end
1580 of the disk to cover the free space, which is much less user-
1581 friendly.
1582 "lvexpand=/dev/VolGroup/LogVol"
1584 When expanding the image to its final size, instruct virt-resize(1)
1585 to expand the named logical volume in the guest image to fill up
1586 all available space. This works like the virt-resize --lv-expand
1587 option.
1588 If the guest uses LVM2 you should usually put the LV of the guest’s
1590 root filesystem here. If the guest does not use LVM2 or its root
1591 filesystem is not on an LV, don't use this option.
1592 "notes=NOTES"
1594 Any notes that go with this image, especially notes describing what
1595 packages are in the image, how the image was prepared, and
1596 licensing information.
1597 This information is shown in the --notes and --list --long modes.
1599 You can use multi-line notes here by indenting each new line with
1601 at least one character of whitespace (even on blank lines):
1602 notes=This image was prepared using
1604 the following kickstart script:
1605 <-- one space at beginning of line
1606 part /boot --fstype ext3
1607 ...
1608 "hidden=true"
1610 Using the hidden flag prevents the template from being listed by
1611 the --list option (but it is still installable). This is used for
1612 test images.
1613 "aliases=ALIAS1 ALIAS2 ..."
1615 This optional field specifies a list of aliases, separated by
1616 spaces, for the image. For example, an alias could be used to
1617 always point to the latest version of a certain image, leaving the
1618 old versions available in the index instead of updating the same
1619 image (see the "revision" field).
1620 Running virt-builder against multiple sources
1622 It is possible to use multiple sources with virt-builder. The
1624 recommended way is to deploy .conf files pointing to the index files.
1625 Another way is to specify the sources using multiple --source and/or
1626 --fingerprint options:
1627 virt-builder \
1629 --source http://example.com/s1/index.asc \
1630 --source http://example.com/s2/index.asc
1631 You can provide N or 1 fingerprints. In the case where you provide N
1633 fingerprints, N = number of sources and there is a 1-1 correspondence
1634 between each source and each fingerprint:
1635 virt-builder \
1637 --source http://example.com/s1/index.asc --fingerprint '0123 ...' \
1638 --source http://example.com/s2/index.asc --fingerprint '9876 ...'
1639 In the case where you provide 1 fingerprint, the same fingerprint is
1641 used for all sources.
1642 You "must" provide at least 1 fingerprint.
1644 Licensing of templates
1646 You should be aware of the licensing of images that you distribute.
1648 For open source guests, provide a link to the source code in the
1649 "notes" field and comply with other requirements (eg. around
1650 trademarks).
1651 Formal specification of the index file
1653 The index file format has a formal specification defined by the flex
1655 scanner and bison parser used to parse the file. This can be found in
1656 the following files in the libguestfs source tree:
1657 builder/index-scan.l
1659 builder/index-parse.y
1660 A tool called virt-index-validate(1) is available to validate the index
1662 file to ensure it is correct.
1663 Note that the parser and tool can work on either the signed or unsigned
1665 index file (ie. index or index.asc).
1666 The index is always encoded in UTF-8.
1668 CACHING
1670 Caching templates
1671 Since the templates are usually very large, downloaded templates are
1673 cached in the user’s home directory.
1674 The location of the cache is $XDG_CACHE_HOME/virt-builder/ or
1676 $HOME/.cache/virt-builder.
1677 You can print out information about the cache directory, including
1679 which guests are currently cached, by doing:
1680 virt-builder --print-cache
1682 The cache can be deleted if you want to save space by doing:
1684 virt-builder --delete-cache
1686 You can download all (current) templates to the local cache by doing:
1688 virt-builder --cache-all-templates
1690 To disable the template cache, use --no-cache.
1692 Only templates are cached. The index and detached digital signatures
1694 are not cached.
1695 Caching packages
1697 Virt-builder uses curl(1) to download files and it also uses the
1699 current "http_proxy" (etc) settings when installing packages
1700 (--install, --update).
1701 You may therefore want to set those environment variables in order to
1703 maximize the amount of local caching that happens. See "ENVIRONMENT
1704 VARIABLES" and curl(1).
1705 Local mirrors
1707 To increase both speed and reliability of installing packages, you can
1709 set up a local mirror of the target distribution, and point the guest
1710 package manager at that.
1711 Using a local mirror with Fedora
1713 To install a Fedora guest using a local mirror:
1715 virt-builder fedora-27 \
1717 --edit '/etc/yum.repos.d/fedora.repo:
1718 s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
1719 s{.*metalink=.*}{};
1720 ' \
1721 --edit '/etc/yum.repos.d/fedora-updates.repo:
1722 s{.*baseurl=.*}{baseurl=http://example.com/mirror-updates/};
1723 s{.*metalink=.*}{};
1724 ' \
1725 --run-command 'dnf -y update' \
1726 --install 'pkg1,pkg2,...'
1727 Using a local mirror with Debian
1729 Assuming that you are using "apt-proxy" to mirror the repository, you
1731 should create a new sources.list file to point to your proxy (see
1732 https://help.ubuntu.com/community/AptProxy) and then do:
1733 virt-builder debian-8 \
1735 --upload sources.list:/etc/apt/sources.list \
1736 --run-command 'apt-get -y update' \
1737 --install 'pkg1,pkg2,...'
1738 DIGITAL SIGNATURES
1740 Virt-builder uses GNU Privacy Guard (GnuPG or gpg) to verify that the
1741 index and templates have not been tampered with.
1742 The source points to an index file, which is optionally signed.
1744 Virt-builder downloads the index and checks that the signature is valid
1746 and the signer’s fingerprint matches the specified fingerprint (ie. the
1747 one specified in gpgkey=.. in the .conf, or with --fingerprint, in that
1748 order).
1749 For checking against the built-in public key/fingerprint, this requires
1751 importing the public key into the user’s local gpg keyring (that’s just
1752 the way that gpg works).
1753 When a template is downloaded, its signature is checked in the same
1755 way.
1756 Although the signatures are optional, if you don’t have them then virt-
1758 builder users will have to use --no-check-signature on the command
1759 line. This prevents an attacker from replacing the signed index file
1760 with an unsigned index file and having virt-builder silently work
1761 without checking the signature. In any case it is highly recommended
1762 that you always create signed index and templates.
1763 ARCHITECTURE
1765 Virt-builder can build a guest for any architecture no matter what the
1766 host architecture is. For example an x86-64 guest on an ARM host.
1767 However certain options may not work, specifically options that require
1769 running commands in the guest during the build process: --install,
1770 --update, --run, --run-command. You may need to replace these with
1771 their firstboot-equivalents.
1772 An x86-64 host building 32 bit i686 guests should work without any
1774 special steps.
1775 SECURITY
1777 Virt-builder does not need to run as root (in fact, should not be run
1778 as root), and doesn't use setuid, "sudo" or any similar mechanism.
1779 --install, --update, --run and --run-command are implemented using an
1781 appliance (a small virtual machine) so these commands do not run on the
1782 host. If you are using the libguestfs libvirt backend and have SELinux
1783 enabled then the virtual machine is additionally encapsulated in an
1784 SELinux container (sVirt).
1785 However these options will have access to the host’s network and since
1787 the template may contain untrusted code, the code might try to access
1788 host network resources which it should not. You can use --no-network
1789 to prevent this.
1790 Firstboot commands run in the context of the guest when it is booted,
1792 and so the security of your hypervisor / cloud should be considered.
1793 Virt-builder injects a random seed into every guest which it builds.
1795 This helps to ensure that TCP sequence numbers, UUIDs, ssh host keys
1796 etc are truly random when the guest boots.
1797 You should check digital signatures and not ignore any signing errors.
1799 CLONES
1801 If you wish to create many new guests of the same type, it is tempting
1802 to run virt-builder once and then copy the output file. You should not
1803 do this. You should run virt-builder once for each new guest you need.
1804 The reason is that each clone needs to have (at least) a separate
1806 random seed, and possibly other unique features (such as filesystem
1807 UUIDs) in future versions of virt-builder.
1808 Another thing you should not do is to boot the guest, then clone the
1810 booted disk image. The reason is that some guests create unique
1811 machine IDs, SSH host keys and so on at first boot, and you would not
1812 want clones to have duplicate identities.
1813 See also: virt-sysprep(1).
1815 PERFORMANCE
1817 The most important aspect of getting good performance is caching.
1818 Templates gets downloaded into the cache the first time they are used,
1819 or if you use the --cache-all-templates option. See "CACHING" above
1820 for further information.
1821 Packages required for the --install and --update options are downloaded
1823 using the host network connection. Setting the "http_proxy",
1824 "https_proxy" and "ftp_proxy" environment variables to point to a local
1825 web cache may ensure they only need to be downloaded once. You can
1826 also try using a local package repository, although this can be complex
1827 to set up and varies according to which Linux distro you are trying to
1828 install.
1829 Using --no-sync
1831 Use --no-sync. However read the caveats in the "OPTIONS" section
1833 above, since this can cause disk corruption if not used correctly.
1834 Skipping virt-resize
1836 Virt-builder can skip the virt-resize step under certain conditions.
1838 This makes virt-builder much faster. The conditions are:
1839 • the output must be a regular file (not a block device), and
1841 • the user did not use the --size option, and
1843 • the output format is the same as the template format (usually raw).
1845 pxzcat
1847 Virt-builder uses an internal implementation of pxzcat (parallel xzcat)
1849 if liblzma was found at build time. If liblzma was not found at build
1850 time, regular "xzcat" is used which is single-threaded.
1851 SELINUX
1853 Guests which use SELinux (such as Fedora and Red Hat Enterprise Linux)
1854 require that each file has a correct SELinux label.
1855 Virt-builder does not know how to give new files a label, so there are
1857 two possible strategies it can use to ensure correct labelling:
1858 Automatic relabeling
1860 This runs setfiles(8) just before finalizing the guest, which sets
1861 SELinux labels correctly in the disk image.
1862 This is the recommended method.
1864 Using --no-selinux-relabel --touch /.autorelabel
1866 Guest templates may already contain a file called /.autorelabel or
1867 you may touch it.
1868 For guests that use SELinux, this causes restorecon(8) to run at
1870 first boot. Guests will reboot themselves once the first time you
1871 use them, which is normal and harmless.
1872
1874 The --machine-readable option can be used to make the output more
1875 machine friendly, which is useful when calling virt-builder from other
1876 programs, GUIs etc.
1877 Use the option on its own to query the capabilities of the virt-builder
1879 binary. Typical output looks like this:
1880 $ virt-builder --machine-readable
1882 virt-builder
1883 arch
1884 config-file
1885 customize
1886 json-list
1887 pxzcat
1888 A list of features is printed, one per line, and the program exits with
1890 status 0.
1891 It is possible to specify a format string for controlling the output;
1893 see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
1894
1896 For other environment variables which affect all libguestfs programs,
1897 see "ENVIRONMENT VARIABLES" in guestfs(3).
1898 "http_proxy"
1900 "https_proxy"
1901 "no_proxy"
1902 Set the proxy for downloads. These environment variables (and
1903 more) are actually interpreted by curl(1), not virt-builder.
1904 "HOME"
1906 Used to determine the location of the template cache, and the
1907 location of the user' sources. See "CACHING" and "SOURCES OF
1908 TEMPLATES".
1909 "VIRT_TOOLS_DATA_DIR"
1911 This can point to the directory containing data files used for
1912 Windows firstboot installation.
1913 Normally you do not need to set this. If not set, a compiled-in
1915 default will be used (something like /usr/share/virt-tools).
1916 This directory may contain the following files:
1918 rhsrvany.exe
1920 This is the RHSrvAny Windows binary, used to install a
1921 "firstboot" script in Windows guests. It is required if you
1922 intend to use the --firstboot or --firstboot-command options
1923 with Windows guests.
1924 See also: "https://github.com/rwmjones/rhsrvany"
1926 pvvxsvc.exe
1928 This is a Windows binary shipped with SUSE VMDP, used to
1929 install a "firstboot" script in Windows guests. It is required
1930 if you intend to use the --firstboot or --firstboot-command
1931 options with Windows guests.
1932 "XDG_CACHE_HOME"
1934 Used to determine the location of the template cache. See
1935 "CACHING".
1936 "XDG_CONFIG_HOME"
1938 Used to determine the location of the user' sources. See "SOURCES
1939 OF TEMPLATES".
1940 "VIRT_BUILDER_DIRS"
1942 Used to determine the location of the system sources. See "SOURCES
1943 OF TEMPLATES".
1944
1946 This program returns 0 if successful, or non-zero if there was an
1947 error.
1948
1950 guestfs(3), guestfish(1), guestmount(1), virt-builder-repository(1),
1951 virt-copy-out(1), virt-customize(1), virt-get-kernel(1),
1952 virt-install(1), virt-rescue(1), virt-resize(1), virt-sysprep(1),
1953 oz-install(1), gpg(1), gpg2(1), curl(1), virt-make-fs(1),
1954 genisoimage(1), http://libguestfs.org/.
1955
1957 Richard W.M. Jones http://people.redhat.com/~rjones/
1958
1960 Copyright (C) 2013 Red Hat Inc.
1961
1963 This program is free software; you can redistribute it and/or modify it
1964 under the terms of the GNU General Public License as published by the
1965 Free Software Foundation; either version 2 of the License, or (at your
1966 option) any later version.
1967 This program is distributed in the hope that it will be useful, but
1969 WITHOUT ANY WARRANTY; without even the implied warranty of
1970 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1971 General Public License for more details.
1972 You should have received a copy of the GNU General Public License along
1974 with this program; if not, write to the Free Software Foundation, Inc.,
1975 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
1976
1978 To get a list of bugs against libguestfs, use this link:
1979 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
1980 To report a new bug against libguestfs, use this link:
1982 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1983 When reporting a bug, please supply:
1985 • The version of libguestfs.
1987 • Where you got libguestfs (eg. which Linux distro, compiled from
1989 source, etc)
1990 • Describe the bug accurately and give a way to reproduce it.
1992 • Run libguestfs-test-tool(1) and paste the complete, unedited output
1994 into the bug report.
1995guestfs-tools-1.49.7 2022-12-10 virt-builder(1)