1virt-builder(1)             Virtualization Support             virt-builder(1)
2
3
4

NAME

6       virt-builder - Build virtual machine images quickly
7

SYNOPSIS

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
29
30        virt-builder -l|--list [--long] [--list-format short|long|json] [os-version]
31
32        virt-builder --notes os-version
33
34        virt-builder --print-cache
35
36        virt-builder --cache-all-templates
37
38        virt-builder --delete-cache
39
40        virt-builder --get-kernel DISKIMAGE
41           [--format raw|qcow2] [--output OUTPUTDIR]
42

DESCRIPTION

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
50       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
56       The easiest way to get started is by looking at the examples in the
57       next section.
58

EXAMPLES

60   List the virtual machines available
61        virt-builder --list
62
63       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
67       After choosing a guest from the list, you may want to see if there are
68       any installation notes:
69
70        virt-builder --notes fedora-27
71
72   Build a virtual machine
73        virt-builder fedora-27
74
75       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
81       You do not need to run this command as root.
82
83       The first time this runs it has to download the template over the
84       network, but this gets cached (see "CACHING").
85
86       The name of the output file is derived from the template name, so above
87       it will be fedora-27.img.  You can change the output filename using the
88       -o option:
89
90        virt-builder fedora-27 -o mydisk.img
91
92       You can also use the -o option to write to existing devices or logical
93       volumes.
94
95        virt-builder fedora-27 --format qcow2
96
97       As above, but write the output in qcow2 format to fedora-27.qcow2.
98
99        virt-builder fedora-27 --size 20G
100
101       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
104        virt-builder fedora-27 --arch i686
105
106       As above, but using an i686 template, if available.
107
108   Setting the root password
109        virt-builder fedora-27 --root-password file:/tmp/rootpw
110
111       Create a Fedora 25 image.  The root password is taken from the file
112       /tmp/rootpw.
113
114       Note if you don’t set --root-password then the guest is given a random
115       root password which is printed on stdout.
116
117       You can also create user accounts.  See "USERS AND PASSWORDS" below.
118
119   Set the hostname
120        virt-builder fedora-27 --hostname virt.example.com
121
122       Set the hostname to "virt.example.com".
123
124   Installing software
125       To install packages from the ordinary (guest) software repository (eg.
126       dnf or apt):
127
128        virt-builder fedora-27 --install "inkscape,@Xfce Desktop"
129
130       (In Fedora, "@" is used to install groups of packages.  On Debian you
131       would install a meta-package instead.)
132
133       To update the installed packages to the latest version:
134
135        virt-builder debian-7 --update
136
137       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
141        virt-builder fedora-27 --update --selinux-relabel
142
143   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
151       For example:
152
153        cat <<'EOF' > /tmp/dnf-update.sh
154        dnf -y --best update
155        EOF
156
157        virt-builder fedora-27 --firstboot /tmp/dnf-update.sh
158
159       or simply:
160
161        virt-builder fedora-27 --firstboot-command 'dnf -y --best update'
162
163       which makes the dnf(8) "update" command run once the first time the
164       guest boots.
165
166       Or:
167
168        virt-builder fedora-27 \
169          --edit '/etc/dnf/dnf.conf:
170                    s/gpgcheck=1/gpgcheck=0/'
171
172       which edits /etc/dnf/dnf.conf inside the disk image (during disk image
173       creation, long before boot).
174
175       You can combine these options, and have multiple options of all types.
176

OPTIONS

