Alpine Linux - User contributions [en]

How to make a custom ISO image

2017-05-06T16:43:12Z

Mauli: /* Live Disk Setup with APKOVL */

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

== Prerequisite ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk xorriso syslinux}}

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

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

== Core Configuration ==

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):
{{Cmd|ls /etc/apk/keys/}}

Learn apk-tools to find your home-built apk's:
{{Cmd|echo "~/.cache/abuild/" >> /etc/apk/repositories}}
}}

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

We create the ISO image by telling the makefile the profile name. The makefile target is ''iso''.
{{Cmd|<nowiki>make PROFILE=alpine-rescue iso</nowiki>}}

{{Tip| If you are building inside an LXC guest, use fakeroot:
{{Cmd|<nowiki>fakeroot make PROFILE=alpine-rescue iso</nowiki>}}
}}

To generate the sha256 sum we use the ''sha256'' make target.
{{Cmd|<nowiki>make PROFILE=alpine-rescue sha256</nowiki>}}

== 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 plain text description by <code>apk search --exact -v $(cat alpine.packages)</code>.

So far the lists below are available (check [[:Category:ISO|here]] for more.)

* [[Alpine_mini|Alpine Mini]]
* [[Alpine_rescue|Alpine Rescue]]
* [[Alpine_security|Alpine Security]]
* [[Alpine SCST]]

== Live Disk Setup with APKOVL ==

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 [[Alpine_local_backup|lbu]], <code>lbu ci</code>
* 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 <code>APKOVL</code> 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 - <code>busybox httpd -p 127.0.0.1:80</code>
* In general, <code>lbu</code> will only handle files in <code>/etc</code>, to customize this further, you need to add additional files.
* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

== 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

2017-05-05T22:07:34Z

Mauli: /* A rescue CD example */

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

== Prerequisite ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk xorriso syslinux}}

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

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

== Core Configuration ==

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):
{{Cmd|ls /etc/apk/keys/}}

Learn apk-tools to find your home-built apk's:
{{Cmd|echo "~/.cache/abuild/" >> /etc/apk/repositories}}
}}

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

We create the ISO image by telling the makefile the profile name. The makefile target is ''iso''.
{{Cmd|<nowiki>make PROFILE=alpine-rescue iso</nowiki>}}

{{Tip| If you are building inside an LXC guest, use fakeroot:
{{Cmd|<nowiki>fakeroot make PROFILE=alpine-rescue iso</nowiki>}}
}}

To generate the sha256 sum we use the ''sha256'' make target.
{{Cmd|<nowiki>make PROFILE=alpine-rescue sha256</nowiki>}}

== 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 plain text description by <code>apk search --exact -v $(cat alpine.packages)</code>.

So far the lists below are available (check [[:Category:ISO|here]] for more.)

* [[Alpine_mini|Alpine Mini]]
* [[Alpine_rescue|Alpine Rescue]]
* [[Alpine_security|Alpine Security]]
* [[Alpine SCST]]

== Live Disk Setup with APKOVL ==

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 [[Alpine_local_backup|lbu]], <code>lbu ci</code>
* 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 <code>APKOVL</code> 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 - <code>busybox -p 127.0.0.1:80</code>
* In general, <code>lbu</code> will only handle files in <code>/etc</code>, to customize this further, you need to add additional files.
* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

== Testing your ISO image ==

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

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