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] [--selinux-relabel]
27 [--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-25
71 Build a virtual machine
73 virt-builder fedora-25
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-25.img. You can change the output filename using the
88 -o option:
89 virt-builder fedora-25 -o mydisk.img
91 You can also use the -o option to write to existing devices or logical
93 volumes.
94 virt-builder fedora-25 --format qcow2
96 As above, but write the output in qcow2 format to fedora-25.qcow2.
98 virt-builder fedora-25 --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-25 --arch i686
105 As above, but using an i686 template, if available.
107 Setting the root password
109 virt-builder fedora-25 --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-25 --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-25 --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 For guests which use SELinux, like Fedora and Red Hat Enterprise Linux,
138 you may need to do SELinux relabelling after installing or updating
139 packages (see "SELINUX" below):
140 virt-builder fedora-25 --update --selinux-relabel
142 Customizing the installation
144 There are many options that let you customize the installation. These
145 include: --run/--run-command, which run a shell script or command while
146 the disk image is being generated and lets you add or edit files that
147 go into the disk image. --firstboot/--firstboot-command, which let you
148 add scripts/commands that are run the first time the guest boots.
149 --edit to edit files. --upload to upload files.
150 For example:
152 cat <<'EOF' > /tmp/dnf-update.sh
154 dnf -y --best update
155 EOF
156 virt-builder fedora-25 --firstboot /tmp/dnf-update.sh
158 or simply:
160 virt-builder fedora-25 --firstboot-command 'dnf -y --best update'
162 which makes the dnf(8) "update" command run once the first time the
164 guest boots.
165 Or:
167 virt-builder fedora-25 \
169 --edit '/etc/dnf/dnf.conf:
170 s/gpgcheck=1/gpgcheck=0/'
171 which edits /etc/dnf/dnf.conf inside the disk image (during disk image
173 creation, long before boot).
174 You can combine these options, and have multiple options of all types.
176
178 --help
179 Display help.
180 --arch ARCHITECTURE
182 Use the specified architecture for the output image. This means
183 there must be sources providing the requested template for the
184 requested architecture.
185 See also "ARCHITECTURE".
187 --attach ISOFILE
189 During the customization phase, the given disk is attached to the
190 libguestfs appliance. This is used to provide extra software
191 repositories or other data for customization.
192 You probably want to ensure the volume(s) or filesystems in the
194 attached disks are labelled (or use an ISO volume name) so that you
195 can mount them by label in your run-scripts:
196 mkdir /tmp/mount
198 mount LABEL=EXTRA /tmp/mount
199 You can have multiple --attach options, and the format can be any
201 disk format (not just an ISO).
202 See also: --run, "Installing packages at build time from a side
204 repository", genisoimage(1), virt-make-fs(1).
205 --attach-format FORMAT
207 Specify the disk format for the next --attach option. The "FORMAT"
208 is usually "raw" or "qcow2". Use "raw" for ISOs.
209 --cache DIR
211 --no-cache
212 --cache DIR sets the directory to use/check for cached template
213 files. If not set, defaults to either
214 $XDG_CACHE_HOME/virt-builder/ or $HOME/.cache/virt-builder/.
215 --no-cache disables template caching.
217 --cache-all-templates
219 Download all templates to the cache and then exit. See "CACHING".
220 Note this doesn't cache everything. More templates might be
222 uploaded. Also this doesn't cache packages (the --install,
223 --update options).
224 --check-signature
226 --no-check-signature
227 Check/don’t check the digital signature of the OS template. The
228 default is to check the signature and exit if it is not correct.
229 Using --no-check-signature bypasses this check.
230 See also --fingerprint.
232 --colors
234 --colours
235 Use ANSI colour sequences to colourize messages. This is the
236 default when the output is a tty. If the output of the program is
237 redirected to a file, ANSI colour sequences are disabled unless you
238 use this option.
239 --curl CURL
241 Specify an alternate curl(1) binary. You can also use this to add
242 curl parameters, for example to disable https certificate checks:
243 virt-builder --curl "curl --insecure" [...]
245 --delete-cache
247 Delete the template cache. See "CACHING".
248 --no-delete-on-failure
250 Don’t delete the output file on failure to build. You can use this
251 to debug failures to run scripts. See "DEBUGGING BUILDS" for ways
252 to debug images.
253 The default is to delete the output file if virt-builder fails (or,
255 for example, some script that it runs fails).
256 --fingerprint 'AAAA BBBB ...'
258 Check that the index and templates are signed by the key with the
259 given fingerprint. (The fingerprint is a long string, usually
260 written as 10 groups of 4 hexadecimal digits).
261 You can give this option multiple times. If you have multiple
263 source URLs, then you can have either no fingerprint, one
264 fingerprint or multiple fingerprints. If you have multiple, then
265 each must correspond 1-1 with a source URL.
266 --format qcow2
268 --format raw
269 For ordinary builds, this selects the output format. The default
270 is raw.
271 With --get-kernel this specifies the input format.
273 To create an old-style qcow2 file (for compatibility with RHEL 6 or
275 very old qemu < 1.1), after running virt-builder, use this command:
276 qemu-img amend -f qcow2 -o compat=0.10 output.qcow2
278 --get-kernel IMAGE
280 This option extracts the kernel and initramfs from a previously
281 built disk image called "IMAGE" (in fact it works for any VM disk
282 image, not just ones built using virt-builder).
283 Note this method is deprecated: there is a separate tool for this,
285 virt-get-kernel(1), which has more options for the file extraction.
286 The kernel and initramfs are written to the current directory,
288 unless you also specify the --output "outputdir" directory name.
289 The format of the disk image is automatically detected unless you
291 specify it by using the --format option.
292 In the case where the guest contains multiple kernels, the one with
294 the highest version number is chosen. To extract arbitrary kernels
295 from the disk image, see guestfish(1). To extract the entire /boot
296 directory of a guest, see virt-copy-out(1).
297 --gpg GPG
299 Specify an alternate gpg(1) (GNU Privacy Guard) binary. By default
300 virt-builder looks for either "gpg2" or "gpg" in the $PATH.
301 You can also use this to add gpg parameters, for example to specify
303 an alternate home directory:
304 virt-builder --gpg "gpg --homedir /tmp" [...]
306 -l [os-version]
308 --list [os-version]
309 --list --list-format format [os-version]
310 --list --long [os-version]
311 List all the available templates if no guest is specified, or only
312 for the specified one.
313 It is possible to choose with --list-format the output format for
315 the list templates:
316 short
318 The default format, prints only the template identifier and,
319 next to it, its short description.
320 long
322 Prints a textual list with the details of the available
323 sources, followed by the details of the available templates.
324 json
326 Prints a JSON object with the details of the available sources
327 and the details of the available templates.
328 The "version" key in the main object represents the
330 "compatibility version", and it is bumped every time the
331 resulting JSON output is incompatible with the previous
332 versions (for example the structure has changed, or non-
333 optional keys are no more present).
334 --long is a shorthand for the "long" format.
336 See also: --source, --notes, "SOURCES OF TEMPLATES".
338 --machine-readable
340 This option is used to make the output more machine friendly when
341 being parsed by other programs. See "MACHINE READABLE OUTPUT"
342 below.
343 -m MB
345 --memsize MB
346 Change the amount of memory allocated to --run scripts. Increase
347 this if you find that --run scripts or the --install option are
348 running out of memory.
349 The default can be found with this command:
351 guestfish get-memsize
353 --network
355 --no-network
356 Enable or disable network access from the guest during the
357 installation.
358 Enabled is the default. Use --no-network to disable access.
360 The network only allows outgoing connections and has other minor
362 limitations. See "NETWORK" in virt-rescue(1).
363 If you use --no-network then certain other options such as
365 --install will not work.
366 This does not affect whether the guest can access the network once
368 it has been booted, because that is controlled by your hypervisor
369 or cloud environment and has nothing to do with virt-builder.
370 Generally speaking you should not use --no-network. But here are
372 some reasons why you might want to:
373 1. Because the libguestfs backend that you are using doesn't
375 support the network. (See: "BACKEND" in guestfs(3)).
376 2. Any software you need to install comes from an attached ISO, so
378 you don't need the network.
379 3. You don’t want untrusted guest code trying to access your host
381 network when running virt-builder. This is particularly an
382 issue when you don't trust the source of the operating system
383 templates. (See "SECURITY" below).
384 4. You don’t have a host network (eg. in secure/restricted
386 environments).
387 --no-sync
389 Do not sync the output file on exit.
390 Virt-builder "fsync"s the output file or disk image when it exits.
392 The reason is that qemu/KVM’s default caching mode is "none" or
394 "directsync", both of which bypass the host page cache. Therefore
395 these would not work correctly if you immediately started the guest
396 after running virt-builder - they would not see the complete output
397 file. (Note that you should not use these caching modes - they are
398 fundamentally broken for this and other reasons.)
399 If you are not using these broken caching modes, you can use
401 --no-sync to avoid this unnecessary sync and gain considerable
402 extra performance.
403 --notes os-version
405 List any notes associated with this guest, then exit (this does not
406 do the install).
407 -o filename
409 --output filename
410 Write the output to filename. If you don’t specify this option,
411 then the output filename is generated by taking the "os-version"
412 string and adding ".img" (for raw format) or ".qcow2" (for qcow2
413 format).
414 Note that the output filename could be a device, partition or
416 logical volume.
417 When used with --get-kernel, this option specifies the output
419 directory.
420 --print-cache
422 Print information about the template cache. See "CACHING".
423 -q
425 --quiet
426 Don’t print ordinary progress messages.
427 --size SIZE
429 Select the size of the output disk, where the size can be specified
430 using common names such as "32G" (32 gigabytes) etc.
431 Virt-builder will resize filesystems inside the disk image
433 automatically.
434 If the size is not specified, then one of two things happens. If
436 the output is a file, then the size is the same as the template.
437 If the output is a device, partition, etc then the size of that
438 device is used.
439 To specify size in bytes, the number must be followed by the
441 lowercase letter b, eg: "--size 10737418240b".
442 --smp N
444 Enable N ≥ 2 virtual CPUs for --run scripts to use.
445 --source URL
447 Set the source URL to look for indexes.
448 You can give this option multiple times to specify multiple
450 sources.
451 See also "SOURCES OF TEMPLATES" below.
453 Note that you should not point --source to sources that you don’t
455 trust (unless the source is signed by someone you do trust). See
456 also the --no-network option.
457 --no-warn-if-partition
459 Do not emit a warning if the output device is a partition. This
460 warning avoids a common user error when writing to a USB key or
461 external drive, when you should normally write to the whole device
462 (--output /dev/sdX), not to a partition on the device
463 (--output /dev/sdX1). Use this option to suppress this warning.
464 -v
466 --verbose
467 Enable debug messages and/or produce verbose output.
468 When reporting bugs, use this option and attach the complete output
470 to your bug report.
471 -V
473 --version
474 Display version number and exit.
475 -x Enable tracing of libguestfs API calls.
477 Customization options
479 --append-line FILE:LINE
480 Append a single line of text to the "FILE". If the file does not
481 already end with a newline, then one is added before the appended
482 line. Also a newline is added to the end of the "LINE" string
483 automatically.
484 For example (assuming ordinary shell quoting) this command:
486 --append-line '/etc/hosts:10.0.0.1 foo'
488 will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
490 the latter only if the existing file does not already end with a
491 newline.
492 "⏎" represents a newline character, which is guessed by looking at
494 the existing content of the file, so this command does the right
495 thing for files using Unix or Windows line endings. It also works
496 for empty or non-existent files.
497 To insert several lines, use the same option several times:
499 --append-line '/etc/hosts:10.0.0.1 foo'
501 --append-line '/etc/hosts:10.0.0.2 bar'
502 To insert a blank line before the appended line, do:
504 --append-line '/etc/hosts:'
506 --append-line '/etc/hosts:10.0.0.1 foo'
507 --chmod PERMISSIONS:FILE
509 Change the permissions of "FILE" to "PERMISSIONS".
510 Note: "PERMISSIONS" by default would be decimal, unless you prefix
512 it with 0 to get octal, ie. use 0700 not 700.
513 --commands-from-file FILENAME
515 Read the customize commands from a file, one (and its arguments)
516 each line.
517 Each line contains a single customization command and its
519 arguments, for example:
520 delete /some/file
522 install some-package
523 password some-user:password:its-new-password
524 Empty lines are ignored, and lines starting with "#" are comments
526 and are ignored as well. Furthermore, arguments can be spread
527 across multiple lines, by adding a "\" (continuation character) at
528 the of a line, for example
529 edit /some/file:\
531 s/^OPT=.*/OPT=ok/
532 The commands are handled in the same order as they are in the file,
534 as if they were specified as --delete /some/file on the command
535 line.
536 --copy SOURCE:DEST
538 Copy files or directories recursively inside the guest.
539 Wildcards cannot be used.
541 --copy-in LOCALPATH:REMOTEDIR
543 Copy local files or directories recursively into the disk image,
544 placing them in the directory "REMOTEDIR" (which must exist).
545 Wildcards cannot be used.
547 --delete PATH
549 Delete a file from the guest. Or delete a directory (and all its
550 contents, recursively).
551 You can use shell glob characters in the specified path. Be
553 careful to escape glob characters from the host shell, if that is
554 required. For example:
555 virt-customize --delete '/var/log/*.log'.
557 See also: --upload, --scrub.
559 --edit FILE:EXPR
561 Edit "FILE" using the Perl expression "EXPR".
562 Be careful to properly quote the expression to prevent it from
564 being altered by the shell.
565 Note that this option is only available when Perl 5 is installed.
567 See "NON-INTERACTIVE EDITING" in virt-edit(1).
569 --firstboot SCRIPT
571 Install "SCRIPT" inside the guest, so that when the guest first
572 boots up, the script runs (as root, late in the boot process).
573 The script is automatically chmod +x after installation in the
575 guest.
576 The alternative version --firstboot-command is the same, but it
578 conveniently wraps the command up in a single line script for you.
579 You can have multiple --firstboot options. They run in the same
581 order that they appear on the command line.
582 Please take a look at "FIRST BOOT SCRIPTS" for more information and
584 caveats about the first boot scripts.
585 See also --run.
587 --firstboot-command 'CMD+ARGS'
589 Run command (and arguments) inside the guest when the guest first
590 boots up (as root, late in the boot process).
591 You can have multiple --firstboot options. They run in the same
593 order that they appear on the command line.
594 Please take a look at "FIRST BOOT SCRIPTS" for more information and
596 caveats about the first boot scripts.
597 See also --run.
599 --firstboot-install PKG,PKG..
601 Install the named packages (a comma-separated list). These are
602 installed when the guest first boots using the guest’s package
603 manager (eg. apt, yum, etc.) and the guest’s network connection.
604 For an overview on the different ways to install packages, see
606 "INSTALLING PACKAGES".
607 --hostname HOSTNAME
609 Set the hostname of the guest to "HOSTNAME". You can use a dotted
610 hostname.domainname (FQDN) if you want.
611 --install PKG,PKG..
613 Install the named packages (a comma-separated list). These are
614 installed during the image build using the guest’s package manager
615 (eg. apt, yum, etc.) and the host’s network connection.
616 For an overview on the different ways to install packages, see
618 "INSTALLING PACKAGES".
619 See also --update, --uninstall.
621 --link TARGET:LINK[:LINK..]
623 Create symbolic link(s) in the guest, starting at "LINK" and
624 pointing at "TARGET".
625 --mkdir DIR
627 Create a directory in the guest.
628 This uses "mkdir -p" so any intermediate directories are created,
630 and it also works if the directory already exists.
631 --move SOURCE:DEST
633 Move files or directories inside the guest.
634 Wildcards cannot be used.
636 --no-logfile
638 Scrub "builder.log" (log file from build commands) from the image
639 after building is complete. If you don't want to reveal precisely
640 how the image was built, use this option.
641 See also: "LOG FILE".
643 --password USER:SELECTOR
645 Set the password for "USER". (Note this option does not create the
646 user account).
647 See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
649 and also how to set up user accounts.
650 --password-crypto md5|sha256|sha512
652 When the virt tools change or set a password in the guest, this
653 option sets the password encryption of that password to "md5",
654 "sha256" or "sha512".
655 "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
657 the guest).
658 "md5" will work with relatively old Linux guests (eg. RHEL 3), but
660 is not secure against modern attacks.
661 The default is "sha512" unless libguestfs detects an old guest that
663 didn't have support for SHA-512, in which case it will use "md5".
664 You can override libguestfs by specifying this option.
665 Note this does not change the default password encryption used by
667 the guest when you create new user accounts inside the guest. If
668 you want to do that, then you should use the --edit option to
669 modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
670 "/etc/pam.d/common-password" (Debian, Ubuntu).
671 --root-password SELECTOR
673 Set the root password.
674 See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
676 and also how to set up user accounts.
677 Note: In virt-builder, if you don't set --root-password then the
679 guest is given a random root password.
680 --run SCRIPT
682 Run the shell script (or any program) called "SCRIPT" on the disk
683 image. The script runs virtualized inside a small appliance,
684 chrooted into the guest filesystem.
685 The script is automatically chmod +x.
687 If libguestfs supports it then a limited network connection is
689 available but it only allows outgoing network connections. You can
690 also attach data disks (eg. ISO files) as another way to provide
691 data (eg. software packages) to the script without needing a
692 network connection (--attach). You can also upload data files
693 (--upload).
694 You can have multiple --run options. They run in the same order
696 that they appear on the command line.
697 See also: --firstboot, --attach, --upload.
699 --run-command 'CMD+ARGS'
701 Run the command and arguments on the disk image. The command runs
702 virtualized inside a small appliance, chrooted into the guest
703 filesystem.
704 If libguestfs supports it then a limited network connection is
706 available but it only allows outgoing network connections. You can
707 also attach data disks (eg. ISO files) as another way to provide
708 data (eg. software packages) to the script without needing a
709 network connection (--attach). You can also upload data files
710 (--upload).
711 You can have multiple --run-command options. They run in the same
713 order that they appear on the command line.
714 See also: --firstboot, --attach, --upload.
716 --scrub FILE
718 Scrub a file from the guest. This is like --delete except that:
719 · It scrubs the data so a guest could not recover it.
721 · It cannot delete directories, only regular files.
723 --selinux-relabel
725 Relabel files in the guest so that they have the correct SELinux
726 label.
727 This will attempt to relabel files immediately, but if the
729 operation fails this will instead touch /.autorelabel on the image
730 to schedule a relabel operation for the next time the image boots.
731 You should only use this option for guests which support SELinux.
733 --sm-attach SELECTOR
735 Attach to a pool using "subscription-manager".
736 See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
738 --sm-credentials SELECTOR
740 Set the credentials for "subscription-manager".
741 See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
743 --sm-register
745 Register the guest using "subscription-manager".
746 This requires credentials being set using --sm-credentials.
748 --sm-remove
750 Remove all the subscriptions from the guest using
751 "subscription-manager".
752 --sm-unregister
754 Unregister the guest using "subscription-manager".
755 --ssh-inject USER[:SELECTOR]
757 Inject an ssh key so the given "USER" will be able to log in over
758 ssh without supplying a password. The "USER" must exist already in
759 the guest.
760 See "SSH KEYS" for the format of the "SELECTOR" field.
762 You can have multiple --ssh-inject options, for different users and
764 also for more keys for each user.
765 --timezone TIMEZONE
767 Set the default timezone of the guest to "TIMEZONE". Use a
768 location string like "Europe/London"
769 --touch FILE
771 This command performs a touch(1)-like operation on "FILE".
772 --truncate FILE
774 This command truncates "FILE" to a zero-length file. The file must
775 exist already.
776 --truncate-recursive PATH
778 This command recursively truncates all files under "PATH" to zero-
779 length.
780 --uninstall PKG,PKG..
782 Uninstall the named packages (a comma-separated list). These are
783 removed during the image build using the guest’s package manager
784 (eg. apt, yum, etc.). Dependent packages may also need to be
785 uninstalled to satisfy the request.
786 See also --install, --update.
788 --update
790 Do the equivalent of "yum update", "apt-get upgrade", or whatever
791 command is required to update the packages already installed in the
792 template to their latest versions.
793 See also --install, --uninstall.
795 --upload FILE:DEST
797 Upload local file "FILE" to destination "DEST" in the disk image.
798 File owner and permissions from the original are preserved, so you
799 should set them to what you want them to be in the disk image.
800 "DEST" could be the final filename. This can be used to rename the
802 file on upload.
803 If "DEST" is a directory name (which must already exist in the
805 guest) then the file is uploaded into that directory, and it keeps
806 the same name as on the local filesystem.
807 See also: --mkdir, --delete, --scrub.
809 --write FILE:CONTENT
811 Write "CONTENT" to "FILE".
812
814 INSTALLING PACKAGES
815 There are several approaches to installing packages or applications in
816 the guest which have different trade-offs.
817 Installing packages at build time
819 If the guest OS you are installing is similar to the host OS (eg. both
821 are Linux), and if libguestfs supports network connections, then you
822 can use --install to install packages like this:
823 virt-builder fedora-25 --install inkscape
825 This uses the guest’s package manager and the host’s network
827 connection.
828 Updating packages at build time
830 To update the installed packages in the template at build time:
832 virt-builder fedora-25 --update
834 Most of the templates that ship with virt-builder come with a very
836 minimal selection of packages (known as a "JEOS" or "Just Enough
837 Operating System"), which are up to date at the time the template is
838 created, but could be out of date by the time you come to install an OS
839 from the template. This option updates those template packages.
840 Installing packages at first boot
842 Another option is to install the packages when the guest first boots:
844 virt-builder fedora-25 --firstboot-install inkscape
846 This uses the guest’s package manager and the guest’s network
848 connection.
849 The downsides are that it will take the guest a lot longer to boot
851 first time, and there’s nothing much you can do if package installation
852 fails (eg. if a network problem means the guest can't reach the package
853 repositories).
854 Installing packages at build time from a side repository
856 If the software you want to install is not available in the main
858 package repository of the guest, then you can add a side repository.
859 Usually this is presented as an ISO (CD disk image) file containing
860 extra packages.
861 You can create the disk image using either genisoimage(1) or
863 virt-make-fs(1). For genisoimage, use a command like this:
864 genisoimage -o extra-packages.iso -R -J -V EXTRA cdcontents/
866 Create a script that mounts the ISO and sets up the repository. For
868 dnf, create /tmp/install.sh containing:
869 mkdir /tmp/mount
871 mount LABEL=EXTRA /tmp/mount
872 cat <<'EOF' > /etc/yum.repos.d/extra.repo
874 [extra]
875 name=extra
876 baseurl=file:///tmp/mount
877 enabled=1
878 EOF
879 dnf -y install famousdatabase
881 For apt, create /tmp/install.sh containing:
883 mkdir /tmp/mount
885 mount LABEL=EXTRA /tmp/mount
886 apt-cdrom -d=/tmp/mount add
888 apt-get -y install famousdatabase
889 Use the --attach option to attach the CD / disk image and the --run
891 option to run the script:
892 virt-builder fedora-25 \
894 --attach extra-packages.iso \
895 --run /tmp/install.sh
896 USERS AND PASSWORDS
898 The --root-password option is used to change the root password
899 (otherwise a random password is used). This option takes a password
900 "SELECTOR" in one of the following formats:
901 --root-password file:FILENAME
903 Read the root password from "FILENAME". The whole first line of
904 this file is the replacement password. Any other lines are
905 ignored. You should create the file with mode 0600 to ensure no
906 one else can read it.
907 --root-password password:PASSWORD
909 Set the root password to the literal string "PASSWORD".
910 Note: this is not secure since any user on the same machine can see
912 the cleartext password using ps(1).
913 --root-password random
915 Choose a random password, which is printed on stdout. The password
916 has approximately 120 bits of randomness.
917 This is the default.
919 --root-password disabled
921 The root account password is disabled. This is like putting "*" in
922 the password field.
923 --root-password locked:file:FILENAME
925 --root-password locked:password:PASSWORD
926 --root-password locked:random
927 The root account is locked, but a password is placed on the
928 account. If first unlocked (using "passwd -u") then logins will
929 use the given password.
930 --root-password locked
932 --root-password locked:disabled
933 The root account is locked and password is disabled.
934 Creating user accounts
936 To create user accounts, use the useradd(8) command with
938 --firstboot-command like this:
939 virt-builder --firstboot-command \
941 'useradd -m -p "" rjones ; chage -d 0 rjones'
942 The above command will create an "rjones" account with no password, and
944 force the user to set a password when they first log in. There are
945 other ways to manage passwords, see useradd(8) for details.
946 KEYBOARD LAYOUT
948 Because there are so many different ways to set the keyboard layout in
949 Linux distributions, virt-builder does not yet attempt to have a simple
950 command line option. This section describes how to set the keyboard
951 for some common Linux distributions.
952 Keyboard layout with systemd
954 For distros that use systemd "localectl", use a command like this:
956 virt-builder fedora-25 \
958 --firstboot-command 'localectl set-keymap uk'
959 See localectl(1) and
961 https://www.happyassassin.net/2013/11/23/keyboard-layouts-in-fedora-20-and-previously/
962 for more details.
963 Keyboard layout using /etc/sysconfig/keyboard
965 For RHEL ≤ 6, Fedora ≤ 18 and similar, upload or modify the keyboard
967 configuration file using the --upload, --write or --edit options. For
968 example:
969 virt-builder centos-6 \
971 --edit '/etc/sysconfig/keyboard: s/^KEYTABLE=.*/KEYTABLE="uk"/'
972 The format of this file can be found documented in many places online.
974 Keyboard layout with Debian-derived distros
976 For Debian-derived distros using /etc/default/keyboard, upload or
978 modify the keyboard file using the --upload, --write or --edit options.
979 For example:
980 virt-builder debian-8 \
982 --edit '/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/'
983 See https://wiki.debian.org/Keyboard.
985 LANGUAGE
987 Most Linux distributions support multiple locale settings so that you
988 can have guest messages printed in another language such as Russian.
989 However there is no single setting which controls this, since extra
991 packages may need to be installed to support console and X fonts, and
992 keyboard input methods. The packages required, and their configuration
993 is highly distro-specific, and it is outside the scope of virt-builder
994 to do this.
995 This section contains examples for some common Linux distributions.
997 Setting Japanese in Fedora 25
999 virt-builder fedora-25 \
1001 --size 20G \
1002 --update \
1003 --install @japanese-support \
1004 --install @xfce \
1005 --install xorg-x11-server-Xorg,xorg-x11-drivers,rsyslog \
1006 --link /usr/lib/systemd/system/graphical.target:/etc/systemd/system/default.target \
1007 --firstboot-command 'localectl set-locale LANG=ja_JP.utf8' \
1008 --firstboot-command 'localectl set-keymap jp' \
1009 --firstboot-command 'systemctl isolate graphical.target'
1010 Setting Japanese in Debian 8 (Jessie)
1012 Note that although this enables Japanese in the text console too, it is
1014 unlikely that you will see properly rendered Japanese there. However
1015 Japanese is properly rendered in X applications and terminals.
1016 pkgs=locales,xfce4,\
1018 ibus,ibus-anthy,\
1019 fonts-ipafont-gothic,fonts-ipafont-mincho,\
1020 fonts-takao-mincho,\
1021 xfonts-intl-japanese,xfonts-intl-japanese-big,\
1022 iceweasel-l10n-ja,manpages-ja
1023 virt-builder debian-8 \
1025 --size 20G \
1026 --install $pkgs \
1027 --edit '/etc/locale.gen: s,^#\s*ja,ja,' \
1028 --write '/etc/default/locale:LANG="ja_JP.UTF-8"' \
1029 --run-command "locale-gen"
1030 LOG FILE
1032 Scripts and package installation that runs at build time (--run,
1033 --run-command, --install, --update, but not firstboot) is logged in one
1034 of the following locations:
1035 /tmp/builder.log
1037 On Linux, BSD, and other non-Windows guests.
1038 C:\Temp\builder.log
1040 On Windows, DOS guests.
1041 /builder.log
1043 If /tmp or C:\Temp is missing.
1044 If you don’t want the log file to appear in the final image, then use
1046 the --no-logfile command line option.
1047 SSH KEYS
1049 The --ssh-inject option is used to inject ssh keys for users in the
1050 guest, so they can login without supplying a password.
1051 The "SELECTOR" part of the option value is optional; in this case,
1053 --ssh-inject "USER" means that we look in the current user’s ~/.ssh
1054 directory to find the default public ID file. That key is uploaded.
1055 "default public ID" is the default_ID_file file described in
1056 ssh-copy-id(1).
1057 If specified, the "SELECTOR" can be in one of the following formats:
1059 --ssh-inject USER:file:FILENAME
1061 Read the ssh key from FILENAME. FILENAME is usually a .pub file.
1062 --ssh-inject USER:string:KEY_STRING
1064 Use the specified "KEY_STRING". "KEY_STRING" is usually a public
1065 string like ssh-rsa AAAA.... user@localhost.
1066 In any case, the ~USER/.ssh directory and the
1068 ~USER/.ssh/authorized_keys file will be created if not existing
1069 already.
1070 FIRST BOOT SCRIPTS
1072 The --firstboot and --firstboot-command options allow you to execute
1073 commands at the first boot of the guest. To do so, an init script for
1074 the guest init system is installed, which takes care of running all the
1075 added scripts and commands.
1076 Supported operating systems are:
1078 Linux
1080 Init systems supported are: systemd, System-V init (known also as
1081 sysvinit), and Upstart (using the System-V scripts).
1082 Note that usually init scripts run as root, but with a more limited
1084 environment than what could be available from a normal shell: for
1085 example, $HOME may be unset or empty.
1086 The output of the first boot scripts is available in the guest as
1088 ~root/virt-sysprep-firstboot.log.
1089 Windows
1091 rhsrvany.exe, available from sources at
1092 https://github.com/rwmjones/rhsrvany, or pvvxsvc.exe, available
1093 with SUSE VMDP is installed to run the first boot scripts. It is
1094 required, and the setup of first boot scripts will fail if it is
1095 not present.
1096 rhsrvany.exe or pvvxsvc.exe is copied from the location pointed to
1098 by the "VIRT_TOOLS_DATA_DIR" environment variable; if not set, a
1099 compiled-in default will be used (something like
1100 /usr/share/virt-tools).
1101 The output of the first boot scripts is available in the guest as
1103 C:\Program Files\Guestfs\Firstboot\log.txt.
1104 SUBSCRIPTION-MANAGER
1106 It is possible to automate the registration and attaching of the system
1107 using "subscription-manager". This is typical on Red Hat Enterprise
1108 Linux guests. There are few options which ease this process, avoid
1109 executing commands manually and exposing passwords on command line.
1110 --sm-register starts the registration process, and requires
1112 --sm-credentials to be specified; the format of the "SELECTOR" of
1113 --sm-credentials is one of the following formats:
1114 --sm-credentials USER:file:FILENAME
1116 Read the password for the specified "USER" from FILENAME.
1117 --sm-credentials USER:password:PASSWORD
1119 Use the literal string "PASSWORD" for the specified "USER".
1120 --sm-attach attaches the system to subscriptions; the format of its
1122 "SELECTOR" is one of the following:
1123 --sm-attach auto
1125 "subscription-manager" attaches to the best-fitting subscriptions
1126 for the system.
1127 --sm-attach file:FILENAME
1129 Read the pool ID from FILENAME.
1130 --sm-attach pool:POOL
1132 Use the literal string "POOL" as pool ID.
1133 --sm-remove removes all the subscriptions from the guest, while
1135 --sm-unregister completely unregister the system.
1136 INSTALLATION PROCESS
1138 When you invoke virt-builder, installation proceeds as follows:
1139 · The template image is downloaded.
1141 If the template image is present in the cache, the cached version
1143 is used instead. (See "CACHING").
1144 · The template signature is checked.
1146 · The template is uncompressed to a tmp file.
1148 · The template image is resized into the destination, using
1150 virt-resize(1).
1151 · Extra disks are attached (--attach).
1153 · A new random seed is generated for the guest.
1155 · Guest customization is performed, in the order specified on the
1157 command line.
1158 · SELinux relabelling is done (--selinux-relabel).
1160 IMPORTING THE DISK IMAGE
1162 Importing into libvirt
1163 Import the disk image into libvirt using virt-install(1) --import
1165 option.
1166 virt-install --import \
1168 --name guest --ram 2048 \
1169 --disk path=disk.img,format=raw --os-variant fedora25
1170 Notes:
1172 1. You must specify the correct format. The format is "raw" unless
1174 you used virt-builder’s --format option.
1175 2. --os-variant is highly recommended, because it will present optimum
1177 devices to enable the guest to run most efficiently. To get a list
1178 of all variants, do:
1179 osinfo-query os
1181 The above tool is provided by libosinfo package.
1183 3. You can run virt-install as root or non-root. Each works slightly
1185 differently because libvirt manages a different set of virtual
1186 machines for each user. In particular virt-manager normally shows
1187 the root-owned VMs, whereas Boxes shows the user-owned VMs, and
1188 other tools probably work differently as well.
1189 Importing into OpenStack
1191 Import the image into Glance (the OpenStack image store) by doing:
1193 glance image-create --name fedora-25-image --file fedora-25.img \
1195 --disk-format raw --container-format bare \
1196 --is-public True
1197 The --file parameter is the virt-builder-generated disk image. It
1199 should match virt-builder’s --output option. The --disk-format
1200 parameter should match virt-builder’s --format option (or "raw" if you
1201 didn't use that option). The --container-format should always be
1202 "bare" since virt-builder doesn't put images into containers.
1203 You can use the "glance image-show fedora-25-image" command to display
1205 the properties of the image.
1206 To boot up an instance of your image on a Nova compute node, do:
1208 nova boot fedora-25-server --image fedora-25-image \
1210 --flavor m1.medium
1211 Use "nova flavor-list" to list possible machine flavors. Use
1213 "nova list" to list running instances.
1214 Booting directly using qemu or KVM
1216 The qemu command line is not very stable or easy to use, hence libvirt
1218 should be used if possible. However a command line similar to the
1219 following could be used to boot the virtual machine:
1220 qemu-system-x86_64 \
1222 -machine accel=kvm:tcg \
1223 -cpu host \
1224 -m 2048 \
1225 -drive file=disk.img,format=raw,if=virtio
1226 As with libvirt, it is very important that the correct format is
1228 chosen. It will be "raw" unless the --format option was used.
1229 CONFIGURATION MANAGEMENT
1231 Puppet
1232 To enable the Puppet agent in a guest, install the package, point the
1234 configuration at your Puppetmaster, and ensure the agent runs at boot.
1235 A typical virt-builder command would be:
1237 virt-builder fedora-25 \
1239 --hostname client.example.com \
1240 --update \
1241 --install puppet \
1242 --append-line '/etc/puppet/puppet.conf:[agent]' \
1243 --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
1244 --run-command 'systemctl enable puppet' \
1245 --selinux-relabel
1246 The precise instructions vary according to the Linux distro. For
1248 further information see:
1249 https://docs.puppet.com/puppet/latest/install_pre.html
1250 DEBUGGING BUILDS
1252 If virt-builder itself fails, then enable debugging (-v) and report a
1253 bug (see "BUGS" below).
1254 If virt-builder fails because some script or package it is installing
1256 fails, try using --no-delete-on-failure to preserve the output file,
1257 and continue reading this section.
1258 If virt-builder is successful but the image doesn't work, here are some
1260 things to try:
1261 Use virt-rescue
1263 Run virt-rescue(1) on the disk image:
1264 virt-rescue -a disk.img
1266 This gives you a rescue shell. You can mount the filesystems from
1268 the disk image on /sysroot and examine them using ordinary Linux
1269 commands. You can also chroot into the guest to reinstall the
1270 bootloader. The virt-rescue man page has a lot more information
1271 and examples.
1272 Use guestfish
1274 Run guestfish(1) on the disk image:
1275 guestfish -a disk.img -i
1277 Use guestfish commands like "ll /directory" and "cat /file" to
1279 examine directories and files.
1280 Use guestmount
1282 Mount the disk image safely on the host using FUSE and
1283 guestmount(1):
1284 mkdir /tmp/mp
1286 guestmount -a disk.img -i /tmp/mp
1287 cd /tmp/mp
1288 To unmount the disk image do:
1290 fusermount -u /tmp/mp
1292 Add a serial console
1294 If the guest hangs during boot, it can be helpful to add a serial
1295 console to the guest, and direct kernel messages to the serial
1296 console. Adding the serial console will involve looking at the
1297 documentation for your hypervisor. To direct kernel messages to
1298 the serial console, add the following on the kernel command line:
1299 console=tty0 console=ttyS0,115200
1301 SOURCES OF TEMPLATES
1303 virt-builder reads the available sources from configuration files, with
1304 the .conf extension and located in the following paths:
1305 · $XDG_CONFIG_HOME/virt-builder/repos.d/ ($XDG_CONFIG_HOME is
1307 $HOME/.config if not set).
1308 · $XDG_CONFIG_DIRS/virt-builder/repos.d/ (where $XDG_CONFIG_DIRS
1310 means any of the directories in that environment variable, or just
1311 /etc/xdg if not set)
1312 Each .conf file in those paths has a simple text format like the
1314 following:
1315 [libguestfs.org]
1317 uri=http://libguestfs.org/download/builder/index.asc
1318 gpgkey=file:///etc/xdg/virt-builder/repos.d/libguestfs.gpg
1319 The part in square brackets is the repository identifier, which is used
1321 as unique identifier.
1322 The following fields can appear:
1324 "uri=URI"
1326 The URI of the index file which this repository refers to.
1327 This field is required.
1329 "gpgkey=URI"
1331 This optional field represents the URI (although only file:// URIs
1332 are accepted) of the key used to sign the index file. If not
1333 present, the index file referred by uri=.. is not signed.
1334 "proxy=MODE"
1336 This optional field specifies the proxy mode, to be used when
1337 downloading the index file of this repository. The possible values
1338 are:
1339 no, off
1341 No proxy is being used at all, even overriding the system
1342 configuration.
1343 system
1345 The proxy used is the system one.
1346 anything else
1348 Specifies the actual proxy configuration to be used, overriding
1349 the system configuration.
1350 If not present, the assumed value is to respect the proxy settings
1352 of the system (i.e. as if system would be specified).
1353 "format=FORMAT"
1355 This optional field specifies the format of the repository. The
1356 possible values are:
1357 native
1359 The native format of the "virt-builder" repository. See also
1360 "Creating and signing the index file" below.
1361 simplestreams
1363 The URI represents the root of a Simple Streams v1.0 tree of
1364 metadata.
1365 For more information about Simple Streams, see also
1367 https://launchpad.net/simplestreams.
1368 If not present, the assumed value is "native".
1370 For serious virt-builder use, you may want to create your own
1372 repository of templates.
1373 Libguestfs.org repository
1375 Out of the box, virt-builder downloads the file
1377 http://libguestfs.org/download/builder/index.asc which is an index of
1378 available templates plus some information about each one, wrapped up in
1379 a digital signature. The command "virt-builder --list" lists out the
1380 information in this index file.
1381 The templates hosted on libguestfs.org were created using shell
1383 scripts, kickstart files and preseed files which can be found in the
1384 libguestfs source tree, in "builder/templates".
1385 Setting up the repository
1387 You can set up your own site containing an index file and some
1389 templates, and then point virt-builder at the site by creating a .conf
1390 file pointing to it.
1391 Note that if your index is signed, you will need to properly fill
1393 gpgkey=.. in your .conf file, making sure to deploy also the GPG key
1394 file.
1395 virt-builder --source https://example.com/builder/index.asc \
1397 --fingerprint 'AAAA BBBB ...' \
1398 --list
1399 You can host this on any web or FTP server, or a local or network
1401 filesystem.
1402 Setting up a GPG key
1404 If you don’t have a GnuPG key, you will need to set one up. (Strictly
1406 speaking this is optional, but if your index and template files are not
1407 signed then virt-builder users will have to use the
1408 --no-check-signature flag every time they use virt-builder.)
1409 To create a key, see the GPG manual
1411 http://www.gnupg.org/gph/en/manual.html.
1412 Export your GPG public key:
1414 gpg --export -a "you@example.com" > pubkey
1416 Create the templates
1418 There are many ways to create the templates. For example you could
1420 clone existing guests (see virt-sysprep(1)), or you could install a
1421 guest by hand (virt-install(1)). To see how the templates were created
1422 for virt-builder, look at the scripts in "builder/templates"
1423 Virt-builder supports any image format (e.g. raw, qcow2, etc) as
1425 template, both as-is, and compressed as XZ. This way, existing images
1426 (e.g. cleaned using virt-sysprep(1)) can be used as templates.
1427 For best results when compressing the templates, use the following xz
1429 options (see nbdkit-xz-plugin(1) for further explanation):
1430 xz --best --block-size=16777216 disk
1432 Creating and signing the index file
1434 The index file has a simple text format (shown here without the digital
1436 signature):
1437 [fedora-18]
1439 name=Fedora® 18
1440 osinfo=fedora18
1441 arch=x86_64
1442 file=fedora-18.xz
1443 checksum[sha512]=...
1444 format=raw
1445 size=6442450944
1446 compressed_size=148947524
1447 expand=/dev/sda3
1448 [fedora-19]
1450 name=Fedora® 19
1451 osinfo=fedora19
1452 arch=x86_64
1453 file=fedora-19.xz
1454 checksum[sha512]=...
1455 revision=3
1456 format=raw
1457 size=4294967296
1458 compressed_size=172190964
1459 expand=/dev/sda3
1460 The part in square brackets is the "os-version", which is the same
1462 string that is used on the virt-builder command line to build that OS.
1463 The index file creation and signature can be eased with the
1465 virt-builder-repository(1) tool.
1466 After preparing the "index" file in the correct format, clearsign it
1468 using the following command:
1469 gpg --clearsign --armor index
1471 This will create the final file called index.asc which can be uploaded
1473 to the server (and is the uri=.. URL). As noted above, signing the
1474 index file is optional, but recommended.
1475 The following fields can appear:
1477 "name=NAME"
1479 The user-friendly name of this template. This is displayed in the
1480 --list output but is otherwise not significant.
1481 "osinfo=ID"
1483 This optional field maps the operating system to the associated
1484 libosinfo ID. Virt-builder does not use it (yet).
1485 "arch=ARCH"
1487 The architecture of the operating system installed within the
1488 template. This field is required.
1489 "file=PATH"
1491 The path (relative to the index) of the xz-compressed template.
1492 Note that absolute paths or URIs are not permitted here. This is
1494 because virt-builder has a "same origin" policy for templates so
1495 they cannot come from other servers.
1496 "sig=PATH"
1498 This option is deprecated. Use the checksum field instead.
1499 The path (relative to the index) of the GPG detached signature of
1501 the xz file.
1502 Note that absolute paths or URIs are not permitted here. This is
1504 because virt-builder has a "same origin" policy for templates so
1505 they cannot come from other servers.
1506 The file can be created as follows:
1508 gpg --detach-sign --armor -o disk.xz.sig disk.xz
1510 "checksum[sha512]=7b882fe9b82eb0fef..."
1512 The SHA-512 checksum of the file specified in file=.. is checked
1513 after it is downloaded. To work out the signature, do:
1514 sha512sum disk.xz
1516 Note if you use this, you don’t need to sign the file, ie. don’t
1518 use "sig". This option overrides "sig".
1519 "checksum=7b882fe9b82eb0fef..."
1521 "checksum" is an alias for "checksum[sha512]".
1522 If you need to interoperate with virt-builder = 1.24.0 then you
1524 have to use "checksum" because that version would give a parse
1525 error with square brackets and numbers in the key of a field. This
1526 is fixed in virt-builder ≥ 1.24.1.
1527 "revision=N"
1529 The revision is an integer which is used to control the template
1530 cache. Increasing the revision number causes clients to download
1531 the template again even if they have a copy in the cache.
1532 The revision number is optional. If omitted it defaults to 1.
1534 "format=raw"
1536 "format=qcow2"
1537 Specify the format of the disk image; in case it is compressed,
1538 that is the format before the compression. If not given, the
1539 format is autodetected, but generally it is better to be explicit
1540 about the intended format.
1541 Note this is the source format, which is different from the
1543 --format option (requested output format). Virt-builder does on-
1544 the-fly conversion from the source format to the requested output
1545 format.
1546 "size=NNN"
1548 The virtual size of the image in bytes. This is the size of the
1549 image when uncompressed. If using a non-raw format such as qcow2
1550 then it means the virtual disk size, not the size of the qcow2
1551 file.
1552 This field is required.
1554 Virt-builder also uses this as the minimum size that users can
1556 request via the --size option, or as the default size if there is
1557 no --size option.
1558 "compressed_size=NNN"
1560 The actual size of the disk image in bytes, i.e. what was specified
1561 in file=... This is just used for information (when using "long",
1562 and "json" formats of --list).
1563 "expand=/dev/sdaX"
1565 When expanding the image to its final size, instruct virt-resize(1)
1566 to expand the named partition in the guest image to fill up all
1567 available space. This works like the virt-resize --expand option.
1568 You should usually put the device name of the guest’s root
1570 filesystem here.
1571 It’s a good idea to use this, but not required. If the field is
1573 omitted then virt-resize will create an extra partition at the end
1574 of the disk to cover the free space, which is much less user-
1575 friendly.
1576 "lvexpand=/dev/VolGroup/LogVol"
1578 When expanding the image to its final size, instruct virt-resize(1)
1579 to expand the named logical volume in the guest image to fill up
1580 all available space. This works like the virt-resize --lv-expand
1581 option.
1582 If the guest uses LVM2 you should usually put the LV of the guest’s
1584 root filesystem here. If the guest does not use LVM2 or its root
1585 filesystem is not on an LV, don't use this option.
1586 "notes=NOTES"
1588 Any notes that go with this image, especially notes describing what
1589 packages are in the image, how the image was prepared, and
1590 licensing information.
1591 This information is shown in the --notes and --list --long modes.
1593 You can use multi-line notes here by indenting each new line with
1595 at least one character of whitespace (even on blank lines):
1596 notes=This image was prepared using
1598 the following kickstart script:
1599 <-- one space at beginning of line
1600 part /boot --fstype ext3
1601 ...
1602 "hidden=true"
1604 Using the hidden flag prevents the template from being listed by
1605 the --list option (but it is still installable). This is used for
1606 test images.
1607 "aliases=ALIAS1 ALIAS2 ..."
1609 This optional field specifies a list of aliases, separated by
1610 spaces, for the image. For example, an alias could be used to
1611 always point to the latest version of a certain image, leaving the
1612 old versions available in the index instead of updating the same
1613 image (see the "revision" field).
1614 Running virt-builder against multiple sources
1616 It is possible to use multiple sources with virt-builder. The
1618 recommended way is to deploy .conf files pointing to the index files.
1619 Another way is to specify the sources using multiple --source and/or
1620 --fingerprint options:
1621 virt-builder \
1623 --source http://example.com/s1/index.asc \
1624 --source http://example.com/s2/index.asc
1625 You can provide N or 1 fingerprints. In the case where you provide N
1627 fingerprints, N = number of sources and there is a 1-1 correspondence
1628 between each source and each fingerprint:
1629 virt-builder \
1631 --source http://example.com/s1/index.asc --fingerprint '0123 ...' \
1632 --source http://example.com/s2/index.asc --fingerprint '9876 ...'
1633 In the case where you provide 1 fingerprint, the same fingerprint is
1635 used for all sources.
1636 You "must" provide at least 1 fingerprint.
1638 Licensing of templates
1640 You should be aware of the licensing of images that you distribute.
1642 For open source guests, provide a link to the source code in the
1643 "notes" field and comply with other requirements (eg. around
1644 trademarks).
1645 Formal specification of the index file
1647 The index file format has a formal specification defined by the flex
1649 scanner and bison parser used to parse the file. This can be found in
1650 the following files in the libguestfs source tree:
1651 builder/index-scan.l
1653 builder/index-parse.y
1654 A tool called virt-index-validate(1) is available to validate the index
1656 file to ensure it is correct.
1657 Note that the parser and tool can work on either the signed or unsigned
1659 index file (ie. index or index.asc).
1660 The index is always encoded in UTF-8.
1662 CACHING
1664 Caching templates
1665 Since the templates are usually very large, downloaded templates are
1667 cached in the user’s home directory.
1668 The location of the cache is $XDG_CACHE_HOME/virt-builder/ or
1670 $HOME/.cache/virt-builder.
1671 You can print out information about the cache directory, including
1673 which guests are currently cached, by doing:
1674 virt-builder --print-cache
1676 The cache can be deleted if you want to save space by doing:
1678 virt-builder --delete-cache
1680 You can download all (current) templates to the local cache by doing:
1682 virt-builder --cache-all-templates
1684 To disable the template cache, use --no-cache.
1686 Only templates are cached. The index and detached digital signatures
1688 are not cached.
1689 Caching packages
1691 Virt-builder uses curl(1) to download files and it also uses the
1693 current "http_proxy" (etc) settings when installing packages
1694 (--install, --update).
1695 You may therefore want to set those environment variables in order to
1697 maximize the amount of local caching that happens. See "ENVIRONMENT
1698 VARIABLES" and curl(1).
1699 Local mirrors
1701 To increase both speed and reliability of installing packages, you can
1703 set up a local mirror of the target distribution, and point the guest
1704 package manager at that.
1705 Using a local mirror with Fedora
1707 To install a Fedora guest using a local mirror:
1709 virt-builder fedora-25 \
1711 --edit '/etc/yum.repos.d/fedora.repo:
1712 s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
1713 s{.*metalink=.*}{};
1714 ' \
1715 --edit '/etc/yum.repos.d/fedora-updates.repo:
1716 s{.*baseurl=.*}{baseurl=http://example.com/mirror-updates/};
1717 s{.*metalink=.*}{};
1718 ' \
1719 --run-command 'dnf -y update' \
1720 --install 'pkg1,pkg2,...'
1721 Using a local mirror with Debian
1723 Assuming that you are using "apt-proxy" to mirror the repository, you
1725 should create a new sources.list file to point to your proxy (see
1726 https://help.ubuntu.com/community/AptProxy) and then do:
1727 virt-builder debian-8 \
1729 --upload sources.list:/etc/apt/sources.list \
1730 --run-command 'apt-get -y update' \
1731 --install 'pkg1,pkg2,...'
1732 DIGITAL SIGNATURES
1734 Virt-builder uses GNU Privacy Guard (GnuPG or gpg) to verify that the
1735 index and templates have not been tampered with.
1736 The source points to an index file, which is optionally signed.
1738 Virt-builder downloads the index and checks that the signature is valid
1740 and the signer’s fingerprint matches the specified fingerprint (ie. the
1741 one specified in gpgkey=.. in the .conf, or with --fingerprint, in that
1742 order).
1743 For checking against the built-in public key/fingerprint, this requires
1745 importing the public key into the user’s local gpg keyring (that’s just
1746 the way that gpg works).
1747 When a template is downloaded, its signature is checked in the same
1749 way.
1750 Although the signatures are optional, if you don’t have them then virt-
1752 builder users will have to use --no-check-signature on the command
1753 line. This prevents an attacker from replacing the signed index file
1754 with an unsigned index file and having virt-builder silently work
1755 without checking the signature. In any case it is highly recommended
1756 that you always create signed index and templates.
1757 ARCHITECTURE
1759 Virt-builder can build a guest for any architecture no matter what the
1760 host architecture is. For example an x86-64 guest on an ARM host.
1761 However certain options may not work, specifically options that require
1763 running commands in the guest during the build process: --install,
1764 --update, --run, --run-command. You may need to replace these with
1765 their firstboot-equivalents.
1766 An x86-64 host building 32 bit i686 guests should work without any
1768 special steps.
1769 SECURITY
1771 Virt-builder does not need to run as root (in fact, should not be run
1772 as root), and doesn't use setuid, "sudo" or any similar mechanism.
1773 --install, --update, --run and --run-command are implemented using an
1775 appliance (a small virtual machine) so these commands do not run on the
1776 host. If you are using the libguestfs libvirt backend and have SELinux
1777 enabled then the virtual machine is additionally encapsulated in an
1778 SELinux container (sVirt).
1779 However these options will have access to the host’s network and since
1781 the template may contain untrusted code, the code might try to access
1782 host network resources which it should not. You can use --no-network
1783 to prevent this.
1784 Firstboot commands run in the context of the guest when it is booted,
1786 and so the security of your hypervisor / cloud should be considered.
1787 Virt-builder injects a random seed into every guest which it builds.
1789 This helps to ensure that TCP sequence numbers, UUIDs, ssh host keys
1790 etc are truly random when the guest boots.
1791 You should check digital signatures and not ignore any signing errors.
1793 CLONES
1795 If you wish to create many new guests of the same type, it is tempting
1796 to run virt-builder once and then copy the output file. You should not
1797 do this. You should run virt-builder once for each new guest you need.
1798 The reason is that each clone needs to have (at least) a separate
1800 random seed, and possibly other unique features (such as filesystem
1801 UUIDs) in future versions of virt-builder.
1802 Another thing you should not do is to boot the guest, then clone the
1804 booted disk image. The reason is that some guests create unique
1805 machine IDs, SSH host keys and so on at first boot, and you would not
1806 want clones to have duplicate identities.
1807 See also: virt-sysprep(1).
1809 PERFORMANCE
1811 The most important aspect of getting good performance is caching.
1812 Templates gets downloaded into the cache the first time they are used,
1813 or if you use the --cache-all-templates option. See "CACHING" above
1814 for further information.
1815 Packages required for the --install and --update options are downloaded
1817 using the host network connection. Setting the "http_proxy",
1818 "https_proxy" and "ftp_proxy" environment variables to point to a local
1819 web cache may ensure they only need to be downloaded once. You can
1820 also try using a local package repository, although this can be complex
1821 to set up and varies according to which Linux distro you are trying to
1822 install.
1823 Using --no-sync
1825 Use --no-sync. However read the caveats in the "OPTIONS" section
1827 above, since this can cause disk corruption if not used correctly.
1828 Skipping virt-resize
1830 Virt-builder can skip the virt-resize step under certain conditions.
1832 This makes virt-builder much faster. The conditions are:
1833 · the output must be a regular file (not a block device), and
1835 · the user did not use the --size option, and
1837 · the output format is the same as the template format (usually raw).
1839 pxzcat
1841 Virt-builder uses an internal implementation of pxzcat (parallel xzcat)
1843 if liblzma was found at build time. If liblzma was not found at build
1844 time, regular "xzcat" is used which is single-threaded.
1845 User-Mode Linux
1847 You can use virt-builder with the User-Mode Linux (UML) backend. This
1849 may be faster when running virt-builder inside a virtual machine (eg.
1850 in the cloud).
1851 To enable the UML backend, read the instructions in "USER-MODE LINUX
1853 BACKEND" in guestfs(3).
1854 Currently you have to use the --no-network option. This should be
1856 fixed in a future version.
1857 The qcow2 output format is not supported by UML. You can only create
1859 raw-format guests.
1860 SELINUX
1862 Guests which use SELinux (such as Fedora and Red Hat Enterprise Linux)
1863 require that each file has a correct SELinux label.
1864 Virt-builder does not know how to give new files a label, so there are
1866 two possible strategies it can use to ensure correct labelling:
1867 Using --selinux-relabel
1869 This runs setfiles(8) just before finalizing the guest, which sets
1870 SELinux labels correctly in the disk image.
1871 This is the recommended method.
1873 --touch /.autorelabel
1875 Guest templates may already contain a file called /.autorelabel or
1876 you may touch it.
1877 For guests that use SELinux, this causes restorecon(8) to run at
1879 first boot. Guests will reboot themselves once the first time you
1880 use them, which is normal and harmless.
1881 Please note that if your guest uses SELinux, and you are doing
1883 operations on it which might create new files or change existing ones,
1884 you are recommended to use --selinux-relabel. This will help in making
1885 sure that files have the right SELinux labels.
1886
1888 The --machine-readable option can be used to make the output more
1889 machine friendly, which is useful when calling virt-builder from other
1890 programs, GUIs etc.
1891 Use the option on its own to query the capabilities of the virt-builder
1893 binary. Typical output looks like this:
1894 $ virt-builder --machine-readable
1896 virt-builder
1897 arch
1898 config-file
1899 customize
1900 json-list
1901 pxzcat
1902 A list of features is printed, one per line, and the program exits with
1904 status 0.
1905
1907 For other environment variables which affect all libguestfs programs,
1908 see "ENVIRONMENT VARIABLES" in guestfs(3).
1909 "http_proxy"
1911 "https_proxy"
1912 "no_proxy"
1913 Set the proxy for downloads. These environment variables (and
1914 more) are actually interpreted by curl(1), not virt-builder.
1915 "HOME"
1917 Used to determine the location of the template cache, and the
1918 location of the user' sources. See "CACHING" and "SOURCES OF
1919 TEMPLATES".
1920 "VIRT_TOOLS_DATA_DIR"
1922 This can point to the directory containing data files used for
1923 Windows firstboot installation.
1924 Normally you do not need to set this. If not set, a compiled-in
1926 default will be used (something like /usr/share/virt-tools).
1927 This directory may contain the following files:
1929 rhsrvany.exe
1931 This is the RHSrvAny Windows binary, used to install a
1932 "firstboot" script in Windows guests. It is required if you
1933 intend to use the --firstboot or --firstboot-command options
1934 with Windows guests.
1935 See also: "https://github.com/rwmjones/rhsrvany"
1937 pvvxsvc.exe
1939 This is a Windows binary shipped with SUSE VMDP, used to
1940 install a "firstboot" script in Windows guests. It is required
1941 if you intend to use the --firstboot or --firstboot-command
1942 options with Windows guests.
1943 "XDG_CACHE_HOME"
1945 Used to determine the location of the template cache. See
1946 "CACHING".
1947 "XDG_CONFIG_HOME"
1949 Used to determine the location of the user' sources. See "SOURCES
1950 OF TEMPLATES".
1951 "XDG_CONFIG_DIRS"
1953 Used to determine the location of the system sources. See "SOURCES
1954 OF TEMPLATES".
1955
1957 This program returns 0 if successful, or non-zero if there was an
1958 error.
1959
1961 guestfs(3), guestfish(1), guestmount(1), virt-builder-repository(1),
1962 virt-copy-out(1), virt-customize(1), virt-get-kernel(1),
1963 virt-install(1), virt-rescue(1), virt-resize(1), virt-sysprep(1),
1964 oz-install(1), gpg(1), gpg2(1), curl(1), virt-make-fs(1),
1965 genisoimage(1), http://libguestfs.org/.
1966
1968 Richard W.M. Jones http://people.redhat.com/~rjones/
1969
1971 Copyright (C) 2013 Red Hat Inc.
1972
1974 This program is free software; you can redistribute it and/or modify it
1975 under the terms of the GNU General Public License as published by the
1976 Free Software Foundation; either version 2 of the License, or (at your
1977 option) any later version.
1978 This program is distributed in the hope that it will be useful, but
1980 WITHOUT ANY WARRANTY; without even the implied warranty of
1981 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1982 General Public License for more details.
1983 You should have received a copy of the GNU General Public License along
1985 with this program; if not, write to the Free Software Foundation, Inc.,
1986 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
1987
1989 To get a list of bugs against libguestfs, use this link:
1990 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
1991 To report a new bug against libguestfs, use this link:
1993 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1994 When reporting a bug, please supply:
1996 · The version of libguestfs.
1998 · Where you got libguestfs (eg. which Linux distro, compiled from
2000 source, etc)
2001 · Describe the bug accurately and give a way to reproduce it.
2003 · Run libguestfs-test-tool(1) and paste the complete, unedited output
2005 into the bug report.
2006libguestfs-1.38.2 2018-05-15 virt-builder(1)