archiso - ArchWiki

Jump to content

# archiso

From ArchWiki

Related articles

- Offline installation
- Preboot Execution Environment
- USB flash installation medium

Archiso is a highly-customizable tool for building Arch Linux live CD/USB ISO images, netboot artifacts and bootstrap tarballs. The official images are built with archiso and include these packages. It can be used as the basis for rescue systems, Linux installers or other systems.

This 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.

## Installation

Install the archiso package.

## Prepare a custom profile

Note You can read about profiles in-depth in the archiso project's README.profile.rst.

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.

To build an unmodified version of the profiles, skip to #Build the ISO. Otherwise, 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:

    $ cp -r /usr/share/archiso/configs/releng/ archlive

Proceed to the following sections to customize and build the custom profile.

### 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`[1].

### 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:

    archlive/pacman.conf

    ...
    [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. To do this, see #Adding repositories to the image.
- 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.
- mkarchiso will look for a repo called `custom`, so when you create it run:

     $ repo-add /path/to/custom.db.tar.zst /path/to/package-1.0-1-x86_64.pkg.tar.zst

#### 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 custom nftables rules on your current system you want to be used on your live image, copy them over as such:

    $ cp /etc/nftables.conf 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(1).

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`. See README.profile.rst for details.

### 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

    ...
    [archzfs]
    Include = /etc/pacman.d/archzfs_mirrorlist
    ...

    airootfs/etc/pacman.d/archzfs_mirrorlist

    Server = https://github.com/archzfs/archzfs/releases/download/experimental

    airootfs/usr/share/pacman/keyrings/archzfs-trusted

    3A9917BF0DED5C13F69AC68FABEC0A1208037BE9:4:

Import and trust the key (during image build or post-boot setup script):

    $ curl -Lo archzfs.gpg 'https://github.com/archzfs/archzfs-keyring/raw/master/keyring/packager/archzfs/3A9917BF0DED5C13F69AC68FABEC0A1208037BE9/3A9917BF0DED5C13F69AC68FABEC0A1208037BE9.asc'
    # pacman-key --add archzfs.gpg
    # pacman-key --lsign-key 3A9917BF0DED5C13F69AC68FABEC0A1208037BE9

### 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'
    archiso_config='/etc/mkinitcpio.conf.d/archiso.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.

Tip

- The releng profile by default builds into an ISO that supports both BIOS and UEFI booting when burned to an optical disc using El Torito, or when written to a hard disk (or USB flash drive, or similar) using Isohybrid.
- Due to the modular nature of isolinux, you are able to use lots of addons since all .c32 files are copied and available to you. Take a look at the official syslinux site and the archiso git repo. Using said addons, it is possible to make visually attractive and complex menus. See [2].

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. You can follow the instructions on Secure Boot#Booting an installation medium.

### 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:

    $ 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:

    $ ls -l /etc/systemd/system/display-manager.service

Now create the same symlink in `archlive/airootfs/etc/systemd/system/`. For LXDM:

    $ ln -s /usr/lib/systemd/system/lxdm.service archlive/airootfs/etc/systemd/system/display-manager.service

This will enable LXDM at system start on your live 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:

    [Service]
    ExecStart=
    ExecStart=-/sbin/agetty --noreset --noclear --autologin username - ${TERM}

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:

    [Service]
    ExecStart=
    ExecStart=-/sbin/agetty --noreset --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(5) syntax:

    archlive/airootfs/etc/passwd

    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(5). 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:

    archlive/airootfs/etc/shadow

    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(5). For example:

    archlive/airootfs/etc/group

    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(5):

    archlive/airootfs/etc/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.

### Keymaps

To change the live system's default keymap on the console, add a `vconsole.conf` with the desired keymap. Check Linux console/Keyboard configuration and vconsole.conf(5) for details and more options.

For example, to change the console's and X11's default keymap to German (`de-latin1`), create `archlive/airootfs/etc/vconsole.conf` with the following contents:

    archlive/airootfs/etc/vconsole.conf

    KEYMAP=de-latin1
    XKBLAYOUT=de

### Locales

To change the live system's locale, you must first enable and generate the localization files. For this to work you must add a custom `locale.gen` with the required locales and run `locale-gen` within the live system. This then enables you to also change the system's default locale.

For example, to enable `de_DE.UTF-8 UTF-8` and `en_US.UTF-8 UTF-8`, create `archlive/airootfs/etc/locale.gen` with the following contents (check Locale#Generating locales for details):

    archlive/airootfs/etc/locale.gen

    de_DE.UTF-8 UTF-8
    en_US.UTF-8 UTF-8

You then need to run `locale-gen` within the live system. This can be achieved with a Pacman hook that is later automatically removed from the image by another hook. Create `archlive/airootfs/etc/pacman.d/hooks/locale-gen.hook` with the following contents (check Pacman#Hooks and alpm-hooks(5) for details):

    archlive/airootfs/etc/pacman.d/hooks/locale-gen.hook

    # remove from airootfs!
    [Trigger]
    Operation = Install
    Operation = Upgrade
    Type = Package
    Target = glibc

    [Action]
    Description = Generating localisation files...
    When = PostTransaction
    Depends = glibc
    Exec = /usr/bin/locale-gen

Optionally, you can then change the live system's default locale by adding a custom `locale.conf`. For example, to change the default locale to `de_DE.UTF-8`, create `archlive/airootfs/etc/locale.conf` with the following contents (check Locale#Variables and locale.conf(5) for details):

    archlive/airootfs/etc/locale.conf

    LANG=de_DE.UTF-8

### 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.

## Build the ISO

Build an ISO which you can then burn to CD or USB by running:

    # mkarchiso -v -r -w /tmp/archiso-tmp -o /path/to/out_dir /path/to/profile/

- `-w` specifies the working directory. If the option is not specified, it will default to `work` in the current directory. If memory allows, it is preferred to place the working directory on tmpfs (as shown above) to speed up the process.
- `-r` deletes the working directory (if it was created by mkarchiso) after successfully building the ISO.
- `-o` specifies the directory where the built ISO image will be placed. If the option is not specified, it will default to `out` in the current directory.
- It should be noted the profile file `profiledef.sh` cannot be specified when running mkarchiso, only the path to the file.

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.

### Removal of work directory

Warning If mkarchiso is interrupted, run findmnt(8) 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).

Temporary files are copied into a work directory. If mkarchiso is run with the `-r` option, it will delete the work directory after successfully building the ISO as long as the directory did not exist beforehand. Alternatively, you can delete the work directory manually:

    # rm -rf /path/to/work_dir

## Using the ISO

See Installation guide#Prepare an installation medium for various options.

## Test the ISO in QEMU

Install the optional dependencies qemu-desktop and edk2-ovmf.

Use the convenience script `run_archiso` to run a built image using QEMU.

    $ run_archiso -i /path/to/archlinux-yyyy.mm.dd-x86_64.iso

The virtual machine can also be run using UEFI emulation:

    $ run_archiso -u -i /path/to/archlinux-yyyy.mm.dd-x86_64.iso

Tip As well as the VNC/SDL screen, the script forwards TCP connections from host port 60022 to guest port 22, which the guest's SSH daemon listens on. This can be used in complement with #Prepare an ISO for an installation via SSH.

## Tips and tricks

### Run setup commands as part of the ISO build process

When creating a custom profile, some modifications will require you to run setup commands within the live system's environment before creating the ISO. For example, if you want to enable additional locales, you must run `locale-gen` within the live system to generate the necessary localization files.

To run setup commands before creating the ISO, add a Pacman hook below `archlive/airootfs/etc/pacman.d/hooks/`. Check Pacman#Hooks and alpm-hooks(5) for details on how to create custom Pacman hooks. Also check #Locales for an example.

Since these setup hooks are often required to run just once as part of the ISO build process, the releng profile includes a Pacman hook that removes any Pacman hook that is marked with the string `"remove from airootfs"`. So, if you don't want your Pacman hook to also apply on the running live system, add the following comment to your Pacman hook:

    # remove from airootfs!

### Prepare an ISO for an installation via SSH

Note Since `archlinux-2021.02.01-x86_64.iso`, cloud-init support is provided, and `sshd.service` is enabled by default.

To install Arch Linux via SSH without any interaction with the system, an SSH public key must be placed in `authorized_keys`.

Adding the SSH key can either be done manually (explained here), or by cloud-init.

To add the key manually, first copy archiso's releng profile to a writable directory. The following example uses `archlive`.

    $ cp -r /usr/share/archiso/configs/profile/ archlive

Create a `.ssh` directory in the home directory of the user which will be used to log in. The following example will be using the root user.

    $ mkdir archlive/airootfs/root/.ssh

Add the SSH public key(s), which will be used to log in, to `authorized_keys`:

    $ cat ~/.ssh/key1.pub >> archlive/airootfs/root/.ssh/authorized_keys
    $ cat ~/.ssh/key2.pub >> archlive/airootfs/root/.ssh/authorized_keys

Set correct permissions and ownership for the `.ssh` directory and the `authorized_keys` file:

    archlive/profiledef.sh

    ...
    file_permissions=(
      ...
      ["/root"]="0:0:0750"
      ["/root/.ssh"]="0:0:0700"
      ["/root/.ssh/authorized_keys"]="0:0:0600"
    )

Finally build the ISO. Upon booting the ISO, OpenSSH will start and it will be possible to log in using the corresponding SSH private key(s).

### Automatically connect to a Wi-Fi network using iwd

Create `/var/lib/iwd/` inside the profile's `airootfs` directory and set the correct permissions:

    $ mkdir -p archlive/airootfs/var/lib/iwd

    archlive/profiledef.sh

    ...
    file_permissions=(
      ...
      ["/var/lib/iwd"]="0:0:0700"
    )

Follow the instructions in iwd#Network configuration and iwd.network(5) to create a network configuration file for your Wi-Fi network.

Save the configuration file inside `archlive/airootfs/var/lib/iwd/`.

### 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.

Tip See BBS#210389 for the reason behind the chosen size, and FS#45618 for historical details.

It will manifest as the following error message when downloading files or installing packages in the live environment:

    error: partition / too full: 63256 blocks needed, 61450 blocks free
    error: not enough free disk space
    error: failed to commit transaction (not enough free disk space)
    Errors occurred: no packages were upgraded.

To adjust the size on the fly:

    # mount -o remount,size=SIZE /run/archiso/cowspace

See tmpfs(5) § size for the possible parameters of `SIZE`.

To adjust the size at the boot loader stage (by pressing `e` or `Tab`) use the boot option:

    cow_spacesize=SIZE

To adjust the size while building an image add the boot option to:

- `efiboot/loader/entries/*.cfg`
- `grub/*.cfg`
- `syslinux/*.cfg`

The result can be checked with:

    $ df -h

See mkinitcpio-archiso boot parameters.

## Troubleshooting

### Window manager freezes

If you want to use a window manager in the Live CD, you must add the necessary and correct video drivers, or the WM may freeze on loading.

## See also

- Archiso project page
- Official documentation
- Arch Linux Release Engineering mailing list
- #archlinux-releng — Arch Linux Release Engineering IRC channel
- archiso-manager — the tool used for building the official monthly ISOs

Categories:

- Live Arch systems
- Installation process
- Arch projects

archiso
Add topic