Archboot Project |

© 2006 - 2023 | Tobias Powalowski | Arch Linux Developer tpowa
Last update: 23.11.2023 08:28

1. Introduction

Archboot is a most advanced, modular Arch Linux boot/install image creation utility to generate
reproducible bootable media for UKI/CD/USB/PXE, designed for installation or rescue operation.
The additional ISOs and UKIs focus on being small, fast and (power)user friendly.

2. Releases

• Latest News, Changelog, Screenshot Gallery
• Release schedule: on 10th, 20th and 30th of a month new images are released.
• Build Sources
• Hybrid images, Unified Kernel Images, Kernels, Initrd, and Microcodes are provided.
• PGP KEY: 5B7E 3FB7 1B7F 1032 9A1C 03AB 771D F662 7EDF 681F for file verification is provided.
• Supported Glibc Locales: be, bg, cs, da, de, en, el, es, fi, fr, hu, it, lt, lv, mk, nl, nn, pl, pt, ro, ru, sk, sr, sv, tr, uk

2.1 ISOs - USB / CD / Virtual Machine

¹ The ISO supports aarch64, Apple Mac M1 and higher for virtual machines eg. Parallels Desktop, UTM and VMware
² The ISO supports riscv64 and needs U-Boot to launch. Recommended only for testing in a virtual machine.
³ The ISO supports x86_64. Use it for real machines and/or virtual machines.

2.2 UKIs - Unified Kernel Images

The Unified Kernel Image can be booted from your UEFI firmware or bootloader like any other <EFI> file.

2.3 Kernel / Initrd / Microcode / Rescue System / PXE

• For rescue booting, add an entry pointing to the Kernel, Initrd, Microcode to your bootloader.
• For PXE booting, add the Kernel, Initrd and Microcode to your TFTP setup.

2.4 ISO / Initrd / UKI Types

• During boot, all ethernet network interfaces will try to obtain an IP address through DHCP.
• With a fast ethernet internet connection and a running DHCP server, go for the latest image.
• Without an internet connection for installation, you should use the local image.
  It includes a local package repository for installation.

2.5 ISO Boot Modes

* Firmware 32bit / OS 64bit

2.6 ISO Writing To USB / CD

A hybrid image file is a standard CD/DVD-burnable image and also a raw disk image.

• Can be burned to CD/DVD(RW) media using most CD Burning utilities.
• Can be raw-written to a drive using dd or similar utilities.

• In Rufus for Windows use dd-Mode to write the image.
• Power users might consider using a Ventoy boot stick. One stick to boot everything, without reformat the stick all the time.

3. Features In A Nutshell

3.1 Secure Boot - MOK / Machine Owner Key

Please read Roderick Smith’s guide for initial shim setup first.

The included tools for key management: mokutil, sbsigntools, sbctl and mkkeys.sh

3.1.1 Secure Boot - ISO Booting

On initial Secure Boot setup MOK manager is launched:

3.1.2 Secure Boot - Automatic Setup Routine

The setup script supports the following Secure Boot layout:

• The fedora's signed shim is copied to the installed system
• Creating of new keys is supported
• Using existing keys from /etc/secureboot/keys in layout secureboot-keys.sh produces
• MOK setup is done with personal MOK keys
• Adding a pacman hook for automatic signing with personal keys
• On first boot you need to enroll the used personal key as MOK.
• Then your installed system is dual boot ready.

3.1.3 Secure Boot - Manual Create MOK

3.1.4 Secure Boot - Reset MOK

In order to reset the MOK setup:

• Turn off Secure Boot in firmware
• Boot the system and use mokutil to reset the setup.

• Reboot and turn on Secure Boot again in firmware.
• Start again at point 3.1.1.

3.2 Terminal Access

3.2.1 Virtual Consoles - VCs

Use left/right SUPER | Windows | Command | Search | Apple key or ALT+⇽ or ALT+⇾ to toggle consoles.

3.2.2 Serial Console

Serial console is enabled on ttyS0, ttyAMA0 and ttyUSB0.

3.3 Remote Terminal Access

3.3.1 OpenSSH Terminal

• Access the terminal with OpenSSH.
• Attention: root password is not set/empty by default!

GNU screen is launched on login and last session will be reattached.

3.3.2 HTTP Browser Terminal - TTYD

• Access the ttyd terminal in your browser.
• Attention: The connection is not encrypted!

GNU screen is launched on login and last session will be reattached.

3.4 Interactive Basic Setup

The interactive scripts are launched on first login.

3.4.1 Localization

Your locale, console font and keymap will be configured by the localize script.

3.4.2 Network Configuration (Online Mode)

• Your network will be configured by the network script.
• Your network will be configured by systemd-networkd.
• Your wifi network will be authentificated by iwd.

3.4.3 Clock Configuration

• Your timezone and date will be configured by the clock script.
• In Online Mode the timezone will be configured by your GeoIP and timesyncd will be activated.

3.4.4 Pacman Setup (Online Mode)

