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

QUICKSTART

204       Run this as root to create a boot.iso in ./results/:
205
206          dnf install lorax
207          setenforce 0
208          lorax -p Fedora -v 23 -r 23 \
209          -s http://dl.fedoraproject.org/pub/fedora/linux/releases/23/Everything/x86_64/os/ \
210          -s http://dl.fedoraproject.org/pub/fedora/linux/updates/23/x86_64/ \
211          ./results/
212          setenforce 1
213
214       You  can  add your own repos with -s and packages with higher NVRs will
215       override the ones in the distribution repositories.
216
217       Under ./results/ will be the release tree files: .discinfo,  .treeinfo,
218       everything  that goes onto the boot.iso, the pxeboot directory, and the
219       boot.iso under ./images/.
220

RUNNING INSIDE OF MOCK

222       If you are using lorax with mock v1.3.4 or later you will need to  pass
223       --old-chroot  to  mock. Mock now defaults to using systemd-nspawn which
224       cannot create the needed loop device nodes. Passing  --old-chroot  will
225       use the old system where /dev/loop* is setup for you.
226

HOW IT WORKS

228       Lorax  uses dnf to install packages into a temporary directory, sets up
229       configuration files, it then removes unneeded files to save space,  and
230       creates  a  squashfs  filesystem  of  the files.  The iso is then built
231       using a generic initramfs and the kernel from  the  selected  reposito‐
232       ries.
233
234       To  drive these processes Lorax uses a custom template system, based on
235       Mako templates with the addition  of  custom  commands  (documented  in
236       pylorax.ltmpl.LoraxTemplateRunner).  Mako supports %if/%endif blocks as
237       well as free-form python code inside <% %> tags and variable  substitu‐
238       tion  with  ${}.  The  default  templates  are  shipped  with  lorax in
239       /usr/share/lorax/templates.d/99-generic/ and use the .tmpl extension.
240
241   runtime-install.tmpl
242       The runtime-install.tmpl template lists packages to be installed  using
243       the  installpkg  command.   This  template is fairly simple, installing
244       common packages and architecture specific packages. It  must  end  with
245       the run_pkg_transaction command which tells dnf to download and install
246       the packages.
247
248   runtime-postinstall.tmpl
249       The runtime-postinstall.tmpl template is where the system configuration
250       happens.  The installer environment is similar to a normal running sys‐
251       tem, but needs some special handling. Configuration  files  are  setup,
252       systemd  is told to start the anaconda.target instead of a default sys‐
253       tem target, and a number of unneeded services  are  disabled,  some  of
254       which  can  interfere  with the installation. A number of template com‐
255       mands are used here:
256
257       · append to add text to a file.
258
259       · chmod changes the file's mode.
260
261       · install to install a file into the installroot.
262
263       · mkdir makes a new directory.
264
265       · move to move a file into the installroot
266
267       · replace does text substitution in a file
268
269       · remove deletes a file
270
271       · runcmd run arbitrary commands.
272
273       · symlink creates a symlink
274
275       · systemctl runs systemctl in the installroot
276
277   runtime-cleanup.tmpl
278       The runtime-cleanup.tmpl template is used to remove files  that  aren't
279       strictly  needed  by  the  installation environment. In addition to the
280       remove template command it uses:
281
282       · removepkg remove all of a specific package's contents. A package  may
283         be pulled in as a dependency, but not really used. eg. sound support.
284
285       · removefrom  Removes  some  files  from  a package. A file glob can be
286         used, or the --allbut option to remove  everything  except  a  select
287         few.
288
289       · removekmod Removes kernel modules
290
291   The squashfs filesystem
292       After  runtime-*.tmpl  templates have finished their work lorax creates
293       an empty ext4 filesystem, copies the remaining files to it, and makes a
294       squashfs  filesystem  of  it.  This file is the / of the boot.iso's in‐
295       staller environment and is what is in the LiveOS/squashfs.img  file  on
296       the iso.
297
298   iso creation
299       The  iso  creation is handled by another set of templates. The one used
300       depends on the architecture that the iso is being created for. They are
301       also  stored  in  /usr/share/lorax/templates.d/99-generic and are named
302       after the arch, like x86.tmpl and aarch64.tmpl. They handle creation of
303       the  tree, copying configuration template files, configuration variable
304       substitution, treeinfo metadata (via the  treeinfo  template  command).
305       Kernel  and initrd are copied from the installroot to their final loca‐
306       tions and then xorrisofs is run to create the boot.iso
307

CUSTOM TEMPLATES

309       The  default  set  of  templates  and  configuration  files  from   the
310       lorax-generic-templates      package     are     shipped     in     the
311       /usr/share/lorax/templates.d/99-generic/ directory. You can make a copy
312       of  them  and  place  them into another directory under templates.d and
313       they will be used instead if their sort order is below all other direc‐
314       tories.  This  allows multiple packages to ship lorax templates without
315       conflict. You can (and probably should) select  the  specific  template
316       directory by passing --sharedir to lorax.
317

AUTHOR

319       Weldr Team
320
322       2018, Red Hat, Inc.
323
324
325
326
32731.9                             Jul 29, 2019                         LORAX(1)
Impressum