178       --help
179           Display help.
180
181       --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
186           See also "ARCHITECTURE".
187
188       --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
193           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
197            mkdir /tmp/mount
198            mount LABEL=EXTRA /tmp/mount
199
200           You can have multiple --attach options, and the format can be any
201           disk format (not just an ISO).
202
203           See also: --run, "Installing packages at build time from a side
204           repository", genisoimage(1), virt-make-fs(1).
205
206       --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
210       --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
216           --no-cache disables template caching.
217
218       --cache-all-templates
219           Download all templates to the cache and then exit.  See "CACHING".
220
221           Note this doesn't cache everything.  More templates might be
222           uploaded.  Also this doesn't cache packages (the --install,
223           --update options).
224
225       --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
231           See also --fingerprint.
232
233       --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
240       --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
244            virt-builder --curl "curl --insecure" [...]
245
246       --delete-cache
247           Delete the template cache.  See "CACHING".
248
249       --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
254           The default is to delete the output file if virt-builder fails (or,
255           for example, some script that it runs fails).
256
257       --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
262           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
267       --format qcow2
268       --format raw
269           For ordinary builds, this selects the output format.  The default
270           is raw.
271
272           With --get-kernel this specifies the input format.
273
274           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
277            qemu-img amend -f qcow2 -o compat=0.10 output.qcow2
278
279       --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
284           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
287           The kernel and initramfs are written to the current directory,
288           unless you also specify the --output "outputdir" directory name.
289
290           The format of the disk image is automatically detected unless you
291           specify it by using the --format option.
292
293           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
298       --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
302           You can also use this to add gpg parameters, for example to specify
303           an alternate home directory:
304
305            virt-builder --gpg "gpg --homedir /tmp" [...]
306
307       -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
314           It is possible to choose with --list-format the output format for
315           the list templates:
316
317           short
318               The default format, prints only the template identifier and,
319               next to it, its short description.
320
321           long
322               Prints a textual list with the details of the available
323               sources, followed by the details of the available templates.
324
325           json
326               Prints a JSON object with the details of the available sources
327               and the details of the available templates.
328
329               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
335           --long is a shorthand for the "long" format.
336
337           See also: --source, --notes, "SOURCES OF TEMPLATES".
338
339       --machine-readable
340       --machine-readable=format
341           This option is used to make the output more machine friendly when
342           being parsed by other programs.  See "MACHINE READABLE OUTPUT"
343           below.
344
345       -m MB
346       --memsize MB
347           Change the amount of memory allocated to --run scripts.  Increase
348           this if you find that --run scripts or the --install option are
349           running out of memory.
350
351           The default can be found with this command:
352
353            guestfish get-memsize
354
355       --network
356       --no-network
357           Enable or disable network access from the guest during the
358           installation.
359
360           Enabled is the default.  Use --no-network to disable access.
361
362           The network only allows outgoing connections and has other minor
363           limitations.  See "NETWORK" in virt-rescue(1).
364
365           If you use --no-network then certain other options such as
366           --install will not work.
367
368           This does not affect whether the guest can access the network once
369           it has been booted, because that is controlled by your hypervisor
370           or cloud environment and has nothing to do with virt-builder.
371
372           Generally speaking you should not use --no-network.  But here are
373           some reasons why you might want to:
374
375           1.  Because the libguestfs backend that you are using doesn't
376               support the network.  (See: "BACKEND" in guestfs(3)).
377
378           2.  Any software you need to install comes from an attached ISO, so
379               you don't need the network.
380
381           3.  You don’t want untrusted guest code trying to access your host
382               network when running virt-builder.  This is particularly an
383               issue when you don't trust the source of the operating system
384               templates.  (See "SECURITY" below).
385
386           4.  You don’t have a host network (eg. in secure/restricted
387               environments).
388
389       --no-sync
390           Do not sync the output file on exit.
391
392           Virt-builder "fsync"s the output file or disk image when it exits.
393
394           The reason is that qemu/KVM’s default caching mode is "none" or
395           "directsync", both of which bypass the host page cache.  Therefore
396           these would not work correctly if you immediately started the guest
397           after running virt-builder - they would not see the complete output
398           file.  (Note that you should not use these caching modes - they are
399           fundamentally broken for this and other reasons.)
400
401           If you are not using these broken caching modes, you can use
402           --no-sync to avoid this unnecessary sync and gain considerable
403           extra performance.
404
405       --notes os-version
406           List any notes associated with this guest, then exit (this does not
407           do the install).
408
409       -o filename
410       --output filename
411           Write the output to filename.  If you don’t specify this option,
412           then the output filename is generated by taking the "os-version"
413           string and adding ".img" (for raw format) or ".qcow2" (for qcow2
414           format).
415
416           Note that the output filename could be a device, partition or
417           logical volume.
418
419           When used with --get-kernel, this option specifies the output
420           directory.
421
422       --print-cache
423           Print information about the template cache.  See "CACHING".
424
425       -q
426       --quiet
427           Don’t print ordinary progress messages.
428
429       --size SIZE
430           Select the size of the output disk, where the size can be specified
431           using common names such as "32G" (32 gigabytes) etc.
432
433           Virt-builder will resize filesystems inside the disk image
434           automatically.
435
436           If the size is not specified, then one of two things happens.  If
437           the output is a file, then the size is the same as the template.
438           If the output is a device, partition, etc then the size of that
439           device is used.
440
441           To specify size in bytes, the number must be followed by the
442           lowercase letter b, eg: "--size 10737418240b".
443
444       --smp N
445           Enable N ≥ 2 virtual CPUs for --run scripts to use.
446
447       --source URL
448           Set the source URL to look for indexes.
449
450           You can give this option multiple times to specify multiple
451           sources.
452
453           See also "SOURCES OF TEMPLATES" below.
454
455           Note that you should not point --source to sources that you don’t
456           trust (unless the source is signed by someone you do trust).  See
457           also the --no-network option.
458
459       --no-warn-if-partition
460           Do not emit a warning if the output device is a partition.  This
461           warning avoids a common user error when writing to a USB key or
462           external drive, when you should normally write to the whole device
463           (--output /dev/sdX), not to a partition on the device
464           (--output /dev/sdX1).  Use this option to suppress this warning.
465
466       -v
467       --verbose
468           Enable debug messages and/or produce verbose output.
469
470           When reporting bugs, use this option and attach the complete output
471           to your bug report.
472
473       -V
474       --version
475           Display version number and exit.
476
477       -x  Enable tracing of libguestfs API calls.
478
479   Customization options
480       --append-line FILE:LINE
481           Append a single line of text to the "FILE".  If the file does not
482           already end with a newline, then one is added before the appended
483           line.  Also a newline is added to the end of the "LINE" string
484           automatically.
485
486           For example (assuming ordinary shell quoting) this command:
487
488            --append-line '/etc/hosts:10.0.0.1 foo'
489
490           will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file,
491           the latter only if the existing file does not already end with a
492           newline.
493
494           "⏎" represents a newline character, which is guessed by looking at
495           the existing content of the file, so this command does the right
496           thing for files using Unix or Windows line endings.  It also works
497           for empty or non-existent files.
498
499           To insert several lines, use the same option several times:
500
501            --append-line '/etc/hosts:10.0.0.1 foo'
502            --append-line '/etc/hosts:10.0.0.2 bar'
503
504           To insert a blank line before the appended line, do:
505
506            --append-line '/etc/hosts:'
507            --append-line '/etc/hosts:10.0.0.1 foo'
508
509       --chmod PERMISSIONS:FILE
510           Change the permissions of "FILE" to "PERMISSIONS".
511
512           Note: "PERMISSIONS" by default would be decimal, unless you prefix
513           it with 0 to get octal, ie. use 0700 not 700.
514
515       --commands-from-file FILENAME
516           Read the customize commands from a file, one (and its arguments)
517           each line.
518
519           Each line contains a single customization command and its
520           arguments, for example:
521
522            delete /some/file
523            install some-package
524            password some-user:password:its-new-password
525
526           Empty lines are ignored, and lines starting with "#" are comments
527           and are ignored as well.  Furthermore, arguments can be spread
528           across multiple lines, by adding a "\" (continuation character) at
529           the of a line, for example
530
531            edit /some/file:\
532              s/^OPT=.*/OPT=ok/
533
534           The commands are handled in the same order as they are in the file,
535           as if they were specified as --delete /some/file on the command
536           line.
537
538       --copy SOURCE:DEST
539           Copy files or directories recursively inside the guest.
540
541           Wildcards cannot be used.
542
543       --copy-in LOCALPATH:REMOTEDIR
544           Copy local files or directories recursively into the disk image,
545           placing them in the directory "REMOTEDIR" (which must exist).
546
547           Wildcards cannot be used.
548
549       --delete PATH
550           Delete a file from the guest.  Or delete a directory (and all its
551           contents, recursively).
552
553           You can use shell glob characters in the specified path.  Be
554           careful to escape glob characters from the host shell, if that is
555           required.  For example:
556
557            virt-customize --delete '/var/log/*.log'.
558
559           See also: --upload, --scrub.
560
561       --edit FILE:EXPR
562           Edit "FILE" using the Perl expression "EXPR".
563
564           Be careful to properly quote the expression to prevent it from
565           being altered by the shell.
566
567           Note that this option is only available when Perl 5 is installed.
568
569           See "NON-INTERACTIVE EDITING" in virt-edit(1).
570
571       --firstboot SCRIPT
572           Install "SCRIPT" inside the guest, so that when the guest first
573           boots up, the script runs (as root, late in the boot process).
574
575           The script is automatically chmod +x after installation in the
576           guest.
577
578           The alternative version --firstboot-command is the same, but it
579           conveniently wraps the command up in a single line script for you.
580
581           You can have multiple --firstboot options.  They run in the same
582           order that they appear on the command line.
583
584           Please take a look at "FIRST BOOT SCRIPTS" for more information and
585           caveats about the first boot scripts.
586
587           See also --run.
588
589       --firstboot-command 'CMD+ARGS'
590           Run command (and arguments) inside the guest when the guest first
591           boots up (as root, late in the boot process).
592
593           You can have multiple --firstboot options.  They run in the same
594           order that they appear on the command line.
595
596           Please take a look at "FIRST BOOT SCRIPTS" for more information and
597           caveats about the first boot scripts.
598
599           See also --run.
600
601       --firstboot-install PKG,PKG..
602           Install the named packages (a comma-separated list).  These are
603           installed when the guest first boots using the guest’s package
604           manager (eg. apt, yum, etc.) and the guest’s network connection.
605
606           For an overview on the different ways to install packages, see
607           "INSTALLING PACKAGES".
608
609       --hostname HOSTNAME
610           Set the hostname of the guest to "HOSTNAME".  You can use a dotted
611           hostname.domainname (FQDN) if you want.
612
613       --install PKG,PKG..
614           Install the named packages (a comma-separated list).  These are
615           installed during the image build using the guest’s package manager
616           (eg. apt, yum, etc.) and the host’s network connection.
617
618           For an overview on the different ways to install packages, see
619           "INSTALLING PACKAGES".
620
621           See also --update, --uninstall.
622
623       --link TARGET:LINK[:LINK..]
624           Create symbolic link(s) in the guest, starting at "LINK" and
625           pointing at "TARGET".
626
627       --mkdir DIR
628           Create a directory in the guest.
629
630           This uses "mkdir -p" so any intermediate directories are created,
631           and it also works if the directory already exists.
632
633       --move SOURCE:DEST
634           Move files or directories inside the guest.
635
636           Wildcards cannot be used.
637
638       --no-logfile
639           Scrub "builder.log" (log file from build commands) from the image
640           after building is complete.  If you don't want to reveal precisely
641           how the image was built, use this option.
642
643           See also: "LOG FILE".
644
645       --password USER:SELECTOR
646           Set the password for "USER".  (Note this option does not create the
647           user account).
648
649           See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
650           and also how to set up user accounts.
651
652       --password-crypto md5|sha256|sha512
653           When the virt tools change or set a password in the guest, this
654           option sets the password encryption of that password to "md5",
655           "sha256" or "sha512".
656
657           "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
658           the guest).
659
660           "md5" will work with relatively old Linux guests (eg. RHEL 3), but
661           is not secure against modern attacks.
662
663           The default is "sha512" unless libguestfs detects an old guest that
664           didn't have support for SHA-512, in which case it will use "md5".
665           You can override libguestfs by specifying this option.
666
667           Note this does not change the default password encryption used by
668           the guest when you create new user accounts inside the guest.  If
669           you want to do that, then you should use the --edit option to
670           modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
671           "/etc/pam.d/common-password" (Debian, Ubuntu).
672
673       --root-password SELECTOR
674           Set the root password.
675
676           See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
677           and also how to set up user accounts.
678
679           Note: In virt-builder, if you don't set --root-password then the
680           guest is given a random root password.
681
682       --run SCRIPT
683           Run the shell script (or any program) called "SCRIPT" on the disk
684           image.  The script runs virtualized inside a small appliance,
685           chrooted into the guest filesystem.
686
687           The script is automatically chmod +x.
688
689           If libguestfs supports it then a limited network connection is
690           available but it only allows outgoing network connections.  You can
691           also attach data disks (eg. ISO files) as another way to provide
692           data (eg. software packages) to the script without needing a
693           network connection (--attach).  You can also upload data files
694           (--upload).
695
696           You can have multiple --run options.  They run in the same order
697           that they appear on the command line.
698
699           See also: --firstboot, --attach, --upload.
700
701       --run-command 'CMD+ARGS'
702           Run the command and arguments on the disk image.  The command runs
703           virtualized inside a small appliance, chrooted into the guest
704           filesystem.
705
706           If libguestfs supports it then a limited network connection is
707           available but it only allows outgoing network connections.  You can
708           also attach data disks (eg. ISO files) as another way to provide
709           data (eg. software packages) to the script without needing a
710           network connection (--attach).  You can also upload data files
711           (--upload).
712
713           You can have multiple --run-command options.  They run in the same
714           order that they appear on the command line.
715
716           See also: --firstboot, --attach, --upload.
717
718       --scrub FILE
719           Scrub a file from the guest.  This is like --delete except that:
720
721           •   It scrubs the data so a guest could not recover it.
722
723           •   It cannot delete directories, only regular files.
724
725       --selinux-relabel
726           Relabel files in the guest so that they have the correct SELinux
727           label.
728
729           This will attempt to relabel files immediately, but if the
730           operation fails this will instead touch /.autorelabel on the image
731           to schedule a relabel operation for the next time the image boots.
732
733           You should only use this option for guests which support SELinux.
734
735       --sm-attach SELECTOR
736           Attach to a pool using "subscription-manager".
737
738           See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
739
740       --sm-credentials SELECTOR
741           Set the credentials for "subscription-manager".
742
743           See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
744
745       --sm-register
746           Register the guest using "subscription-manager".
747
748           This requires credentials being set using --sm-credentials.
749
750       --sm-remove
751           Remove all the subscriptions from the guest using
752           "subscription-manager".
753
754       --sm-unregister
755           Unregister the guest using "subscription-manager".
756
757       --ssh-inject USER[:SELECTOR]
758           Inject an ssh key so the given "USER" will be able to log in over
759           ssh without supplying a password.  The "USER" must exist already in
760           the guest.
761
762           See "SSH KEYS" for the format of the "SELECTOR" field.
763
764           You can have multiple --ssh-inject options, for different users and
765           also for more keys for each user.
766
767       --timezone TIMEZONE
768           Set the default timezone of the guest to "TIMEZONE".  Use a
769           location string like "Europe/London"
770
771       --touch FILE
772           This command performs a touch(1)-like operation on "FILE".
773
774       --truncate FILE
775           This command truncates "FILE" to a zero-length file. The file must
776           exist already.
777
778       --truncate-recursive PATH
779           This command recursively truncates all files under "PATH" to zero-
780           length.
781
782       --uninstall PKG,PKG..
783           Uninstall the named packages (a comma-separated list).  These are
784           removed during the image build using the guest’s package manager
785           (eg. apt, yum, etc.).  Dependent packages may also need to be
786           uninstalled to satisfy the request.
787
788           See also --install, --update.
789
790       --update
791           Do the equivalent of "yum update", "apt-get upgrade", or whatever
792           command is required to update the packages already installed in the
793           template to their latest versions.
794
795           See also --install, --uninstall.
796
797       --upload FILE:DEST
798           Upload local file "FILE" to destination "DEST" in the disk image.
799           File owner and permissions from the original are preserved, so you
800           should set them to what you want them to be in the disk image.
801
802           "DEST" could be the final filename.  This can be used to rename the
803           file on upload.
804
805           If "DEST" is a directory name (which must already exist in the
806           guest) then the file is uploaded into that directory, and it keeps
807           the same name as on the local filesystem.
808
809           See also: --mkdir, --delete, --scrub.
810
811       --write FILE:CONTENT
812           Write "CONTENT" to "FILE".
813

