.\" Man page generated from reStructuredText. . .TH "LORAX" "1" "Oct 01, 2020" "32.12" "Lorax" .SH NAME lorax \- Lorax Documentation . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .INDENT 0.0 .TP .B Authors Brian C. Lane <\fI\%bcl@redhat.com\fP> .UNINDENT .sp "I am the Lorax. I speak for the trees [and images]." .sp The \fI\%lorax\fP tool is used to create the \fI\%Anaconda\fP installer boot.iso as well as the basic release tree, and .treeinfo metadata file. Its dependencies are fairly light\-weight because it needs to be able to run in a mock chroot environment. It is best to run lorax from the same release as is being targeted because the templates may have release specific logic in them. eg. Use the rawhide version to build the boot.iso for rawhide, along with the rawhide repositories. .SH LORAX CMDLINE ARGUMENTS .sp Create the Anaconda boot.iso .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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] [\-\-buildarch ARCH] [\-\-volid VOLID] [\-\-macboot] [\-\-nomacboot] [\-\-noupgrade] [\-\-logfile LOGFILE] [\-\-tmp TMP] [\-\-cachedir CACHEDIR] [\-\-workdir WORKDIR] [\-\-force] [\-\-add\-template ADD_TEMPLATES] [\-\-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]] [\-\-disablerepo [repo]] [\-\-rootfs\-size ROOTFS_SIZE] [\-\-noverifyssl] [\-\-dnfplugin DNFPLUGINS] [\-\-squashfs\-only] [\-\-skip\-branding] [\-\-dracut\-conf DRACUT_CONF] [\-\-dracut\-arg DRACUT_ARGS] [\-V] OUTPUTDIR .ft P .fi .UNINDENT .UNINDENT .SS Positional Arguments .INDENT 0.0 .TP .BOUTPUTDIR Output directory .UNINDENT .SS Named Arguments .INDENT 0.0 .TP .B\-V show program\(aqs version number and exit .UNINDENT .SS required arguments .INDENT 0.0 .TP .B\-p, \-\-product product name .TP .B\-v, \-\-version version identifier .TP .B\-r, \-\-release release information .TP .B\-s, \-\-source source repository (may be listed multiple times) .sp Default: [] .TP .B\-\-repo source dnf repository file .sp Default: [] .UNINDENT .SS Named Arguments .INDENT 0.0 .TP .B\-m, \-\-mirrorlist mirrorlist repository (may be listed multiple times) .sp Default: [] .TP .B\-t, \-\-variant variant name .sp Default: "" .TP .B\-b, \-\-bugurl bug reporting URL for the product .sp Default: "your distribution provided bug reporting tool" .TP .B\-\-isfinal Default: False .TP .B\-c, \-\-config config file .sp Default: "/etc/lorax/lorax.conf" .TP .B\-\-proxy repo proxy url:port .TP .B\-i, \-\-installpkgs package glob to install before runtime\-install.tmpl runs. (may be listed multiple times) .sp Default: [] .TP .B\-e, \-\-excludepkgs package glob to remove before runtime\-install.tmpl runs. (may be listed multiple times) .sp Default: [] .TP .B\-\-buildarch build architecture .TP .B\-\-volid volume id .TP .B\-\-macboot Make the iso bootable on UEFI based Mac systems .sp Default: True .TP .B\-\-nomacboot Do not create a Mac bootable iso .sp Default: False .TP .B\-\-noupgrade Default: True .TP .B\-\-logfile Path to logfile .sp Default: ./lorax.log .TP .B\-\-tmp Top level temporary directory .sp Default: "/var/tmp/lorax" .TP .B\-\-cachedir DNF cache directory. Default is a temporary dir. .TP .B\-\-workdir Work directory, overrides \-\-tmp. Default is a temporary dir under /var/tmp/lorax .TP .B\-\-force Run even when the destination directory exists .sp Default: False .TP .B\-\-add\-template Additional template for runtime image .sp Default: [] .TP .B\-\-add\-template\-var Set variable for runtime image template .sp Default: [] .TP .B\-\-add\-arch\-template Additional template for architecture\-specific image .sp Default: [] .TP .B\-\-add\-arch\-template\-var Set variable for architecture\-specific image .sp Default: [] .TP .B\-\-noverify Do not verify the install root .sp Default: True .TP .B\-\-sharedir Directory containing all the templates. Overrides config file sharedir .TP .B\-\-enablerepo Names of repos to enable .sp Default: [] .TP .B\-\-disablerepo Names of repos to disable .sp Default: [] .TP .B\-\-rootfs\-size Size of root filesystem in GiB. Defaults to 2. .sp Default: 2 .TP .B\-\-noverifyssl Do not verify SSL certificates .sp Default: False .TP .B\-\-dnfplugin Enable a DNF plugin by name/glob, or * to enable all of them. .sp Default: [] .TP .B\-\-squashfs\-only Use a plain squashfs filesystem for the runtime. .sp Default: False .TP .B\-\-skip\-branding Disable automatic branding package selection. Use \-\-installpkgs to add custom branding. .sp Default: False .UNINDENT .SS dracut arguments: (default: ) .INDENT 0.0 .TP .B\-\-dracut\-conf Path to a dracut.conf file to use instead of the default arguments. See the dracut.conf(5) manpage. .TP .B\-\-dracut\-arg Argument to pass to dracut when rebuilding the initramfs. Pass this once for each argument. NOTE: this overrides the defaults. .UNINDENT .SH QUICKSTART .sp Run this as root to create a boot.iso in \fB\&./results/\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dnf install lorax setenforce 0 lorax \-p Fedora \-v 23 \-r 23 \e \-s http://dl.fedoraproject.org/pub/fedora/linux/releases/23/Everything/x86_64/os/ \e \-s http://dl.fedoraproject.org/pub/fedora/linux/updates/23/x86_64/ \e \&./results/ setenforce 1 .ft P .fi .UNINDENT .UNINDENT .sp You can add your own repos with \fB\-s\fP and packages with higher NVRs will override the ones in the distribution repositories. .sp Under \fB\&./results/\fP will be the release tree files: .discinfo, .treeinfo, everything that goes onto the boot.iso, the pxeboot directory, and the boot.iso under \fB\&./images/\fP\&. .SH BRANDING .sp By default lorax will search for the first package that provides \fBsystem\-release\fP that doesn\(aqt start with \fBgeneric\-\fP and will install it. It then selects a corresponding logo package by using the first part of the system\-release package and appending \fB\-logos\fP to it. eg. fedora\-release and fedora\-logos. .SS Variants .sp If a \fBvariant\fP is passed to lorax it will select a \fBsystem\-release\fP package that ends with the variant name. eg. Passing \fB\-\-variant workstation\fP will select the \fBfedora\-release\-workstation\fP package if it exists. It will select a logo package the same way it does for non\-variants. eg. \fBfedora\-logos\fP\&. .sp If there is no package ending with the variant name it will fall back to using the first non\-generic package providing \fBsystem\-release\fP\&. .SS Custom Branding .sp If \fB\-\-skip\-branding\fP is passed to lorax it will skip selecting the \fBsystem\-release\fP, and logos packages and leave it up to the user to pass any branding related packages to lorax using \fB\-\-installpkgs\fP\&. When using \fBskip\-branding\fP you must make sure that you provide all of the expected files, otherwise Anaconda may not work as expected. See the contents of \fBfedora\-release\fP and \fBfedora\-logos\fP for examples of what to include. .sp Note that this does not prevent something else in the dependency tree from causing these packages to be included. Using \fB\-\-excludepkgs\fP may help if they are unexpectedly included. .SH RUNNING INSIDE OF MOCK .sp As of mock version 2.0 you no longer need to pass \fB\-\-old\-chroot\fP\&. You will, however, need to pass \fB\-\-enable\-network\fP so that the mock container can download packages. .sp Older versions of mock, between 1.3.4 and 2.0, will need to pass \fB\-\-old\-chroot\fP to mock. These versions of mock default to using systemd\-nspawn which cannot create the needed loop device nodes. Passing \fB\-\-old\-chroot\fP will use the old system where \fB/dev/loop*\fP is setup for you. .SH HOW IT WORKS .sp Lorax uses \fI\%dnf\fP to install packages into a temporary directory, sets up configuration files, it then removes unneeded files to save space, and creates a squashfs filesystem of the files. The iso is then built using a generic initramfs and the kernel from the selected repositories. .sp To drive these processes Lorax uses a custom template system, based on \fI\%Mako templates\fP with the addition of custom commands (documented in \fBpylorax.ltmpl.LoraxTemplateRunner\fP). Mako supports \fB%if/%endif\fP blocks as well as free\-form python code inside \fB<% %>\fP tags and variable substitution with \fB${}\fP\&. The default templates are shipped with lorax in \fB/usr/share/lorax/templates.d/99\-generic/\fP and use the \fB\&.tmpl\fP extension. .SS runtime\-install.tmpl .sp The \fBruntime\-install.tmpl\fP template lists packages to be installed using the \fBinstallpkg\fP command. This template is fairly simple, installing common packages and architecture specific packages. It must end with the \fBrun_pkg_transaction\fP command which tells dnf to download and install the packages. .SS runtime\-postinstall.tmpl .sp The \fBruntime\-postinstall.tmpl\fP template is where the system configuration happens. The installer environment is similar to a normal running system, but needs some special handling. Configuration files are setup, systemd is told to start the anaconda.target instead of a default system target, and a number of unneeded services are disabled, some of which can interfere with the installation. A number of template commands are used here: .INDENT 0.0 .IP \(bu 2 \fBappend\fP to add text to a file. .IP \(bu 2 \fBchmod\fP changes the file\(aqs mode. .IP \(bu 2 \fBinstall\fP to install a file into the installroot. .IP \(bu 2 \fBmkdir\fP makes a new directory. .IP \(bu 2 \fBmove\fP to move a file into the installroot .IP \(bu 2 \fBreplace\fP does text substitution in a file .IP \(bu 2 \fBremove\fP deletes a file .IP \(bu 2 \fBruncmd\fP run arbitrary commands. .IP \(bu 2 \fBsymlink\fP creates a symlink .IP \(bu 2 \fBsystemctl\fP runs systemctl in the installroot .UNINDENT .SS runtime\-cleanup.tmpl .sp The \fBruntime\-cleanup.tmpl\fP template is used to remove files that aren\(aqt strictly needed by the installation environment. In addition to the \fBremove\fP template command it uses: .INDENT 0.0 .IP \(bu 2 \fBremovepkg\fP remove all of a specific package\(aqs contents. A package may be pulled in as a dependency, but not really used. eg. sound support. .IP \(bu 2 \fBremovefrom\fP Removes some files from a package. A file glob can be used, or the \-\-allbut option to remove everything except a select few. .IP \(bu 2 \fBremovekmod\fP Removes kernel modules .UNINDENT .SS The squashfs filesystem .sp After \fBruntime\-*.tmpl\fP templates have finished their work lorax creates an empty ext4 filesystem, copies the remaining files to it, and makes a squashfs filesystem of it. This file is the / of the boot.iso\(aqs installer environment and is what is in the LiveOS/squashfs.img file on the iso. .SS iso creation .sp The iso creation is handled by another set of templates. The one used depends on the architecture that the iso is being created for. They are also stored in \fB/usr/share/lorax/templates.d/99\-generic\fP and are named after the arch, like \fBx86.tmpl\fP and \fBaarch64.tmpl\fP\&. They handle creation of the tree, copying configuration template files, configuration variable substitution, treeinfo metadata (via the \fBtreeinfo\fP template command). Kernel and initrd are copied from the installroot to their final locations and then xorrisofs is run to create the boot.iso .SH CUSTOM TEMPLATES .sp The default set of templates and configuration files from the lorax\-generic\-templates package are shipped in the \fB/usr/share/lorax/templates.d/99\-generic/\fP directory. You can make a copy of them and place them into another directory under \fBtemplates.d\fP and they will be used instead if their sort order is below all other directories. This allows multiple packages to ship lorax templates without conflict. You can (and probably should) select the specific template directory by passing \fB\-\-sharedir\fP to lorax. .SH AUTHOR Weldr Team .SH COPYRIGHT 2018, Red Hat, Inc. .\" Generated by docutils manpage writer. .