How to make a custom ISO image with mkimage

From Alpine Linux
Revision as of 13:12, 6 July 2022 by Psykose (talk | contribs) (apk add)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This document explains how to build a custom ISO image using the new mkimage scripts located in aports directory.


First make sure we have the needed tools (community repositories is required for 'sudo')

apk add alpine-sdk build-base apk-tools alpine-conf busybox fakeroot syslinux xorriso squashfs-tools sudo

For efi you should add the following:

apk add mtools dosfstools grub-efi

Create a user (e.g. build) and add them to the abuild group:

adduser build -G abuild

Give administrative access to the abuild group:

echo "%abuild ALL=(ALL) ALL" > /etc/sudoers.d/abuild

Change to the build user:

su - build

Then create signing keys (-i installs them in /etc/apk/keys which is required for later)

abuild-keygen -i -a

Tip: Make sure your public keys are placed in /etc/apk/keys/ (example:

ls /etc/apk/keys/

Clone (or update) the git repository.

git clone --depth=1

Make sure the apk index is up to date (so apk can find the packages):

sudo apk update


The mkimg scripts are shipped with pre-configured profiles.

The format is mkimg.$

In order to have a custom ISO, you should create your own mkimg.$ script.

This is an example used to make a ZFS module, overlayfs (which enables r/w mode for /lib/modules), a serial console output and some other useful apks to build a simple NAS:

export PROFILENAME=nas
cat << EOF > ~/aports/scripts/mkimg.$
profile_$PROFILENAME() {
        kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
        syslinux_serial="0 115200"
        apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
                cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
                parted rsync sfdisk syslinux util-linux xfsprogs
                dosfstools ntfs-3g
        local _k _a
        for _k in \$kernel_flavors; do
                apks="\$apks linux-\$_k"
                for _a in \$kernel_addons; do
                        apks="\$apks \$_a-\$_k"
        apks="\$apks linux-firmware"

Set the script as executable:

chmod +x ~/aports/scripts/mkimg.$

Making packages available on boot

A package may be made available in the live system by defining the generation of an apkovl which contains a corresponding /etc/apk/world file, and adding that overlay definition to the mkimg-profile, e.g. with `apkovl=""`

Note that to *use* your added apks, you have to install them, with apk add.

The definition may be done as in the example. Copy the relevant parts (including the rc_add lines) into a `` file and add the package(s) that should be installed in the live system on separate lines in the file contents for /etc/apk/world.

Create the ISO [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR] [--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate] [--repository REPO] [--extra-repository REPO] [--yaml FILE] --help options: --arch Specify which architecture images to build (default: x86_64) --hostkeys Copy system apk signing keys to created images --outdir Specify directory for the created images --profile Specify which profiles to build --repository Package repository to use for the image create --extra-repository Add repository to search packages from --simulate Don't execute commands --tag Build images for tag RELEASE --workdir Specify temporary working directory (cache) --yaml known profiles: ali rpi uboot base minirootfs standard vanilla extended virt xen

Tip: You can use the --repository option multiple times, which is very useful when mixing local and official repositories. The --extra-repository option is there only for backward-compatibility.

Create an iso directory in your home dir:

mkdir -p ~/iso

Then create the actual ISO. In this example we will use the edge version x86_64:

sh aports/scripts/ --tag edge \ --outdir ~/iso \ --arch x86_64 \ --repository \ --profile $PROFILENAME


  • If you want to make a customized installer, you need to create .default_boot_services which will cause mkinitfs to create the defaults for the live image.
  • Several parts of this doc can be automated with a script, like the repository/arch/outdir settings.

Those steps are left to you and your imagination :)

Testing your ISO image

QEMU is useful for a quick test of your newly created ISO image.