Archiso

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Archiso is a highly-customizable tool for building Arch Linux live CD/USB ISO images. The official images are built with Archiso. 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.

Installation

Install the archiso or archiso-git^AUR package.

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 minimalistic 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/profile/ 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. custom packages or packages from AUR/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.

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 you live image, copy them over as such:

$ 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(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.

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 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 systemd-boot configuration is in the efiboot directory, and syslinux configuration in syslinux and isolinux directories.

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 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 --autologin username --noclear %I 38400 linux

Or remove it altogether to disable auto login.

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

Generate a password hash with openssl passwd -6 and add it to archlive/airootfs/etc/shadow following the syntax of shadow(5). For example:

archlive/airootfs/etc/shadow

root::14871::::::
archie:$6$randomsalt$cij4/pJREFQV/NgAgh9YyBIoCRRNq2jp5l8lbnE5aLggJnzIRmNVlogAg8N6hEEecLwXHtMQIl2NX2HlDqhCU1:14871::::::

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.

Build the ISO

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

# mkarchiso -v -w /path/to/work_dir -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.
-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.

Tip: If memory allows, it is preferred to place the working directory on tmpfs. E.g.:

# mkarchiso -v -w /tmp/archiso-tmp /path/to/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).

The temporary files are copied into work directory. After successfully building the ISO , the work directory and its contents can be deleted. E.g.:

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

Tips and tricks

Encryption

To generate an encrypted image, you can use the archiso-encryption^AUR package.

To build the included releng profile , you have to setup a custom repository containing the cryptsetup-archiso^AUR package.

If you have troubles finding the root device at runtime, tune the encrypt hook from the above package.

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 root partition on the fly

The factual accuracy of this article or section is disputed.

Reason: Explaining how but omitting the why renders the whole section useless. (Discuss in Talk:Archiso)

If you get the following error message when downloading files or installing packages in the booted ISO environment, you may need to shutdown and adjust the size of the root partition while booting the Archiso again.

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 of the root partition on the live Archlinux system, hit the TAB key to edit the kernel parameters. Append cow_spacesize=2G at the end to get 2G size for the root partition. Press Enter to continue booting into the live system. You can check the size of the filesystems by running:

$ df -h

You can also adjust the root partition size on the fly by running this command:

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

See more boot parameters here

Troubleshooting

Window manager freezes

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