Alpine Linux - User contributions [en]

How to make a custom ISO image with mkimage

2020-08-02T22:37:17Z

Ferneu: /* Create the ISO */

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

== Prerequisite ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk build-base apk-tools alpine-conf busybox fakeroot syslinux xorriso squashfs-tools}}
For efi you should add
{{Cmd|mtools dosfstools grub-efi}}

Create a user (e.g. build) and add it to abuild group:
{{Cmd|adduser build -G abuild}}

Then create signing keys (-i installs them in /etc/apk/keys which is required for later)
{{Cmd|abuild-keygen -i -a}}

{{Tip| Make sure your public keys are placed in /etc/apk/keys/ (example: build-xxxxxxxx.rsa.pub)}}
{{Cmd|ls /etc/apk/keys/}}

Clone (or update) the [http://git.alpinelinux.org/cgit/aports/ git repository].
{{Cmd|git clone git://git.alpinelinux.org/aports}}

Make sure the apk index is up to date (so apk finds the packages):
{{Cmd|apk update}}

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

So, in order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

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

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs spl"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux unrar 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"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

Set the script as executable:
{{Cmd|chmod +x mkimg.$PROFILENAME.sh}}

== 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="genapkovl-mkimgoverlay.sh"`

The definition may be done as in the [https://git.alpinelinux.org/aports/tree/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` 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 ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --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 only there for backward-compatibility.}}

Create a iso directory in your home dir:

{{Cmd|mkdir -p ~/iso}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository http://dl-cdn.alpinelinux.org/alpine/edge/main \
--profile $PROFILENAME
}}

'''Notes:'''

Of course, several passages of this doc can be automated with a script, like the repository/arch/outdir settings.
This steps are left to you and to your imagination :)

== Testing your ISO image ==

[[Qemu#Live_mode| Qemu]] is useful for a quick test of your created ISO image.

[[Category:Package Manager]]
[[Category:ISO]]

How to make a custom ISO image with mkimage

2020-08-02T22:36:05Z

Ferneu: /* Create the ISO */

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

== Prerequisite ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk build-base apk-tools alpine-conf busybox fakeroot syslinux xorriso squashfs-tools}}
For efi you should add
{{Cmd|mtools dosfstools grub-efi}}

Create a user (e.g. build) and add it to abuild group:
{{Cmd|adduser build -G abuild}}

Then create signing keys (-i installs them in /etc/apk/keys which is required for later)
{{Cmd|abuild-keygen -i -a}}

{{Tip| Make sure your public keys are placed in /etc/apk/keys/ (example: build-xxxxxxxx.rsa.pub)}}
{{Cmd|ls /etc/apk/keys/}}

Clone (or update) the [http://git.alpinelinux.org/cgit/aports/ git repository].
{{Cmd|git clone git://git.alpinelinux.org/aports}}

Make sure the apk index is up to date (so apk finds the packages):
{{Cmd|apk update}}

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

So, in order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

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

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs spl"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux unrar 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"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

Set the script as executable:
{{Cmd|chmod +x mkimg.$PROFILENAME.sh}}

== 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="genapkovl-mkimgoverlay.sh"`

The definition may be done as in the [https://git.alpinelinux.org/aports/tree/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` 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 ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --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}}

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

Create a iso directory in your home dir:

{{Cmd|mkdir -p ~/iso}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository http://dl-cdn.alpinelinux.org/alpine/edge/main \
--profile $PROFILENAME
}}

'''Notes:'''

Of course, several passages of this doc can be automated with a script, like the repository/arch/outdir settings.
This steps are left to you and to your imagination :)

== Testing your ISO image ==

[[Qemu#Live_mode| Qemu]] is useful for a quick test of your created ISO image.

[[Category:Package Manager]]
[[Category:ISO]]