Send patches - preferably formatted by git format-patch - to patches at archlinux32 dot org.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authornl6720 <nl6720@gmail.com>2021-03-22 13:40:34 +0000
committernl6720 <nl6720@gmail.com>2021-04-30 20:51:24 +0300
commit6294d1d985441483f10d897a5a43c2d95e1e9cd7 (patch)
tree84684774b8f3377222489f713166eef40551b9bb
parent5754000d2ec98cd8a6cc1063b8cd99546974c3eb (diff)
Update README.profile.rst
* Don't nest code blocks inside quote blocks. * Use monospace for paths, options, values, etc.
-rw-r--r--README.profile.rst123
1 files changed, 61 insertions, 62 deletions
diff --git a/README.profile.rst b/README.profile.rst
index 89477d2..a8c4487 100644
--- a/README.profile.rst
+++ b/README.profile.rst
@@ -4,15 +4,15 @@ profile
An archiso profile consists of several configuration files and a directory for files to be added to the resulting image.
- .. code:: bash
+.. code:: plaintext
- profile
- |- airootfs/
- |- efiboot/
- |- syslinux/
- |- packages.arch
- |- pacman.conf
- \- profiledef.sh
+ profile/
+ ├── airootfs/
+ ├── efiboot/
+ ├── syslinux/
+ ├── packages.arch
+ ├── pacman.conf
+ └── profiledef.sh
The required files and directories are explained in the following sections.
@@ -22,45 +22,45 @@ 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`)
-* `bootmodes`: A list of strings, that state the supported boot modes of the resulting image. Only the following are
+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``)
+* ``bootmodes``: A list of strings, that state the supported boot modes of the resulting image. Only the following are
understood:
- - `bios.syslinux.mbr`: Syslinux for x86 BIOS booting from a disk
- - `bios.syslinux.eltorito`: Syslinux for x86 BIOS booting from an optical disc
- - `uefi-x64.systemd-boot.esp`: Systemd-boot for x86_64 UEFI booting from a disk
- - `uefi-x64.systemd-boot.eltorito`: Systemd-boot for x86_64 UEFI booting from an optical disc
+ - ``bios.syslinux.mbr``: Syslinux for x86 BIOS booting from a disk
+ - ``bios.syslinux.eltorito``: Syslinux for x86 BIOS booting from an optical disc
+ - ``uefi-x64.systemd-boot.esp``: systemd-boot for x86_64 UEFI booting from a disk
+ - ``uefi-x64.systemd-boot.eltorito``: systemd-boot for x86_64 UEFI booting from an optical disc
Note that BIOS El Torito boot mode must always be listed before UEFI El Torito boot mode.
-* `arch`: The architecture (e.g. `x86_64`) to build the image for. This is also used to resolve the name of the packages
- file (e.g. `packages.x86_64`)
-* `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.
-* `file_permissions`: An associative array that lists files and/or directories who need specific ownership or
+* ``arch``: The architecture (e.g. ``x86_64``) to build the image for. This is also used to resolve the name of the packages
+ file (e.g. ``packages.x86_64``)
+* ``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
+* ``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.
+ 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.
packages.arch
=============
All packages to be installed into the environment of the image have to be listed in an architecture specific file (e.g.
-`packages.x86_64`), which resides top-level in the profile.
+``packages.x86_64``), which resides top-level in the profile.
Packages have to be listed one per line. Lines starting with a `#` and blank lines are ignored.
@@ -76,32 +76,31 @@ 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
+* ``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
+* ``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`)
+* ``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
+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**.
+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
+``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
@@ -111,18 +110,18 @@ A profile may contain configuration for several boot loaders. These reside in sp
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**:
+respective variables in ``profiledef.sh``:
-* `%ARCHISO_LABEL%`: Set this using the `iso_label` variable in **profiledef.sh**
-* `%INSTALL_DIR%`: Set this using the `iso_label` variable in **profiledef.sh**
-* `%ARCH%`: Set this using the `arch` variable in **profiledef.sh**
+* ``%ARCHISO_LABEL%``: Set this using the ``iso_label`` variable in ``profiledef.sh``.
+* ``%INSTALL_DIR%``: Set this using the ``iso_label`` variable in ``profiledef.sh``.
+* ``%ARCH%``: Set this using the ``arch`` variable in ``profiledef.sh``.
efiboot
-------
-This directory is mandatory when the `uefi-x64.systemd-boot.esp` or `uefi-x64.systemd-boot.eltorito` bootmodes are
-selected in **profiledef.sh**. It contains configuration for `systemd-boot
+This directory is mandatory when the ``uefi-x64.systemd-boot.esp`` or ``uefi-x64.systemd-boot.eltorito`` bootmodes are
+selected in ``profiledef.sh``. It contains configuration for `systemd-boot
<https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`_.
.. note::
@@ -131,13 +130,13 @@ selected in **profiledef.sh**. It contains configuration for `systemd-boot
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`).
+``loader.conf``).
syslinux
--------
-This directory is mandatory when the `bios.syslinux.mbr` or the `bios.syslinux.eltorito` bootmodes are selected in
-**profiledef.sh**.
+This directory is mandatory when the ``bios.syslinux.mbr`` or the ``bios.syslinux.eltorito`` bootmodes are 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 resuling image.