Pacman will be configured by the pacsetup script.

• You will be asked if you want to activate the testing repositories <default=no>.
• Latest pacman mirrors will be GeoIP synced and you have to select your favourite mirror.
• If a new kernel is online available, you can decide to load the latest archboot environment <default=no>.

3.5 Interactive Launcher

• The interactive launcher script for quick navigation is launched on first login.
• You can go straight to setup, launch desktop environment, do environment management or leave to shell.

3.5.1 Launch Desktop Environment / Remote VNC Access

Gnome, Plasma, Sway and Xfce are supported.

• VNC is automatically launched with starting Xorg.
  • Connect with your VNC client and use password:archboot
  • Edit /etc/archboot/defaults to change default vnc password.
• On Wayland environments VNC is only available in Sway.
  • Connect with your VNC client without user and password.
• On MacOS/Windows you can use RealVNC for passwordless login.

3.5.2 Manage Archboot Environment

3.5.2.1 Full Arch Linux System

• The Archboot system is stripped down to minimal space usage.
• Though perl, python, man/info pages, includes, additional kernel modules (eg. sound)
  and other things are not provided by default.
• This will also stop cleaning the system, while running other update tasks.

3.5.2.2 Update Archboot Environment

• The Archboot Environment will be updated to latest packages.
• Depending on the available RAM, you will get the new system with or without package cache.
• The new system will be booted through kexec.

3.5.2.3 Create New Images

• You will get new images with latest packages.

3.6 Interactive Setup

• The interactive setup script is used for installation.
• You can run each menu point for doing the mentioned task.
• If you do a fresh install, it is recommended to run each point in the order as presented.

3.6.1 Prepare Storage Drive

• You prepare your storage drive, filesystems and define your mountpoints.
• Quick Setup, manual partitioning, GUID (GPT) support, MBR (BIOS) support,
  Advanced Format 4k sector drive support etc.
• Persistent block device naming support: PARTUUID, PARTLABEL, UUID, LABEL and KERNEL
• Creation of software RAID/RAID partitions, LVM devices and LUKS encrypted devices
• Supports standard linux, RAID/RAID_partitions, dmraid/fakeraid, LVM and LUKS encrypted devices
• Filesystem support: BTRFS, EXT2/3/4, F2FS, NILFS2, XFS, JFS, VFAT

3.6.2 Install Packages

• You can modify the packages to install in /etc/archboot/defaults.
• Pacman will install the packages for the first boot to your storage drive.
• Autoconfiguration of basic system will be done:
  Locale, Linux console, Bash, Keymap, Timezone, Fstab, SSD performance, Swap performance, Systemd,
  Pacman, Network, Crypttab and Mdadm

3.6.3 Configure System

• You set the root password.
• Preconfiguration of mkinitcpio.conf and KMS mode is done by the hwdetect script
• Choose your text editor: nano or neovim
• Configuration of basic system files:
  hostname, Linux console, locale.conf, fstab, mkinitcpio.conf, modprobe.conf,
  resolv.conf, hosts, Locale, mirrors, pacman.conf

3.6.4 Install Bootloader

• You configure your preferred bootloader.
• Microcode and other needed programs will be installed automatically.
• GPT UEFI supported bootloaders: GRUB, Limine, rEFInd, Systemd-boot, Unified Kernel Image
• MBR BIOS supported bootloaders: GRUB, Limine
• Secure Boot supports only shim signed by fedora with GRUB
• The selected bootloader will be installed to your system and you can modify the configuration file(s) afterwards.
• Pacman hooks for automatic bootloader upgrade will be enabled by default.

3.7 For Experts: Quickinst Installation

• This script is for experts, who assemble the filesystems first and mount them in a directory.
• quickinst will autodetect the packages to install for a minimal system.

3.8 For Experts: CLI Manage Environment

You can always bump your image to latest available possibilities.

3.9 Tools For Backup And Copying Of An Existing System

Archboot provides 2 additional scripts for doing those tasks.

3.10 Restoring An USB Device To FAT32 State

• When you have used the .iso image to create an USB installer, your USB stick is no longer useful for anything else.
• Any remaining space on the stick (supposing you used a larger-than the .img file) is inaccessible.
• Check carefully which device actually is your USB stick.

3.11 System Configuration On Installed System

You can also run archboot-setup.sh for system configuration on an installed system.

Install your corresponding archboot package for getting the archboot-setup.sh script.

4. FAQ / Known Issues / Limitations

Please check the forum threads or project page for posted fixes and workarounds.

• The screen stays blank or other weird screen issues happen?
  Some hardware does not like the KMS activation. Use one of the following kernel parameters:
  radeon.modeset=0, i915.modeset=0, amdgpu.modeset=0 or nouveau.modeset=0

• Your system hangs during the boot process?
  Any combinations of the following kernel parameters may be useful:
  noapic, nolapic, acpi=off, pci=routeirq, pci=nosmp or pci=nomsi

• Package XYZ is missing in archboot environment.
  Install the missing package as needed. For example, archinstall is not included by default.
  It needs python3, which is a large dependency.