REFERENCE

815   INSTALLING PACKAGES
816       There are several approaches to installing packages or applications in
817       the guest which have different trade-offs.
818
819       Installing packages at build time
820
821       If the guest OS you are installing is similar to the host OS (eg.  both
822       are Linux), and if libguestfs supports network connections, then you
823       can use --install to install packages like this:
824
825        virt-builder fedora-27 --install inkscape
826
827       This uses the guest’s package manager and the host’s network
828       connection.
829
830       Updating packages at build time
831
832       To update the installed packages in the template at build time:
833
834        virt-builder fedora-27 --update
835
836       Most of the templates that ship with virt-builder come with a very
837       minimal selection of packages (known as a "JEOS" or "Just Enough
838       Operating System"), which are up to date at the time the template is
839       created, but could be out of date by the time you come to install an OS
840       from the template.  This option updates those template packages.
841
842       Installing packages at first boot
843
844       Another option is to install the packages when the guest first boots:
845
846        virt-builder fedora-27 --firstboot-install inkscape
847
848       This uses the guest’s package manager and the guest’s network
849       connection.
850
851       The downsides are that it will take the guest a lot longer to boot
852       first time, and there’s nothing much you can do if package installation
853       fails (eg. if a network problem means the guest can't reach the package
854       repositories).
855
856       Installing packages at build time from a side repository
857
858       If the software you want to install is not available in the main
859       package repository of the guest, then you can add a side repository.
860       Usually this is presented as an ISO (CD disk image) file containing
861       extra packages.
862
863       You can create the disk image using either genisoimage(1) or
864       virt-make-fs(1).  For genisoimage, use a command like this:
865
866        genisoimage -o extra-packages.iso -R -J -V EXTRA cdcontents/
867
868       Create a script that mounts the ISO and sets up the repository.  For
869       dnf, create /tmp/install.sh containing:
870
871        mkdir /tmp/mount
872        mount LABEL=EXTRA /tmp/mount
873
874        cat <<'EOF' > /etc/yum.repos.d/extra.repo
875        [extra]
876        name=extra
877        baseurl=file:///tmp/mount
878        enabled=1
879        EOF
880
881        dnf -y install famousdatabase
882
883       For apt, create /tmp/install.sh containing:
884
885        mkdir /tmp/mount
886        mount LABEL=EXTRA /tmp/mount
887
888        apt-cdrom -d=/tmp/mount add
889        apt-get -y install famousdatabase
890
891       Use the --attach option to attach the CD / disk image and the --run
892       option to run the script:
893
894        virt-builder fedora-27 \
895          --attach extra-packages.iso \
896          --run /tmp/install.sh
897
898   USERS AND PASSWORDS
899       The --root-password option is used to change the root password
900       (otherwise a random password is used).  This option takes a password
901       "SELECTOR" in one of the following formats:
902
903       --root-password file:FILENAME
904           Read the root password from "FILENAME".  The whole first line of
905           this file is the replacement password.  Any other lines are
906           ignored.  You should create the file with mode 0600 to ensure no
907           one else can read it.
908
909       --root-password password:PASSWORD
910           Set the root password to the literal string "PASSWORD".
911
912           Note: this is not secure since any user on the same machine can see
913           the cleartext password using ps(1).
914
915       --root-password random
916           Choose a random password, which is printed on stdout.  The password
917           has approximately 120 bits of randomness.
918
919           This is the default.
920
921       --root-password disabled
922           The root account password is disabled.  This is like putting "*" in
923           the password field.
924
925       --root-password locked:file:FILENAME
926       --root-password locked:password:PASSWORD
927       --root-password locked:random
928           The root account is locked, but a password is placed on the
929           account.  If first unlocked (using "passwd -u") then logins will
930           use the given password.
931
932       --root-password locked
933       --root-password locked:disabled
934           The root account is locked and password is disabled.
935
936       Creating user accounts
937
938       To create user accounts, use the useradd(8) command with
939       --firstboot-command like this:
940
941        virt-builder --firstboot-command \
942           'useradd -m -p "" rjones ; chage -d 0 rjones'
943
944       The above command will create an "rjones" account with no password, and
945       force the user to set a password when they first log in.  There are
946       other ways to manage passwords, see useradd(8) for details.
947
948   KEYBOARD LAYOUT
949       Because there are so many different ways to set the keyboard layout in
950       Linux distributions, virt-builder does not yet attempt to have a simple
951       command line option.  This section describes how to set the keyboard
952       for some common Linux distributions.
953
954       Keyboard layout with systemd
955
956       For distros that use systemd "localectl", use a command like this:
957
958        virt-builder fedora-27 \
959          --firstboot-command 'localectl set-keymap uk'
960
961       See localectl(1) and
962       https://www.happyassassin.net/2013/11/23/keyboard-layouts-in-fedora-20-and-previously/
963       for more details.
964
965       Keyboard layout using /etc/sysconfig/keyboard
966
967       For RHEL ≤ 6, Fedora ≤ 18 and similar, upload or modify the keyboard
968       configuration file using the --upload, --write or --edit options.  For
969       example:
970
971        virt-builder centos-6 \
972          --edit '/etc/sysconfig/keyboard: s/^KEYTABLE=.*/KEYTABLE="uk"/'
973
974       The format of this file can be found documented in many places online.
975
976       Keyboard layout with Debian-derived distros
977
978       For Debian-derived distros using /etc/default/keyboard, upload or
979       modify the keyboard file using the --upload, --write or --edit options.
980       For example:
981
982        virt-builder debian-8 \
983          --edit '/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/'
984
985       See https://wiki.debian.org/Keyboard.
986
987   LANGUAGE
988       Most Linux distributions support multiple locale settings so that you
989       can have guest messages printed in another language such as Russian.
990
991       However there is no single setting which controls this, since extra
992       packages may need to be installed to support console and X fonts, and
993       keyboard input methods.  The packages required, and their configuration
994       is highly distro-specific, and it is outside the scope of virt-builder
995       to do this.
996
997       This section contains examples for some common Linux distributions.
998
999       Setting Japanese in Fedora 25
1000
1001        virt-builder fedora-27 \
1002          --size 20G \
1003          --update \
1004          --install @japanese-support \
1005          --install @xfce \
1006          --install xorg-x11-server-Xorg,xorg-x11-drivers,rsyslog \
1007          --link /usr/lib/systemd/system/graphical.target:/etc/systemd/system/default.target \
1008          --firstboot-command 'localectl set-locale LANG=ja_JP.utf8' \
1009          --firstboot-command 'localectl set-keymap jp' \
1010          --firstboot-command 'systemctl isolate graphical.target'
1011
1012       Setting Japanese in Debian 8 (Jessie)
1013
1014       Note that although this enables Japanese in the text console too, it is
1015       unlikely that you will see properly rendered Japanese there.  However
1016       Japanese is properly rendered in X applications and terminals.
1017
1018        pkgs=locales,xfce4,\
1019        ibus,ibus-anthy,\
1020        fonts-ipafont-gothic,fonts-ipafont-mincho,\
1021        fonts-takao-mincho,\
1022        xfonts-intl-japanese,xfonts-intl-japanese-big,\
1023        iceweasel-l10n-ja,manpages-ja
1024
1025        virt-builder debian-8 \
1026          --size 20G \
1027          --install $pkgs \
1028          --edit '/etc/locale.gen: s,^#\s*ja,ja,' \
1029          --write '/etc/default/locale:LANG="ja_JP.UTF-8"' \
1030          --run-command "locale-gen"
1031
1032   LOG FILE
1033       Scripts and package installation that runs at build time (--run,
1034       --run-command, --install, --update, but not firstboot) is logged in one
1035       of the following locations:
1036
1037       /tmp/builder.log
1038           On Linux, BSD, and other non-Windows guests.
1039
1040       C:\Temp\builder.log
1041           On Windows, DOS guests.
1042
1043       /builder.log
1044           If /tmp or C:\Temp is missing.
1045
1046       If you don’t want the log file to appear in the final image, then use
1047       the --no-logfile command line option.
1048
1049   SSH KEYS
1050       The --ssh-inject option is used to inject ssh keys for users in the
1051       guest, so they can login without supplying a password.
1052
1053       The "SELECTOR" part of the option value is optional; in this case,
1054       --ssh-inject "USER" means that we look in the current user’s ~/.ssh
1055       directory to find the default public ID file.  That key is uploaded.
1056       "default public ID" is the default_ID_file file described in
1057       ssh-copy-id(1).
1058
1059       If specified, the "SELECTOR" can be in one of the following formats:
1060
1061       --ssh-inject USER:file:FILENAME
1062           Read the ssh key from FILENAME.  FILENAME is usually a .pub file.
1063
1064       --ssh-inject USER:string:KEY_STRING
1065           Use the specified "KEY_STRING".  "KEY_STRING" is usually a public
1066           string like ssh-rsa AAAA.... user@localhost.
1067
1068       In any case, the ~USER/.ssh directory and the
1069       ~USER/.ssh/authorized_keys file will be created if not existing
1070       already.
1071
1072   FIRST BOOT SCRIPTS
1073       The --firstboot and --firstboot-command options allow you to execute
1074       commands at the first boot of the guest.  To do so, an init script for
1075       the guest init system is installed, which takes care of running all the
1076       added scripts and commands.
1077
1078       Supported operating systems are:
1079
1080       Linux
1081           Init systems supported are: systemd, System-V init (known also as
1082           sysvinit), and Upstart (using the System-V scripts).
1083
1084           Note that usually init scripts run as root, but with a more limited
1085           environment than what could be available from a normal shell: for
1086           example, $HOME may be unset or empty.
1087
1088           The output of the first boot scripts is available in the guest as
1089           ~root/virt-sysprep-firstboot.log.
1090
1091       Windows
1092           rhsrvany.exe, available from sources at
1093           https://github.com/rwmjones/rhsrvany, or pvvxsvc.exe, available
1094           with SUSE VMDP is installed to run the first boot scripts.  It is
1095           required, and the setup of first boot scripts will fail if it is
1096           not present.
1097
1098           rhsrvany.exe or pvvxsvc.exe is copied from the location pointed to
1099           by the "VIRT_TOOLS_DATA_DIR" environment variable; if not set, a
1100           compiled-in default will be used (something like
1101           /usr/share/virt-tools).
1102
1103           The output of the first boot scripts is available in the guest as
1104           C:\Program Files\Guestfs\Firstboot\log.txt.
1105
1106   SUBSCRIPTION-MANAGER
1107       It is possible to automate the registration and attaching of the system
1108       using "subscription-manager".  This is typical on Red Hat Enterprise
1109       Linux guests.  There are few options which ease this process, avoid
1110       executing commands manually and exposing passwords on command line.
1111
1112       --sm-register starts the registration process, and requires
1113       --sm-credentials to be specified; the format of the "SELECTOR" of
1114       --sm-credentials is one of the following formats:
1115
1116       --sm-credentials USER:file:FILENAME
1117           Read the password for the specified "USER" from FILENAME.
1118
1119       --sm-credentials USER:password:PASSWORD
1120           Use the literal string "PASSWORD" for the specified "USER".
1121
1122       --sm-attach attaches the system to subscriptions; the format of its
1123       "SELECTOR" is one of the following:
1124
1125       --sm-attach auto
1126           "subscription-manager" attaches to the best-fitting subscriptions
1127           for the system.
1128
1129       --sm-attach file:FILENAME
1130           Read the pool ID from FILENAME.
1131
1132       --sm-attach pool:POOL
1133           Use the literal string "POOL" as pool ID.
1134
1135       --sm-remove removes all the subscriptions from the guest, while
1136       --sm-unregister completely unregister the system.
1137
1138   INSTALLATION PROCESS
1139       When you invoke virt-builder, installation proceeds as follows:
1140
1141       •   The template image is downloaded.
1142
1143           If the template image is present in the cache, the cached version
1144           is used instead.  (See "CACHING").
1145
1146       •   The template signature is checked.
1147
1148       •   The template is uncompressed to a tmp file.
1149
1150       •   The template image is resized into the destination, using
1151           virt-resize(1).
1152
1153       •   Extra disks are attached (--attach).
1154
1155       •   A new random seed is generated for the guest.
1156
1157       •   Guest customization is performed, in the order specified on the
1158           command line.
1159
1160       •   SELinux relabelling is done (--selinux-relabel).
1161
1162   IMPORTING THE DISK IMAGE
1163       Importing into libvirt
1164
1165       Import the disk image into libvirt using virt-install(1) --import
1166       option.
1167
1168        virt-install --import \
1169          --name guest --ram 2048 \
1170          --disk path=disk.img,format=raw --os-variant fedora27
1171
1172       Notes:
1173
1174       1.  You must specify the correct format.  The format is "raw" unless
1175           you used virt-builder’s --format option.
1176
1177       2.  --os-variant is highly recommended, because it will present optimum
1178           devices to enable the guest to run most efficiently.  To get a list
1179           of all variants, do:
1180
1181            osinfo-query os
1182
1183           The above tool is provided by libosinfo package.
1184
1185       3.  You can run virt-install as root or non-root.  Each works slightly
1186           differently because libvirt manages a different set of virtual
1187           machines for each user.  In particular virt-manager normally shows
1188           the root-owned VMs, whereas Boxes shows the user-owned VMs, and
1189           other tools probably work differently as well.
1190
1191       Importing into OpenStack
1192
1193       Import the image into Glance (the OpenStack image store) by doing:
1194
1195        glance image-create --name fedora-27-image --file fedora-27.img \
1196          --disk-format raw --container-format bare \
1197          --is-public True
1198
1199       The --file parameter is the virt-builder-generated disk image.  It
1200       should match virt-builder’s --output option.  The --disk-format
1201       parameter should match virt-builder’s --format option (or "raw" if you
1202       didn't use that option).  The --container-format should always be
1203       "bare" since virt-builder doesn't put images into containers.
1204
1205       You can use the "glance image-show fedora-27-image" command to display
1206       the properties of the image.
1207
1208       To boot up an instance of your image on a Nova compute node, do:
1209
1210        nova boot fedora-27-server --image fedora-27-image \
1211          --flavor m1.medium
1212
1213       Use "nova flavor-list" to list possible machine flavors.  Use
1214       "nova list" to list running instances.
1215
1216       Booting directly using qemu or KVM
1217
1218       The qemu command line is not very stable or easy to use, hence libvirt
1219       should be used if possible.  However a command line similar to the
1220       following could be used to boot the virtual machine:
1221
1222        qemu-system-x86_64 \
1223          -machine accel=kvm:tcg \
1224          -cpu host \
1225          -m 2048 \
1226          -drive file=disk.img,format=raw,if=virtio
1227
1228       As with libvirt, it is very important that the correct format is
1229       chosen.  It will be "raw" unless the --format option was used.
1230
1231   CONFIGURATION MANAGEMENT
1232       Puppet
1233
1234       To enable the Puppet agent in a guest, install the package, point the
1235       configuration at your Puppetmaster, and ensure the agent runs at boot.
1236
1237       A typical virt-builder command would be:
1238
1239        virt-builder fedora-27 \
1240          --hostname client.example.com \
1241          --update \
1242          --install puppet \
1243          --append-line '/etc/puppet/puppet.conf:[agent]' \
1244          --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
1245          --run-command 'systemctl enable puppet' \
1246          --selinux-relabel
1247
1248       The precise instructions vary according to the Linux distro.  For
1249       further information see:
1250       https://docs.puppet.com/puppet/latest/install_pre.html
1251
1252   DEBUGGING BUILDS
1253       If virt-builder itself fails, then enable debugging (-v) and report a
1254       bug (see "BUGS" below).
1255
1256       If virt-builder fails because some script or package it is installing
1257       fails, try using --no-delete-on-failure to preserve the output file,
1258       and continue reading this section.
1259
1260       If virt-builder is successful but the image doesn't work, here are some
1261       things to try:
1262
1263       Use virt-rescue
1264           Run virt-rescue(1) on the disk image:
1265
1266            virt-rescue -a disk.img
1267
1268           This gives you a rescue shell.  You can mount the filesystems from
1269           the disk image on /sysroot and examine them using ordinary Linux
1270           commands.  You can also chroot into the guest to reinstall the
1271           bootloader.  The virt-rescue man page has a lot more information
1272           and examples.
1273
1274       Use guestfish
1275           Run guestfish(1) on the disk image:
1276
1277            guestfish -a disk.img -i
1278
1279           Use guestfish commands like "ll /directory" and "cat /file" to
1280           examine directories and files.
1281
1282       Use guestmount
1283           Mount the disk image safely on the host using FUSE and
1284           guestmount(1):
1285
1286            mkdir /tmp/mp
1287            guestmount -a disk.img -i /tmp/mp
1288            cd /tmp/mp
1289
1290           To unmount the disk image do:
1291
1292            fusermount -u /tmp/mp
1293
1294       Add a serial console
1295           If the guest hangs during boot, it can be helpful to add a serial
1296           console to the guest, and direct kernel messages to the serial
1297           console.  Adding the serial console will involve looking at the
1298           documentation for your hypervisor.  To direct kernel messages to
1299           the serial console, add the following on the kernel command line:
1300
1301            console=tty0 console=ttyS0,115200
1302
1303   SOURCES OF TEMPLATES
1304       virt-builder reads the available sources from configuration files, with
1305       the .conf extension and located in the following paths:
1306
1307       •   $XDG_CONFIG_HOME/virt-builder/repos.d/ ($XDG_CONFIG_HOME is
1308           $HOME/.config if not set).
1309
1310       •   $VIRT_BUILDER_DIRS/virt-builder/repos.d/ (where $VIRT_BUILDER_DIRS
1311           means any of the directories in that environment variable, or just
1312           /etc if not set).
1313
1314       Each .conf file in those paths has a simple text format like the
1315       following:
1316
1317        [libguestfs.org]
1318        uri=http://libguestfs.org/download/builder/index.asc
1319        gpgkey=file:///etc/xdg/virt-builder/repos.d/libguestfs.gpg
1320
1321       The part in square brackets is the repository identifier, which is used
1322       as unique identifier.
1323
1324       The following fields can appear:
1325
1326       "uri=URI"
1327           The URI of the index file which this repository refers to.
1328
1329           This field is required.
1330
1331       "gpgkey=URI"
1332           This optional field represents the URI (although only file:// URIs
1333           are accepted) of the key used to sign the index file.  If not
1334           present, the index file referred by uri=.. is not signed.
1335
1336       "proxy=MODE"
1337           This optional field specifies the proxy mode, to be used when
1338           downloading the index file of this repository.  The possible values
1339           are:
1340
1341           no, off
1342               No proxy is being used at all, even overriding the system
1343               configuration.
1344
1345           system
1346               The proxy used is the system one.
1347
1348           anything else
1349               Specifies the actual proxy configuration to be used, overriding
1350               the system configuration.
1351
1352           If not present, the assumed value is to respect the proxy settings
1353           of the system (i.e. as if system would be specified).
1354
1355       "format=FORMAT"
1356           This optional field specifies the format of the repository.  The
1357           possible values are:
1358
1359           native
1360               The native format of the "virt-builder" repository.  See also
1361               "Creating and signing the index file" below.
1362
1363           simplestreams
1364               The URI represents the root of a Simple Streams v1.0 tree of
1365               metadata.
1366
1367               For more information about Simple Streams, see also
1368               https://launchpad.net/simplestreams.
1369
1370           If not present, the assumed value is "native".
1371
1372       For serious virt-builder use, you may want to create your own
1373       repository of templates.
1374
1375       Libguestfs.org repository
1376
1377       Out of the box, virt-builder downloads the file
1378       http://libguestfs.org/download/builder/index.asc which is an index of
1379       available templates plus some information about each one, wrapped up in
1380       a digital signature.  The command "virt-builder --list" lists out the
1381       information in this index file.
1382
1383       The templates hosted on libguestfs.org were created using shell
1384       scripts, kickstart files and preseed files which can be found in the
1385       libguestfs source tree, in "builder/templates".
1386
1387       Setting up the repository
1388
1389       You can set up your own site containing an index file and some
1390       templates, and then point virt-builder at the site by creating a .conf
1391       file pointing to it.
1392
1393       Note that if your index is signed, you will need to properly fill
1394       gpgkey=.. in your .conf file, making sure to deploy also the GPG key
1395       file.
1396
1397        virt-builder --source https://example.com/builder/index.asc \
1398           --fingerprint 'AAAA BBBB ...' \
1399           --list
1400
1401       You can host this on any web or FTP server, or a local or network
1402       filesystem.
1403
1404       Setting up a GPG key
1405
1406       If you don’t have a GnuPG key, you will need to set one up.  (Strictly
1407       speaking this is optional, but if your index and template files are not
1408       signed then virt-builder users will have to use the
1409       --no-check-signature flag every time they use virt-builder.)
1410
1411       To create a key, see the GPG manual
1412       http://www.gnupg.org/gph/en/manual.html.
1413
1414       Export your GPG public key:
1415
1416        gpg --export -a "you@example.com" > pubkey
1417
1418       Create the templates
1419
1420       There are many ways to create the templates.  For example you could
1421       clone existing guests (see virt-sysprep(1)), or you could install a
1422       guest by hand (virt-install(1)).  To see how the templates were created
1423       for virt-builder, look at the scripts in "builder/templates"
1424
1425       Virt-builder supports any image format (e.g. raw, qcow2, etc) as
1426       template, both as-is, and compressed as XZ.  This way, existing images
1427       (e.g. cleaned using virt-sysprep(1)) can be used as templates.
1428
1429       For best results when compressing the templates, use the following xz
1430       options (see nbdkit-xz-plugin(1) for further explanation):
1431
1432        xz --best --block-size=16777216 disk
1433
1434       Creating and signing the index file
1435
1436       The index file has a simple text format (shown here without the digital
1437       signature):
1438
1439        [fedora-18]
1440        name=Fedora® 18
1441        osinfo=fedora18
1442        arch=x86_64
1443        file=fedora-18.xz
1444        checksum[sha512]=...
1445        format=raw
1446        size=6442450944
1447        compressed_size=148947524
1448        expand=/dev/sda3
1449
1450        [fedora-19]
1451        name=Fedora® 19
1452        osinfo=fedora19
1453        arch=x86_64
1454        file=fedora-19.xz
1455        checksum[sha512]=...
1456        revision=3
1457        format=raw
1458        size=4294967296
1459        compressed_size=172190964
1460        expand=/dev/sda3
1461
1462       The part in square brackets is the "os-version", which is the same
1463       string that is used on the virt-builder command line to build that OS.
1464
1465       The index file creation and signature can be eased with the
1466       virt-builder-repository(1) tool.
1467
1468       After preparing the "index" file in the correct format, clearsign it
1469       using the following command:
1470
1471        gpg --clearsign --armor index
1472
1473       This will create the final file called index.asc which can be uploaded
1474       to the server (and is the uri=.. URL).  As noted above, signing the
1475       index file is optional, but recommended.
1476
1477       The following fields can appear:
1478
1479       "name=NAME"
1480           The user-friendly name of this template.  This is displayed in the
1481           --list output but is otherwise not significant.
1482
1483       "osinfo=ID"
1484           This optional field maps the operating system to the associated
1485           libosinfo ID.  Virt-builder does not use it (yet).
1486
1487       "arch=ARCH"
1488           The architecture of the operating system installed within the
1489           template. This field is required.
1490
1491       "file=PATH"
1492           The path (relative to the index) of the xz-compressed template.
1493
1494           Note that absolute paths or URIs are not permitted here.  This is
1495           because virt-builder has a "same origin" policy for templates so
1496           they cannot come from other servers.
1497
1498       "sig=PATH"
1499           This option is deprecated.  Use the checksum field instead.
1500
1501           The path (relative to the index) of the GPG detached signature of
1502           the xz file.
1503
1504           Note that absolute paths or URIs are not permitted here.  This is
1505           because virt-builder has a "same origin" policy for templates so
1506           they cannot come from other servers.
1507
1508           The file can be created as follows:
1509
1510            gpg --detach-sign --armor -o disk.xz.sig disk.xz
1511
1512       "checksum[sha512]=7b882fe9b82eb0fef..."
1513           The SHA-512 checksum of the file specified in file=.. is checked
1514           after it is downloaded.  To work out the signature, do:
1515
1516            sha512sum disk.xz
1517
1518           Note if you use this, you don’t need to sign the file, ie. don’t
1519           use "sig".  This option overrides "sig".
1520
1521       "checksum=7b882fe9b82eb0fef..."
1522           "checksum" is an alias for "checksum[sha512]".
1523
1524           If you need to interoperate with virt-builder = 1.24.0 then you
1525           have to use "checksum" because that version would give a parse
1526           error with square brackets and numbers in the key of a field.  This
1527           is fixed in virt-builder ≥ 1.24.1.
1528
1529       "revision=N"
1530           The revision is an integer which is used to control the template
1531           cache.  Increasing the revision number causes clients to download
1532           the template again even if they have a copy in the cache.
1533
1534           The revision number is optional.  If omitted it defaults to 1.
1535
1536       "format=raw"
1537       "format=qcow2"
1538           Specify the format of the disk image; in case it is compressed,
1539           that is the format before the compression.  If not given, the
1540           format is autodetected, but generally it is better to be explicit
1541           about the intended format.
1542
1543           Note this is the source format, which is different from the
1544           --format option (requested output format).  Virt-builder does on-
1545           the-fly conversion from the source format to the requested output
1546           format.
1547
1548       "size=NNN"
1549           The virtual size of the image in bytes.  This is the size of the
1550           image when uncompressed.  If using a non-raw format such as qcow2
1551           then it means the virtual disk size, not the size of the qcow2
1552           file.
1553
1554           This field is required.
1555
1556           Virt-builder also uses this as the minimum size that users can
1557           request via the --size option, or as the default size if there is
1558           no --size option.
1559
1560       "compressed_size=NNN"
1561           The actual size of the disk image in bytes, i.e. what was specified
1562           in file=...  This is just used for information (when using "long",
1563           and "json" formats of --list).
1564
1565       "expand=/dev/sdaX"
1566           When expanding the image to its final size, instruct virt-resize(1)
1567           to expand the named partition in the guest image to fill up all
1568           available space.  This works like the virt-resize --expand option.
1569
1570           You should usually put the device name of the guest’s root
1571           filesystem here.
1572
1573           It’s a good idea to use this, but not required.  If the field is
1574           omitted then virt-resize will create an extra partition at the end
1575           of the disk to cover the free space, which is much less user-
1576           friendly.
1577
1578       "lvexpand=/dev/VolGroup/LogVol"
1579           When expanding the image to its final size, instruct virt-resize(1)
1580           to expand the named logical volume in the guest image to fill up
1581           all available space.  This works like the virt-resize --lv-expand
1582           option.
1583
1584           If the guest uses LVM2 you should usually put the LV of the guest’s
1585           root filesystem here.  If the guest does not use LVM2 or its root
1586           filesystem is not on an LV, don't use this option.
1587
1588       "notes=NOTES"
1589           Any notes that go with this image, especially notes describing what
1590           packages are in the image, how the image was prepared, and
1591           licensing information.
1592
1593           This information is shown in the --notes and --list --long modes.
1594
1595           You can use multi-line notes here by indenting each new line with
1596           at least one character of whitespace (even on blank lines):
1597
1598            notes=This image was prepared using
1599             the following kickstart script:
1600                                           <-- one space at beginning of line
1601             part /boot --fstype ext3
1602             ...
1603
1604       "hidden=true"
1605           Using the hidden flag prevents the template from being listed by
1606           the --list option (but it is still installable).  This is used for
1607           test images.
1608
1609       "aliases=ALIAS1 ALIAS2 ..."
1610           This optional field specifies a list of aliases, separated by
1611           spaces, for the image.  For example, an alias could be used to
1612           always point to the latest version of a certain image, leaving the
1613           old versions available in the index instead of updating the same
1614           image (see the "revision" field).
1615
1616       Running virt-builder against multiple sources
1617
1618       It is possible to use multiple sources with virt-builder.  The
1619       recommended way is to deploy .conf files pointing to the index files.
1620       Another way is to specify the sources using multiple --source and/or
1621       --fingerprint options:
1622
1623        virt-builder \
1624          --source http://example.com/s1/index.asc \
1625          --source http://example.com/s2/index.asc
1626
1627       You can provide N or 1 fingerprints.  In the case where you provide N
1628       fingerprints, N = number of sources and there is a 1-1 correspondence
1629       between each source and each fingerprint:
1630
1631        virt-builder \
1632          --source http://example.com/s1/index.asc --fingerprint '0123 ...' \
1633          --source http://example.com/s2/index.asc --fingerprint '9876 ...'
1634
1635       In the case where you provide 1 fingerprint, the same fingerprint is
1636       used for all sources.
1637
1638       You "must" provide at least 1 fingerprint.
1639
1640       Licensing of templates
1641
1642       You should be aware of the licensing of images that you distribute.
1643       For open source guests, provide a link to the source code in the
1644       "notes" field and comply with other requirements (eg. around
1645       trademarks).
1646
1647       Formal specification of the index file
1648
1649       The index file format has a formal specification defined by the flex
1650       scanner and bison parser used to parse the file.  This can be found in
1651       the following files in the libguestfs source tree:
1652
1653        builder/index-scan.l
1654        builder/index-parse.y
1655
1656       A tool called virt-index-validate(1) is available to validate the index
1657       file to ensure it is correct.
1658
1659       Note that the parser and tool can work on either the signed or unsigned
1660       index file (ie. index or index.asc).
1661
1662       The index is always encoded in UTF-8.
1663
1664   CACHING
1665       Caching templates
1666
1667       Since the templates are usually very large, downloaded templates are
1668       cached in the user’s home directory.
1669
1670       The location of the cache is $XDG_CACHE_HOME/virt-builder/ or
1671       $HOME/.cache/virt-builder.
1672
1673       You can print out information about the cache directory, including
1674       which guests are currently cached, by doing:
1675
1676        virt-builder --print-cache
1677
1678       The cache can be deleted if you want to save space by doing:
1679
1680        virt-builder --delete-cache
1681
1682       You can download all (current) templates to the local cache by doing:
1683
1684        virt-builder --cache-all-templates
1685
1686       To disable the template cache, use --no-cache.
1687
1688       Only templates are cached.  The index and detached digital signatures
1689       are not cached.
1690
1691       Caching packages
1692
1693       Virt-builder uses curl(1) to download files and it also uses the
1694       current "http_proxy" (etc) settings when installing packages
1695       (--install, --update).
1696
1697       You may therefore want to set those environment variables in order to
1698       maximize the amount of local caching that happens.  See "ENVIRONMENT
1699       VARIABLES" and curl(1).
1700
1701       Local mirrors
1702
1703       To increase both speed and reliability of installing packages, you can
1704       set up a local mirror of the target distribution, and point the guest
1705       package manager at that.
1706
1707       Using a local mirror with Fedora
1708
1709       To install a Fedora guest using a local mirror:
1710
1711        virt-builder fedora-27 \
1712          --edit '/etc/yum.repos.d/fedora.repo:
1713              s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
1714              s{.*metalink=.*}{};
1715          ' \
1716          --edit '/etc/yum.repos.d/fedora-updates.repo:
1717              s{.*baseurl=.*}{baseurl=http://example.com/mirror-updates/};
1718              s{.*metalink=.*}{};
1719          ' \
1720          --run-command 'dnf -y update' \
1721          --install 'pkg1,pkg2,...'
1722
1723       Using a local mirror with Debian
1724
1725       Assuming that you are using "apt-proxy" to mirror the repository, you
1726       should create a new sources.list file to point to your proxy (see
1727       https://help.ubuntu.com/community/AptProxy) and then do:
1728
1729        virt-builder debian-8 \
1730          --upload sources.list:/etc/apt/sources.list \
1731          --run-command 'apt-get -y update' \
1732          --install 'pkg1,pkg2,...'
1733
1734   DIGITAL SIGNATURES
1735       Virt-builder uses GNU Privacy Guard (GnuPG or gpg) to verify that the
1736       index and templates have not been tampered with.
1737
1738       The source points to an index file, which is optionally signed.
1739
1740       Virt-builder downloads the index and checks that the signature is valid
1741       and the signer’s fingerprint matches the specified fingerprint (ie. the
1742       one specified in gpgkey=.. in the .conf, or with --fingerprint, in that
1743       order).
1744
1745       For checking against the built-in public key/fingerprint, this requires
1746       importing the public key into the user’s local gpg keyring (that’s just
1747       the way that gpg works).
1748
1749       When a template is downloaded, its signature is checked in the same
1750       way.
1751
1752       Although the signatures are optional, if you don’t have them then virt-
1753       builder users will have to use --no-check-signature on the command
1754       line.  This prevents an attacker from replacing the signed index file
1755       with an unsigned index file and having virt-builder silently work
1756       without checking the signature.  In any case it is highly recommended
1757       that you always create signed index and templates.
1758
1759   ARCHITECTURE
1760       Virt-builder can build a guest for any architecture no matter what the
1761       host architecture is.  For example an x86-64 guest on an ARM host.
1762
1763       However certain options may not work, specifically options that require
1764       running commands in the guest during the build process: --install,
1765       --update, --run, --run-command.  You may need to replace these with
1766       their firstboot-equivalents.
1767
1768       An x86-64 host building 32 bit i686 guests should work without any
1769       special steps.
1770
1771   SECURITY
1772       Virt-builder does not need to run as root (in fact, should not be run
1773       as root), and doesn't use setuid, "sudo" or any similar mechanism.
1774
1775       --install, --update, --run and --run-command are implemented using an
1776       appliance (a small virtual machine) so these commands do not run on the
1777       host.  If you are using the libguestfs libvirt backend and have SELinux
1778       enabled then the virtual machine is additionally encapsulated in an
1779       SELinux container (sVirt).
1780
1781       However these options will have access to the host’s network and since
1782       the template may contain untrusted code, the code might try to access
1783       host network resources which it should not.  You can use --no-network
1784       to prevent this.
1785
1786       Firstboot commands run in the context of the guest when it is booted,
1787       and so the security of your hypervisor / cloud should be considered.
1788
1789       Virt-builder injects a random seed into every guest which it builds.
1790       This helps to ensure that TCP sequence numbers, UUIDs, ssh host keys
1791       etc are truly random when the guest boots.
1792
1793       You should check digital signatures and not ignore any signing errors.
1794
1795   CLONES
1796       If you wish to create many new guests of the same type, it is tempting
1797       to run virt-builder once and then copy the output file.  You should not
1798       do this.  You should run virt-builder once for each new guest you need.
1799
1800       The reason is that each clone needs to have (at least) a separate
1801       random seed, and possibly other unique features (such as filesystem
1802       UUIDs) in future versions of virt-builder.
1803
1804       Another thing you should not do is to boot the guest, then clone the
1805       booted disk image.  The reason is that some guests create unique
1806       machine IDs, SSH host keys and so on at first boot, and you would not
1807       want clones to have duplicate identities.
1808
1809       See also: virt-sysprep(1).
1810
1811   PERFORMANCE
1812       The most important aspect of getting good performance is caching.
1813       Templates gets downloaded into the cache the first time they are used,
1814       or if you use the --cache-all-templates option.  See "CACHING" above
1815       for further information.
1816
1817       Packages required for the --install and --update options are downloaded
1818       using the host network connection.  Setting the "http_proxy",
1819       "https_proxy" and "ftp_proxy" environment variables to point to a local
1820       web cache may ensure they only need to be downloaded once.  You can
1821       also try using a local package repository, although this can be complex
1822       to set up and varies according to which Linux distro you are trying to
1823       install.
1824
1825       Using --no-sync
1826
1827       Use --no-sync.  However read the caveats in the "OPTIONS" section
1828       above, since this can cause disk corruption if not used correctly.
1829
1830       Skipping virt-resize
1831
1832       Virt-builder can skip the virt-resize step under certain conditions.
1833       This makes virt-builder much faster.  The conditions are:
1834
1835       •   the output must be a regular file (not a block device), and
1836
1837       •   the user did not use the --size option, and
1838
1839       •   the output format is the same as the template format (usually raw).
1840
1841       pxzcat
1842
1843       Virt-builder uses an internal implementation of pxzcat (parallel xzcat)
1844       if liblzma was found at build time.  If liblzma was not found at build
1845       time, regular "xzcat" is used which is single-threaded.
1846
1847       User-Mode Linux
1848
1849       You can use virt-builder with the User-Mode Linux (UML) backend.  This
1850       may be faster when running virt-builder inside a virtual machine (eg.
1851       in the cloud).
1852
1853       To enable the UML backend, read the instructions in "USER-MODE LINUX
1854       BACKEND" in guestfs(3).
1855
1856       Currently you have to use the --no-network option.  This should be
1857       fixed in a future version.
1858
1859       The qcow2 output format is not supported by UML.  You can only create
1860       raw-format guests.
1861
1862   SELINUX
1863       Guests which use SELinux (such as Fedora and Red Hat Enterprise Linux)
1864       require that each file has a correct SELinux label.
1865
1866       Virt-builder does not know how to give new files a label, so there are
1867       two possible strategies it can use to ensure correct labelling:
1868
1869       Using --selinux-relabel
1870           This runs setfiles(8) just before finalizing the guest, which sets
1871           SELinux labels correctly in the disk image.
1872
1873           This is the recommended method.
1874
1875       --touch /.autorelabel
1876           Guest templates may already contain a file called /.autorelabel or
1877           you may touch it.
1878
1879           For guests that use SELinux, this causes restorecon(8) to run at
1880           first boot.  Guests will reboot themselves once the first time you
1881           use them, which is normal and harmless.
1882
1883       Please note that if your guest uses SELinux, and you are doing
1884       operations on it which might create new files or change existing ones,
1885       you are recommended to use --selinux-relabel.  This will help in making
1886       sure that files have the right SELinux labels.
1887

MACHINE READABLE OUTPUT

1889       The --machine-readable option can be used to make the output more
1890       machine friendly, which is useful when calling virt-builder from other
1891       programs, GUIs etc.
1892
1893       Use the option on its own to query the capabilities of the virt-builder
1894       binary.  Typical output looks like this:
1895
1896        $ virt-builder --machine-readable
1897        virt-builder
1898        arch
1899        config-file
1900        customize
1901        json-list
1902        pxzcat
1903
1904       A list of features is printed, one per line, and the program exits with
1905       status 0.
1906
1907       It is possible to specify a format string for controlling the output;
1908       see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
1909

ENVIRONMENT VARIABLES

1911       For other environment variables which affect all libguestfs programs,
1912       see "ENVIRONMENT VARIABLES" in guestfs(3).
1913
1914       "http_proxy"
1915       "https_proxy"
1916       "no_proxy"
1917           Set the proxy for downloads.  These environment variables (and
1918           more) are actually interpreted by curl(1), not virt-builder.
1919
1920       "HOME"
1921           Used to determine the location of the template cache, and the
1922           location of the user' sources.  See "CACHING" and "SOURCES OF
1923           TEMPLATES".
1924
1925       "VIRT_TOOLS_DATA_DIR"
1926           This can point to the directory containing data files used for
1927           Windows firstboot installation.
1928
1929           Normally you do not need to set this.  If not set, a compiled-in
1930           default will be used (something like /usr/share/virt-tools).
1931
1932           This directory may contain the following files:
1933
1934           rhsrvany.exe
1935               This is the RHSrvAny Windows binary, used to install a
1936               "firstboot" script in Windows guests.  It is required if you
1937               intend to use the --firstboot or --firstboot-command options
1938               with Windows guests.
1939
1940               See also: "https://github.com/rwmjones/rhsrvany"
1941
1942           pvvxsvc.exe
1943               This is a Windows binary shipped with SUSE VMDP, used to
1944               install a "firstboot" script in Windows guests.  It is required
1945               if you intend to use the --firstboot or --firstboot-command
1946               options with Windows guests.
1947
1948       "XDG_CACHE_HOME"
1949           Used to determine the location of the template cache.  See
1950           "CACHING".
1951
1952       "XDG_CONFIG_HOME"
1953           Used to determine the location of the user' sources.  See "SOURCES
1954           OF TEMPLATES".
1955
1956       "VIRT_BUILDER_DIRS"
1957           Used to determine the location of the system sources.  See "SOURCES
1958           OF TEMPLATES".
1959

EXIT STATUS

1961       This program returns 0 if successful, or non-zero if there was an
1962       error.
1963

SEE ALSO

1965       guestfs(3), guestfish(1), guestmount(1), virt-builder-repository(1),
1966       virt-copy-out(1), virt-customize(1), virt-get-kernel(1),
1967       virt-install(1), virt-rescue(1), virt-resize(1), virt-sysprep(1),
1968       oz-install(1), gpg(1), gpg2(1), curl(1), virt-make-fs(1),
1969       genisoimage(1), http://libguestfs.org/.
1970

AUTHOR

1972       Richard W.M. Jones http://people.redhat.com/~rjones/
1973
1975       Copyright (C) 2013 Red Hat Inc.
1976

LICENSE

1978       This program is free software; you can redistribute it and/or modify it
1979       under the terms of the GNU General Public License as published by the
1980       Free Software Foundation; either version 2 of the License, or (at your
1981       option) any later version.
1982
1983       This program is distributed in the hope that it will be useful, but
1984       WITHOUT ANY WARRANTY; without even the implied warranty of
1985       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1986       General Public License for more details.
1987
1988       You should have received a copy of the GNU General Public License along
1989       with this program; if not, write to the Free Software Foundation, Inc.,
1990       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
1991

BUGS

1993       To get a list of bugs against libguestfs, use this link:
1994       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
1995
1996       To report a new bug against libguestfs, use this link:
1997       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1998
1999       When reporting a bug, please supply:
2000
2001       •   The version of libguestfs.
2002
2003       •   Where you got libguestfs (eg. which Linux distro, compiled from
2004           source, etc)
2005
2006       •   Describe the bug accurately and give a way to reproduce it.
2007
2008       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
2009           into the bug report.
2010
2011
2012
2013guestfs-tools-1.46.1              2021-05-13                   virt-builder(1)
Impressum