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 --wrap
145 Wrap error, warning, and informative messages. This is the default
146 when the output is a tty. If the output of the program is
147 redirected to a file, wrapping is disabled unless you use this
148 option.
149 -x Enable tracing of libguestfs API calls.
151
153 The --machine-readable option can be used to make the output more
154 machine friendly, which is useful when calling virt-builder-repository
155 from other programs, GUIs etc.
156 Use the option on its own to query the capabilities of the virt-
158 builder-repository binary. Typical output looks like this:
159 $ virt-builder-repository --machine-readable
161 virt-builder-repository
162 A list of features is printed, one per line, and the program exits with
164 status 0.
165 It is possible to specify a format string for controlling the output;
167 see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
168
170 This program returns 0 if successful, or non-zero if there was an
171 error.
172
174 virt-builder(1) http://libguestfs.org/.
175
177 Cédric Bosdonnat mailto:cbosdonnat@suse.com
178
180 Copyright (C) 2016-2020 SUSE Inc.
181
183 This program is free software; you can redistribute it and/or modify it
184 under the terms of the GNU General Public License as published by the
185 Free Software Foundation; either version 2 of the License, or (at your
186 option) any later version.
187 This program is distributed in the hope that it will be useful, but
189 WITHOUT ANY WARRANTY; without even the implied warranty of
190 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
191 General Public License for more details.
192 You should have received a copy of the GNU General Public License along
194 with this program; if not, write to the Free Software Foundation, Inc.,
195 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
196
198 To get a list of bugs against libguestfs, use this link:
199 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
200 To report a new bug against libguestfs, use this link:
202 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
203 When reporting a bug, please supply:
205 • The version of libguestfs.
207 • Where you got libguestfs (eg. which Linux distro, compiled from
209 source, etc)
210 • Describe the bug accurately and give a way to reproduce it.
212 • Run libguestfs-test-tool(1) and paste the complete, unedited output
214 into the bug report.
215guestfs-tools-1.48.2 2022-05-26 virt-builder-repository(1)