• Parallels Desktop might have keyboard issues.
  Workaround: Use COMMAND+TAB to switch out of the VM and reactivate the parallels window.

• UTM does not work with Apple virtualization.
  The AARCH64 kernel does not seem to support this feature. This cannot be fixed on archboot side.

• dmraid/fakeraid/biosraid might not work on some boards.
  mdadm only supports some isw and ddf fakeraid chipsets.

• How much RAM is needed to boot <EFI> or <INITRD>?
  The calculated size to boot the image follows the formula:
  Initrd + Kernel + Unpackedkernel + Unpackedinitrd = minimum RAM to boot

5. Comparison To Archiso Image

★ Optional | ¹ Only local image | ² Acer R11 Chromebook 4GB RAM

³ QEMU (4GB RAM, kvm and virtio backend), normal image

6. Development: GIT And Bugtracker

• GIT repository can be found at Arch Linux Gitlab or Github .
• Use the Arch Linux Gitlab Bugtracker for filling bugs.

7. Package - Repository / Installation / Usage

• Install the archboot package on x86_64 hardware.
• Install the archboot-arm package on aarch64 hardware.
• Install the archboot-riscv package on riscv64 hardware.
• Install the qemu-user-static package for building aarch64 or riscv64 images on x86_64 hardware.

If you want to build aarch64 or riscv64 images replace x86_64 with the architecture of your choice in the commands and files below.

7.1 Create Rescue System Out Of The Running System

Add your used kernel and initrd to your bootloader.

7.2 Create Image Files

7.2.1 Requirement

In order to build images you will need around 3G free space on disk.

7.2.2 Create Image Files Without Modifications

This script creates every installation media with latest available core/extra packages and boot/ directory with kernel and initrds.

7.2.3 Create Image Files With Modifications:

Explanation of the image tools / toolchain.

7.2.3.1 archboot-x86_64-create-container.sh

Modify your container to your needs. Then run archboot-x86_64-iso.sh for image creation in container.

7.2.3.2 Configuration Files For Image Creation:

• /etc/archboot/defaults: defaults for packages, bootloader config and server setup.
• /etc/archboot/<profile>.conf: contains the _KERNEL and the _HOOKS, which are used for the initrd.

7.2.3.3 archboot-cpio.sh

• objdump is used for library detection. It's faster than ldd!
• libraries for binaries outside of bin/ are not detected!
• libraries outside of lib/ are not checked!
• tar is used for copying/renaming files and directories. It's faster than install and cp!
• mkdir is used for creating directories. It's faster than install!

7.2.3.4 archboot-x86_64-iso.sh

Script for image creation from running system or for use in archboot container.

7.3. Setting Up An Image Server

7.3.1 Requirements

• You have a normal user, which has access to a working gpg setup with own signature.
• You have a normal user with ssh access to the server, on which the images should upload.
• Add the directories on the remote server, you want to upload to.

7.3.2 Configuration File

You need to configure all your settings in the configuration file: /etc/archboot/defaults

7.3.3 Running Commands

7.3.3.1 X86_64 Architecture

7.3.3.2 Aarch64/Riscv64 Architecture

• You have to skip the tarball creation step, on aarch64 or riscv64 hardware.
• Install the qemu-user-static package, for building on x86_64 hardware.
• On first time setup you need to create the pacman-aarch64-chroot tarball on x86_64 hardware.

Afterwards you only have to run for each release:

7.3.3.3 Server Cleanup

The /etc/archboot/defaults file defines old images purging after 1 month.

8. Testing Image And Files With QEMU

You can run QEMU tests at different stages of ISO creation.

8.1 Running AARCH64:

Install the edk2-armvirt package.

8.2 Running RISCV64:

Use ssh root@localhost -p 2222 to connect to machine from your running host.

8.3 Running X86_64:

8.3.1 Running Kernel, BIOS MBR, UEFI GPT Without Secure Boot:

8.3.2 UEFI GPT Secure Boot

The file already includes a basic set of keys from fedora ovmf package.

8.4 Additional Qemu Parameters

8.5 Setting Up A Hwsim SSID

9. Arch Linux Wiki

• Installation Guide
• Improving performance
• Dual boot
• Secure Boot
• Unified Kernel Image / UKI
• Serial console
• Parallels Desktop
• QEMU
• VirtualBox
• VMware
• Gnome
• KDE/Plasma
• Xfce
• VNC
• Wayland

10. Project Links

• Blog
• Development
• Download
• Screenshots
• Build Sources
• Repository

11. Videos

• Parallels installation on Macbook M1
• UTM installation on Macbook M1
• Running local image

12. History

• Official Arch Linux install medium from Release 0.7 till 2008.03.
• Provided i686 and x86_64 on one ISO until 2018.
• Since 10-2021 Secureboot support.
• Since 01-2022 aarch64 support.
• Since 10-2022 riscv64 support.

13. References

• Qemu display devices
• Qemu on RISC-V