How to make a custom ISO image

This document explains how to build a custom ISO image using the alpine-iso scripts.

First make sure we have the needed tools

apk add alpine-sdk xorriso syslinux

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

abuild-keygen -i

Clone (or update) the alpine-iso git repository.

git clone git://git.alpinelinux.org/alpine-iso

The alpine-iso scripts is a simple makefile which you need to feed with a <name>.conf.mk file and a <name>.packages.

In the <name>.conf.mk we specify

ALPINE_NAME

name of iso image

ALPINE_VERSION

(optional) version string. Will default to todays date.

KERNEL_FLAVOR

(optional) either grsec, vserver or pae. Will default to grsec.

MODLOOP_EXTRA

(optional) Extra kernel module packages for the modloop image. For example: dahdi-linux-vserver

APK_REPOS

(optional) Path to addidtional apk repository.

The <name>.packages is just a plaintext list of packages that should be included in the ISO image. You should always add alpine-base in there or the CD might not be able to boot. The dependencies for the packages will automatically be pulled in.

A rescue CD example

As an example, let us make a rescue ISO image with packages needed for rescue operations. We call it alpine-rescue

We create the alpine-rescue.conf.mk as follows:

ALPINE_NAME   := alpine-rescue
KERNEL_FLAVOR := grsec
MODLOOP_EXTRA :=

If you are going to use a custom kernel, don't forget to specify KERNEL_FLAVOR_DEFAULT which will set the default kernel to boot.

And then the alpine-rescue.packages as:

alpine-base
bkeymaps
openssh
e2fsprogs
mdadm
lvm2
parted
debootstrap
ntfs-3g

Tip: Make sure your public keys are placed in /etc/apk/keys/ (example: root-xxxxxxxx.rsa.pub):

ls /etc/apk/keys/

Learn apk-tools to find your home-built apk's:

echo "~/.cache/abuild/" >> /etc/apk/repositories

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

apk update

We create the ISO image by telling the makefile the profile name. The makefile target is iso.

make PROFILE=alpine-rescue iso

Tip: If you are building inside an LXC guest, use fakeroot:

fakeroot make PROFILE=alpine-rescue iso

To generate the sha1 sum we use the sha1 make target.

make PROFILE=alpine-rescue sha1

Package lists

Beside the plaintext package lists in the git repository, there are more documented package lists contributed by Alpine users. Those lists can be transformed into a plaintext to use with alpine-iso list with the simple python-based config-builder script.

So far the lists below are available (check here for more.)

• Alpine Mini
• Alpine Rescue
• Alpine Security
• Alpine SCST

Live Disk

Once you have customized your custom ISO, you can now setup the live environment to operate outside of the standard installer as follows:

• Generate an APKOVL file with lbu, lbu ci
• Alpine ISO requires the OVL Volume to be hosted on a web server. Put the APKOVL file on a webserver and identify the url.
• Uncomment the APKOVL line in the alpine flavor of your choice and set it to the address of your ovl volume.

Notes:

• Any packages you add to /etc/apk/world of your lbu will automatically be installed onto the live system image.
• If you don't have a web server you can run busybox's httpd temporarily - busybox -p 127.0.0.1:80
• In general, lbu will only handle files in /etc, to customize this further, you need to add additional files.
• 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.

Testing your ISO image

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