Archiso is a tool for building Arch Linux live CD ISO images. The official images are built with Archiso. Archiso is configurable and can be used as the basis for different systems, for example rescue systems, or linux installers. 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 its usage output and not covered here.
- 1 Installation
- 2 Prepare a custom profile
- 3 Build the ISO
- 4 Using the ISO
- 5 Test the ISO in QEMU
- 6 Tips and tricks
- 7 Troubleshooting
- 8 See also
Install the or AUR package.
Prepare a custom profile
0022. If not, it is very likely that the live environment will have wrong file permissions.
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.
An archiso profile contains configuration that defines the resulting ISO image. It contains the following files and directories:
packages.x86_64—a file that lists the packages that will be installed on the live system image.
pacman.conf—pacman configuration file used in place of
/etc/pacman.conffor installing packages.
airootfs—a directory whose contents will be copied to the root of the live system image before package installation.
efiboot—a directory that contains systemd-boot configuration for the medium.
syslinux—a directory that contains syslinux configuration for booting the medium.
isolinux—a directory that contains syslinux configuration for booting the medium from a optical disc via El Torito.
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:
... [customrepo] SigLevel = Optional TrustAll Server = file:///path/to/customrepo ...
pacman.confmatters. 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
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.
Although both archiso's included profiles only have kernels., ISOs can be made to include other or even multiple
packages.x86_64 to include kernel package names that you want. When mkarchiso runs, it will include all
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 :
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).
- 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 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 .
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.
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
$ 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.
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
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
For example, to add a user
archie. Add them to
archlive/airootfs/etc/passwd following the syntax:
Generate a password hash with
openssl passwd -6 and add it to
archlive/airootfs/etc/shadow following the syntax of . For example:
Add the user's group and the groups which they will part of to
archlive/airootfs/etc/group according to . For example:
root:x:0:root adm:x:4:archie wheel:x:10:archie uucp:x:14:archie archie:x:1000:
Create the apropriate
archlive/airootfs/etc/gshadow according to :
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/
-wspecifies the working directory. If the option is not specified, it will default to
workin the current directory.
-ospecifies the directory where the built ISO image will be placed. If the option is not specified, it will default to
outin the current directory.
/usr/share/archiso/configs/releng/ if you are building an unmodified profile or with the path to your custom profile.
# 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
/run/media/user/labelgets bound within
work/x86_64/airootfs/run/media/user/labelduring 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 and .
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
Prepare an ISO for an installation via SSH
To install Arch Linux via SSH without any interraction with the system, the installation ISO must have installed,
sshd.service enabled and a public SSH key must be placed in
First copy Archiso's releng profile to writable directory. The following examples will use
$ cp -r /usr/share/archiso/configs/profile/ archlive
As described in #systemd units, systemd services in the live environment are enabled by creating the correct symbolic links. Use the following commands to enable
sshd.service so that it gets started when the live environment boots:
$ mkdir -p archlive/airootfs/etc/systemd/system/multi-user.target.wants $ ln -s /usr/lib/systemd/system/sshd.service archlive/airootfs/etc/systemd/system/multi-user.target.wants/
.ssh directory with permissions
0700 in the home directory of the user which will be used to log in. The following examples will be using the root user.
$ mkdir -m 0700 archlive/root/.ssh
Add the public SSH key(s), which will be used to log in, to
$ cat ~/.ssh/id_ed25519.pub >> archlive/root/.ssh/authorized_keys
Set the correct permissions for the
$ chmod 0600 archlive/root/.ssh/authorized_keys
.sshdirectory permissions must be
0600, otherwise OpenSSH will ignore them.
Automatically connect to a Wi-Fi network using iwd
/var/lib/iwd/ with the correct permissions inside the profile's directory:
$ mkdir -m 0755 archlive/var archlive/var/lib $ mkdir -m 0700 archlive/var/lib/iwd
Follow the instructions in iwd#Network configuration and to create a network configuration file for your Wi-Fi network. Save the file inside