1LORAX(1) Lorax LORAX(1)
2
6 lorax - Lorax Documentation
7 Authors
9 Brian C. Lane <bcl@redhat.com>
10 "I am the Lorax. I speak for the trees [and images]."
12 The lorax tool is used to create the Anaconda installer boot.iso as
14 well as the basic release tree, and .treeinfo metadata file. Its depen‐
15 dencies are fairly light-weight because it needs to be able to run in a
16 mock chroot environment. It is best to run lorax from the same release
17 as is being targeted because the templates may have release specific
18 logic in them. eg. Use the rawhide version to build the boot.iso for
19 rawhide, along with the rawhide repositories.
20
22 Create the Anaconda boot.iso
23 usage: lorax [-h] -p PRODUCT -v VERSION -r RELEASE [-s REPOSITORY] [--repo REPOSITORY] [-m REPOSITORY]
26 [-t VARIANT] [-b URL] [--isfinal] [-c CONFIGFILE] [--proxy HOST] [-i PACKAGE] [-e PACKAGE]
27 [--buildarch ARCH] [--volid VOLID] [--macboot] [--nomacboot] [--noupgrade]
28 [--logfile LOGFILE] [--tmp TMP] [--cachedir CACHEDIR] [--workdir WORKDIR] [--force]
29 [--add-template ADD_TEMPLATES] [--add-template-var ADD_TEMPLATE_VARS]
30 [--add-arch-template ADD_ARCH_TEMPLATES] [--add-arch-template-var ADD_ARCH_TEMPLATE_VARS]
31 [--noverify] [--sharedir SHAREDIR] [--enablerepo [repo]] [--disablerepo [repo]]
32 [--rootfs-size ROOTFS_SIZE] [--noverifyssl] [--dnfplugin DNFPLUGINS] [--squashfs-only]
33 [--skip-branding] [--dracut-conf DRACUT_CONF] [--dracut-arg DRACUT_ARGS] [-V]
34 OUTPUTDIR
35 Positional Arguments
37 OUTPUTDIR
38 Output directory
39 options
41 -V show program's version number and exit
42 required arguments
44 -p, --product
45 product name
46 -v, --version
48 version identifier
49 -r, --release
51 release information
52 -s, --source
54 source repository (may be listed multiple times)
55 Default: []
57 --repo source dnf repository file
59 Default: []
61 Named Arguments
63 -m, --mirrorlist
64 mirrorlist repository (may be listed multiple times)
65 Default: []
67 -t, --variant
69 variant name
70 Default: ""
72 -b, --bugurl
74 bug reporting URL for the product
75 Default: "your distribution provided bug reporting tool"
77 --isfinal
79 Default: False
80 -c, --config
82 config file
83 Default: "/etc/lorax/lorax.conf"
85 --proxy
87 repo proxy url:port
88 -i, --installpkgs
90 package glob to install before runtime-install.tmpl runs. (may
91 be listed multiple times)
92 Default: []
94 -e, --excludepkgs
96 package glob to remove before runtime-install.tmpl runs. (may be
97 listed multiple times)
98 Default: []
100 --buildarch
102 build architecture
103 --volid
105 volume id
106 --macboot
108 Make the iso bootable on UEFI based Mac systems
109 Default: True
111 --nomacboot
113 Do not create a Mac bootable iso
114 Default: False
116 --noupgrade
118 Default: True
119 --logfile
121 Path to logfile
122 Default: ./lorax.log
124 --tmp Top level temporary directory
126 Default: "/var/tmp/lorax"
128 --cachedir
130 DNF cache directory. Default is a temporary dir.
131 --workdir
133 Work directory, overrides --tmp. Default is a temporary dir un‐
134 der /var/tmp/lorax
135 --force
137 Run even when the destination directory exists
138 Default: False
140 --add-template
142 Additional template for runtime image
143 Default: []
145 --add-template-var
147 Set variable for runtime image template
148 Default: []
150 --add-arch-template
152 Additional template for architecture-specific image
153 Default: []
155 --add-arch-template-var
157 Set variable for architecture-specific image
158 Default: []
160 --noverify
162 Do not verify the install root
163 Default: True
165 --sharedir
167 Directory containing all the templates. Overrides config file
168 sharedir
169 --enablerepo
171 Names of repos to enable
172 Default: []
174 --disablerepo
176 Names of repos to disable
177 Default: []
179 --rootfs-size
181 Size of root filesystem in GiB. Defaults to 2.
182 Default: 2
184 --noverifyssl
186 Do not verify SSL certificates
187 Default: False
189 --dnfplugin
191 Enable a DNF plugin by name/glob, or * to enable all of them.
192 Default: []
194 --squashfs-only
196 Use a plain squashfs filesystem for the runtime.
197 Default: False
199 --skip-branding
201 Disable automatic branding package selection. Use --installpkgs
202 to add custom branding.
203 Default: False
205 dracut arguments: (default: )
207 --dracut-conf
208 Path to a dracut.conf file to use instead of the default argu‐
209 ments. See the dracut.conf(5) manpage.
210 --dracut-arg
212 Argument to pass to dracut when rebuilding the initramfs. Pass
213 this once for each argument. NOTE: this overrides the defaults.
214
216 Run this as root to create a boot.iso in ./results/:
217 dnf install lorax
219 setenforce 0
220 lorax -p Fedora -v 23 -r 23 \
221 -s http://dl.fedoraproject.org/pub/fedora/linux/releases/23/Everything/x86_64/os/ \
222 -s http://dl.fedoraproject.org/pub/fedora/linux/updates/23/x86_64/ \
223 ./results/
224 setenforce 1
225 You can add your own repos with -s and packages with higher NVRs will
227 override the ones in the distribution repositories.
228 Under ./results/ will be the release tree files: .discinfo, .treeinfo,
230 everything that goes onto the boot.iso, the pxeboot directory, and the
231 boot.iso under ./results/images/.
232
234 By default lorax will search for the first package that provides sys‐
235 tem-release that doesn't start with generic- and will install it. It
236 then selects a corresponding logo package by using the first part of
237 the system-release package and appending -logos to it. eg. fedora-re‐
238 lease and fedora-logos.
239 Variants
241 If a variant is passed to lorax it will select a system-release package
242 that ends with the variant name. eg. Passing --variant workstation will
243 select the fedora-release-workstation package if it exists. It will se‐
244 lect a logo package the same way it does for non-variants. eg. fe‐
245 dora-logos.
246 If there is no package ending with the variant name it will fall back
248 to using the first non-generic package providing system-release.
249 Custom Branding
251 If --skip-branding is passed to lorax it will skip selecting the sys‐
252 tem-release, and logos packages and leave it up to the user to pass any
253 branding related packages to lorax using --installpkgs. When using
254 skip-branding you must make sure that you provide all of the expected
255 files, otherwise Anaconda may not work as expected. See the contents of
256 fedora-release and fedora-logos for examples of what to include.
257 Note that this does not prevent something else in the dependency tree
259 from causing these packages to be included. Using --excludepkgs may
260 help if they are unexpectedly included.
261
263 As of mock version 2.0 you no longer need to pass --old-chroot. You
264 will, however, need to pass --enable-network so that the mock container
265 can download packages.
266 Older versions of mock, between 1.3.4 and 2.0, will need to pass
268 --old-chroot to mock. These versions of mock default to using sys‐
269 temd-nspawn which cannot create the needed loop device nodes. Passing
270 --old-chroot will use the old system where /dev/loop* is setup for you.
271
273 Lorax uses dnf to install packages into a temporary directory, sets up
274 configuration files, it then removes unneeded files to save space, and
275 creates a squashfs filesystem of the files. The iso is then built us‐
276 ing a generic initramfs and the kernel from the selected repositories.
277 To drive these processes Lorax uses a custom template system, based on
279 Mako templates with the addition of custom commands (documented in
280 pylorax.ltmpl.LoraxTemplateRunner). Mako supports %if/%endif blocks as
281 well as free-form python code inside <% %> tags and variable substitu‐
282 tion with ${}. The default templates are shipped with lorax in
283 /usr/share/lorax/templates.d/99-generic/ and use the .tmpl extension.
284 runtime-install.tmpl
286 The runtime-install.tmpl template lists packages to be installed using
287 the installpkg command. This template is fairly simple, installing
288 common packages and architecture specific packages. It must end with
289 the run_pkg_transaction command which tells dnf to download and install
290 the packages.
291 runtime-postinstall.tmpl
293 The runtime-postinstall.tmpl template is where the system configuration
294 happens. The installer environment is similar to a normal running sys‐
295 tem, but needs some special handling. Configuration files are setup,
296 systemd is told to start the anaconda.target instead of a default sys‐
297 tem target, and a number of unneeded services are disabled, some of
298 which can interfere with the installation. A number of template com‐
299 mands are used here:
300 • append to add text to a file.
302 • chmod changes the file's mode.
304 • install to install a file into the installroot.
306 • mkdir makes a new directory.
308 • move to move a file into the installroot
310 • replace does text substitution in a file
312 • remove deletes a file
314 • runcmd run arbitrary commands.
316 • symlink creates a symlink
318 • systemctl runs systemctl in the installroot
320 runtime-cleanup.tmpl
322 The runtime-cleanup.tmpl template is used to remove files that aren't
323 strictly needed by the installation environment. In addition to the re‐
324 move template command it uses:
325 • removepkg remove all of a specific package's contents. A package may
327 be pulled in as a dependency, but not really used. eg. sound support.
328 • removefrom Removes some files from a package. A file glob can be
330 used, or the --allbut option to remove everything except a select
331 few.
332 • removekmod Removes kernel modules
334 The squashfs filesystem
336 After runtime-*.tmpl templates have finished their work lorax creates
337 an empty ext4 filesystem, copies the remaining files to it, and makes a
338 squashfs filesystem of it. This file is the / of the boot.iso's in‐
339 staller environment and is what is in the LiveOS/squashfs.img file on
340 the iso.
341 iso creation
343 The iso creation is handled by another set of templates. The one used
344 depends on the architecture that the iso is being created for. They are
345 also stored in /usr/share/lorax/templates.d/99-generic and are named
346 after the arch, like x86.tmpl and aarch64.tmpl. They handle creation of
347 the tree, copying configuration template files, configuration variable
348 substitution, treeinfo metadata (via the treeinfo template command).
349 Kernel and initrd are copied from the installroot to their final loca‐
350 tions and then xorrisofs is run to create the boot.iso
351
353 The default set of templates and configuration files from the lo‐
354 rax-generic-templates package are shipped in the /usr/share/lorax/tem‐
355 plates.d/99-generic/ directory. You can make a copy of them and place
356 them into another directory under templates.d and they will be used in‐
357 stead if their sort order is below all other directories. This allows
358 multiple packages to ship lorax templates without conflict. You can
359 (and probably should) select the specific template directory by passing
360 --sharedir to lorax.
361
363 Weldr Team
364
366 2018, Red Hat, Inc.
36737.1 May 11, 2022 LORAX(1)