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] [--no-selinux-relabel]
27           [--selinux-relabel] [--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   Customizing the installation
138       There are many options that let you customize the installation.  These
139       include: --run/--run-command, which run a shell script or command while
140       the disk image is being generated and lets you add or edit files that
141       go into the disk image.  --firstboot/--firstboot-command, which let you
142       add scripts/commands that are run the first time the guest boots.
143       --edit to edit files.  --upload to upload files.
144
145       For example:
146
147        cat <<'EOF' > /tmp/dnf-update.sh
148        dnf -y --best update
149        EOF
150
151        virt-builder fedora-27 --firstboot /tmp/dnf-update.sh
152
153       or simply:
154
155        virt-builder fedora-27 --firstboot-command 'dnf -y --best update'
156
157       which makes the dnf(8) "update" command run once the first time the
158       guest boots.
159
160       Or:
161
162        virt-builder fedora-27 \
163          --edit '/etc/dnf/dnf.conf:
164                    s/gpgcheck=1/gpgcheck=0/'
165
166       which edits /etc/dnf/dnf.conf inside the disk image (during disk image
167       creation, long before boot).
168
169       You can combine these options, and have multiple options of all types.
170

OPTIONS

172       --help
173           Display help.
174
175       --arch ARCHITECTURE
176           Use the specified architecture for the output image.  This means
177           there must be sources providing the requested template for the
178           requested architecture.
179
180           See also "ARCHITECTURE".
181
182       --attach ISOFILE
183           During the customization phase, the given disk is attached to the
184           libguestfs appliance.  This is used to provide extra software
185           repositories or other data for customization.
186
187           You probably want to ensure the volume(s) or filesystems in the
188           attached disks are labelled (or use an ISO volume name) so that you
189           can mount them by label in your run-scripts:
190
191            mkdir /tmp/mount
192            mount LABEL=EXTRA /tmp/mount
193
194           You can have multiple --attach options, and the format can be any
195           disk format (not just an ISO).
196
197           See also: --run, "Installing packages at build time from a side
198           repository", genisoimage(1), virt-make-fs(1).
199
200       --attach-format FORMAT
201           Specify the disk format for the next --attach option.  The "FORMAT"
202           is usually "raw" or "qcow2".  Use "raw" for ISOs.
203
204       --cache DIR
205       --no-cache
206           --cache DIR sets the directory to use/check for cached template
207           files.  If not set, defaults to either
208           $XDG_CACHE_HOME/virt-builder/ or $HOME/.cache/virt-builder/.
209
210           --no-cache disables template caching.
211
212       --cache-all-templates
213           Download all templates to the cache and then exit.  See "CACHING".
214
215           Note this doesn't cache everything.  More templates might be
216           uploaded.  Also this doesn't cache packages (the --install,
217           --update options).
218
219       --check-signature
220       --no-check-signature
221           Check/don’t check the digital signature of the OS template.  The
222           default is to check the signature and exit if it is not correct.
223           Using --no-check-signature bypasses this check.
224
225           See also --fingerprint.
226
227       --colors
228       --colours
229           Use ANSI colour sequences to colourize messages.  This is the
230           default when the output is a tty.  If the output of the program is
231           redirected to a file, ANSI colour sequences are disabled unless you
232           use this option.
233
234       --curl CURL
235           Specify an alternate curl(1) binary.  You can also use this to add
236           curl parameters, for example to disable https certificate checks:
237
238            virt-builder --curl "curl --insecure" [...]
239
240       --delete-cache
241           Delete the template cache.  See "CACHING".
242
243       --no-delete-on-failure
244           Don’t delete the output file on failure to build.  You can use this
245           to debug failures to run scripts.  See "DEBUGGING BUILDS" for ways
246           to debug images.
247
248           The default is to delete the output file if virt-builder fails (or,
249           for example, some script that it runs fails).
250
251       --fingerprint 'AAAA BBBB ...'
252           Check that the index and templates are signed by the key with the
253           given fingerprint.  (The fingerprint is a long string, usually
254           written as 10 groups of 4 hexadecimal digits).
255
256           You can give this option multiple times.  If you have multiple
257           source URLs, then you can have either no fingerprint, one
258           fingerprint or multiple fingerprints.  If you have multiple, then
259           each must correspond 1-1 with a source URL.
260
261       --format qcow2
262       --format raw
263           For ordinary builds, this selects the output format.  The default
264           is raw.
265
266           With --get-kernel this specifies the input format.
267
268           To create an old-style qcow2 file (for compatibility with RHEL 6 or
269           very old qemu < 1.1), after running virt-builder, use this command:
270
271            qemu-img amend -f qcow2 -o compat=0.10 output.qcow2
272
273       --get-kernel IMAGE
274           This option extracts the kernel and initramfs from a previously
275           built disk image called "IMAGE" (in fact it works for any VM disk
276           image, not just ones built using virt-builder).
277
278           Note this method is deprecated: there is a separate tool for this,
279           virt-get-kernel(1), which has more options for the file extraction.
280
281           The kernel and initramfs are written to the current directory,
282           unless you also specify the --output "outputdir" directory name.
283
284           The format of the disk image is automatically detected unless you
285           specify it by using the --format option.
286
287           In the case where the guest contains multiple kernels, the one with
288           the highest version number is chosen.  To extract arbitrary kernels
289           from the disk image, see guestfish(1).  To extract the entire /boot
290           directory of a guest, see virt-copy-out(1).
291
292       --gpg GPG
293           Specify an alternate gpg(1) (GNU Privacy Guard) binary.  By default
294           virt-builder looks for either "gpg2" or "gpg" in the $PATH.
295
296           You can also use this to add gpg parameters, for example to specify
297           an alternate home directory:
298
299            virt-builder --gpg "gpg --homedir /tmp" [...]
300
301       -l [os-version]
302       --list [os-version]
303       --list --list-format format [os-version]
304       --list --long [os-version]
305           List all the available templates if no guest is specified, or only
306           for the specified one.
307
308           It is possible to choose with --list-format the output format for
309           the list templates:
310
311           short
312               The default format, prints only the template identifier and,
313               next to it, its short description.
314
315           long
316               Prints a textual list with the details of the available
317               sources, followed by the details of the available templates.
318
319           json
320               Prints a JSON object with the details of the available sources
321               and the details of the available templates.
322
323               The "version" key in the main object represents the
324               "compatibility version", and it is bumped every time the
325               resulting JSON output is incompatible with the previous
326               versions (for example the structure has changed, or non-
327               optional keys are no more present).
328
329           --long is a shorthand for the "long" format.
330
331           See also: --source, --notes, "SOURCES OF TEMPLATES".
332
333       --machine-readable
334       --machine-readable=format
335           This option is used to make the output more machine friendly when
336           being parsed by other programs.  See "MACHINE READABLE OUTPUT"
337           below.
338
339       -m MB
340       --memsize MB
341           Change the amount of memory allocated to --run scripts.  Increase
342           this if you find that --run scripts or the --install option are
343           running out of memory.
344
345           The default can be found with this command:
346
347            guestfish get-memsize
348
349       --network
350       --no-network
351           Enable or disable network access from the guest during the
352           installation.
353
354           Enabled is the default.  Use --no-network to disable access.
355
356           The network only allows outgoing connections and has other minor
357           limitations.  See "NETWORK" in virt-rescue(1).
358
359           If you use --no-network then certain other options such as
360           --install will not work.
361
362           This does not affect whether the guest can access the network once
363           it has been booted, because that is controlled by your hypervisor
364           or cloud environment and has nothing to do with virt-builder.
365
366           Generally speaking you should not use --no-network.  But here are
367           some reasons why you might want to:
368
369           1.  Because the libguestfs backend that you are using doesn't
370               support the network.  (See: "BACKEND" in guestfs(3)).
371
372           2.  Any software you need to install comes from an attached ISO, so
373               you don't need the network.
374
375           3.  You don’t want untrusted guest code trying to access your host
376               network when running virt-builder.  This is particularly an
377               issue when you don't trust the source of the operating system
378               templates.  (See "SECURITY" below).
379
380           4.  You don’t have a host network (eg. in secure/restricted
381               environments).
382
383       --no-sync
384           Do not sync the output file on exit.
385
386           Virt-builder "fsync"s the output file or disk image when it exits.
387
388           The reason is that qemu/KVM’s default caching mode is "none" or
389           "directsync", both of which bypass the host page cache.  Therefore
390           these would not work correctly if you immediately started the guest
391           after running virt-builder - they would not see the complete output
392           file.  (Note that you should not use these caching modes - they are
393           fundamentally broken for this and other reasons.)
394
395           If you are not using these broken caching modes, you can use
396           --no-sync to avoid this unnecessary sync and gain considerable
397           extra performance.
398
399       --notes os-version
400           List any notes associated with this guest, then exit (this does not
401           do the install).
402
403       -o filename
404       --output filename
405           Write the output to filename.  If you don’t specify this option,
406           then the output filename is generated by taking the "os-version"
407           string and adding ".img" (for raw format) or ".qcow2" (for qcow2
408           format).
409
410           Note that the output filename could be a device, partition or
411           logical volume.
412
413           When used with --get-kernel, this option specifies the output
414           directory.
415
416       --print-cache
417           Print information about the template cache.  See "CACHING".
418
419       -q
420       --quiet
421           Don’t print ordinary progress messages.
422
423       --size SIZE
424           Select the size of the output disk, where the size can be specified
425           using common names such as "32G" (32 gigabytes) etc.
426
427           Virt-builder will resize filesystems inside the disk image
428           automatically.
429
430           If the size is not specified, then one of two things happens.  If
431           the output is a file, then the size is the same as the template.
432           If the output is a device, partition, etc then the size of that
433           device is used.
434
435           To specify size in bytes, the number must be followed by the
436           lowercase letter b, eg: "--size 10737418240b".
437
438       --smp N
439           Enable N ≥ 2 virtual CPUs for --run scripts to use.
440
441       --source URL
442           Set the source URL to look for indexes.
443
444           You can give this option multiple times to specify multiple
445           sources.
446
447           See also "SOURCES OF TEMPLATES" below.
448
449           Note that you should not point --source to sources that you don’t
450           trust (unless the source is signed by someone you do trust).  See
451           also the --no-network option.
452
453       --no-warn-if-partition
454           Do not emit a warning if the output device is a partition.  This
455           warning avoids a common user error when writing to a USB key or
456           external drive, when you should normally write to the whole device
457           (--output /dev/sdX), not to a partition on the device
458           (--output /dev/sdX1).  Use this option to suppress this warning.
459
460       -v
461       --verbose
462           Enable debug messages and/or produce verbose output.
463
464           When reporting bugs, use this option and attach the complete output
465           to your bug report.
466
467       -V
468       --version
469           Display version number and exit.
470
471       --wrap
472           Wrap error, warning, and informative messages.  This is the default
473           when the output is a tty.  If the output of the program is
474           redirected to a file, wrapping is disabled unless you use this
475           option.
476
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       --no-selinux-relabel
646           Do not attempt to correct the SELinux labels of files in the guest.
647
648           In such guests that support SELinux, customization automatically
649           relabels files so that they have the correct SELinux label.  (The
650           relabeling is performed immediately, but if the operation fails,
651           customization will instead touch /.autorelabel on the image to
652           schedule a relabel operation for the next time the image boots.)
653           This option disables the automatic relabeling.
654
655           The option is a no-op for guests that do not support SELinux.
656
657       --password USER:SELECTOR
658           Set the password for "USER".  (Note this option does not create the
659           user account).
660
661           See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
662           and also how to set up user accounts.
663
664       --password-crypto md5|sha256|sha512
665           When the virt tools change or set a password in the guest, this
666           option sets the password encryption of that password to "md5",
667           "sha256" or "sha512".
668
669           "sha256" and "sha512" require glibc ≥ 2.7 (check crypt(3) inside
670           the guest).
671
672           "md5" will work with relatively old Linux guests (eg. RHEL 3), but
673           is not secure against modern attacks.
674
675           The default is "sha512" unless libguestfs detects an old guest that
676           didn't have support for SHA-512, in which case it will use "md5".
677           You can override libguestfs by specifying this option.
678
679           Note this does not change the default password encryption used by
680           the guest when you create new user accounts inside the guest.  If
681           you want to do that, then you should use the --edit option to
682           modify "/etc/sysconfig/authconfig" (Fedora, RHEL) or
683           "/etc/pam.d/common-password" (Debian, Ubuntu).
684
685       --root-password SELECTOR
686           Set the root password.
687
688           See "USERS AND PASSWORDS" for the format of the "SELECTOR" field,
689           and also how to set up user accounts.
690
691           Note: In virt-builder, if you don't set --root-password then the
692           guest is given a random root password.
693
694       --run SCRIPT
695           Run the shell script (or any program) called "SCRIPT" on the disk
696           image.  The script runs virtualized inside a small appliance,
697           chrooted into the guest filesystem.
698
699           The script is automatically chmod +x.
700
701           If libguestfs supports it then a limited network connection is
702           available but it only allows outgoing network connections.  You can
703           also attach data disks (eg. ISO files) as another way to provide
704           data (eg. software packages) to the script without needing a
705           network connection (--attach).  You can also upload data files
706           (--upload).
707
708           You can have multiple --run options.  They run in the same order
709           that they appear on the command line.
710
711           See also: --firstboot, --attach, --upload.
712
713       --run-command 'CMD+ARGS'
714           Run the command and arguments on the disk image.  The command runs
715           virtualized inside a small appliance, chrooted into the guest
716           filesystem.
717
718           If libguestfs supports it then a limited network connection is
719           available but it only allows outgoing network connections.  You can
720           also attach data disks (eg. ISO files) as another way to provide
721           data (eg. software packages) to the script without needing a
722           network connection (--attach).  You can also upload data files
723           (--upload).
724
725           You can have multiple --run-command options.  They run in the same
726           order that they appear on the command line.
727
728           See also: --firstboot, --attach, --upload.
729
730       --scrub FILE
731           Scrub a file from the guest.  This is like --delete except that:
732
733           •   It scrubs the data so a guest could not recover it.
734
735           •   It cannot delete directories, only regular files.
736
737       --selinux-relabel
738           This is a compatibility option that does nothing.
739
740       --sm-attach SELECTOR
741           Attach to a pool using "subscription-manager".
742
743           See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
744
745       --sm-credentials SELECTOR
746           Set the credentials for "subscription-manager".
747
748           See "SUBSCRIPTION-MANAGER" for the format of the "SELECTOR" field.
749
750       --sm-register
751           Register the guest using "subscription-manager".
752
753           This requires credentials being set using --sm-credentials.
754
755       --sm-remove
756           Remove all the subscriptions from the guest using
757           "subscription-manager".
758
759       --sm-unregister
760           Unregister the guest using "subscription-manager".
761
762       --ssh-inject USER[:SELECTOR]
763           Inject an ssh key so the given "USER" will be able to log in over
764           ssh without supplying a password.  The "USER" must exist already in
765           the guest.
766
767           See "SSH KEYS" for the format of the "SELECTOR" field.
768
769           You can have multiple --ssh-inject options, for different users and
770           also for more keys for each user.
771
772       --timezone TIMEZONE
773           Set the default timezone of the guest to "TIMEZONE".  Use a
774           location string like "Europe/London"
775
776       --touch FILE
777           This command performs a touch(1)-like operation on "FILE".
778
779       --truncate FILE
780           This command truncates "FILE" to a zero-length file. The file must
781           exist already.
782
783       --truncate-recursive PATH
784           This command recursively truncates all files under "PATH" to zero-
785           length.
786
787       --uninstall PKG,PKG..
788           Uninstall the named packages (a comma-separated list).  These are
789           removed during the image build using the guest’s package manager
790           (eg. apt, yum, etc.).  Dependent packages may also need to be
791           uninstalled to satisfy the request.
792
793           See also --install, --update.
794
795       --update
796           Do the equivalent of "yum update", "apt-get upgrade", or whatever
797           command is required to update the packages already installed in the
798           template to their latest versions.
799
800           See also --install, --uninstall.
801
802       --upload FILE:DEST
803           Upload local file "FILE" to destination "DEST" in the disk image.
804           File owner and permissions from the original are preserved, so you
805           should set them to what you want them to be in the disk image.
806
807           "DEST" could be the final filename.  This can be used to rename the
808           file on upload.
809
810           If "DEST" is a directory name (which must already exist in the
811           guest) then the file is uploaded into that directory, and it keeps
812           the same name as on the local filesystem.
813
814           See also: --mkdir, --delete, --scrub.
815
816       --write FILE:CONTENT
817           Write "CONTENT" to "FILE".
818

