1LORAX(1)                             Lorax                            LORAX(1)
2
3
4

NAME

6       lorax - Lorax Documentation
7
8       Authors
9              Brian C. Lane <bcl@redhat.com>
10
11       "I am the Lorax.  I speak for the trees [and images]."
12
13       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

LORAX CMDLINE ARGUMENTS

22       Create the Anaconda boot.iso
23
24
25          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
36   Positional Arguments
37       OUTPUTDIR
38              Output directory
39
40   options
41       -V     show program's version number and exit
42
43   required arguments
44       -p, --product
45              product name
46
47       -v, --version
48              version identifier
49
50       -r, --release
51              release information
52
53       -s, --source
54              source repository (may be listed multiple times)
55
56              Default: []
57
58       --repo source dnf repository file
59
60              Default: []
61
62   Named Arguments
63       -m, --mirrorlist
64              mirrorlist repository (may be listed multiple times)
65
66              Default: []
67
68       -t, --variant
69              variant name
70
71              Default: ""
72
73       -b, --bugurl
74              bug reporting URL for the product
75
76              Default: "your distribution provided bug reporting tool"
77
78       --isfinal
79              Default: False
80
81       -c, --config
82              config file
83
84              Default: "/etc/lorax/lorax.conf"
85
86       --proxy
87              repo proxy url:port
88
89       -i, --installpkgs
90              package  glob  to install before runtime-install.tmpl runs. (may
91              be listed multiple times)
92
93              Default: []
94
95       -e, --excludepkgs
96              package glob to remove before runtime-install.tmpl runs. (may be
97              listed multiple times)
98
99              Default: []
100
101       --buildarch
102              build architecture
103
104       --volid
105              volume id
106
107       --macboot
108              Make the iso bootable on UEFI based Mac systems
109
110              Default: True
111
112       --nomacboot
113              Do not create a Mac bootable iso
114
115              Default: False
116
117       --noupgrade
118              Default: True
119
120       --logfile
121              Path to logfile
122
123              Default: ./lorax.log
124
125       --tmp  Top level temporary directory
126
127              Default: "/var/tmp/lorax"
128
129       --cachedir
130              DNF cache directory. Default is a temporary dir.
131
132       --workdir
133              Work  directory, overrides --tmp. Default is a temporary dir un‐
134              der /var/tmp/lorax
135
136       --force
137              Run even when the destination directory exists
138
139              Default: False
140
141       --add-template
142              Additional template for runtime image
143
144              Default: []
145
146       --add-template-var
147              Set variable for runtime image template
148
149              Default: []
150
151       --add-arch-template
152              Additional template for architecture-specific image
153
154              Default: []
155
156       --add-arch-template-var
157              Set variable for architecture-specific image
158
159              Default: []
160
161       --noverify
162              Do not verify the install root
163
164              Default: True
165
166       --sharedir
167              Directory containing all the templates.  Overrides  config  file
168              sharedir
169
170       --enablerepo
171              Names of repos to enable
172
173              Default: []
174
175       --disablerepo
176              Names of repos to disable
177
178              Default: []
179
180       --rootfs-size
181              Size of root filesystem in GiB. Defaults to 2.
182
183              Default: 2
184
185       --noverifyssl
186              Do not verify SSL certificates
187
188              Default: False
189
190       --dnfplugin
191              Enable a DNF plugin by name/glob, or * to enable all of them.
192
193              Default: []
194
195       --squashfs-only
196              Use a plain squashfs filesystem for the runtime.
197
198              Default: False
199
200       --skip-branding
201              Disable  automatic branding package selection. Use --installpkgs
202              to add custom branding.
203
204              Default: False
205
206   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
211       --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

QUICKSTART

216       Run this as root to create a boot.iso in ./results/:
217
218          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
226       You can add your own repos with -s and packages with higher  NVRs  will
227       override the ones in the distribution repositories.
228
229       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

BRANDING

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
240   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
247       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
250   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
258       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

RUNNING INSIDE OF MOCK

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
267       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

HOW IT WORKS

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
278       To  drive these processes Lorax uses a custom template system, based on
279       Mako templates with the addition of custom commands (documented in  py‐
280       lorax.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
285   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
292   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
301append to add text to a file.
302
303chmod changes the file's mode.
304
305install to install a file into the installroot.
306
307mkdir makes a new directory.
308
309move to move a file into the installroot
310
311replace does text substitution in a file
312
313remove deletes a file
314
315runcmd run arbitrary commands.
316
317symlink creates a symlink
318
319systemctl runs systemctl in the installroot
320
321   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
326removepkg 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
329removefrom  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
333removekmod Removes kernel modules
334
335   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
342   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

CUSTOM TEMPLATES

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

AUTHOR

363       Weldr Team
364
366       2018, Red Hat, Inc.
367
368
369
370
37136.5                             Dec 21, 2021                         LORAX(1)
Impressum