187 lines
10 KiB
ReStructuredText
187 lines
10 KiB
ReStructuredText
=======
|
|
profile
|
|
=======
|
|
|
|
An archiso profile consists of several configuration files and a directory for files to be added to the resulting image.
|
|
|
|
.. code:: plaintext
|
|
|
|
profile/
|
|
├── airootfs/
|
|
├── efiboot/
|
|
├── syslinux/
|
|
├── grub/
|
|
├── bootstrap_packages.arch
|
|
├── packages.arch
|
|
├── pacman.conf
|
|
└── profiledef.sh
|
|
|
|
The required files and directories are explained in the following sections.
|
|
|
|
profiledef.sh
|
|
=============
|
|
|
|
This file describes several attributes of the resulting image and is a place for customization to the general behavior
|
|
of the image.
|
|
|
|
The image file is constructed from some of the variables in ``profiledef.sh``: ``<iso_name>-<iso_version>-<arch>.iso``
|
|
(e.g. ``archlinux-202010-x86_64.iso``).
|
|
|
|
* ``iso_name``: The first part of the name of the resulting image (defaults to ``mkarchiso``)
|
|
* ``iso_label``: The ISO's volume label (defaults to ``MKARCHISO``)
|
|
* ``iso_publisher``: A free-form string that states the publisher of the resulting image (defaults to ``mkarchiso``)
|
|
* ``iso_application``: A free-form string that states the application (i.e. its use-case) of the resulting image (defaults
|
|
to ``mkarchiso iso``)
|
|
* ``iso_version``: A string that states the version of the resulting image (defaults to ``""``)
|
|
* ``install_dir``: A string (maximum eight characters long, which **must** consist of ``[a-z0-9]``) that states the
|
|
directory on the resulting image into which all files will be installed (defaults to ``mkarchiso``)
|
|
* ``buildmodes``: An optional list of strings, that state the build modes that the profile uses. Only the following are
|
|
understood:
|
|
|
|
- ``bootstrap``: Build a compressed file containing a minimal system to bootstrap from
|
|
- ``iso``: Build a bootable ISO image (implicit default, if no ``buildmodes`` are set)
|
|
- ``netboot``: Build artifacts required for netboot using iPXE
|
|
* ``bootmodes``: A list of strings, that state the supported boot modes of the resulting image. Only the following are
|
|
understood:
|
|
|
|
- ``bios.syslinux``: Syslinux for x86 BIOS booting
|
|
- ``uefi.grub``: GRUB for UEFI booting. For the x86_64 architecture, in addition to x64 UEFI, support for mixed-mode
|
|
booting (IA32 UEFI) will also be added.
|
|
- ``uefi.systemd-boot``: systemd-boot for UEFI booting. For the x86_64 architecture, in addition to x64 UEFI, support
|
|
for mixed-mode booting (IA32 UEFI) will also be added.
|
|
* ``arch``: The architecture (e.g. ``x86_64``) to build the image for (defaults to the value returned by ``uname -m``).
|
|
This is also used to resolve the name of the packages file (e.g. ``packages.x86_64``)
|
|
* ``packages``: File path to a text file containing a list of packages to install into the environment in ``iso`` and
|
|
``netboot`` build modes (defaults to ``packages.${arch}``).
|
|
* ``bootstrap_packages``: File path to a text file containing a list of packages to install into the environment in the
|
|
``bootstrap`` build mode (defaults to ``bootstrap_packages.${arch}``).
|
|
* ``pacman_conf``: The ``pacman.conf`` to use to install packages to the work directory when creating the image (defaults to
|
|
the host's ``/etc/pacman.conf``)
|
|
* ``airootfs_image_type``: The image type to create. The following options are understood (defaults to ``squashfs``):
|
|
|
|
- ``squashfs``: Create a squashfs image directly from the airootfs work directory
|
|
- ``ext4+squashfs``: Create an ext4 partition, copy the airootfs work directory to it and create a squashfs image from it
|
|
- ``erofs``: Create an EROFS image for the airootfs work directory
|
|
* ``airootfs_image_tool_options``: An array of options to pass to the tool to create the airootfs image. ``mksquashfs`` and
|
|
``mkfs.erofs`` are supported. See ``mksquashfs --help`` or ``mkfs.erofs --help`` for all possible options
|
|
* ``bootstrap_tarball_compression``: An array containing the compression program and arguments passed to it for
|
|
compressing the bootstrap tarball (defaults to ``cat``). For example: ``bootstrap_tarball_compression=(zstd -c -T0 --long -19)``.
|
|
* ``file_permissions``: An associative array that lists files and/or directories who need specific ownership or
|
|
permissions. The array's keys contain the path and the value is a colon separated list of owner UID, owner GID and
|
|
access mode. E.g. ``file_permissions=(["/etc/shadow"]="0:0:400")``. When directories are listed with a trailing backslash (``/``) **all** files and directories contained within the listed directory will have the same owner UID, owner GID, and access mode applied recursively.
|
|
|
|
bootstrap_packages.arch
|
|
=======================
|
|
|
|
All packages to be installed into the environment of a bootstrap image have to be listed in a file specified by the
|
|
``bootstrap_packages`` variable. If the variable is not specified, the architecture specific
|
|
``bootstrap_packages.${arch}`` file (e.g. ``bootstrap_packages.x86_64``) or the ``bootstrap_packages`` file which reside
|
|
top-level in the profile will be used instead.
|
|
|
|
Packages have to be listed one per line. Lines starting with a ``#`` and blank lines are ignored.
|
|
|
|
This file is required when generating bootstrap images using the ``bootstrap`` build mode.
|
|
|
|
packages.arch
|
|
=============
|
|
|
|
All packages to be installed into the environment of an ISO image have to be listed in a file specified by the
|
|
``packages`` variable. If the variable is not specified, the architecture specific ``packages.${arch}`` file (e.g.
|
|
``packages.x86_64``) or the ``packages`` file which reside top-level in the profile will be used instead.
|
|
|
|
Packages have to be listed one per line. Lines starting with a ``#`` and blank lines are ignored.
|
|
|
|
.. note::
|
|
|
|
The **mkinitcpio** and **mkinitcpio-archiso** packages are mandatory (see `#30
|
|
<https://gitlab.archlinux.org/archlinux/archiso/-/issues/30>`_).
|
|
|
|
This file is required when generating ISO images using the ``iso`` or ``netboot`` build modes.
|
|
|
|
pacman.conf
|
|
===========
|
|
|
|
A configuration for pacman is required per profile.
|
|
|
|
Some configuration options will not be used or will be modified:
|
|
|
|
* ``CacheDir``: the profile's option is **only** used if it is not the default (i.e. ``/var/cache/pacman/pkg``) and if it is
|
|
not the same as the system's option. In all other cases the system's pacman cache is used.
|
|
* ``HookDir``: it is **always** set to the ``/etc/pacman.d/hooks`` directory in the work directory's airootfs to allow
|
|
modification via the profile and ensure interoparability with hosts using dracut (see `#73
|
|
<https://gitlab.archlinux.org/archlinux/archiso/-/issues/73>`_)
|
|
* ``RootDir``: it is **always** removed, as setting it explicitely otherwise refers to the host's root filesystem (see
|
|
``man 8 pacman`` for further information on the ``-r`` option used by ``pacstrap``)
|
|
* ``LogFile``: it is **always** removed, as setting it explicitely otherwise refers to the host's pacman log file (see
|
|
``man 8 pacman`` for further information on the ``-r`` option used by ``pacstrap``)
|
|
* ``DBPath``: it is **always** removed, as setting it explicitely otherwise refers to the host's pacman database (see
|
|
``man 8 pacman`` for further information on the ``-r`` option used by ``pacstrap``)
|
|
|
|
airootfs
|
|
========
|
|
|
|
This optional directory may contain files and directories that will be copied to the work directory of the resulting
|
|
image's root filesystem.
|
|
The files are copied before packages are being installed to work directory location.
|
|
Ownership and permissions of files and directories from the profile's ``airootfs`` directory are not preserved. The mode
|
|
will be ``644`` for files and ``755`` for directories, all of them will be owned by root. To set custom ownership and/or
|
|
permissions, use ``file_permissions`` in ``profiledef.sh``.
|
|
|
|
With this overlay structure it is possible to e.g. create users and set passwords for them, by providing
|
|
``airootfs/etc/passwd``, ``airootfs/etc/shadow``, ``airootfs/etc/gshadow`` (see ``man 5 passwd``, ``man 5 shadow`` and ``man 5 gshadow`` respectively).
|
|
If user home directories exist in the profile's ``airootfs``, their ownership and (and top-level) permissions will be
|
|
altered according to the provided information in the password file.
|
|
|
|
Boot loader configuration
|
|
=========================
|
|
|
|
A profile may contain configuration for several boot loaders. These reside in specific top-level directories, which are
|
|
explained in the following subsections.
|
|
|
|
The following *custom template identifiers* are understood and will be replaced according to the assignments of the
|
|
respective variables in ``profiledef.sh``:
|
|
|
|
* ``%ARCHISO_LABEL%``: Set this using the ``iso_label`` variable in ``profiledef.sh``.
|
|
* ``%INSTALL_DIR%``: Set this using the ``install_dir`` variable in ``profiledef.sh``.
|
|
* ``%ARCH%``: Set this using the ``arch`` variable in ``profiledef.sh``.
|
|
|
|
Additionally there are also *custom template identifiers* have harcoded values set by ``mkarchiso`` that cannot be
|
|
overridden:
|
|
|
|
* ``%ARCHISO_UUID%``: the ISO 9660 modification date in UTC, i.e. its "UUID",
|
|
* ``%ARCHISO_SEARCH_FILENAME%``: file path on ISO 9660 that can be used by GRUB to find the ISO volume
|
|
(**for GRUB ``.cfg`` files only**).
|
|
|
|
efiboot
|
|
-------
|
|
|
|
This directory is mandatory when the ``uefi.systemd-boot`` bootmode is selected in ``profiledef.sh``.
|
|
It contains configuration for `systemd-boot
|
|
<https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`_.
|
|
|
|
.. note::
|
|
|
|
The directory is a top-level representation of the systemd-boot configuration directories and files found in the
|
|
root of an EFI system partition.
|
|
|
|
The *custom template identifiers* are **only** understood in the boot loader entry `.conf` files (i.e. **not** in
|
|
``loader.conf``). Boot entries for foreign UEFI architectures will be skipped with the exception of IA32 boot entries
|
|
when building for the x86_64 architecture.
|
|
|
|
syslinux
|
|
--------
|
|
|
|
This directory is mandatory when the ``bios.syslinux`` bootmode is selected in ``profiledef.sh``.
|
|
It contains configuration files for `syslinux <https://wiki.syslinux.org/wiki/index.php?title=SYSLINUX>`_ or `isolinux
|
|
<https://wiki.syslinux.org/wiki/index.php?title=ISOLINUX>`_ , or `pxelinux
|
|
<https://wiki.syslinux.org/wiki/index.php?title=PXELINUX>`_ used in the resulting image.
|
|
|
|
The *custom template identifiers* are understood in all `.cfg` files in this directory.
|
|
|
|
grub
|
|
----
|
|
|
|
This directory is mandatory when the ``uefi.grub`` bootmode is selected in ``profiledef.sh``.
|
|
It contains configuration files for `GRUB <https://www.gnu.org/software/grub/>`_
|
|
used in the resulting image.
|