View source for Alpine Linux in a chroot

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

Before made and enter into the chrooted system must be prepared with device nodes and tempfs :

==== 1.A fast way: using bind mount ====

{{Warning|Mounts with bind, can mount in read-only the /dev at the alpine chroot so due limited will not touch the  access time of the host system}}

{{Cmd|mount /dev/ /alpine/dev/ --bind
mount -o remount,ro,bind /alpine/dev
}}

If you need SCSI or R/W access only do the first command, mounting with "ro" makes more secure your chroot.

==== 1.B manual way: creating need nodes ====

{{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}}

==== 2. Made available proc and sys fs ====

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

==== 3. Make networking resolution access ====

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

==== 4. prepare the apk sources software ====

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. 

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

== chroot: cannot run command ' ... Exec format error ==

This usually indicates that you booted with one architecture (e.g. armf) and are trying to chroot into another (e.g. x86_64). If you plans to make chroot into another installation must use same arch for both host and hosted chrooted!

Note that with one exception you can run 32 bit x86 chroot in x86_64, but not viceversa!

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

= External links =

* https://web.archive.org/web/20190808203313/https://isc.sans.edu/forums/diary/Forensic+use+of+mount+bind/22854/
[[Category:Installation]]