Alpine Linux in a chroot: Difference between revisions

From Alpine Linux
m (fix package name)
No edit summary
(29 intermediate revisions by 9 users not shown)
Line 1: Line 1:
This document explains how to set up an Alpine build environment in a chroot under a "normal" Linux distro, such as Arch, Debian, Fedora, Gentoo, or Ubuntu. Once inside the chroot environment, you can build, debug, and run alpine packages.
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.


== Requirements ==
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 will need a few gigabytes of free disk space to have enough space for kernel compiling and storing all the binary packages.


== Creating the installation ==
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).
This example installation of Alpine Linux in a chroot will work with the lastest release. But it's also possible to make a chroot with '''[[Edge|edge]]''' or older releases of Alpine Linux to test backports.


'''Note:''' The variables below:
== 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.


*'''${build_dir}''' = You can name it whatever you like.
== Prerequisites ==
*'''${mirror}''' = Should be replaced with one of the available Alpine Linux mirrors.
The variables below:


Choose a mirror from the [http://dl-2.alpinelinux.org/alpine/MIRRORS.txt mirror list].
*'''${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].


Let's start by getting the latest apk static package:
== Set up APK ==


{{Tip|In the command below, replace x86_64 with x86 if running on a 32 bit installation}}
{{Tip|In the command below, replace x86_64 with x86 if running on a 32 bit installation}}
Line 20: Line 20:
{{Warning|You will need Kernel version 2.6.22 or later to use apk-tools-static}}
{{Warning|You will need Kernel version 2.6.22 or later to use apk-tools-static}}


{{Cmd|wget http://dl-3.alpinelinux.org/alpine/v2.4/main/x86_64/apk-tools-static-2.3.3-r0.apk}}
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}}


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


We are setting up a basic chroot:
== Install the alpine base installation onto the chroot ==


{{Cmd|mkdir ${build_dir}
{{Cmd|./sbin/apk.static -X ${mirror}/latest-stable/main -U --allow-untrusted --root ${chroot_dir} --initdb add alpine-base}}
sudo ./sbin/apk.static -X ${mirror}/v2.4/main -U --allow-untrusted --root ${build_dir} --initdb add alpine-base alpine-sdk
mkdir -p ./${build_dir}/proc}}


Lets setup our needed devices:
== Set up the chroot ==


{{Cmd|sudo mknod -m 666 ./${build_dir}/dev/full c 1 7
Set up some devices in the chroot
sudo mknod -m 666 ./${build_dir}/dev/ptmx c 5 2
{{Tip|Manually creating devices is not needed if you choose to mount /dev of the hosts in the chroot described later.}}
sudo mknod -m 644 ./${build_dir}/dev/random c 1 8
sudo mknod -m 644 ./${build_dir}/dev/urandom c 1 9
sudo mknod -m 666 ./${build_dir}/dev/zero c 1 5
sudo mknod -m 666 ./${build_dir}/dev/tty c 5 0}}
seems as /dev/null is wrong


{{Cmd|sudo rm -f ./${build_dir}/dev/null && sudo mknod -m 666 ./${build_dir}/dev/null c 1 3}}
{{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}}


We need a resolv.conf is needed for the DNS servers and the /root directory:  
If you need SCSI disc access:


{{Cmd|sudo cp /etc/resolv.conf ./${build_dir}/etc/
{{Cmd|mknod -m 666 ${chroot_dir}/dev/sda b 8 0
mkdir -p ./${build_dir}/root}}
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}}


If you don't want to copy the resolv.conf from the local machine, create this file with your DNS server entry.
A resolv.conf is needed for name resolution:
{{Cmd|echo 'nameserver 8.8.8.8' >/etc/resolv.conf}}


We are setting up APK mirrors:
{{Cmd|cp /etc/resolv.conf ${chroot_dir}/etc/
mkdir -p ${chroot_dir}/root}}


{{Cmd|sudo mkdir -p ./${build_dir}/etc/apk
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):
echo "${mirror}/v2.3/main" > ./${build_dir}/etc/apk/repositories}}
{{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 ==
== Entering your chroot ==
After the installation you should be able to enter 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:


<!-- Don't we need to mount more, as in Arch instructions? Also should explain how to cleanly exit the chroot. -->
{{Cmd|mount -t proc none ${chroot_dir}/proc
mount -o bind /sys ${chroot_dir}/sys}}


{{Cmd|sudo mount --bind /proc ./${build_dir}/proc
If you don't want to create special device files yourself, mount the hosts device directory onto the chroot:
sudo chroot ./${build_dir} /bin/sh -l}}
{{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
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
Line 75: Line 115:
== Alpine Linux in a chroot on Fedora ==
== 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/fab/scripts/tree/alpine-chroot.sh script].
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.}}
{{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]]
[[Category:Installation]]

Revision as of 17:52, 13 January 2019

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 or older releases of Alpine Linux to test backports.

You can also use script 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:

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 ${version} with actual version):

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

.apk packages are just gzipped tarballs, unpack using:

tar -xzf apk-tools-static-*.apk

Install the alpine base installation onto the chroot

./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.

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:

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:

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):

echo -e 'nameserver 208.67.222.222\nnameserver 2620:0:ccc::2' > ${chroot_dir}/etc/resolv.conf

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

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:

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:

mount -o bind /dev ${chroot_dir}/dev

You can now chroot:

chroot ${chroot_dir} /bin/sh -l

To make the system actually bootable, we need to add some initscripts to appropriate runlevels:

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:

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

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 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 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 ${chroot_dir}/etc/apk/repositories is valid and inside the chroot run:

apk update