1virt-builder-repository(1) Virtualization Support virt-builder-repository(1)
2
6 virt-builder-repository - Build virt-builder source repository easily
7
9 virt-builder-repository /path/to/repository
10 [-i|--interactive] [--gpg-key KEYID]
11
13 Virt-builder is a tool for quickly building new virtual machines. It
14 can be configured to use template repositories. However creating and
15 maintaining a repository involves many tasks which can be automated.
16 virt-builder-repository is a tool helping to manage these repositories.
17 Virt-builder-repository loops over the files in the directory specified
19 as argument, compresses the files with a name ending by "qcow2", "raw",
20 "img" or without extension, extracts data from them and creates or
21 updates the "index" file.
22 Some of the image-related data needed for the index file can’t be
24 computed from the image file. virt-builder-repository first tries to
25 find them in the existing index file. If data are still missing after
26 this, they are prompted in interactive mode, otherwise an error will be
27 triggered.
28 If a "KEYID" is provided, the generated index file will be signed with
30 this GPG key.
31
33 Create the initial repository
34 Create a folder and copy the disk image template files in it. Then run
35 a command like the following one:
36 virt-builder-repository --gpg-key "joe@hacker.org" -i /path/to/folder
38 Note that this example command runs in interactive mode. To run in
40 automated mode, a minimal index file needs to be created before running
41 the command containing sections like this one:
42 [template_id]
44 file=template_filename.qcow.xz
45 The file value needs to match the image name extended with the ".xz"
47 suffix if the --no-compression parameter is not provided or the image
48 name if no compression is involved. Other optional data can be
49 prefilled. Default values are computed by inspecting the disk image.
50 For more informations, see "Creating and signing the index file" in
51 virt-builder(1).
52 Update images in an existing repository
54 In this use case, a new image or a new revision of an existing image
55 needs to be added to the repository. Place the corresponding image
56 template files in the repository folder.
57 To update the revision of an image, the file needs to have the same
59 name than the existing one (without the "xz" extension).
60 As in the repository creation use case, a minimal fragment can be added
62 to the index file for the automated mode. This can be done on the
63 signed index even if it may sound a strange idea: the index will be
64 signed again by the tool.
65 To remove an image from the repository, just remove the corresponding
67 image file before running virt-builder-repository.
68 Then running the following command will complete and update the index
70 file:
71 virt-builder-repository --gpg-key "joe@hacker.org" -i /path/to/folder
73 virt-builder-repository works in a temporary folder inside the
75 repository one. If anything wrong happens when running the tool, the
76 repository is left untouched.
77
79 --help
80 Display help.
81 --gpg GPG
83 Specify an alternate gpg(1) (GNU Privacy Guard) binary. You can
84 also use this to add gpg parameters, for example to specify an
85 alternate home directory:
86 virt-builder-repository --gpg "gpg --homedir /tmp" [...]
88 This can also be used to avoid gpg asking for the key passphrase:
90 virt-builder-repository --gpg "gpg --passphrase-file /tmp/pass --batch" [...]
92 -K KEYID
94 --gpg-key KEYID
95 Specify the GPG key to be used to sign the repository index file.
96 If not provided, the index will left unsigned. "KEYID" is used to
97 identify the GPG key to use. This value is passed to gpg’s
98 --default-key option and can thus be an email address or a
99 fingerprint.
100 NOTE: by default, virt-builder-repository searches for the key in
102 the user’s GPG keyring.
103 -i
105 --interactive
106 Prompt for missing data. Default values are computed from the disk
107 image.
108 When prompted for data, inputting "-" corresponds to leaving the
110 value empty. This can be used to avoid setting the default computed
111 value.
112 --no-compression
114 Don’t compress the template images.
115 --machine-readable
117 --machine-readable=format
118 This option is used to make the output more machine friendly when
119 being parsed by other programs. See "MACHINE READABLE OUTPUT"
120 below.
121 --colors
123 --colours
124 Use ANSI colour sequences to colourize messages. This is the
125 default when the output is a tty. If the output of the program is
126 redirected to a file, ANSI colour sequences are disabled unless you
127 use this option.
128 -q
130 --quiet
131 Don’t print ordinary progress messages.
132 -v
134 --verbose
135 Enable debug messages and/or produce verbose output.
136 When reporting bugs, use this option and attach the complete output
138 to your bug report.
139 -V
141 --version
142 Display version number and exit.
143 -x Enable tracing of libguestfs API calls.
145
147 The --machine-readable option can be used to make the output more
148 machine friendly, which is useful when calling virt-builder-repository
149 from other programs, GUIs etc.
150 Use the option on its own to query the capabilities of the virt-
152 builder-repository binary. Typical output looks like this:
153 $ virt-builder-repository --machine-readable
155 virt-builder-repository
156 A list of features is printed, one per line, and the program exits with
158 status 0.
159 It is possible to specify a format string for controlling the output;
161 see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
162
164 This program returns 0 if successful, or non-zero if there was an
165 error.
166
168 virt-builder(1) http://libguestfs.org/.
169
171 Cédric Bosdonnat mailto:cbosdonnat@suse.com
172
174 Copyright (C) 2016-2020 SUSE Inc.
175
177 This program is free software; you can redistribute it and/or modify it
178 under the terms of the GNU General Public License as published by the
179 Free Software Foundation; either version 2 of the License, or (at your
180 option) any later version.
181 This program is distributed in the hope that it will be useful, but
183 WITHOUT ANY WARRANTY; without even the implied warranty of
184 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
185 General Public License for more details.
186 You should have received a copy of the GNU General Public License along
188 with this program; if not, write to the Free Software Foundation, Inc.,
189 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
190
192 To get a list of bugs against libguestfs, use this link:
193 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
194 To report a new bug against libguestfs, use this link:
196 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
197 When reporting a bug, please supply:
199 • The version of libguestfs.
201 • Where you got libguestfs (eg. which Linux distro, compiled from
203 source, etc)
204 • Describe the bug accurately and give a way to reproduce it.
206 • Run libguestfs-test-tool(1) and paste the complete, unedited output
208 into the bug report.
209guestfs-tools-1.47.2 2021-07-22 virt-builder-repository(1)