jmarya/knowledge
jmarya/knowledge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

add archiso
All checks were successful
ci/woodpecker/push/validate_schema Pipeline was successful
Details

Browse source
This commit is contained in:
JMARyA 2024-12-17 14:25:09 +01:00
parent e0ff5de746
commit f7374157b3
Signed by: jmarya
GPG key ID: 901B2ADDF27C2263
2 changed files with 428 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
technology/linux/Arch Linux.md
View file

@ -12,6 +12,8 @@ Installation of Arch Linux is typically done manually following the [Wiki](https
curl -L matmoul.github.io/archfi | bash
```
You can create a (custom) ISO with [archiso](./archiso.md).
## Basic Install
```shell
# Set keyboard

426
technology/linux/archiso.md Normal file
View file

@ -0,0 +1,426 @@
---
obj: application
arch-wiki: https://wiki.archlinux.org/title/Archiso
repo: https://gitlab.archlinux.org/archlinux/archiso
rev: 2024-12-17
---
# archiso
Archiso is a highly-customizable tool for building Arch Linux live CD/USB ISO images. The official images are built with archiso and include the following packages. It can be used as the basis for rescue systems, linux installers or other systems. This wiki article explains how to install archiso, and how to configure it to control aspects of the resulting ISO image such as included packages and files. Technical requirements and build steps can be found in the official project documentation. Archiso is implemented with a number of bash scripts. The core component of archiso is the mkarchiso command. Its options are documented in mkarchiso -h and not covered here.
## Prepare a custom profile
Archiso comes with two profiles, `releng` and `baseline`.
- `releng` is used to create the official monthly installation ISO. It can be used as a starting point for creating a customized ISO image.
- `baseline` is a minimal configuration, that includes only the bare minimum packages required to boot the live environment from the medium.
If you wish to adapt or customize one of archiso's shipped profiles, copy it from `/usr/share/archiso/configs/profile-name/` to a writable directory with a name of your choice. For example:
```sh
cp -r /usr/share/archiso/configs/releng/ archlive
```
## Profile structure
An archiso profile contains configuration that defines the resulting ISO image. The profile structure is documented in `/usr/share/doc/archiso/README.profile.rst`.
An archiso profile consists of several configuration files and a directory for files to be added to the resulting image.
```
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.mbr``: Syslinux for x86 BIOS booting from a disk
- ``bios.syslinux.eltorito``: Syslinux for x86 BIOS booting from an optical disc
- ``uefi-ia32.grub.esp``: GRUB for IA32 UEFI booting from a disk
- ``uefi-ia32.grub.eltorito``: GRUB for IA32 UEFI booting from an optical disc
- ``uefi-x64.grub.esp``: GRUB for x64 UEFI booting from a disk
- ``uefi-x64.grub.eltorito``: GRUB for x64 UEFI booting from an optical disc
- ``uefi-ia32.systemd-boot.esp``: systemd-boot for IA32 UEFI booting from a disk
- ``uefi-ia32.systemd-boot.eltorito``: systemd-boot for IA32UEFI booting from an optical disc
- ``uefi-x64.systemd-boot.esp``: systemd-boot for x64 UEFI booting from a disk
- ``uefi-x64.systemd-boot.eltorito``: systemd-boot for x64 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
* ``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 an architecture specific file (e.g. ``bootstrap_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.
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 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.
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
* ``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-x64.systemd-boot.esp`` or ``uefi-x64.systemd-boot.eltorito`` bootmodes are selected in ``profiledef.sh``. It contains configuration for `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``).
### 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` or `isolinux` , or `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 any of the following bootmodes is used in ``profiledef.sh``:
- ``uefi-ia32.grub.esp`` or
- ``uefi-ia32.grub.eltorito`` or
- ``uefi-x64.grub.esp`` or
- ``uefi-x64.grub.eltorito``
It contains configuration files for `GRUB` used in the resulting image.
## Customization
### Selecting packages
Edit `packages.x86_64` to select which packages are to be installed on the live system image, listing packages line by line.
### Custom local repository
To add packages not located in standard Arch repositories (e.g. packages from the AUR or customized with the ABS), set up a custom local repository and add your custom packages to it. Then add your repository to `pacman.conf` as follows:
```ini
[customrepo]
SigLevel = Optional TrustAll
Server = file:///path/to/customrepo
```
> **Note**: The ordering within `pacman.conf` matters. To give top priority to your custom repository, place it above the other repository entries.
> This `pacman.conf` is only used for building the image. It will not be used in the live environment.
> Ensure that the repository is located in a directory accessible by the chrooted mkarchiso process, such as `/tmp`, to ensure the repository is read correctly during the image building process.
### Packages from multilib
To install packages from the multilib repository, simply uncomment that repository in `pacman.conf`.
### Adding files to image
The `airootfs` directory is used as the starting point for the root directory (`/`) of the live system on the image. All its contents will be copied over to the working directory before packages are installed.
Place any custom files and/or directories in the desired location under `airootfs/`. For example, if you have a set of iptables scripts on your current system you want to be used on your live image, copy them over as such:
```sh
cp -r /etc/iptables archlive/airootfs/etc
```
Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. Missing parts of the directory structure can be simply created with `mkdir`.
Tip: To add a file to the install user's home directory, place it in `archlive/airootfs/root/`. To add a file to all other users home directories, place it in `archlive/airootfs/etc/skel/`.
> **Note**: Custom files that conflict with those provided by packages will be overwritten unless a package specifies them as backup files.
By default, permissions will be 644 for files and 755 for directories. All of them will be owned by the root user. To set different permissions or ownership for specific files and/or folders, use the `file_permissions` associative array in `profiledef.sh`.
### Adding repositories to the image
To add a repository that can be used in the live environment, create a suitably modified `pacman.conf` and place it in `archlive/airootfs/etc/`.
If the repository also uses a key, place the key in `archlive/airootfs/usr/share/pacman/keyrings/`. The key file name must end with `.gpg`. Additionally, the key must be trusted. This can be accomplished by creating a GnuPG exported trust file in the same directory. The file name must end with `-trusted`. The first field is the key fingerprint, and the second is the trust. You can reference `/usr/share/pacman/keyrings/archlinux-trusted` for an example.
#### archzfs example
The files in this example are:
```
airootfs
├── etc
│ ├── pacman.conf
│ └── pacman.d
│ └── archzfs_mirrorlist
└── usr
└── share
└── pacman
└── keyrings
├── archzfs.gpg
└── archzfs-trusted
```
`airootfs/etc/pacman.conf`:
```ini
[archzfs]
Include = /etc/pacman.d/archzfs_mirrorlist
```
`airootfs/etc/pacman.d/archzfs_mirrorlist`:
```
Server = https://archzfs.com/$repo/$arch
Server = https://mirror.sum7.eu/archlinux/archzfs/$repo/$arch
Server = https://mirror.biocrafting.net/archlinux/archzfs/$repo/$arch
Server = https://mirror.in.themindsmaze.com/archzfs/$repo/$arch
Server = https://zxcvfdsa.com/archzfs/$repo/$arch
```
`airootfs/usr/share/pacman/keyrings/archzfs-trusted`:
```
DDF7DB817396A49B2A2723F7403BD972F75D9D76:4:
```
`archzfs.gpg` itself can be obtained directly from the repository site at https://archzfs.com/archzfs.gpg.
### Kernel
Although both archiso's included profiles only have linux, ISOs can be made to include other or even multiple kernels.
First, edit `packages.x86_64` to include kernel package names that you want. When mkarchiso runs, it will include all `work_dir/airootfs/boot/vmlinuz-*` and `work_dir/boot/initramfs-*.img` files in the ISO (and additionally in the FAT image used for UEFI booting).
mkinitcpio presets by default will build fallback initramfs images. For an ISO, the main initramfs image would not typically include the autodetect hook, thus making an additional fallback image unnecessary. To prevent the creation of an fallback initramfs image, so that it does not take up space or slow down the build process, place a custom preset in `archlive/airootfs/etc/mkinitcpio.d/pkgbase.preset`. For example, for linux-lts:
`archlive/airootfs/etc/mkinitcpio.d/linux-lts.preset`:
```
PRESETS=('archiso')
ALL_kver='/boot/vmlinuz-linux-lts'
ALL_config='/etc/mkinitcpio.conf'
archiso_image="/boot/initramfs-linux-lts.img"
```
Finally create boot loader configuration to allow booting the kernel(s).
### Boot loader
Archiso supports syslinux for BIOS booting and GRUB or systemd-boot for UEFI booting. Refer to the articles of the boot loaders for information on their configuration syntax.
mkarchiso expects that GRUB configuration is in the `grub` directory, systemd-boot configuration is in the `efiboot` directory and syslinux configuration in the `syslinux` directory.
### UEFI Secure Boot
If you want to make your archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed boot loader.
### systemd units
To enable systemd services/sockets/timers for the live environment, you need to manually create the symbolic links just as `systemctl enable` does it.
For example, to enable `gpm.service`, which contains `WantedBy=multi-user.target`, run:
```sh
mkdir -p archlive/airootfs/etc/systemd/system/multi-user.target.wants
ln -s /usr/lib/systemd/system/gpm.service archlive/airootfs/etc/systemd/system/multi-user.target.wants/
```
The required symlinks can be found out by reading the systemd unit, or if you have the service installed, by enabling it and observing the systemctl output.
### Login manager
Starting X at boot is done by enabling your login manager's systemd service. If you do not know which `.service` to enable, you can easily find out in case you are using the same program on the system you build your ISO on. Just use:
```sh
ls -l /etc/systemd/system/display-manager.service
```
Now create the same symlink in `archlive/airootfs/etc/systemd/system/`.
### Changing automatic login
The configuration for getty's automatic login is located under `airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf`.
You can modify this file to change the auto login user:
```ini
[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin username --noclear %I 38400 linux
```
Or remove `autologin.conf` altogether to disable auto login.
If you are using the serial console, create `airootfs/etc/systemd/system/serial-getty@ttyS0.service.d/autologin.conf` with the following content instead:
```ini
[Service]
ExecStart=
ExecStart=-/sbin/agetty -o '-p -- \\u' --noclear --autologin root --keep-baud 115200,57600,38400,9600 - $TERM
```
### Users and passwords
To create a user which will be available in the live environment, you must manually edit `archlive/airootfs/etc/passwd`, `archlive/airootfs/etc/shadow`, `archlive/airootfs/etc/group` and `archlive/airootfs/etc/gshadow`.
> **Note**: If these files exist, they must contain the root user and group.
For example, to add a user `archie`. Add them to `archlive/airootfs/etc/passwd` following the passwd syntax:
```
root:x:0:0:root:/root:/usr/bin/zsh
archie:x:1000:1000::/home/archie:/usr/bin/zsh
```
> **Note**: The passwd file must end with a newline.
Add the user to `archlive/airootfs/etc/shadow` following the syntax of shadow. If you want to define a password for the user, generate a password hash with `openssl passwd -6` and add it to the file. For example:
```
root::14871::::::
archie:$6$randomsalt$cij4/pJREFQV/NgAgh9YyBIoCRRNq2jp5l8lbnE5aLggJnzIRmNVlogAg8N6hEEecLwXHtMQIl2NX2HlDqhCU1:14871::::::
```
Otherwise, you may keep the password field empty, meaning that the user can log in with no password.
Add the user's group and the groups which they will part of to `archlive/airootfs/etc/group` according to group syntax. For example:
```
root:x:0:root
adm:x:4:archie
wheel:x:10:archie
uucp:x:14:archie
archie:x:1000:
```
Create the appropriate `archlive/airootfs/etc/gshadow` according to gshadow:
```
root:!*::root
archie:!*::
```
Make sure `/etc/shadow` and `/etc/gshadow` have the correct permissions:
`archlive/profiledef.sh`:
```
file_permissions=(
...
["/etc/shadow"]="0:0:0400"
["/etc/gshadow"]="0:0:0400"
)
```
After package installation, mkarchiso will create all specified home directories for users listed in `archlive/airootfs/etc/passwd` and copy `work_directory/x86_64/airootfs/etc/skel/*` to them. The copied files will have proper user and group ownership.
### Changing the distribution name used in the ISO
Start by copying the file `/etc/os-release` into the `etc/` folder in the rootfs. Then, edit the file accordingly. You can also change the name inside of GRUB and syslinux.
### Adjusting the size of the root file system
When installing packages in the live environment, for example on hardware requiring DKMS modules, the default size of the root file system might not allow the download and installation of such packages due to its size.
To adjust the size on the fly:
```sh
mount -o remount,size=SIZE /run/archiso/cowspace
```
To adjust the size at the bootloader stage (as a kernel cmdline by pressing `e` or `Tab`) use the boot option:
```sh
cow_spacesize=SIZE
```
To adjust the size while building an image add the boot option to:
- `efiboot/loader/entries/*.cfg`
- `grub/*.cfg`
- `syslinux/*.cfg`
## Build the ISO
Build an ISO which you can then burn to CD or USB by running:
```sh
mkarchiso -v -w /path/to/work_dir -o /path/to/out_dir /path/to/profile/
```
Replace `/path/to/profile/` with the path to your custom profile, or with `/usr/share/archiso/configs/releng/` if you are building an unmodified profile.
When run, the script will download and install the packages you specified to `work_directory/x86_64/airootfs`, create the kernel and init images, apply your customizations and finally build the ISO into the output directory.
> **Tip**: If memory allows, it is preferred to place the working directory on `tmpfs`.
```sh
mkdir ./work
mount -t tmpfs -o size=1G tmpfs ./work
mkarchiso -v -w ./work -o /path/to/out_dir /path/to/profile/
umount -r ./work
```
### Removal of work directory
> **Warning**: If mkarchiso is interrupted, run `findmnt` to make sure there are no mount binds before deleting it - otherwise, you may lose data (e.g. an external device mounted at `/run/media/user/label` gets bound within `work/x86_64/airootfs/run/media/user/label` during the build process).
The temporary files are copied into work directory. After successfully building the ISO , the work directory and its contents can be deleted. E.g.:
```sh
rm -rf /path/to/work_dir
```