Archiso
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-gitAUR package. The archiso-profilesAUR package contains additional community-provided profiles.
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/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.
Selecting packages
Edit 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 as follows:
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 mkdir(1).
By default, permissions will be for files and 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 associative array in . See README.profile.rst for details.
Kernel
Although both archiso's included profiles only have , ISOs can be made to include other or even multiple kernels.
First, edit to include kernel package names that you want. When mkarchiso runs, it will include all 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 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 . For example, for :
''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.
mkarchiso expects that systemd-boot configuration is in the directory, and syslinux configuration in and 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 does it.
For example, to enable , 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 . 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 , , and .
For example, to add a user archie. Add them to following the 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 and add it to following the syntax of . For example:
Add the user's group and the groups which they will part of to according to . For example:
Create the appropriate according to :
Make sure /etc/shadow and 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 and copy 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 into the 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 -w /path/to/work_dir -o /path/to/out_dir /path/to/profile/
- specifies the working directory. If the option is not specified, it will default to in the current directory.
- specifies the directory where the built ISO image will be placed. If the option is not specified, it will default to in the current directory.
- It should be noted the profile file 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 if you are building an unmodified profile.
When run, the script will download and install the packages you specified to , create the kernel and init images, apply your customizations and finally build the ISO into the output directory.
Removal of work directory
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-desktop and .
Use the convenience script 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
Online build
If you do not have an arch system available or you need to setup Archiso from another GNU/Linux distribution, be aware there exists an online builder.
Prepare an ISO for an installation via SSH
To install Arch Linux via SSH without any interaction with the system, an SSH public key must be placed in .
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 .
$ 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 :
$ 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 file:
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 inside the profile's directory and set the correct permissions:
$ mkdir -p archlive/airootfs/var/lib/iwd
Follow the instructions in iwd#Network configuration and to create a network configuration file for your Wi-Fi network.
Save the configuration file inside .
Adjusting the size of root partition on the fly
When installing packages on a live Archiso, for example on hardware requiring DKMS modules, the default size of the Archiso might not allow the download and installation of such packages due to its size.
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.
You can also adjust the root partition size on the fly by running:
# mount -o remount,size=2G /run/archiso/cowspace
To adjust the size of the root partition on the live Arch Linux system before booting it, press the Tab key to edit the kernel parameters. Append at the end to get 2G size for the root partition.
Press to continue booting into the live system.
You can check the size of the filesystems by running:
$ df -h
See more boot parameters here
Encryption
In order for vanilla to produce encrypted images, LUKS support in archiso, encrypt hook's compatibility in mkinitcpio-archiso and nested cryptkeys support in merge requests need to be approved.
Packages with such features already merged are , and .
To enable encryption on an existing profile:
- add to the value in ;
- set an in (to use a key file instead of a password).
- enable the
encrypthook in ; - add AUR packages (or build custom replacements with the aforementioned sources) to
- add the
keysbuildmode to the array in (to build a second ISO containing the key file that put on external storage is able to boot the system).
Example configurations based on the and profiles are available as and in the archiso-profilesAUR package.
Google Compute Engine images
A Google Compute Engine-compatible compressed image is available as .
Libvirt VM configuration
A libvirt configuration which runs the image is available as archlinux-libvirtAUR.
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.