Alpine Linux - User contributions [en]

Alpine Linux in a chroot

2019-01-13T17:52:51Z

Emolitor:

This document explains how to set up an Alpine build environment in a chroot under a different Linux distro, such as Arch, Debian, Fedora, Gentoo, or Ubuntu. Once inside the chroot environment, you can build, debug, and run alpine packages. The guide can also be used to install Alpine Linux from a non-Alpine Linux livecd such as Ubuntu or System rescue CD.

This example installation of Alpine Linux in a chroot will work with the latest release. But it's also possible to make a chroot with '''[[Edge|edge]]''' or older releases of Alpine Linux to test backports.

You can also use script [https://github.com/alpinelinux/alpine-chroot-install/ alpine-chroot-install] that simplifies this process to just two commands. This script is useful especially on CI environment (e.g. Travis CI).

== Requirements ==
For the base Alpine Linux you will only need around 6MB of free space; though to build packages you'll need at least 500 MB.

== Prerequisites ==
The variables below:

*'''${chroot_dir}''' = Should point to the chroot directory where you
*'''${mirror}''' = Should be replaced with [http://nl.alpinelinux.org/alpine/MIRRORS.txt one of the available Alpine Linux mirrors].

== Set up APK ==

{{Tip|In the command below, replace x86_64 with x86 if running on a 32 bit installation}}

{{Warning|You will need Kernel version 2.6.22 or later to use apk-tools-static}}

Download the latest apk static package (replace <tt>${version}</tt> with actual version):

{{Cmd|wget ${mirror}/latest-stable/main/x86_64/apk-tools-static-${version}.apk}}

.apk packages are just gzipped tarballs, unpack using:
{{Cmd|tar -xzf apk-tools-static-*.apk}}

== Install the alpine base installation onto the chroot ==

{{Cmd|./sbin/apk.static -X ${mirror}/latest-stable/main -U --allow-untrusted --root ${chroot_dir} --initdb add alpine-base}}

== Set up the chroot ==

Set up some devices in the chroot
{{Tip|Manually creating devices is not needed if you choose to mount /dev of the hosts in the chroot described later.}}

{{Cmd|mknod -m 666 ${chroot_dir}/dev/full c 1 7
mknod -m 666 ${chroot_dir}/dev/ptmx c 5 2
mknod -m 644 ${chroot_dir}/dev/random c 1 8
mknod -m 644 ${chroot_dir}/dev/urandom c 1 9
mknod -m 666 ${chroot_dir}/dev/zero c 1 5
mknod -m 666 ${chroot_dir}/dev/tty c 5 0}}

If you need SCSI disc access:

{{Cmd|mknod -m 666 ${chroot_dir}/dev/sda b 8 0
mknod -m 666 ${chroot_dir}/dev/sda1 b 8 1
mknod -m 666 ${chroot_dir}/dev/sda2 b 8 2
mknod -m 666 ${chroot_dir}/dev/sda3 b 8 3
mknod -m 666 ${chroot_dir}/dev/sda4 b 8 4
mknod -m 666 ${chroot_dir}/dev/sda5 b 8 5
mknod -m 666 ${chroot_dir}/dev/sda6 b 8 6
mknod -m 666 ${chroot_dir}/dev/sdb b 8 16
mknod -m 666 ${chroot_dir}/dev/sdb1 b 8 17
mknod -m 666 ${chroot_dir}/dev/sdb2 b 8 18
mknod -m 666 ${chroot_dir}/dev/sdb3 b 8 19
mknod -m 666 ${chroot_dir}/dev/sdb4 b 8 20
mknod -m 666 ${chroot_dir}/dev/sdb5 b 8 21
mknod -m 666 ${chroot_dir}/dev/sdb6 b 8 22}}

A resolv.conf is needed for name resolution:

{{Cmd|cp /etc/resolv.conf ${chroot_dir}/etc/
mkdir -p ${chroot_dir}/root}}

If you don't want to copy the resolv.conf from the local machine, you can create a new one using OpenDNS servers (or any other):
{{Cmd|echo -e 'nameserver 208.67.222.222\nnameserver 2620:0:ccc::2' > ${chroot_dir}/etc/resolv.conf}}

Set up APK mirror (replace <tt>${branch}</tt> with the latest stable branch name, e.g. v3.3):

{{Cmd|mkdir -p ${chroot_dir}/etc/apk
echo "${mirror}/${branch}/main" > ${chroot_dir}/etc/apk/repositories}}

== Entering your chroot ==
At this point, Alpine has been succesfully installed onto the chroot directory. Before you chroot in you
will probably want to mount /proc and /sys in the chroot:

{{Cmd|mount -t proc none ${chroot_dir}/proc
mount -o bind /sys ${chroot_dir}/sys}}

If you don't want to create special device files yourself, mount the hosts device directory onto the chroot:
{{Cmd|mount -o bind /dev ${chroot_dir}/dev}}

You can now chroot:
{{Cmd|chroot ${chroot_dir} /bin/sh -l}}

To make the system actually bootable, we need to add some initscripts to appropriate runlevels:
{{Cmd|rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown}}

Alpine Linux has a great meta-package for building Alpine packages from source available called alpine-sdk. To install, run:
{{Cmd|apk add alpine-sdk}}

If you are using Alpine as a Native build system you will have to make sure that chroot can run chmod. Add following to /etc/sysctl.conf

kernel.grsecurity.chroot_deny_chmod = 0

Then run the following command

{{Cmd|sysctl -p}}

== Alpine Linux in a chroot on Fedora ==

If you want to generate a chroot on a Fedora based system, you can use this [http://git.alpinelinux.org/cgit/user/fab/scripts/tree/alpine-chroot.sh script].

{{Note|Maybe you are able to use this script on other distribution but this is not tested.}}

== Alpine Linux aarch64 in a chroot on AWS Linux ==
If you want to generate a aarch64 chroot on most systems you can use this [https://gist.github.com/emolitor/0567e51c0ce04f4b025fc78d2cf0b4f1 script].

{{Note|I'm currently using this to test my aarch64 packages but it should be useful for others.}}

= Troubleshooting =
== WARNING: Ignoring APKINDEX.xxxx.tar.gz ==
Make sure <tt>${chroot_dir}/etc/apk/repositories</tt> is valid and inside the chroot run:
{{Cmd|apk update}}

[[Category:Installation]]

Create UEFI secureboot USB

2018-12-31T10:39:25Z

Emolitor: /* Install the Keys and Enroll Hash */

This article explains how to create an UEFI boot USB with parted and rEFInd. Unfortunately the version of GRUB that ships with ALpine Linux did not work and Gummiboot only worked on one of two machines I tested. I will submit a PR for a rEFInd package and update these instructions to simplify them given time.

In this example we will use {{Path|/dev/sdX}} and $HOME. This will be different depending on your system. Substitute the paths in the examples below as necessary.

== Create GPT boot partition ==

Install {{Pkg|parted}}
{{Cmd | apk add parted }}

Create a single UEFI boot partitions.
{{warning| This will erase all content of your {{Path|/dev/sdX}}. Make sure that you use correct device.}}

{{Cmd | parted --script /dev/sdX mklabel gpt
parted --script --align{{=}}optimal /dev/sdX mkpart ESP fat32 1MiB 100%
parted --script /dev/sdX set 1 boot on }}

== Create fat32 filesystem ==

Create a fat32 system with the name `Alpine`.

{{Cmd | mkfs.vfat -n ALPINE /dev/sdX1 }}

== Copy content of ISO image to filesystem ==

It is possible to mount the iso image and copy files with {{codeline|cp}} or {{codeline|rsync}} and it is also possible to use {{codeline|7z}} to extract content from the iso. In this example I will use the {{codeline|uniso}} utility from {{Pkg|alpine-conf}} package.

{{Cmd | mount -t vfat /dev/sdX1 /mnt
cd /mnt
uniso < /path/to/alpine-3.8.2-x86_64.iso }}

== Create MOK Key ==
{{Cmd | openssl req -new -x509 -newkey rsa:2048 -keyout $HOME/alpine_local.key -out $HOME/alpine_local.crt -nodes -days 3650 -subj "/CN{{=}}Alpine Local CA/"
openssl x509 -in $HOME/alpine_local.crt -out $HOME/alpine_local.cer -outform DER}}

== Download and install rEFInd ==
Download the binary zip file of rEFInd from http://www.rodsbooks.com/refind/getting.html. In this example we will use the current version of rEFInd, refind-bin-0.11.4.zip. There may be a more recent version of rEFInd available when you download.

{{Cmd | cd /mnt/efi/boot
unzip /path/to/refind-bin-0.11.4.zip
mv refind-bin-0.11.4/refind/* .
rm -rf refind-bin-0.11.4}}

== Copy signed shim ==
Download Matthew J. Garrett's signed shim from http://www.codon.org.uk/~mjg59/shim-signed/shim-signed-0.2.tgz. In this example we assume it is stored in your users download directory. Substitute the paths in the example below as necessary.

{{Cmd | cd /mnt/efi/boot
gunzip -c /path/to/shim-signed-0.2.tgz | tar x --strip-components{{=}}1 --no-same-owner}}

== Install Shim and Certificate ==
{{Cmd | cp $HOME/alpine_local.cer /mnt/efi/boot
cp /mnt/efi/boot/refind_x64.efi /mnt/efi/boot/grubx64.efi
cp /mnt/efi/boot/shim.efi /mnt/efi/boot/bootx64.efi }}

== Sign the Bootloader and kernel with your key ==
{{Cmd | sbsign --key $HOME/alpine_local.key --cert $HOME/alpine_local.crt /mnt/efi/boot/grubx64.efi
mv /mnt/efi/boot/grubx64.efi.signed /mnt/efi/boot/grubx64.efi
sbsign --key $HOME/alpine_local.key --cert $HOME/alpine_local.crt /mnt/boot/vmlinuz-vanilla
mv /mnt/boot/vmlinuz-vanilla.signed /mnt/boot/vmlinuz-vanilla}}

== Unmount the partition ==
Finally umount the disk
{{Cmd | cd ~ && umount /mnt}}

== Install the Keys and Enroll Hash ==
Insert the USB into the target PC and boot. When prompted select to enroll key, navigate to alpine_local.cer and add it. Then select enroll hash navigate to efi/boot/grubx64.efi select it and add the hash. Now reboot and given a bit of luck it should launch alpine. This step is a bit more complex than it needs to be due to the binary distribution of refind already being signed by the authors key. Once rEFInd is packaged it should simplify this step.

[[Category:Installation]]

Create UEFI secureboot USB

2018-12-31T10:38:01Z

Emolitor: /* Unmount the partition */

Create UEFI boot USB

2018-12-30T13:46:51Z

Emolitor:

Create UEFI boot USB

2018-12-30T13:46:03Z

Emolitor: Undo revision 15618 by Emolitor (talk)

Create UEFI secureboot USB

2018-12-30T13:45:24Z

Emolitor: Blanked the page

Create UEFI secureboot USB

2018-12-30T13:36:17Z

Emolitor: Created page with "test"

test

Create UEFI boot USB

2018-12-30T13:35:56Z

Emolitor:

This article explains how to create an UEFI boot USB with parted and gummiboot.

In this example we will use {{Path|/dev/sdX}}. This will be different depending on your system.

== Create GPT boot partition ==

Install {{Pkg|parted}}
{{Cmd | apk add parted }}

Create a single UEFI boot partitions.
{{warning| This will erase all content of your {{Path|/dev/sdX}}. Make sure that you use correct device.}}

{{Cmd | parted --script /dev/sdX mklabel gpt
parted --script --align{{=}}optimal /dev/sdX mkpart ESP fat32 1MiB 100%
parted --script /dev/sdX set 1 boot on }}

== Create fat32 filesystem ==

Create a fat32 system with the name `Alpine`.

{{Cmd | mkfs.vfat -n ALPINE /dev/sdX1 }}

== Copy content of ISO image to filesystem ==

It is possible to mount the iso image and copy files with {{codeline|cp}} or {{codeline|rsync}} and it is also possible to use {{codeline|7z}} to extract content from the iso. In this example I will use the {{codeline|uniso}} utility from {{Pkg|alpine-conf}} package.

{{Cmd | mount -t vfat /dev/sdX1 /mnt
cd /mnt && uniso < /path/to/alpine-3.4.0-x86_64.iso }}

== Copy gummiboot efi binary ==

{{note| Gummiboot has been forked in Alpine Linux since it has been [https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/ consumed by systemd upstream].}}

UEFI will look for a {{Path|EFI/bootx64.efi}} as a fallback efi loader. We copy {{Path|gummibootx64.efi}} to this location.

{{Cmd | mkdir -p /mnt/EFI/Boot
apk add gummiboot
cp /usr/lib/gummiboot/gummibootx64.efi /mnt/EFI/Boot/bootx64.efi }}

== Create configuration files for boot loader ==

We need create some configuration files for gummiboot.
{{Cmd | mkdir -p loader/entries }}

{{Cat | loader/loader.conf |default alpine
timeout 4
}}

The options are taken from {{Path|boot/syslinux/syslinux.cfg}}

{{Cat | loader/entries/alpine.conf |title Alpine Linux
linux /boot/vmlinuz-hardened
initrd /boot/initramfs-hardened
options modloop{{=}}/boot/modloop-hardened modules{{=}}loop,squashfs,sd-mod,usb-storage quiet
}}

Finally umount the disk
{{Cmd | cd ~ && umount /mnt}}

[[Category:Installation]]

Create UEFI boot USB

2018-12-30T13:35:41Z

Emolitor: Update instructions for modern Alpine images which already include grub-efi

File:Final USB Explorer.png

2018-12-29T11:45:35Z

Emolitor:

Final version of what your USB drive should look like.

File:USB-Explorer.png

2018-12-29T11:31:51Z

Emolitor:

When complete the USB drive in explorer should look like this.

File:File Explorer.png

2018-12-29T11:21:30Z

Emolitor:

Your file explorer should look something like this after extracting everything.

File:Rufus Screenshot.jpg

2018-12-29T11:12:23Z

Emolitor:

Rufus screenshot with partition scheme set to GPT