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 Output directory
38 Named Arguments
40 V show program's version number and exit
41 required arguments
43 p, --product
44 product name
45 v, --version
47 version identifier
48 r, --release
50 release information
51 s, --source
53 source repository (may be listed multiple times)
54 Default: []
56 -repo source dnf repository file
58 Default: []
60 Named Arguments
62 m, --mirrorlist
63 mirrorlist repository (may be listed multiple times)
64 Default: []
66 t, --variant
68 variant name
69 Default: ""
71 b, --bugurl
73 bug reporting URL for the product
74 Default: "your distribution provided bug reporting tool"
76 -isfinal
78 Default: False
79 c, --config
81 config file
82 Default: "/etc/lorax/lorax.conf"
84 -proxy repo proxy url:port
86 i, --installpkgs
88 package glob to install before runtime-install.tmpl runs. (may
89 be listed multiple times)
90 Default: []
92 e, --excludepkgs
94 package glob to remove before runtime-install.tmpl runs. (may be
95 listed multiple times)
96 Default: []
98 -buildarch
100 build architecture
101 -volid volume id
103 -macboot
105 Make the iso bootable on UEFI based Mac systems
106 Default: True
108 -nomacboot
110 Do not create a Mac bootable iso
111 Default: False
113 -noupgrade
115 Default: True
116 -logfile
118 Path to logfile
119 Default: ./lorax.log
121 -tmp Top level temporary directory
123 Default: "/var/tmp/lorax"
125 -cachedir
127 DNF cache directory. Default is a temporary dir.
128 -workdir
130 Work directory, overrides --tmp. Default is a temporary dir un‐
131 der /var/tmp/lorax
132 -force Run even when the destination directory exists
134 Default: False
136 -add-template
138 Additional template for runtime image
139 Default: []
141 -add-template-var
143 Set variable for runtime image template
144 Default: []
146 -add-arch-template
148 Additional template for architecture-specific image
149 Default: []
151 -add-arch-template-var
153 Set variable for architecture-specific image
154 Default: []
156 -noverify
158 Do not verify the install root
159 Default: True
161 -sharedir
163 Directory containing all the templates. Overrides config file
164 sharedir
165 -enablerepo
167 Names of repos to enable
168 Default: []
170 -disablerepo
172 Names of repos to disable
173 Default: []
175 -rootfs-size
177 Size of root filesystem in GiB. Defaults to 2.
178 Default: 2
180 -noverifyssl
182 Do not verify SSL certificates
183 Default: False
185 -dnfplugin
187 Enable a DNF plugin by name/glob, or * to enable all of them.
188 Default: []
190 -squashfs-only
192 Use a plain squashfs filesystem for the runtime.
193 Default: False
195 -skip-branding
197 Disable automatic branding package selection. Use --installpkgs
198 to add custom branding.
199 Default: False
201 dracut arguments: (default: )
203 -dracut-conf
204 Path to a dracut.conf file to use instead of the default argu‐
205 ments. See the dracut.conf(5) manpage.
206 -dracut-arg
208 Argument to pass to dracut when rebuilding the initramfs. Pass
209 this once for each argument. NOTE: this overrides the defaults.
210
212 Run this as root to create a boot.iso in ./results/:
213 dnf install lorax
215 setenforce 0
216 lorax -p Fedora -v 23 -r 23 \
217 -s http://dl.fedoraproject.org/pub/fedora/linux/releases/23/Everything/x86_64/os/ \
218 -s http://dl.fedoraproject.org/pub/fedora/linux/updates/23/x86_64/ \
219 ./results/
220 setenforce 1
221 You can add your own repos with -s and packages with higher NVRs will
223 override the ones in the distribution repositories.
224 Under ./results/ will be the release tree files: .discinfo, .treeinfo,
226 everything that goes onto the boot.iso, the pxeboot directory, and the
227 boot.iso under ./images/.
228
230 By default lorax will search for the first package that provides sys‐
231 tem-release that doesn't start with generic- and will install it. It
232 then selects a corresponding logo package by using the first part of
233 the system-release package and appending -logos to it. eg. fedora-re‐
234 lease and fedora-logos.
235 Variants
237 If a variant is passed to lorax it will select a system-release package
238 that ends with the variant name. eg. Passing --variant workstation will
239 select the fedora-release-workstation package if it exists. It will se‐
240 lect a logo package the same way it does for non-variants. eg. fe‐
241 dora-logos.
242 If there is no package ending with the variant name it will fall back
244 to using the first non-generic package providing system-release.
245 Custom Branding
247 If --skip-branding is passed to lorax it will skip selecting the sys‐
248 tem-release, and logos packages and leave it up to the user to pass any
249 branding related packages to lorax using --installpkgs. When using
250 skip-branding you must make sure that you provide all of the expected
251 files, otherwise Anaconda may not work as expected. See the contents of
252 fedora-release and fedora-logos for examples of what to include.
253 Note that this does not prevent something else in the dependency tree
255 from causing these packages to be included. Using --excludepkgs may
256 help if they are unexpectedly included.
257
259 As of mock version 2.0 you no longer need to pass --old-chroot. You
260 will, however, need to pass --enable-network so that the mock container
261 can download packages.
262 Older versions of mock, between 1.3.4 and 2.0, will need to pass
264 --old-chroot to mock. These versions of mock default to using sys‐
265 temd-nspawn which cannot create the needed loop device nodes. Passing
266 --old-chroot will use the old system where /dev/loop* is setup for you.
267
269 Lorax uses dnf to install packages into a temporary directory, sets up
270 configuration files, it then removes unneeded files to save space, and
271 creates a squashfs filesystem of the files. The iso is then built us‐
272 ing a generic initramfs and the kernel from the selected repositories.
273 To drive these processes Lorax uses a custom template system, based on
275 Mako templates with the addition of custom commands (documented in py‐
276 lorax.ltmpl.LoraxTemplateRunner). Mako supports %if/%endif blocks as
277 well as free-form python code inside <% %> tags and variable substitu‐
278 tion with ${}. The default templates are shipped with lorax in
279 /usr/share/lorax/templates.d/99-generic/ and use the .tmpl extension.
280 runtime-install.tmpl
282 The runtime-install.tmpl template lists packages to be installed using
283 the installpkg command. This template is fairly simple, installing
284 common packages and architecture specific packages. It must end with
285 the run_pkg_transaction command which tells dnf to download and install
286 the packages.
287 runtime-postinstall.tmpl
289 The runtime-postinstall.tmpl template is where the system configuration
290 happens. The installer environment is similar to a normal running sys‐
291 tem, but needs some special handling. Configuration files are setup,
292 systemd is told to start the anaconda.target instead of a default sys‐
293 tem target, and a number of unneeded services are disabled, some of
294 which can interfere with the installation. A number of template com‐
295 mands are used here:
296 • append to add text to a file.
298 • chmod changes the file's mode.
300 • install to install a file into the installroot.
302 • mkdir makes a new directory.
304 • move to move a file into the installroot
306 • replace does text substitution in a file
308 • remove deletes a file
310 • runcmd run arbitrary commands.
312 • symlink creates a symlink
314 • systemctl runs systemctl in the installroot
316 runtime-cleanup.tmpl
318 The runtime-cleanup.tmpl template is used to remove files that aren't
319 strictly needed by the installation environment. In addition to the re‐
320 move template command it uses:
321 • removepkg remove all of a specific package's contents. A package may
323 be pulled in as a dependency, but not really used. eg. sound support.
324 • removefrom Removes some files from a package. A file glob can be
326 used, or the --allbut option to remove everything except a select
327 few.
328 • removekmod Removes kernel modules
330 The squashfs filesystem
332 After runtime-*.tmpl templates have finished their work lorax creates
333 an empty ext4 filesystem, copies the remaining files to it, and makes a
334 squashfs filesystem of it. This file is the / of the boot.iso's in‐
335 staller environment and is what is in the LiveOS/squashfs.img file on
336 the iso.
337 iso creation
339 The iso creation is handled by another set of templates. The one used
340 depends on the architecture that the iso is being created for. They are
341 also stored in /usr/share/lorax/templates.d/99-generic and are named
342 after the arch, like x86.tmpl and aarch64.tmpl. They handle creation of
343 the tree, copying configuration template files, configuration variable
344 substitution, treeinfo metadata (via the treeinfo template command).
345 Kernel and initrd are copied from the installroot to their final loca‐
346 tions and then xorrisofs is run to create the boot.iso
347
349 The default set of templates and configuration files from the lo‐
350 rax-generic-templates package are shipped in the /usr/share/lorax/tem‐
351 plates.d/99-generic/ directory. You can make a copy of them and place
352 them into another directory under templates.d and they will be used in‐
353 stead if their sort order is below all other directories. This allows
354 multiple packages to ship lorax templates without conflict. You can
355 (and probably should) select the specific template directory by passing
356 --sharedir to lorax.
357
359 Weldr Team
360
362 2018, Red Hat, Inc.
36334.10 Apr 27, 2021 LORAX(1)