diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.build | 68 | ||||
| -rw-r--r-- | docs/README.knownissues | 12 | ||||
| -rw-r--r-- | docs/README.profile.rst | 150 |
3 files changed, 150 insertions, 80 deletions
diff --git a/docs/README.build b/docs/README.build deleted file mode 100644 index 8855789..0000000 --- a/docs/README.build +++ /dev/null @@ -1,68 +0,0 @@ -INDEX ------ - -* Build requirements -* Building the most basic Parabola GNU/Linux-libre live media. (configs/baseline) -* Building official Parabola GNU/Linux-libre live media. (configs/releng) - - - -*** Build requirements - -** For mkparabolaiso script needs these packages (build host): - + arch-install-scripts for pacstrap/arch-chroot - + edk2-shell for UEFI shell - + squashfs-tools for mksquashfs - + libisoburn for xorriso - + btrfs-progs for mkfs.btrfs (optional) - -** For configs/releng build.sh needs theses packages (build host): - + dosfstools for mkfs.fat - + lynx for fetching the latest installation guide - -** For these hooks needs these packages (on target airootfs) -* parabolaiso - + (none) -* parabolaiso_loop_mnt - + (none) -* parabolaiso_pxe_common - + mkinitcpio-nfs-utils for ipconfig -* parabolaiso_pxe_nbd - + nbd for nbd-client -* parabolaiso_pxe_http - + curl for curl -* parabolaiso_pxe_nfs - + mkinitcpio-nfs-utils for nfsmount -* parabolaiso_shutdown - + (none) - - -*** Building the most basic Parabola GNU/Linux-libre live media. (configs/baseline) - -* Install needed packages. - # pacman -S git make arch-install-scripts squashfs-tools libisoburn --needed - -* Install parabolaiso. - # git clone git://git.parabola.nu/packages/parabolaiso.git - # make -C parabolaiso install - -* Build a basic iso. - # /usr/share/parabolaiso/configs/baseline/build.sh - -Note: If you want to customize, just see the configs/releng directory which is -used to build official images with much more things. - - -*** Building official Parabola GNU/Linux-libre live media. (configs/releng) - -* Install needed packages. - # pacman -S git make arch-install-scripts squashfs-tools libisoburn dosfstools lynx --needed - -* Install parabolaiso. - # git clone git://git.parabola.nu/packages/parabolaiso.git - # make -C parabolaiso install - -* Build them! - # /usr/share/parabolaiso/configs/releng/build.sh - -Note: See build.sh -h for more options. This only runs on x86_64. diff --git a/docs/README.knownissues b/docs/README.knownissues deleted file mode 100644 index 7002c5e..0000000 --- a/docs/README.knownissues +++ /dev/null @@ -1,12 +0,0 @@ -*** Know issues - -** (1) On shutdown lots of messages from systemd like: - - "Could not unmount /run/parabolaiso/<ABC>: Device or resource busy" - "Could not delete loopback /dev/loop<N>: Device or resource busy" - This is not a real issue since, all mounted filesystem, loopback devices - and device mapper devices made by parabolaiso will be "free" on "shutdown tmpfs" - (A.K.A deinitramfs), build at initramfs by [parabolaiso_shutdown] initcpio hook. - Proper shutdown is mostly important when persistent is used. - - diff --git a/docs/README.profile.rst b/docs/README.profile.rst new file mode 100644 index 0000000..f6cce5d --- /dev/null +++ b/docs/README.profile.rst @@ -0,0 +1,150 @@ +======= +profile +======= + +A parabolaiso profile consists of several configuration files and a directory for files to be added to the resulting image. + + .. code:: bash + + profile + |- airootfs/ + |- efiboot/ + |- syslinux/ + |- 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. `parabola-202010-x86_64.iso`). + +* `iso_name`: The first part of the name of the resulting image (defaults to `mkparabolaiso`) +* `iso_label`: The ISO's volume label (defaults to `MKPARABOLAISO`) +* `iso_publisher`: A free-form string that states the publisher of the resulting image (defaults to `mkparabolaiso`) +* `iso_application`: A free-form string that states the application (i.e. its use-case) of the resulting image (defaults + to `mkparabolaiso 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 `mkparabolaiso`) +* `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 + - `uefi-x64.refind.esp`: rEFInd for x86_64 UEFI booting from a disk + - `uefi-x64.refind.eltorito`: rEFInd 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 + 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. + +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 have to be listed one per line. Lines starting with a `#` and blank lines are ignored. + + .. note:: + + The **mkinitcpio** and **mkinitcpio-parabolaiso** packages are mandatory (see `#30 + <https://gitlab.archlinux.org/archlinux/archiso/-/issues/30>`_). + + +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**: + +* `%PARABOLAISO_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 +<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`). + +The same happens when the `uefi-x64.refind.esp` or `uefi-x64.refind.eltorito` bootmodes are selected. + +syslinux +-------- + +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. + +The *custom template identifiers* are understood in all `.cfg` files in this directory. |