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