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