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 [--inject-qemu-ga METHOD] [--inject-virtio-win METHOD]
18 [--install PKG,PKG..] [--link TARGET:LINK[:LINK..]] [--mkdir DIR]
19 [--move SOURCE:DEST] [--password USER:SELECTOR]
20 [--root-password SELECTOR] [--run SCRIPT]
21 [--run-command 'CMD+ARGS'] [--scrub FILE] [--sm-attach SELECTOR]
22 [--sm-register] [--sm-remove] [--sm-unregister]
23 [--ssh-inject USER[:SELECTOR]] [--truncate FILE]
24 [--truncate-recursive PATH] [--timezone TIMEZONE] [--touch FILE]
25 [--uninstall PKG,PKG..] [--update] [--upload FILE:DEST]
26 [--write FILE:CONTENT] [--no-logfile]
27 [--password-crypto md5|sha256|sha512] [--no-selinux-relabel]
28 [--selinux-relabel] [--sm-credentials SELECTOR]
29 virt-builder -l|--list [--long] [--list-format short|long|json] [os-version]
32 virt-builder --notes os-version
34 virt-builder --print-cache
36 virt-builder --cache-all-templates
38 virt-builder --delete-cache
40 virt-builder --get-kernel DISKIMAGE
42 [--format raw|qcow2] [--output OUTPUTDIR]
43
45 Virt-builder is a tool for quickly building new virtual machines. You
46 can build a variety of VMs for local or cloud use, usually within a few
47 minutes or less. Virt-builder also has many ways to customize these
48 VMs. Everything is run from the command line and nothing requires root
49 privileges, so automation and scripting is simple.
50 Note that virt-builder does not install guests from scratch. It takes
52 cleanly prepared, digitally signed OS templates and customizes them.
53 This approach is used because it is much faster, but if you need to do
54 fresh installs you may want to look at virt-install(1) and
55 oz-install(1).
56 The easiest way to get started is by looking at the examples in the
58 next section.
59
61 List the virtual machines available
62 virt-builder --list
63 will list out the operating systems available to install. A selection
65 of freely redistributable OSes is available as standard. You can add
66 your own too (see below).
67 After choosing a guest from the list, you may want to see if there are
69 any installation notes:
70 virt-builder --notes fedora-27
72 Build a virtual machine
74 virt-builder fedora-27
75 will build a Fedora 25 image for the same architecture as virt-builder
77 (so running it from an i686 installation will try to build an i686
78 image, if available). This will have all default configuration
79 (minimal size, no user accounts, random root password, only the bare
80 minimum installed software, etc.).
81 You do not need to run this command as root.
83 The first time this runs it has to download the template over the
85 network, but this gets cached (see "CACHING").
86 The name of the output file is derived from the template name, so above
88 it will be fedora-27.img. You can change the output filename using the
89 -o option:
90 virt-builder fedora-27 -o mydisk.img
92 You can also use the -o option to write to existing devices or logical
94 volumes.
95 virt-builder fedora-27 --format qcow2
97 As above, but write the output in qcow2 format to fedora-27.qcow2.
99 virt-builder fedora-27 --size 20G
101 As above, but the output size will be 20 GB. The guest OS is resized
103 as it is copied to the output (automatically, using virt-resize(1)).
104 virt-builder fedora-27 --arch i686
106 As above, but using an i686 template, if available.
108 Setting the root password
110 virt-builder fedora-27 --root-password file:/tmp/rootpw
111 Create a Fedora 25 image. The root password is taken from the file
113 /tmp/rootpw.
114 Note if you don’t set --root-password then the guest is given a random
116 root password which is printed on stdout.
117 You can also create user accounts. See "USERS AND PASSWORDS" below.
119 Set the hostname
121 virt-builder fedora-27 --hostname virt.example.com
122 Set the hostname to "virt.example.com".
124 Installing software
126 To install packages from the ordinary (guest) software repository (eg.
127 dnf or apt):
128 virt-builder fedora-27 --install "inkscape,@Xfce Desktop"
130 (In Fedora, "@" is used to install groups of packages. On Debian you
132 would install a meta-package instead.)
133 To update the installed packages to the latest version:
135 virt-builder debian-7 --update
137 Customizing the installation
139 There are many options that let you customize the installation. These
140 include: --run/--run-command, which run a shell script or command while
141 the disk image is being generated and lets you add or edit files that
142 go into the disk image. --firstboot/--firstboot-command, which let you
143 add scripts/commands that are run the first time the guest boots.
144 --edit to edit files. --upload to upload files.
145 For example:
147 cat <<'EOF' > /tmp/dnf-update.sh
149 dnf -y --best update
150 EOF
151 virt-builder fedora-27 --firstboot /tmp/dnf-update.sh
153 or simply:
155 virt-builder fedora-27 --firstboot-command 'dnf -y --best update'
157 which makes the dnf(8) "update" command run once the first time the
159 guest boots.
160 Or:
162 virt-builder fedora-27 \
164 --edit '/etc/dnf/dnf.conf:
165 s/gpgcheck=1/gpgcheck=0/'
166 which edits /etc/dnf/dnf.conf inside the disk image (during disk image
168 creation, long before boot).
169 You can combine these options, and have multiple options of all types.
171
173 --help
174 Display help.
175 --arch ARCHITECTURE
177 Use the specified architecture for the output image. This means
178 there must be sources providing the requested template for the
179 requested architecture.
180 See also "ARCHITECTURE".
182 --attach ISOFILE
184 During the customization phase, the given disk is attached to the
185 libguestfs appliance. This is used to provide extra software
186 repositories or other data for customization.
187 You probably want to ensure the volume(s) or filesystems in the
189 attached disks are labelled (or use an ISO volume name) so that you
190 can mount them by label in your run-scripts:
191 mkdir /tmp/mount
193 mount LABEL=EXTRA /tmp/mount
194 You can have multiple --attach options, and the format can be any
196 disk format (not just an ISO).
197 See also: --run, "Installing packages at build time from a side
199 repository", genisoimage(1), virt-make-fs(1).
200 --attach-format FORMAT
202 Specify the disk format for the next --attach option. The "FORMAT"
203 is usually "raw" or "qcow2". Use "raw" for ISOs.
204 --cache DIR
206 --no-cache
207 --cache DIR sets the directory to use/check for cached template
208 files. If not set, defaults to either
209 $XDG_CACHE_HOME/virt-builder/ or $HOME/.cache/virt-builder/.
210 --no-cache disables template caching.
212 --cache-all-templates
214 Download all templates to the cache and then exit. See "CACHING".
215 Note this doesn't cache everything. More templates might be
217 uploaded. Also this doesn't cache packages (the --install,
218 --update options).
219 --check-signature
221 --no-check-signature
222 Check/don’t check the digital signature of the OS template. The
223 default is to check the signature and exit if it is not correct.
224 Using --no-check-signature bypasses this check.
225 See also --fingerprint.
227 --colors
229 --colours
230 Use ANSI colour sequences to colourize messages. This is the
231 default when the output is a tty. If the output of the program is
232 redirected to a file, ANSI colour sequences are disabled unless you
233 use this option.
234 --curl CURL
236 Specify an alternate curl(1) binary. You can also use this to add
237 curl parameters, for example to disable https certificate checks:
238 virt-builder --curl "curl --insecure" [...]
240 --delete-cache
242 Delete the template cache. See "CACHING".
243 --no-delete-on-failure
245 Don’t delete the output file on failure to build. You can use this
246 to debug failures to run scripts. See "DEBUGGING BUILDS" for ways
247 to debug images.
248 The default is to delete the output file if virt-builder fails (or,
250 for example, some script that it runs fails).
251 --fingerprint 'AAAA BBBB ...'
253 Check that the index and templates are signed by the key with the
254 given fingerprint. (The fingerprint is a long string, usually
255 written as 10 groups of 4 hexadecimal digits).
256 You can give this option multiple times. If you have multiple
258 source URLs, then you can have either no fingerprint, one
259 fingerprint or multiple fingerprints. If you have multiple, then
260 each must correspond 1-1 with a source URL.
261 --format qcow2
263 --format raw
264 For ordinary builds, this selects the output format. The default
265 is raw.
266 With --get-kernel this specifies the input format.
268 To create an old-style qcow2 file (for compatibility with RHEL 6 or
270 very old qemu < 1.1), after running virt-builder, use this command:
271 qemu-img amend -f qcow2 -o compat=0.10 output.qcow2
273 --get-kernel IMAGE
275 This option extracts the kernel and initramfs from a previously
276 built disk image called "IMAGE" (in fact it works for any VM disk
277 image, not just ones built using virt-builder).
278 Note this method is deprecated: there is a separate tool for this,
280 virt-get-kernel(1), which has more options for the file extraction.
281 The kernel and initramfs are written to the current directory,
283 unless you also specify the --output "outputdir" directory name.
284 The format of the disk image is automatically detected unless you
286 specify it by using the --format option.
287 In the case where the guest contains multiple kernels, the one with
289 the highest version number is chosen. To extract arbitrary kernels
290 from the disk image, see guestfish(1). To extract the entire /boot
291 directory of a guest, see virt-copy-out(1).
292 --gpg GPG
294 Specify an alternate gpg(1) (GNU Privacy Guard) binary. By default
295 virt-builder looks for either "gpg2" or "gpg" in the $PATH.
296 You can also use this to add gpg parameters, for example to specify
298 an alternate home directory:
299 virt-builder --gpg "gpg --homedir /tmp" [...]
301 -l [os-version]
303 --list [os-version]
304 --list --list-format format [os-version]
305 --list --long [os-version]
306 List all the available templates if no guest is specified, or only
307 for the specified one.
308 It is possible to choose with --list-format the output format for
310 the list templates:
311 short
313 The default format, prints only the template identifier and,
314 next to it, its short description.
315 long
317 Prints a textual list with the details of the available
318 sources, followed by the details of the available templates.
319 json
321 Prints a JSON object with the details of the available sources
322 and the details of the available templates.
323 The "version" key in the main object represents the
325 "compatibility version", and it is bumped every time the
326 resulting JSON output is incompatible with the previous
327 versions (for example the structure has changed, or non-
328 optional keys are no more present).
329 --long is a shorthand for the "long" format.
331 See also: --source, --notes, "SOURCES OF TEMPLATES".
333 --machine-readable
335 --machine-readable=format
336 This option is used to make the output more machine friendly when
337 being parsed by other programs. See "MACHINE READABLE OUTPUT"
338 below.
339 -m MB
341 --memsize MB
342 Change the amount of memory allocated to --run scripts. Increase
343 this if you find that --run scripts or the --install option are
344 running out of memory.
345 The default can be found with this command:
347 guestfish get-memsize
349 --network
351 --no-network
352 Enable or disable network access from the guest during the
353 installation.
354 Enabled is the default. Use --no-network to disable access.
356 The network only allows outgoing connections and has other minor
358 limitations. See "NETWORK" in virt-rescue(1).
359 If you use --no-network then certain other options such as
361 --install will not work.
362 This does not affect whether the guest can access the network once
364 it has been booted, because that is controlled by your hypervisor
365 or cloud environment and has nothing to do with virt-builder.
366 Generally speaking you should not use --no-network. But here are
368 some reasons why you might want to:
369 1. Because the libguestfs backend that you are using doesn't
371 support the network. (See: "BACKEND" in guestfs(3)).
372 2. Any software you need to install comes from an attached ISO, so
374 you don't need the network.
375 3. You don’t want untrusted guest code trying to access your host
377 network when running virt-builder. This is particularly an
378 issue when you don't trust the source of the operating system
379 templates. (See "SECURITY" below).
380 4. You don’t have a host network (eg. in secure/restricted
382 environments).
383 --no-sync
385 Do not sync the output file on exit.
386 Virt-builder "fsync"s the output file or disk image when it exits.
388 The reason is that qemu/KVM’s default caching mode is "none" or
390 "directsync", both of which bypass the host page cache. Therefore
391 these would not work correctly if you immediately started the guest
392 after running virt-builder - they would not see the complete output
393 file. (Note that you should not use these caching modes - they are
394 fundamentally broken for this and other reasons.)
395 If you are not using these broken caching modes, you can use
397 --no-sync to avoid this unnecessary sync and gain considerable
398 extra performance.
399 --notes os-version
401 List any notes associated with this guest, then exit (this does not
402 do the install).
403 -o filename
405 --output filename
406 Write the output to filename. If you don’t specify this option,
407 then the output filename is generated by taking the "os-version"
408 string and adding ".img" (for raw format) or ".qcow2" (for qcow2
409 format).
410 Note that the output filename could be a device, partition or
412 logical volume.
413 When used with --get-kernel, this option specifies the output
415 directory.
416 --print-cache
418 Print information about the template cache. See "CACHING".
419 -q
421 --quiet
422 Don’t print ordinary progress messages.
423 --size SIZE
425 Select the size of the output disk, where the size can be specified
426 using common names such as "32G" (32 gigabytes) etc.
427 Virt-builder will resize filesystems inside the disk image
429 automatically.
430 If the size is not specified, then one of two things happens. If
432 the output is a file, then the size is the same as the template.
433 If the output is a device, partition, etc then the size of that
434 device is used.
435 To specify size in bytes, the number must be followed by the
437 lowercase letter b, eg: "--size 10737418240b".
438 --smp N
440 Enable N ≥ 2 virtual CPUs for --run scripts to use.
441 --source URL
443 Set the source URL to look for indexes.
444 You can give this option multiple times to specify multiple
446 sources.
447 See also "SOURCES OF TEMPLATES" below.
449 Note that you should not point --source to sources that you don’t
451 trust (unless the source is signed by someone you do trust). See
452 also the --no-network option.
453 --no-warn-if-partition
455 Do not emit a warning if the output device is a partition. This
456 warning avoids a common user error when writing to a USB key or
457 external drive, when you should normally write to the whole device
458 (--output /dev/sdX), not to a partition on the device
459 (--output /dev/sdX1). Use this option to suppress this warning.
460 -v
462 --verbose
463 Enable debug messages and/or produce verbose output.
464 When reporting bugs, use this option and attach the complete output
466 to your bug report.
467 -V
469 --version
470 Display version number and exit.
471 --wrap
473 Wrap error, warning, and informative messages. This is the default
474 when the output is a tty. If the output of the program is
475 redirected to a file, wrapping is disabled unless you use this
476 option.
477 -x Enable tracing of libguestfs API calls.
479 Customization options
481 --append-line FILE:LINE
482 Append a single line of text to the "FILE". If the file does not
483 already end with a newline, then one is added before the appended
484 line. Also a newline is added to the end of the "LINE" string
485 automatically.
486 For example (assuming ordinary shell quoting) this command:
488 --append-line '/etc/hosts:10.0.0.1 foo'
490 will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
492 the latter only if the existing file does not already end with a
493 newline.
494 "⏎" represents a newline character, which is guessed by looking at
496 the existing content of the file, so this command does the right
497 thing for files using Unix or Windows line endings. It also works
498 for empty or non-existent files.
499 To insert several lines, use the same option several times:
501 --append-line '/etc/hosts:10.0.0.1 foo'
503 --append-line '/etc/hosts:10.0.0.2 bar'
504 To insert a blank line before the appended line, do:
506 --append-line '/etc/hosts:'
508 --append-line '/etc/hosts:10.0.0.1 foo'
509 --chmod PERMISSIONS:FILE
511 Change the permissions of "FILE" to "PERMISSIONS".
512 Note: "PERMISSIONS" by default would be decimal, unless you prefix
514 it with 0 to get octal, ie. use 0700 not 700.
515 --commands-from-file FILENAME
517 Read the customize commands from a file, one (and its arguments)
518 each line.
519 Each line contains a single customization command and its
521 arguments, for example:
522 delete /some/file
524 install some-package
525 password some-user:password:its-new-password
526 Empty lines are ignored, and lines starting with "#" are comments
528 and are ignored as well. Furthermore, arguments can be spread
529 across multiple lines, by adding a "\" (continuation character) at
530 the of a line, for example
531 edit /some/file:\
533 s/^OPT=.*/OPT=ok/
534 The commands are handled in the same order as they are in the file,
536 as if they were specified as --delete /some/file on the command
537 line.
538 --copy SOURCE:DEST
540 Copy files or directories recursively inside the guest.
541 Wildcards cannot be used.
543 --copy-in LOCALPATH:REMOTEDIR
545 Copy local files or directories recursively into the disk image,
546 placing them in the directory "REMOTEDIR" (which must exist).
547 Wildcards cannot be used.
549 --delete PATH
551 Delete a file from the guest. Or delete a directory (and all its
552 contents, recursively).
553 You can use shell glob characters in the specified path. Be
555 careful to escape glob characters from the host shell, if that is
556 required. For example:
557 virt-customize --delete '/var/log/*.log'.
559 See also: --upload, --scrub.
561 --edit FILE:EXPR
563 Edit "FILE" using the Perl expression "EXPR".
564 Be careful to properly quote the expression to prevent it from
566 being altered by the shell.
567 Note that this option is only available when Perl 5 is installed.
569 See "NON-INTERACTIVE EDITING" in virt-edit(1).
571 --firstboot SCRIPT
573 Install "SCRIPT" inside the guest, so that when the guest first
574 boots up, the script runs (as root, late in the boot process).
575 The script is automatically chmod +x after installation in the
577 guest.
578 The alternative version --firstboot-command is the same, but it
580 conveniently wraps the command up in a single line script for you.
581 You can have multiple --firstboot options. They run in the same
583 order that they appear on the command line.
584 Please take a look at "FIRST BOOT SCRIPTS" for more information and
586 caveats about the first boot scripts.
587 See also --run.
589 --firstboot-command 'CMD+ARGS'
591 Run command (and arguments) inside the guest when the guest first
592 boots up (as root, late in the boot process).
593 You can have multiple --firstboot options. They run in the same
595 order that they appear on the command line.
596 Please take a look at "FIRST BOOT SCRIPTS" for more information and
598 caveats about the first boot scripts.
599 See also --run.
601 --firstboot-install PKG,PKG..
603 Install the named packages (a comma-separated list). These are
604 installed when the guest first boots using the guest’s package
605 manager (eg. apt, yum, etc.) and the guest’s network connection.
606 For an overview on the different ways to install packages, see
608 "INSTALLING PACKAGES".
609 --hostname HOSTNAME
611 Set the hostname of the guest to "HOSTNAME". You can use a dotted
612 hostname.domainname (FQDN) if you want.
613 --inject-qemu-ga METHOD
615 Inject the QEMU Guest Agent into a Windows guest. The guest agent
616 communicates with qemu through a socket in order to provide
617 enhanced features (see qemu-ga(8)). This operation also injects a
618 firstboot script so that the Guest Agent is installed when the
619 guest boots.
620 The parameter is the same as used by the --inject-virtio-win
622 operation.
623 Note that to do a full conversion of a Windows guest from a foreign
625 hypervisor like VMware (which involves many other operations) you
626 should use the virt-v2v(1) tool instead of this.
627 --inject-virtio-win METHOD
629 Inject virtio-win drivers into a Windows guest. These drivers add
630 virtio accelerated drivers suitable when running on top of a
631 hypervisor that supports virtio (such as qemu/KVM). The operation
632 also adjusts the Windows Registry so that the drivers are installed
633 when the guest boots.
634 The parameter can be one of:
636 ISO The path to the ISO image containing the virtio-win drivers
638 (eg. /usr/share/virtio-win/virtio-win.iso).
639 DIR The directory containing the unpacked virtio-win drivers (eg.
641 /usr/share/virtio-win).
642 "osinfo"
644 The literal string "osinfo" means to use the libosinfo database
645 to locate the drivers. (See osinfo-query(1).
646 Note that to do a full conversion of a Windows guest from a foreign
648 hypervisor like VMware (which involves many other operations) you
649 should use the virt-v2v(1) tool instead of this.
650 --install PKG,PKG..
652 Install the named packages (a comma-separated list). These are
653 installed during the image build using the guest’s package manager
654 (eg. apt, yum, etc.) and the host’s network connection.
655 For an overview on the different ways to install packages, see
657 "INSTALLING PACKAGES".
658 See also --update, --uninstall.
660 --link TARGET:LINK[:LINK..]
662 Create symbolic link(s) in the guest, starting at "LINK" and
663 pointing at "TARGET".
664 --mkdir DIR
666 Create a directory in the guest.
667 This uses "mkdir -p" so any intermediate directories are created,
669 and it also works if the directory already exists.
670 --move SOURCE:DEST
672 Move files or directories inside the guest.
673 Wildcards cannot be used.
675 --no-logfile
677 Scrub "builder.log" (log file from build commands) from the image
678 after building is complete. If you don't want to reveal precisely
679 how the image was built, use this option.
680 See also: "LOG FILE".
682 --no-selinux-relabel
684 Do not attempt to correct the SELinux labels of files in the guest.
685 In such guests that support SELinux, customization automatically
687 relabels files so that they have the correct SELinux label. (The
688 relabeling is performed immediately, but if the operation fails,
689 customization will instead touch /.autorelabel on the image to
690 schedule a relabel operation for the next time the image boots.)
691 This option disables the automatic relabeling.
692 The option is a no-op for guests that do not support SELinux.
694 --password USER:SELECTOR
696 Set the password for "USER". (Note this option does not create the
697 user account).
698 See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
700 and also how to set up user accounts.
701 --password-crypto md5|sha256|sha512
703 When the virt tools change or set a password in the guest, this
704 option sets the password encryption of that password to "md5",
705 "sha256" or "sha512".
706 "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
708 the guest).
709 "md5" will work with relatively old Linux guests (eg. RHEL 3), but
711 is not secure against modern attacks.
712 The default is "sha512" unless libguestfs detects an old guest that
714 didn't have support for SHA-512, in which case it will use "md5".
715 You can override libguestfs by specifying this option.
716 Note this does not change the default password encryption used by
718 the guest when you create new user accounts inside the guest. If
719 you want to do that, then you should use the --edit option to
720 modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
721 "/etc/pam.d/common-password" (Debian, Ubuntu).
722 --root-password SELECTOR
724 Set the root password.
725 See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
727 and also how to set up user accounts.
728 Note: In virt-builder, if you don't set --root-password then the
730 guest is given a random root password.
731 --run SCRIPT
733 Run the shell script (or any program) called "SCRIPT" on the disk
734 image. The script runs virtualized inside a small appliance,
735 chrooted into the guest filesystem.
736 The script is automatically chmod +x.
738 If libguestfs supports it then a limited network connection is
740 available but it only allows outgoing network connections. You can
741 also attach data disks (eg. ISO files) as another way to provide
742 data (eg. software packages) to the script without needing a
743 network connection (--attach). You can also upload data files
744 (--upload).
745 You can have multiple --run options. They run in the same order
747 that they appear on the command line.
748 See also: --firstboot, --attach, --upload.
750 --run-command 'CMD+ARGS'
752 Run the command and arguments on the disk image. The command runs
753 virtualized inside a small appliance, chrooted into the guest
754 filesystem.
755 If libguestfs supports it then a limited network connection is
757 available but it only allows outgoing network connections. You can
758 also attach data disks (eg. ISO files) as another way to provide
759 data (eg. software packages) to the script without needing a
760 network connection (--attach). You can also upload data files
761 (--upload).
762 You can have multiple --run-command options. They run in the same
764 order that they appear on the command line.
765 See also: --firstboot, --attach, --upload.
767 --scrub FILE
769 Scrub a file from the guest. This is like --delete except that:
770 • It scrubs the data so a guest could not recover it.
772 • It cannot delete directories, only regular files.
774 --selinux-relabel
776 This is a compatibility option that does nothing.
777 --sm-attach SELECTOR
779 Attach to a pool using "subscription-manager".
780 See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
782 --sm-credentials SELECTOR
784 Set the credentials for "subscription-manager".
785 See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
787 --sm-register
789 Register the guest using "subscription-manager".
790 This requires credentials being set using --sm-credentials.
792 --sm-remove
794 Remove all the subscriptions from the guest using
795 "subscription-manager".
796 --sm-unregister
798 Unregister the guest using "subscription-manager".
799 --ssh-inject USER[:SELECTOR]
801 Inject an ssh key so the given "USER" will be able to log in over
802 ssh without supplying a password. The "USER" must exist already in
803 the guest.
804 See "SSH KEYS" for the format of the "SELECTOR" field.
806 You can have multiple --ssh-inject options, for different users and
808 also for more keys for each user.
809 --timezone TIMEZONE
811 Set the default timezone of the guest to "TIMEZONE". Use a
812 location string like "Europe/London"
813 --touch FILE
815 This command performs a touch(1)-like operation on "FILE".
816 --truncate FILE
818 This command truncates "FILE" to a zero-length file. The file must
819 exist already.
820 --truncate-recursive PATH
822 This command recursively truncates all files under "PATH" to zero-
823 length.
824 --uninstall PKG,PKG..
826 Uninstall the named packages (a comma-separated list). These are
827 removed during the image build using the guest’s package manager
828 (eg. apt, yum, etc.). Dependent packages may also need to be
829 uninstalled to satisfy the request.
830 See also --install, --update.
832 --update
834 Do the equivalent of "yum update", "apt-get upgrade", or whatever
835 command is required to update the packages already installed in the
836 template to their latest versions.
837 See also --install, --uninstall.
839 --upload FILE:DEST
841 Upload local file "FILE" to destination "DEST" in the disk image.
842 File owner and permissions from the original are preserved, so you
843 should set them to what you want them to be in the disk image.
844 "DEST" could be the final filename. This can be used to rename the
846 file on upload.
847 If "DEST" is a directory name (which must already exist in the
849 guest) then the file is uploaded into that directory, and it keeps
850 the same name as on the local filesystem.
851 See also: --mkdir, --delete, --scrub.
853 --write FILE:CONTENT
855 Write "CONTENT" to "FILE".
856
858 INSTALLING PACKAGES
859 There are several approaches to installing packages or applications in
860 the guest which have different trade-offs.
861 Installing packages at build time
863 If the guest OS you are installing is similar to the host OS (eg. both
865 are Linux), and if libguestfs supports network connections, then you
866 can use --install to install packages like this:
867 virt-builder fedora-27 --install inkscape
869 This uses the guest’s package manager and the host’s network
871 connection.
872 Updating packages at build time
874 To update the installed packages in the template at build time:
876 virt-builder fedora-27 --update
878 Most of the templates that ship with virt-builder come with a very
880 minimal selection of packages (known as a "JEOS" or "Just Enough
881 Operating System"), which are up to date at the time the template is
882 created, but could be out of date by the time you come to install an OS
883 from the template. This option updates those template packages.
884 Installing packages at first boot
886 Another option is to install the packages when the guest first boots:
888 virt-builder fedora-27 --firstboot-install inkscape
890 This uses the guest’s package manager and the guest’s network
892 connection.
893 The downsides are that it will take the guest a lot longer to boot
895 first time, and there’s nothing much you can do if package installation
896 fails (eg. if a network problem means the guest can't reach the package
897 repositories).
898 Installing packages at build time from a side repository
900 If the software you want to install is not available in the main
902 package repository of the guest, then you can add a side repository.
903 Usually this is presented as an ISO (CD disk image) file containing
904 extra packages.
905 You can create the disk image using either genisoimage(1) or
907 virt-make-fs(1). For genisoimage, use a command like this:
908 genisoimage -o extra-packages.iso -R -J -V EXTRA cdcontents/
910 Create a script that mounts the ISO and sets up the repository. For
912 dnf, create /tmp/install.sh containing:
913 mkdir /tmp/mount
915 mount LABEL=EXTRA /tmp/mount
916 cat <<'EOF' > /etc/yum.repos.d/extra.repo
918 [extra]
919 name=extra
920 baseurl=file:///tmp/mount
921 enabled=1
922 EOF
923 dnf -y install famousdatabase
925 For apt, create /tmp/install.sh containing:
927 mkdir /tmp/mount
929 mount LABEL=EXTRA /tmp/mount
930 apt-cdrom -d=/tmp/mount add
932 apt-get -y install famousdatabase
933 Use the --attach option to attach the CD / disk image and the --run
935 option to run the script:
936 virt-builder fedora-27 \
938 --attach extra-packages.iso \
939 --run /tmp/install.sh
940 USERS AND PASSWORDS
942 The --root-password option is used to change the root password
943 (otherwise a random password is used). This option takes a password
944 "SELECTOR" in one of the following formats:
945 --root-password file:FILENAME
947 Read the root password from "FILENAME". The whole first line of
948 this file is the replacement password. Any other lines are
949 ignored. You should create the file with mode 0600 to ensure no
950 one else can read it.
951 --root-password password:PASSWORD
953 Set the root password to the literal string "PASSWORD".
954 Note: this is not secure since any user on the same machine can see
956 the cleartext password using ps(1).
957 --root-password random
959 Choose a random password, which is printed on stdout. The password
960 has approximately 120 bits of randomness.
961 This is the default.
963 --root-password disabled
965 The root account password is disabled. This is like putting "*" in
966 the password field.
967 --root-password locked:file:FILENAME
969 --root-password locked:password:PASSWORD
970 --root-password locked:random
971 The root account is locked, but a password is placed on the
972 account. If first unlocked (using "passwd -u") then logins will
973 use the given password.
974 --root-password locked
976 --root-password locked:disabled
977 The root account is locked and password is disabled.
978 Creating user accounts
980 To create user accounts, use the useradd(8) command with
982 --firstboot-command like this:
983 virt-builder --firstboot-command \
985 'useradd -m -p "" rjones ; chage -d 0 rjones'
986 The above command will create an "rjones" account with no password, and
988 force the user to set a password when they first log in. There are
989 other ways to manage passwords, see useradd(8) for details.
990 KEYBOARD LAYOUT
992 Because there are so many different ways to set the keyboard layout in
993 Linux distributions, virt-builder does not yet attempt to have a simple
994 command line option. This section describes how to set the keyboard
995 for some common Linux distributions.
996 Keyboard layout with systemd
998 For distros that use systemd "localectl", use a command like this:
1000 virt-builder fedora-27 \
1002 --firstboot-command 'localectl set-keymap uk'
1003 See localectl(1) and
1005 https://www.happyassassin.net/2013/11/23/keyboard-layouts-in-fedora-20-and-previously/
1006 for more details.
1007 Keyboard layout using /etc/sysconfig/keyboard
1009 For RHEL ≤ 6, Fedora ≤ 18 and similar, upload or modify the keyboard
1011 configuration file using the --upload, --write or --edit options. For
1012 example:
1013 virt-builder centos-6 \
1015 --edit '/etc/sysconfig/keyboard: s/^KEYTABLE=.*/KEYTABLE="uk"/'
1016 The format of this file can be found documented in many places online.
1018 Keyboard layout with Debian-derived distros
1020 For Debian-derived distros using /etc/default/keyboard, upload or
1022 modify the keyboard file using the --upload, --write or --edit options.
1023 For example:
1024 virt-builder debian-8 \
1026 --edit '/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/'
1027 See https://wiki.debian.org/Keyboard.
1029 LANGUAGE
1031 Most Linux distributions support multiple locale settings so that you
1032 can have guest messages printed in another language such as Russian.
1033 However there is no single setting which controls this, since extra
1035 packages may need to be installed to support console and X fonts, and
1036 keyboard input methods. The packages required, and their configuration
1037 is highly distro-specific, and it is outside the scope of virt-builder
1038 to do this.
1039 This section contains examples for some common Linux distributions.
1041 Setting Japanese in Fedora 25
1043 virt-builder fedora-27 \
1045 --size 20G \
1046 --update \
1047 --install @japanese-support \
1048 --install @xfce \
1049 --install xorg-x11-server-Xorg,xorg-x11-drivers,rsyslog \
1050 --link /usr/lib/systemd/system/graphical.target:/etc/systemd/system/default.target \
1051 --firstboot-command 'localectl set-locale LANG=ja_JP.utf8' \
1052 --firstboot-command 'localectl set-keymap jp' \
1053 --firstboot-command 'systemctl isolate graphical.target'
1054 Setting Japanese in Debian 8 (Jessie)
1056 Note that although this enables Japanese in the text console too, it is
1058 unlikely that you will see properly rendered Japanese there. However
1059 Japanese is properly rendered in X applications and terminals.
1060 pkgs=locales,xfce4,\
1062 ibus,ibus-anthy,\
1063 fonts-ipafont-gothic,fonts-ipafont-mincho,\
1064 fonts-takao-mincho,\
1065 xfonts-intl-japanese,xfonts-intl-japanese-big,\
1066 iceweasel-l10n-ja,manpages-ja
1067 virt-builder debian-8 \
1069 --size 20G \
1070 --install $pkgs \
1071 --edit '/etc/locale.gen: s,^#\s*ja,ja,' \
1072 --write '/etc/default/locale:LANG="ja_JP.UTF-8"' \
1073 --run-command "locale-gen"
1074 LOG FILE
1076 Scripts and package installation that runs at build time (--run,
1077 --run-command, --install, --update, but not firstboot) is logged in one
1078 of the following locations:
1079 /tmp/builder.log
1081 On Linux, BSD, and other non-Windows guests.
1082 C:\Temp\builder.log
1084 On Windows, DOS guests.
1085 /builder.log
1087 If /tmp or C:\Temp is missing.
1088 If you don’t want the log file to appear in the final image, then use
1090 the --no-logfile command line option.
1091 SSH KEYS
1093 The --ssh-inject option is used to inject ssh keys for users in the
1094 guest, so they can login without supplying a password.
1095 The "SELECTOR" part of the option value is optional; in this case,
1097 --ssh-inject "USER" means that we look in the current user’s ~/.ssh
1098 directory to find the default public ID file. That key is uploaded.
1099 "default public ID" is the default_ID_file file described in
1100 ssh-copy-id(1).
1101 If specified, the "SELECTOR" can be in one of the following formats:
1103 --ssh-inject USER:file:FILENAME
1105 Read the ssh key from FILENAME. FILENAME is usually a .pub file.
1106 --ssh-inject USER:string:KEY_STRING
1108 Use the specified "KEY_STRING". "KEY_STRING" is usually a public
1109 string like ssh-rsa AAAA.... user@localhost.
1110 In any case, the ~USER/.ssh directory and the
1112 ~USER/.ssh/authorized_keys file will be created if not existing
1113 already.
1114 FIRST BOOT SCRIPTS
1116 The --firstboot and --firstboot-command options allow you to execute
1117 commands at the first boot of the guest. To do so, an init script for
1118 the guest init system is installed, which takes care of running all the
1119 added scripts and commands.
1120 Supported operating systems are:
1122 Linux
1124 Init systems supported are: systemd, System-V init (known also as
1125 sysvinit), and Upstart (using the System-V scripts).
1126 Note that usually init scripts run as root, but with a more limited
1128 environment than what could be available from a normal shell: for
1129 example, $HOME may be unset or empty.
1130 The output of the first boot scripts is available in the guest as
1132 ~root/virt-sysprep-firstboot.log.
1133 Windows
1135 rhsrvany.exe, available from sources at
1136 https://github.com/rwmjones/rhsrvany, or pvvxsvc.exe, available
1137 with SUSE VMDP is installed to run the first boot scripts. It is
1138 required, and the setup of first boot scripts will fail if it is
1139 not present.
1140 rhsrvany.exe or pvvxsvc.exe is copied from the location pointed to
1142 by the "VIRT_TOOLS_DATA_DIR" environment variable; if not set, a
1143 compiled-in default will be used (something like
1144 /usr/share/virt-tools).
1145 The output of the first boot scripts is available in the guest as
1147 C:\Program Files\Guestfs\Firstboot\log.txt.
1148 SUBSCRIPTION-MANAGER
1150 It is possible to automate the registration and attaching of the system
1151 using "subscription-manager". This is typical on Red Hat Enterprise
1152 Linux guests. There are few options which ease this process, avoid
1153 executing commands manually and exposing passwords on command line.
1154 --sm-register starts the registration process, and requires
1156 --sm-credentials to be specified; the format of the "SELECTOR" of
1157 --sm-credentials is one of the following formats:
1158 --sm-credentials USER:file:FILENAME
1160 Read the password for the specified "USER" from FILENAME.
1161 --sm-credentials USER:password:PASSWORD
1163 Use the literal string "PASSWORD" for the specified "USER".
1164 --sm-attach attaches the system to subscriptions; the format of its
1166 "SELECTOR" is one of the following:
1167 --sm-attach auto
1169 "subscription-manager" attaches to the best-fitting subscriptions
1170 for the system.
1171 --sm-attach file:FILENAME
1173 Read the pool ID from FILENAME.
1174 --sm-attach pool:POOL
1176 Use the literal string "POOL" as pool ID.
1177 --sm-remove removes all the subscriptions from the guest, while
1179 --sm-unregister completely unregister the system.
1180 INSTALLATION PROCESS
1182 When you invoke virt-builder, installation proceeds as follows:
1183 • The template image is downloaded.
1185 If the template image is present in the cache, the cached version
1187 is used instead. (See "CACHING").
1188 • The template signature is checked.
1190 • The template is uncompressed to a tmp file.
1192 • The template image is resized into the destination, using
1194 virt-resize(1).
1195 • Extra disks are attached (--attach).
1197 • A new random seed is generated for the guest.
1199 • Guest customization is performed, in the order specified on the
1201 command line.
1202 • SELinux relabelling is done unless disabled with
1204 --no-selinux-relabel.
1205 IMPORTING THE DISK IMAGE
1207 Importing into libvirt
1208 Import the disk image into libvirt using virt-install(1) --import
1210 option.
1211 virt-install --import \
1213 --name guest --ram 2048 \
1214 --disk path=disk.img,format=raw --os-variant fedora27
1215 Notes:
1217 1. You must specify the correct format. The format is "raw" unless
1219 you used virt-builder’s --format option.
1220 2. --os-variant is highly recommended, because it will present optimum
1222 devices to enable the guest to run most efficiently. To get a list
1223 of all variants, do:
1224 osinfo-query os
1226 The above tool is provided by libosinfo package.
1228 3. You can run virt-install as root or non-root. Each works slightly
1230 differently because libvirt manages a different set of virtual
1231 machines for each user. In particular virt-manager normally shows
1232 the root-owned VMs, whereas Boxes shows the user-owned VMs, and
1233 other tools probably work differently as well.
1234 Importing into OpenStack
1236 Import the image into Glance (the OpenStack image store) by doing:
1238 glance image-create --name fedora-27-image --file fedora-27.img \
1240 --disk-format raw --container-format bare \
1241 --is-public True
1242 The --file parameter is the virt-builder-generated disk image. It
1244 should match virt-builder’s --output option. The --disk-format
1245 parameter should match virt-builder’s --format option (or "raw" if you
1246 didn't use that option). The --container-format should always be
1247 "bare" since virt-builder doesn't put images into containers.
1248 You can use the "glance image-show fedora-27-image" command to display
1250 the properties of the image.
1251 To boot up an instance of your image on a Nova compute node, do:
1253 nova boot fedora-27-server --image fedora-27-image \
1255 --flavor m1.medium
1256 Use "nova flavor-list" to list possible machine flavors. Use
1258 "nova list" to list running instances.
1259 Booting directly using qemu or KVM
1261 The qemu command line is not very stable or easy to use, hence libvirt
1263 should be used if possible. However a command line similar to the
1264 following could be used to boot the virtual machine:
1265 qemu-system-x86_64 \
1267 -machine accel=kvm:tcg \
1268 -cpu host \
1269 -m 2048 \
1270 -drive file=disk.img,format=raw,if=virtio
1271 As with libvirt, it is very important that the correct format is
1273 chosen. It will be "raw" unless the --format option was used.
1274 CONFIGURATION MANAGEMENT
1276 Puppet
1277 To enable the Puppet agent in a guest, install the package, point the
1279 configuration at your Puppetmaster, and ensure the agent runs at boot.
1280 A typical virt-builder command would be:
1282 virt-builder fedora-27 \
1284 --hostname client.example.com \
1285 --update \
1286 --install puppet \
1287 --append-line '/etc/puppet/puppet.conf:[agent]' \
1288 --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
1289 --run-command 'systemctl enable puppet'
1290 The precise instructions vary according to the Linux distro. For
1292 further information see:
1293 https://docs.puppet.com/puppet/latest/install_pre.html
1294 DEBUGGING BUILDS
1296 If virt-builder itself fails, then enable debugging (-v) and report a
1297 bug (see "BUGS" below).
1298 If virt-builder fails because some script or package it is installing
1300 fails, try using --no-delete-on-failure to preserve the output file,
1301 and continue reading this section.
1302 If virt-builder is successful but the image doesn't work, here are some
1304 things to try:
1305 Use virt-rescue
1307 Run virt-rescue(1) on the disk image:
1308 virt-rescue -a disk.img
1310 This gives you a rescue shell. You can mount the filesystems from
1312 the disk image on /sysroot and examine them using ordinary Linux
1313 commands. You can also chroot into the guest to reinstall the
1314 bootloader. The virt-rescue man page has a lot more information
1315 and examples.
1316 Use guestfish
1318 Run guestfish(1) on the disk image:
1319 guestfish -a disk.img -i
1321 Use guestfish commands like "ll /directory" and "cat /file" to
1323 examine directories and files.
1324 Use guestmount
1326 Mount the disk image safely on the host using FUSE and
1327 guestmount(1):
1328 mkdir /tmp/mp
1330 guestmount -a disk.img -i /tmp/mp
1331 cd /tmp/mp
1332 To unmount the disk image do:
1334 fusermount -u /tmp/mp
1336 Add a serial console
1338 If the guest hangs during boot, it can be helpful to add a serial
1339 console to the guest, and direct kernel messages to the serial
1340 console. Adding the serial console will involve looking at the
1341 documentation for your hypervisor. To direct kernel messages to
1342 the serial console, add the following on the kernel command line:
1343 console=tty0 console=ttyS0,115200
1345 SOURCES OF TEMPLATES
1347 virt-builder reads the available sources from configuration files, with
1348 the .conf extension and located in the following paths:
1349 • $XDG_CONFIG_HOME/virt-builder/repos.d/ ($XDG_CONFIG_HOME is
1351 $HOME/.config if not set).
1352 • $VIRT_BUILDER_DIRS/virt-builder/repos.d/ (where $VIRT_BUILDER_DIRS
1354 means any of the directories in that environment variable, or just
1355 /etc if not set).
1356 Each .conf file in those paths has a simple text format like the
1358 following:
1359 [libguestfs.org]
1361 uri=http://libguestfs.org/download/builder/index.asc
1362 gpgkey=file:///etc/xdg/virt-builder/repos.d/libguestfs.gpg
1363 The part in square brackets is the repository identifier, which is used
1365 as unique identifier.
1366 The following fields can appear:
1368 "uri=URI"
1370 The URI of the index file which this repository refers to.
1371 This field is required.
1373 "gpgkey=URI"
1375 This optional field represents the URI (although only file:// URIs
1376 are accepted) of the key used to sign the index file. If not
1377 present, the index file referred by uri=.. is not signed.
1378 "proxy=MODE"
1380 This optional field specifies the proxy mode, to be used when
1381 downloading the index file of this repository. The possible values
1382 are:
1383 no, off
1385 No proxy is being used at all, even overriding the system
1386 configuration.
1387 system
1389 The proxy used is the system one.
1390 anything else
1392 Specifies the actual proxy configuration to be used, overriding
1393 the system configuration.
1394 If not present, the assumed value is to respect the proxy settings
1396 of the system (i.e. as if system would be specified).
1397 "format=FORMAT"
1399 This optional field specifies the format of the repository. The
1400 possible values are:
1401 native
1403 The native format of the "virt-builder" repository. See also
1404 "Creating and signing the index file" below.
1405 simplestreams
1407 The URI represents the root of a Simple Streams v1.0 tree of
1408 metadata.
1409 For more information about Simple Streams, see also
1411 https://launchpad.net/simplestreams.
1412 If not present, the assumed value is "native".
1414 For serious virt-builder use, you may want to create your own
1416 repository of templates.
1417 Libguestfs.org repository
1419 Out of the box, virt-builder downloads the file
1421 http://libguestfs.org/download/builder/index.asc which is an index of
1422 available templates plus some information about each one, wrapped up in
1423 a digital signature. The command "virt-builder --list" lists out the
1424 information in this index file.
1425 The templates hosted on libguestfs.org were created using shell
1427 scripts, kickstart files and preseed files which can be found in the
1428 libguestfs source tree, in "builder/templates".
1429 Setting up the repository
1431 You can set up your own site containing an index file and some
1433 templates, and then point virt-builder at the site by creating a .conf
1434 file pointing to it.
1435 Note that if your index is signed, you will need to properly fill
1437 gpgkey=.. in your .conf file, making sure to deploy also the GPG key
1438 file.
1439 virt-builder --source https://example.com/builder/index.asc \
1441 --fingerprint 'AAAA BBBB ...' \
1442 --list
1443 You can host this on any web or FTP server, or a local or network
1445 filesystem.
1446 Setting up a GPG key
1448 If you don’t have a GnuPG key, you will need to set one up. (Strictly
1450 speaking this is optional, but if your index and template files are not
1451 signed then virt-builder users will have to use the
1452 --no-check-signature flag every time they use virt-builder.)
1453 To create a key, see the GPG manual
1455 http://www.gnupg.org/gph/en/manual.html.
1456 Export your GPG public key:
1458 gpg --export -a "you@example.com" > pubkey
1460 Create the templates
1462 There are many ways to create the templates. For example you could
1464 clone existing guests (see virt-sysprep(1)), or you could install a
1465 guest by hand (virt-install(1)). To see how the templates were created
1466 for virt-builder, look at the scripts in "builder/templates"
1467 Virt-builder supports any image format (e.g. raw, qcow2, etc) as
1469 template, both as-is, and compressed as XZ. This way, existing images
1470 (e.g. cleaned using virt-sysprep(1)) can be used as templates.
1471 For best results when compressing the templates, use the following xz
1473 options (see nbdkit-xz-plugin(1) for further explanation):
1474 xz --best --block-size=16777216 disk
1476 Creating and signing the index file
1478 The index file has a simple text format (shown here without the digital
1480 signature):
1481 [fedora-18]
1483 name=Fedora® 18
1484 osinfo=fedora18
1485 arch=x86_64
1486 file=fedora-18.xz
1487 checksum[sha512]=...
1488 format=raw
1489 size=6442450944
1490 compressed_size=148947524
1491 expand=/dev/sda3
1492 [fedora-19]
1494 name=Fedora® 19
1495 osinfo=fedora19
1496 arch=x86_64
1497 file=fedora-19.xz
1498 checksum[sha512]=...
1499 revision=3
1500 format=raw
1501 size=4294967296
1502 compressed_size=172190964
1503 expand=/dev/sda3
1504 The part in square brackets is the "os-version", which is the same
1506 string that is used on the virt-builder command line to build that OS.
1507 The index file creation and signature can be eased with the
1509 virt-builder-repository(1) tool.
1510 After preparing the "index" file in the correct format, clearsign it
1512 using the following command:
1513 gpg --clearsign --armor index
1515 This will create the final file called index.asc which can be uploaded
1517 to the server (and is the uri=.. URL). As noted above, signing the
1518 index file is optional, but recommended.
1519 The following fields can appear:
1521 "name=NAME"
1523 The user-friendly name of this template. This is displayed in the
1524 --list output but is otherwise not significant.
1525 "osinfo=ID"
1527 This optional field maps the operating system to the associated
1528 libosinfo ID. Virt-builder does not use it (yet).
1529 "arch=ARCH"
1531 The architecture of the operating system installed within the
1532 template. This field is required.
1533 "file=PATH"
1535 The path (relative to the index) of the xz-compressed template.
1536 Note that absolute paths or URIs are not permitted here. This is
1538 because virt-builder has a "same origin" policy for templates so
1539 they cannot come from other servers.
1540 "sig=PATH"
1542 This option is deprecated. Use the checksum field instead.
1543 The path (relative to the index) of the GPG detached signature of
1545 the xz file.
1546 Note that absolute paths or URIs are not permitted here. This is
1548 because virt-builder has a "same origin" policy for templates so
1549 they cannot come from other servers.
1550 The file can be created as follows:
1552 gpg --detach-sign --armor -o disk.xz.sig disk.xz
1554 "checksum[sha512]=7b882fe9b82eb0fef..."
1556 The SHA-512 checksum of the file specified in file=.. is checked
1557 after it is downloaded. To work out the signature, do:
1558 sha512sum disk.xz
1560 Note if you use this, you don’t need to sign the file, ie. don’t
1562 use "sig". This option overrides "sig".
1563 "checksum=7b882fe9b82eb0fef..."
1565 "checksum" is an alias for "checksum[sha512]".
1566 If you need to interoperate with virt-builder = 1.24.0 then you
1568 have to use "checksum" because that version would give a parse
1569 error with square brackets and numbers in the key of a field. This
1570 is fixed in virt-builder ≥ 1.24.1.
1571 "revision=N"
1573 The revision is an integer which is used to control the template
1574 cache. Increasing the revision number causes clients to download
1575 the template again even if they have a copy in the cache.
1576 The revision number is optional. If omitted it defaults to 1.
1578 "format=raw"
1580 "format=qcow2"
1581 Specify the format of the disk image; in case it is compressed,
1582 that is the format before the compression. If not given, the
1583 format is autodetected, but generally it is better to be explicit
1584 about the intended format.
1585 Note this is the source format, which is different from the
1587 --format option (requested output format). Virt-builder does on-
1588 the-fly conversion from the source format to the requested output
1589 format.
1590 "size=NNN"
1592 The virtual size of the image in bytes. This is the size of the
1593 image when uncompressed. If using a non-raw format such as qcow2
1594 then it means the virtual disk size, not the size of the qcow2
1595 file.
1596 This field is required.
1598 Virt-builder also uses this as the minimum size that users can
1600 request via the --size option, or as the default size if there is
1601 no --size option.
1602 "compressed_size=NNN"
1604 The actual size of the disk image in bytes, i.e. what was specified
1605 in file=... This is just used for information (when using "long",
1606 and "json" formats of --list).
1607 "expand=/dev/sdaX"
1609 When expanding the image to its final size, instruct virt-resize(1)
1610 to expand the named partition in the guest image to fill up all
1611 available space. This works like the virt-resize --expand option.
1612 You should usually put the device name of the guest’s root
1614 filesystem here.
1615 It’s a good idea to use this, but not required. If the field is
1617 omitted then virt-resize will create an extra partition at the end
1618 of the disk to cover the free space, which is much less user-
1619 friendly.
1620 "lvexpand=/dev/VolGroup/LogVol"
1622 When expanding the image to its final size, instruct virt-resize(1)
1623 to expand the named logical volume in the guest image to fill up
1624 all available space. This works like the virt-resize --lv-expand
1625 option.
1626 If the guest uses LVM2 you should usually put the LV of the guest’s
1628 root filesystem here. If the guest does not use LVM2 or its root
1629 filesystem is not on an LV, don't use this option.
1630 "notes=NOTES"
1632 Any notes that go with this image, especially notes describing what
1633 packages are in the image, how the image was prepared, and
1634 licensing information.
1635 This information is shown in the --notes and --list --long modes.
1637 You can use multi-line notes here by indenting each new line with
1639 at least one character of whitespace (even on blank lines):
1640 notes=This image was prepared using
1642 the following kickstart script:
1643 <-- one space at beginning of line
1644 part /boot --fstype ext3
1645 ...
1646 "hidden=true"
1648 Using the hidden flag prevents the template from being listed by
1649 the --list option (but it is still installable). This is used for
1650 test images.
1651 "aliases=ALIAS1 ALIAS2 ..."
1653 This optional field specifies a list of aliases, separated by
1654 spaces, for the image. For example, an alias could be used to
1655 always point to the latest version of a certain image, leaving the
1656 old versions available in the index instead of updating the same
1657 image (see the "revision" field).
1658 Running virt-builder against multiple sources
1660 It is possible to use multiple sources with virt-builder. The
1662 recommended way is to deploy .conf files pointing to the index files.
1663 Another way is to specify the sources using multiple --source and/or
1664 --fingerprint options:
1665 virt-builder \
1667 --source http://example.com/s1/index.asc \
1668 --source http://example.com/s2/index.asc
1669 You can provide N or 1 fingerprints. In the case where you provide N
1671 fingerprints, N = number of sources and there is a 1-1 correspondence
1672 between each source and each fingerprint:
1673 virt-builder \
1675 --source http://example.com/s1/index.asc --fingerprint '0123 ...' \
1676 --source http://example.com/s2/index.asc --fingerprint '9876 ...'
1677 In the case where you provide 1 fingerprint, the same fingerprint is
1679 used for all sources.
1680 You "must" provide at least 1 fingerprint.
1682 Licensing of templates
1684 You should be aware of the licensing of images that you distribute.
1686 For open source guests, provide a link to the source code in the
1687 "notes" field and comply with other requirements (eg. around
1688 trademarks).
1689 Formal specification of the index file
1691 The index file format has a formal specification defined by the flex
1693 scanner and bison parser used to parse the file. This can be found in
1694 the following files in the libguestfs source tree:
1695 builder/index-scan.l
1697 builder/index-parse.y
1698 A tool called virt-index-validate(1) is available to validate the index
1700 file to ensure it is correct.
1701 Note that the parser and tool can work on either the signed or unsigned
1703 index file (ie. index or index.asc).
1704 The index is always encoded in UTF-8.
1706 CACHING
1708 Caching templates
1709 Since the templates are usually very large, downloaded templates are
1711 cached in the user’s home directory.
1712 The location of the cache is $XDG_CACHE_HOME/virt-builder/ or
1714 $HOME/.cache/virt-builder.
1715 You can print out information about the cache directory, including
1717 which guests are currently cached, by doing:
1718 virt-builder --print-cache
1720 The cache can be deleted if you want to save space by doing:
1722 virt-builder --delete-cache
1724 You can download all (current) templates to the local cache by doing:
1726 virt-builder --cache-all-templates
1728 To disable the template cache, use --no-cache.
1730 Only templates are cached. The index and detached digital signatures
1732 are not cached.
1733 Caching packages
1735 Virt-builder uses curl(1) to download files and it also uses the
1737 current "http_proxy" (etc) settings when installing packages
1738 (--install, --update).
1739 You may therefore want to set those environment variables in order to
1741 maximize the amount of local caching that happens. See "ENVIRONMENT
1742 VARIABLES" and curl(1).
1743 Local mirrors
1745 To increase both speed and reliability of installing packages, you can
1747 set up a local mirror of the target distribution, and point the guest
1748 package manager at that.
1749 Using a local mirror with Fedora
1751 To install a Fedora guest using a local mirror:
1753 virt-builder fedora-27 \
1755 --edit '/etc/yum.repos.d/fedora.repo:
1756 s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
1757 s{.*metalink=.*}{};
1758 ' \
1759 --edit '/etc/yum.repos.d/fedora-updates.repo:
1760 s{.*baseurl=.*}{baseurl=http://example.com/mirror-updates/};
1761 s{.*metalink=.*}{};
1762 ' \
1763 --run-command 'dnf -y update' \
1764 --install 'pkg1,pkg2,...'
1765 Using a local mirror with Debian
1767 Assuming that you are using "apt-proxy" to mirror the repository, you
1769 should create a new sources.list file to point to your proxy (see
1770 https://help.ubuntu.com/community/AptProxy) and then do:
1771 virt-builder debian-8 \
1773 --upload sources.list:/etc/apt/sources.list \
1774 --run-command 'apt-get -y update' \
1775 --install 'pkg1,pkg2,...'
1776 DIGITAL SIGNATURES
1778 Virt-builder uses GNU Privacy Guard (GnuPG or gpg) to verify that the
1779 index and templates have not been tampered with.
1780 The source points to an index file, which is optionally signed.
1782 Virt-builder downloads the index and checks that the signature is valid
1784 and the signer’s fingerprint matches the specified fingerprint (ie. the
1785 one specified in gpgkey=.. in the .conf, or with --fingerprint, in that
1786 order).
1787 For checking against the built-in public key/fingerprint, this requires
1789 importing the public key into the user’s local gpg keyring (that’s just
1790 the way that gpg works).
1791 When a template is downloaded, its signature is checked in the same
1793 way.
1794 Although the signatures are optional, if you don’t have them then virt-
1796 builder users will have to use --no-check-signature on the command
1797 line. This prevents an attacker from replacing the signed index file
1798 with an unsigned index file and having virt-builder silently work
1799 without checking the signature. In any case it is highly recommended
1800 that you always create signed index and templates.
1801 ARCHITECTURE
1803 Virt-builder can build a guest for any architecture no matter what the
1804 host architecture is. For example an x86-64 guest on an ARM host.
1805 However certain options may not work, specifically options that require
1807 running commands in the guest during the build process: --install,
1808 --update, --run, --run-command. You may need to replace these with
1809 their firstboot-equivalents.
1810 An x86-64 host building 32 bit i686 guests should work without any
1812 special steps.
1813 SECURITY
1815 Virt-builder does not need to run as root (in fact, should not be run
1816 as root), and doesn't use setuid, "sudo" or any similar mechanism.
1817 --install, --update, --run and --run-command are implemented using an
1819 appliance (a small virtual machine) so these commands do not run on the
1820 host. If you are using the libguestfs libvirt backend and have SELinux
1821 enabled then the virtual machine is additionally encapsulated in an
1822 SELinux container (sVirt).
1823 However these options will have access to the host’s network and since
1825 the template may contain untrusted code, the code might try to access
1826 host network resources which it should not. You can use --no-network
1827 to prevent this.
1828 Firstboot commands run in the context of the guest when it is booted,
1830 and so the security of your hypervisor / cloud should be considered.
1831 Virt-builder injects a random seed into every guest which it builds.
1833 This helps to ensure that TCP sequence numbers, UUIDs, ssh host keys
1834 etc are truly random when the guest boots.
1835 You should check digital signatures and not ignore any signing errors.
1837 CLONES
1839 If you wish to create many new guests of the same type, it is tempting
1840 to run virt-builder once and then copy the output file. You should not
1841 do this. You should run virt-builder once for each new guest you need.
1842 The reason is that each clone needs to have (at least) a separate
1844 random seed, and possibly other unique features (such as filesystem
1845 UUIDs) in future versions of virt-builder.
1846 Another thing you should not do is to boot the guest, then clone the
1848 booted disk image. The reason is that some guests create unique
1849 machine IDs, SSH host keys and so on at first boot, and you would not
1850 want clones to have duplicate identities.
1851 See also: virt-sysprep(1).
1853 PERFORMANCE
1855 The most important aspect of getting good performance is caching.
1856 Templates gets downloaded into the cache the first time they are used,
1857 or if you use the --cache-all-templates option. See "CACHING" above
1858 for further information.
1859 Packages required for the --install and --update options are downloaded
1861 using the host network connection. Setting the "http_proxy",
1862 "https_proxy" and "ftp_proxy" environment variables to point to a local
1863 web cache may ensure they only need to be downloaded once. You can
1864 also try using a local package repository, although this can be complex
1865 to set up and varies according to which Linux distro you are trying to
1866 install.
1867 Using --no-sync
1869 Use --no-sync. However read the caveats in the "OPTIONS" section
1871 above, since this can cause disk corruption if not used correctly.
1872 Skipping virt-resize
1874 Virt-builder can skip the virt-resize step under certain conditions.
1876 This makes virt-builder much faster. The conditions are:
1877 • the output must be a regular file (not a block device), and
1879 • the user did not use the --size option, and
1881 • the output format is the same as the template format (usually raw).
1883 pxzcat
1885 Virt-builder uses an internal implementation of pxzcat (parallel xzcat)
1887 if liblzma was found at build time. If liblzma was not found at build
1888 time, regular "xzcat" is used which is single-threaded.
1889 SELINUX
1891 Guests which use SELinux (such as Fedora and Red Hat Enterprise Linux)
1892 require that each file has a correct SELinux label.
1893 Virt-builder does not know how to give new files a label, so there are
1895 two possible strategies it can use to ensure correct labelling:
1896 Automatic relabeling
1898 This runs setfiles(8) just before finalizing the guest, which sets
1899 SELinux labels correctly in the disk image.
1900 This is the recommended method.
1902 Using --no-selinux-relabel --touch /.autorelabel
1904 Guest templates may already contain a file called /.autorelabel or
1905 you may touch it.
1906 For guests that use SELinux, this causes restorecon(8) to run at
1908 first boot. Guests will reboot themselves once the first time you
1909 use them, which is normal and harmless.
1910
1912 The --machine-readable option can be used to make the output more
1913 machine friendly, which is useful when calling virt-builder from other
1914 programs, GUIs etc.
1915 Use the option on its own to query the capabilities of the virt-builder
1917 binary. Typical output looks like this:
1918 $ virt-builder --machine-readable
1920 virt-builder
1921 arch
1922 config-file
1923 customize
1924 json-list
1925 pxzcat
1926 A list of features is printed, one per line, and the program exits with
1928 status 0.
1929 It is possible to specify a format string for controlling the output;
1931 see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
1932
1934 For other environment variables which affect all libguestfs programs,
1935 see "ENVIRONMENT VARIABLES" in guestfs(3).
1936 "http_proxy"
1938 "https_proxy"
1939 "no_proxy"
1940 Set the proxy for downloads. These environment variables (and
1941 more) are actually interpreted by curl(1), not virt-builder.
1942 "HOME"
1944 Used to determine the location of the template cache, and the
1945 location of the user' sources. See "CACHING" and "SOURCES OF
1946 TEMPLATES".
1947 "VIRT_TOOLS_DATA_DIR"
1949 This can point to the directory containing data files used for
1950 Windows firstboot installation.
1951 Normally you do not need to set this. If not set, a compiled-in
1953 default will be used (something like /usr/share/virt-tools).
1954 This directory may contain the following files:
1956 rhsrvany.exe
1958 This is the RHSrvAny Windows binary, used to install a
1959 "firstboot" script in Windows guests. It is required if you
1960 intend to use the --firstboot or --firstboot-command options
1961 with Windows guests.
1962 See also: "https://github.com/rwmjones/rhsrvany"
1964 pvvxsvc.exe
1966 This is a Windows binary shipped with SUSE VMDP, used to
1967 install a "firstboot" script in Windows guests. It is required
1968 if you intend to use the --firstboot or --firstboot-command
1969 options with Windows guests.
1970 "XDG_CACHE_HOME"
1972 Used to determine the location of the template cache. See
1973 "CACHING".
1974 "XDG_CONFIG_HOME"
1976 Used to determine the location of the user' sources. See "SOURCES
1977 OF TEMPLATES".
1978 "VIRT_BUILDER_DIRS"
1980 Used to determine the location of the system sources. See "SOURCES
1981 OF TEMPLATES".
1982
1984 This program returns 0 if successful, or non-zero if there was an
1985 error.
1986
1988 guestfs(3), guestfish(1), guestmount(1), virt-builder-repository(1),
1989 virt-copy-out(1), virt-customize(1), virt-get-kernel(1),
1990 virt-install(1), virt-rescue(1), virt-resize(1), virt-sysprep(1),
1991 oz-install(1), gpg(1), gpg2(1), curl(1), virt-make-fs(1),
1992 genisoimage(1), http://libguestfs.org/.
1993
1995 Richard W.M. Jones http://people.redhat.com/~rjones/
1996
1998 Copyright (C) 2013 Red Hat Inc.
1999
2001 This program is free software; you can redistribute it and/or modify it
2002 under the terms of the GNU General Public License as published by the
2003 Free Software Foundation; either version 2 of the License, or (at your
2004 option) any later version.
2005 This program is distributed in the hope that it will be useful, but
2007 WITHOUT ANY WARRANTY; without even the implied warranty of
2008 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
2009 General Public License for more details.
2010 You should have received a copy of the GNU General Public License along
2012 with this program; if not, write to the Free Software Foundation, Inc.,
2013 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
2014
2016 To get a list of bugs against libguestfs, use this link:
2017 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
2018 To report a new bug against libguestfs, use this link:
2020 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
2021 When reporting a bug, please supply:
2023 • The version of libguestfs.
2025 • Where you got libguestfs (eg. which Linux distro, compiled from
2027 source, etc)
2028 • Describe the bug accurately and give a way to reproduce it.
2030 • Run libguestfs-test-tool(1) and paste the complete, unedited output
2032 into the bug report.
2033guestfs-tools-1.50.1 2023-04-06 virt-builder(1)