1LORAX-COMPOSER(1) Lorax LORAX-COMPOSER(1)
2
3
4
6 lorax-composer - Lorax Composer Documentation
7
8 Authors
9 Brian C. Lane <bcl@redhat.com>
10
11 lorax-composer is an API server that allows you to build disk images
12 using Blueprints to describe the package versions to be installed into
13 the image. It is compatible with the Weldr project's bdcs-api REST
14 protocol. More information on Weldr can be found on the Weldr blog.
15
16 Behind the scenes it uses livemedia-creator and Anaconda to handle the
17 installation and configuration of the images.
18
20 · As of version 30.7 SELinux can be set to Enforcing. The current state
21 is logged for debugging purposes and if there are SELinux denials
22 they should be reported as a bug.
23
24 · All image types lock the root account, except for live-iso. You will
25 need to either use one of the Customizations methods for setting a
26 ssh key/password, install a package that creates a user, or use some‐
27 thing like cloud-init to setup access at boot time.
28
30 The best way to install lorax-composer is to use sudo dnf install
31 lorax-composer composer-cli, this will setup the weldr user and install
32 the systemd socket activation service. You will then need to enable it
33 with sudo systemctl enable lorax-composer.socket && sudo systemctl
34 start lorax-composer.socket. This will leave the server off until the
35 first request is made. Systemd will then launch the server and it will
36 remain running until the system is rebooted. This will cause some delay
37 in responding to the first request from the UI or composer-cli.
38
39 NOTE:
40 If you want lorax-composer to respond immediately to the first
41 request you can start and enable lorax-composer.service instead of
42 lorax-composer.socket
43
45 1. Create a weldr user and group by running useradd weldr
46
47 2. Remove any pre-existing socket directory with rm -rf /run/weldr/ A
48 new directory with correct permissions will be created the first
49 time the server runs.
50
51 3. Enable the socket activation with systemctl enable lorax-com‐
52 poser.socket && sudo systemctl start lorax-composer.socket.
53
54 NOTE: You can also run it directly with lorax-composer /path/to/blue‐
55 prints. However, lorax-composer does not react well to being started
56 both on the command line and via socket activation at the same time.
57 It is therefore recommended that you run it directly on the command
58 line only for testing or development purposes. For real use or devel‐
59 opment of other projects that simply use the API, you should stick to
60 socket activation only.
61
62 The /path/to/blueprints/ directory is where the blueprints' git repo
63 will be created, and all the blueprints created with the /api/v0/blue‐
64 prints/new route will be stored. If there are blueprint .toml files in
65 the top level of the directory they will be imported into the blueprint
66 git storage when lorax-composer starts.
67
69 Logs are stored under /var/log/lorax-composer/ and include all console
70 messages as well as extra debugging info and API requests.
71
73 Some security related issues that you should be aware of before running
74 lorax-composer:
75
76 · One of the API server threads needs to retain root privileges in
77 order to run Anaconda.
78
79 · Only allow authorized users access to the weldr group and socket.
80
81 Since Anaconda kickstarts are used there is the possibility that a user
82 could inject commands into a blueprint that would result in the kick‐
83 start executing arbitrary code on the host. Only authorized users
84 should be allowed to build images using lorax-composer.
85
87 Lorax Composer API Server
88
89
90 usage: lorax-composer [-h] [--socket SOCKET] [--user USER] [--group GROUP]
91 [--log LOG] [--mockfiles MOCKFILES]
92 [--sharedir SHAREDIR] [-V] [-c CONFIG]
93 [--releasever STRING] [--tmp TMP] [--proxy PROXY]
94 [--no-system-repos]
95 BLUEPRINTS
96
97 Positional Arguments
98 Path to the blueprints
99
100 Named Arguments
101 -socket
102 Path to the socket file to listen on
103
104 Default: "/run/weldr/api.socket"
105
106 -user User to use for reduced permissions
107
108 Default: "weldr"
109
110 -group Group to set ownership of the socket to
111
112 Default: "weldr"
113
114 -log Path to logfile (/var/log/lorax-composer/composer.log)
115
116 Default: "/var/log/lorax-composer/composer.log"
117
118 -mockfiles
119 Path to JSON files used for /api/mock/ paths
120 (/var/tmp/bdcs-mockfiles/)
121
122 Default: "/var/tmp/bdcs-mockfiles/"
123
124 -sharedir
125 Directory containing all the templates. Overrides config file
126 sharedir
127
128 V show program's version number and exit
129
130 Default: False
131
132 c, --config
133 Path to lorax-composer configuration file.
134
135 Default: "/etc/lorax/composer.conf"
136
137 -releasever
138 Release version to use for $releasever in dnf repository urls
139
140 -tmp Top level temporary directory
141
142 Default: "/var/tmp"
143
144 -proxy Set proxy for DNF, overrides configuration file setting.
145
146 -no-system-repos
147 Do not copy over system repos from /etc/yum.repos.d/ at startup
148
149 Default: False
150
152 The server runs as root, and as weldr. Communication with it is via a
153 unix domain socket (/run/weldr/api.socket by default). The directory
154 and socket are owned by root:weldr so that any user in the weldr group
155 can use the API to control lorax-composer.
156
157 At startup the server will check for the correct permissions and owner‐
158 ship of a pre-existing directory, or it will create a new one if it
159 doesn't exist. The socket path and group owner's name can be changed
160 from the cmdline by passing it the --socket and --group arguments.
161
162 It will then drop root privileges for the API thread and run as the
163 weldr user. The queue and compose thread still runs as root because it
164 needs to be able to mount/umount files and run Anaconda.
165
167 The welder-web GUI project can be used to construct blueprints and cre‐
168 ate composes using a web browser.
169
170 Or use the command line with composer-cli.
171
173 Blueprints are simple text files in TOML format that describe which
174 packages, and what versions, to install into the image. They can also
175 define a limited set of customizations to make to the final image.
176
177 Example blueprints can be found in the lorax-composer test suite, with
178 a simple one looking like this:
179
180 name = "base"
181 description = "A base system with bash"
182 version = "0.0.1"
183
184 [[packages]]
185 name = "bash"
186 version = "4.4.*"
187
188 The name field is the name of the blueprint. It can contain spaces, but
189 they will be converted to - when it is written to disk. It should be
190 short and descriptive.
191
192 description can be a longer description of the blueprint, it is only
193 used for display purposes.
194
195 version is a semver compatible version number. If a new blueprint is
196 uploaded with the same version the server will automatically bump the
197 PATCH level of the version. If the version doesn't match it will be
198 used as is. eg. Uploading a blueprint with version set to 0.1.0 when
199 the existing blueprint version is 0.0.1 will result in the new blue‐
200 print being stored as version 0.1.0.
201
202 [[packages]] and [[modules]]
203 These entries describe the package names and matching version glob to
204 be installed into the image.
205
206 The names must match the names exactly, and the versions can be an
207 exact match or a filesystem-like glob of the version using * wildcards
208 and ? character matching.
209
210 NOTE: As of lorax-composer-29.2-1 the versions are not used for dep‐
211 solving, that is planned for a future release. And currently there are
212 no differences between packages and modules in lorax-composer.
213
214 [[groups]]
215 These entries describe a group of packages to be installed into the
216 image. Package groups are defined in the repository metadata. Each
217 group has a descriptive name used primarily for display in user inter‐
218 faces and an ID more commonly used in kickstart files. Here, the ID is
219 the expected way of listing a group.
220
221 Groups have three different ways of categorizing their packages:
222 mandatory, default, and optional. For purposes of blueprints, manda‐
223 tory and default packages will be installed. There is no mechanism for
224 selecting optional packages.
225
226 Customizations
227 The [[customizations]] section can be used to configure the hostname of
228 the final image. eg.:
229
230 [[customizations]]
231 hostname = "baseimage"
232
233 [[customizations.sshkey]]
234 Set an existing user's ssh key in the final image:
235
236 [[customizations.sshkey]]
237 user = "root"
238 key = "PUBLIC SSH KEY"
239
240 The key will be added to the user's authorized_keys file.
241
242 [[customizations.user]]
243 Add a user to the image, and/or set their ssh key. All fields for this
244 section are optional except for the name, here is a complete example:
245
246 [[customizations.user]]
247 name = "admin"
248 description = "Administrator account"
249 password = "$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L..."
250 key = "PUBLIC SSH KEY"
251 home = "/srv/widget/"
252 shell = "/usr/bin/bash"
253 groups = ["widget", "users", "wheel"]
254 uid = 1200
255 gid = 1200
256
257 If the password starts with $6$, $5$, or $2b$ it will be stored as an
258 encrypted password. Otherwise it will be treated as a plain text pass‐
259 word.
260
261 [[customizations.group]]
262 Add a group to the image. name is required and gid is optional:
263
264 [[customizations.group]]
265 name = "widget"
266 gid = 1130
267
269 livemedia-creator supports a large number of output types, and only
270 some of these are currently available via lorax-composer. To add a new
271 output type to lorax-composer a kickstart file needs to be added to
272 ./share/composer/. The name of the kickstart is what will be used by
273 the /compose/types route, and the compose_type field of the POST to
274 start a compose. It also needs to have code added to the pylo‐
275 rax.api.compose.compose_args() function. The _MAP entry in this func‐
276 tion defines what lorax-composer will pass to pylorax.install‐
277 er.novirt_install() when it runs the compose. When the compose is fin‐
278 ished the output files need to be copied out of the build directory
279 (/var/lib/lorax/composer/results/<UUID>/compose/), pylorax.api.com‐
280 pose.move_compose_results() handles this for each type. You should
281 move them instead of copying to save space.
282
283 If the new output type does not have support in livemedia-creator it
284 should be added there first. This will make the output available to the
285 widest number of users.
286
287 Example: Add partitioned disk support
288 Partitioned disk support is something that livemedia-creator already
289 supports via the --make-disk cmdline argument. To add this to
290 lorax-composer it needs 3 things:
291
292 · A partitioned-disk.ks file in ./share/composer/
293
294 · A new entry in the _MAP in pylorax.api.compose.compose_args()
295
296 · Add a bit of code to pylorax.api.compose.move_compose_results() to
297 move the disk image from the compose directory to the results direc‐
298 tory.
299
300 The partitioned-disk.ks is pretty similar to the example minimal kick‐
301 start in ./docs/fedora-minimal.ks. You should remove the url and repo
302 commands, they will be added by the compose process. Make sure the
303 bootloader packages are included in the %packages section at the end of
304 the kickstart, and you will want to leave off the %end so that the com‐
305 pose can append the list of packages from the blueprint.
306
307 The new _MAP entry should be a copy of one of the existing entries, but
308 with make_disk set to True. Make sure that none of the other make_*
309 options are True. The image_name is what the name of the final image
310 will be.
311
312 move_compose_results() can be as simple as moving the output file into
313 the results directory, or it could do some post-processing on it. The
314 end of the function should always clean up the ./compose/ directory,
315 removing any unneeded extra files. This is especially true for the
316 live-iso since it produces the contents of the iso as well as the
317 boot.iso itself.
318
320 By default lorax-composer uses the host's configured repositories. It
321 copies the *.repo files from /etc/yum.repos.d/ into /var/lib/lorax/com‐
322 poser/repos.d/ at startup, these are immutable system repositories and
323 cannot be deleted or changed. If you want to add additional repos you
324 can put them into /var/lib/lorax/composer/repos.d/ or use the
325 /api/v0/projects/source/* API routes to create them.
326
327 The new source can be added by doing a POST to the
328 /api/v0/projects/source/new route using JSON (with Content-Type header
329 set to application/json) or TOML (with it set to text/x-toml). The
330 format of the source looks like this (in TOML):
331
332 name = "custom-source-1"
333 url = "https://url/path/to/repository/"
334 type = "yum-baseurl"
335 proxy = "https://proxy-url/"
336 check_ssl = true
337 check_gpg = true
338 gpgkey_urls = ["https://url/path/to/gpg-key"]
339
340 The proxy and gpgkey_urls entries are optional. All of the others are
341 required. The supported types for the urls are:
342
343 · yum-baseurl is a URL to a yum repository.
344
345 · yum-mirrorlist is a URL for a mirrorlist.
346
347 · yum-metalink is a URL for a metalink.
348
349 If check_ssl is true the https certificates must be valid. If they are
350 self-signed you can either set this to false, or add your Certificate
351 Authority to the host system.
352
353 If check_gpg is true the GPG key must either be installed on the host
354 system, or gpgkey_urls should point to it.
355
356 You can edit an existing source (other than system sources), by doing a
357 POST to the new route with the new version of the source. It will over‐
358 write the previous one.
359
360 A list of existing sources is available from
361 /api/v0/projects/source/list, and detailed info on a source can be
362 retrieved with the /api/v0/projects/source/info/<source-name> route. By
363 default it returns JSON but it can also return TOML if ?format=toml is
364 added to the request.
365
366 Non-system sources can be deleted by doing a DELETE request to the
367 /api/v0/projects/source/delete/<source-name> route.
368
369 The documentation for the source API routes can be found here
370
371 The configured sources are used for all blueprint depsolve operations,
372 and for composing images. When adding additional sources you must make
373 sure that the packages in the source do not conflict with any other
374 package sources, otherwise depsolving will fail.
375
376 DVD ISO Package Source
377 In some situations the system may want to only use a DVD iso as the
378 package source, not the repos from the network. lorax-composer and ana‐
379 conda understand file:// URLs so you can mount an iso on the host, and
380 replace the system repo files with a configuration file pointing to the
381 DVD.
382
383 · Stop the lorax-composer.service if it is running
384
385 · Move the repo files in /etc/yum.repos.d/ someplace safe
386
387 · Create a new iso.repo file in /etc/yum.repos.d/:
388
389 [iso]
390 name=iso
391 baseurl=file:///mnt/iso/
392 enabled=1
393 gpgcheck=1
394 gpgkey=file:///mnt/iso/RPM-GPG-KEY-redhat-release
395
396 · Remove all the cached repo files from /var/lib/lorax/composer/repos/
397
398 · Restart the lorax-composer.service
399
400 · Check the output of composer-cli status show for any output specific
401 depsolve errors. For example, the DVD usually does not include
402 grub2-efi-*-cdboot-* so the live-iso image type will not be avail‐
403 able.
404
405 If you want to add the DVD source to the existing sources you can do
406 that by mounting the iso and creating a source file to point to it as
407 described in the Package Sources documentation. In that case there is
408 no need to remove the other sources from /etc/yum.repos.d/ or clear the
409 cached repos.
410
412 Weldr Team
413
415 2018, Red Hat, Inc.
416
417
418
419
42029.21 Nov 29, 2018 LORAX-COMPOSER(1)