REFERENCE

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

MACHINE READABLE OUTPUT

1874       The --machine-readable option can be used to make the output more
1875       machine friendly, which is useful when calling virt-builder from other
1876       programs, GUIs etc.
1877
1878       Use the option on its own to query the capabilities of the virt-builder
1879       binary.  Typical output looks like this:
1880
1881        $ virt-builder --machine-readable
1882        virt-builder
1883        arch
1884        config-file
1885        customize
1886        json-list
1887        pxzcat
1888
1889       A list of features is printed, one per line, and the program exits with
1890       status 0.
1891
1892       It is possible to specify a format string for controlling the output;
1893       see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
1894

ENVIRONMENT VARIABLES

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

EXIT STATUS

1946       This program returns 0 if successful, or non-zero if there was an
1947       error.
1948

SEE ALSO

1950       guestfs(3), guestfish(1), guestmount(1), virt-builder-repository(1),
1951       virt-copy-out(1), virt-customize(1), virt-get-kernel(1),
1952       virt-install(1), virt-rescue(1), virt-resize(1), virt-sysprep(1),
1953       oz-install(1), gpg(1), gpg2(1), curl(1), virt-make-fs(1),
1954       genisoimage(1), http://libguestfs.org/.
1955

AUTHOR

1957       Richard W.M. Jones http://people.redhat.com/~rjones/
1958
1960       Copyright (C) 2013 Red Hat Inc.
1961

LICENSE

1963       This program is free software; you can redistribute it and/or modify it
1964       under the terms of the GNU General Public License as published by the
1965       Free Software Foundation; either version 2 of the License, or (at your
1966       option) any later version.
1967
1968       This program is distributed in the hope that it will be useful, but
1969       WITHOUT ANY WARRANTY; without even the implied warranty of
1970       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1971       General Public License for more details.
1972
1973       You should have received a copy of the GNU General Public License along
1974       with this program; if not, write to the Free Software Foundation, Inc.,
1975       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
1976

BUGS

1978       To get a list of bugs against libguestfs, use this link:
1979       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
1980
1981       To report a new bug against libguestfs, use this link:
1982       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1983
1984       When reporting a bug, please supply:
1985
1986       •   The version of libguestfs.
1987
1988       •   Where you got libguestfs (eg. which Linux distro, compiled from
1989           source, etc)
1990
1991       •   Describe the bug accurately and give a way to reproduce it.
1992
1993       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
1994           into the bug report.
1995
1996
1997
1998guestfs-tools-1.49.7              2022-12-10                   virt-builder(1)
Impressum