Difference between revisions of "Alpine Linux in a chroot"

From Alpine Linux
Jump to: navigation, search
m (use '/bin/ash' instead of 'ash' as chroot command - absolute path is required)
 
(20 intermediate revisions by 7 users not shown)
Line 1: Line 1:
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.
+
{{TOC right}}
  
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.
+
Inside the chroot environment, you can build, debug, and run Alpine packages or develop things. It's the most known way to do so without replacing your system or using a Virtual Machine.
 +
This document explains how to set up an [[Alpine_newbie#Developer|Alpine build environment]] in a chroot under a host Linux distro, that can also be used to install Alpine Linux from a non-Alpine Linux system or live environment.
  
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 ==
  
== Requirements ==
+
* Working Linux instalation where to perform all the process
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.
+
* Linux kernel 2.6.22, with <code>curl</code> and <code>chroot</code> binary installed
 +
* target media with at least 100M, 900MB for more complete solution as minimum
 +
* internet connection
  
 
== Prerequisites ==
 
== Prerequisites ==
 +
 
The variables below:  
 
The variables below:  
  
*'''${chroot_dir}''' = Should point to the chroot directory where you
+
*'''${chroot_dir}''' = Should point to the new root directory
 
*'''${mirror}''' = Should be replaced with [http://nl.alpinelinux.org/alpine/MIRRORS.txt one of the available Alpine Linux mirrors].
 
*'''${mirror}''' = Should be replaced with [http://nl.alpinelinux.org/alpine/MIRRORS.txt one of the available Alpine Linux mirrors].
 +
*'''${arch}''' =  Should be the cpu architecture like x86 (i386) or amd64(x86_64)..
  
 
== Set up APK ==
 
== 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):
 
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}}
+
{{Cmd|curl -LO ${mirror}/latest-stable/main/${arch}/apk-tools-static-${version}.apk}}
  
.apk packages are just gzipped tarballs, unpack using:
+
.apk packages are just gzipped tarballs, you can unpack them using:
 
{{Cmd|tar -xzf apk-tools-static-*.apk}}
 
{{Cmd|tar -xzf apk-tools-static-*.apk}}
  
 
== Install the alpine base installation onto the chroot ==
 
== 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}}
+
{{Cmd|./sbin/apk.static -X ${mirror}/latest-stable/main -U --allow-untrusted -p ${chroot_dir} --initdb add alpine-base}}
 +
 
 +
== Seting up the chroot ==
 +
 
 +
Before you change root to the new directory, you need to create the required devices
 +
 
 +
===== Method 1.a Simple way: Using the host's /dev =====
 +
 
 +
{{Cmd|mount -o bind /dev ${chroot_dir}/dev}}
 +
 
 +
{{Note|Bind mounts can be made read-only which would limit the chroot from writing to the devices}}
  
== Set up the chroot ==
+
===== Method 1.b Manual way: Creating needed nodes =====
  
Set up some devices in the chroot
+
{{Warning|Manually creating devices will only provide the ones that have been created}}
{{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
 
{{Cmd|mknod -m 666 ${chroot_dir}/dev/full c 1 7
Line 43: Line 53:
 
mknod -m 666 ${chroot_dir}/dev/tty c 5 0}}
 
mknod -m 666 ${chroot_dir}/dev/tty c 5 0}}
  
If you need SCSI disc access:
+
If you need SCSI disc access you can create the device nodes like this:
 +
 
 +
{{Note|Every device can have 15 sub-nodes, you should always increment by 16 for every new device}}
  
 
{{Cmd|mknod -m 666 ${chroot_dir}/dev/sda b 8 0
 
{{Cmd|mknod -m 666 ${chroot_dir}/dev/sda b 8 0
Line 49: Line 61:
 
mknod -m 666 ${chroot_dir}/dev/sda2 b 8 2
 
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/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/sdb b 8 16
mknod -m 666 ${chroot_dir}/dev/sdb1 b 8 17
+
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
+
==== Make the process fs and /sys fs available ====
mknod -m 666 ${chroot_dir}/dev/sdb4 b 8 20
+
 
mknod -m 666 ${chroot_dir}/dev/sdb5 b 8 21
+
{{Cmd|mount -t proc none ${chroot_dir}/proc
mknod -m 666 ${chroot_dir}/dev/sdb6 b 8 22}}
+
mount -o bind /sys ${chroot_dir}/sys}}
 +
 
 +
==== Set up name resolution ====
  
 
A resolv.conf is needed for name resolution:  
 
A resolv.conf is needed for name resolution:  
  
{{Cmd|cp /etc/resolv.conf ${chroot_dir}/etc/
+
You can either copy your host's resolv.conf:
mkdir -p ${chroot_dir}/root}}
+
{{Cmd|cp -L /etc/resolv.conf ${chroot_dir}/etc/}}
 +
 
 +
or instead you can create a new one (this example uses OpenDNS):
 +
{{Cmd|echo -e 'nameserver 8.8.8.8\nnameserver 2620:0:ccc::2' > ${chroot_dir}/etc/resolv.conf}}
  
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):
+
==== Prepare the 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):
+
Set up APK main repository (replace <tt>${branch}</tt> with the latest stable branch name, e.g. v3.3):
  
 
{{Cmd|mkdir -p ${chroot_dir}/etc/apk
 
{{Cmd|mkdir -p ${chroot_dir}/etc/apk
 
echo "${mirror}/${branch}/main" > ${chroot_dir}/etc/apk/repositories}}
 
echo "${mirror}/${branch}/main" > ${chroot_dir}/etc/apk/repositories}}
  
== Entering your chroot ==
+
{{Warning|The chroot methods are commonly used to have Alpine installed in a existing system. Because of this, the steps for preparing a bootloader are not included.}}
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:
+
==== Entering your chroot ====
 +
 
 +
You then can enter your chroot by running this command as the root user (UID 0).
  
{{Cmd|mount -t proc none ${chroot_dir}/proc
+
{{Cmd|chroot ${chroot_dir} /bin/ash -l}}
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:
+
==== Preparing init services ====
{{Cmd|mount -o bind /dev ${chroot_dir}/dev}}
 
  
You can now chroot:
+
If you plan to use your chroot with a init system or setup a new system on another device you should add these services:
{{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
 
{{Cmd|rc-update add devfs sysinit
 
rc-update add dmesg sysinit
 
rc-update add dmesg sysinit
Line 102: Line 113:
 
rc-update add savecache 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:
+
<!-- TODO: Create a page dedicated to installing GRUB and Syslinux and reference them here
{{Cmd|apk add alpine-sdk}}
+
==== Adding a bootloader ====
 +
 
 +
[[GRUB]]
 +
 
 +
{{Warning|Run this only if Alpine was installed to a dedicated partiton mounted at the <nowiki>${chroot_dir}</nowiki> directory.}}
 +
 
 +
{{Cmd|<nowiki>apk add syslinux
 +
dd if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}
  
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
+
{{Warning|Make sure that the device you give the <code>dd</code> utility is the one you want to install the bootloader to. This process cannot be reverted!}}
 +
-->
 +
= Troubleshooting =
  
kernel.grsecurity.chroot_deny_chmod = 0
+
== Hardened kernels or alpine as chroot host ==
  
Then run the following command
+
If you are using Alpine as a native build system you will have to make sure that you can run <code>chmod</code> from a chroot. Add the following to <code>/etc/sysctl.conf</code>
  
{{Cmd|sysctl -p}}
+
<code>kernel.grsecurity.chroot_deny_chmod = 0</code>
  
== Alpine Linux in a chroot on Fedora ==
+
Then reload the sysctl configuration
  
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].
+
<code>sysctl -p</code>
  
{{Note|Maybe you are able to use this script on other distribution but this is not tested.}}
+
== chroot: cannot run command ' ... Exec format error ==
  
== Alpine Linux aarch64 in a chroot on AWS Linux ==
+
This usually indicates that you booted with one architecture (e.g. armf) and are trying to chroot into another (e.g. x86_64). The binaries must be built for the architecture that the host runs!
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.}}
+
Note that with '''one exception you can run 32 bit x86 chroot in x86_64, but not viceversa'''!
  
= Troubleshooting =
 
 
== WARNING: Ignoring APKINDEX.xxxx.tar.gz ==
 
== 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]]
+
Make sure <code>${chroot_dir}/etc/apk/repositories</code> is valid and run:
 +
 
 +
<code>apk update</code>
 +
 
 +
= External links =
 +
 
 +
* You can also use script [https://github.com/alpinelinux/alpine-chroot-install/ alpine-chroot-install]
 +
* https://web.archive.org/web/20190808203313/https://isc.sans.edu/forums/diary/Forensic+use+of+mount+bind/22854/
 +
* Alpine Linux in a chroot on Fedora : http://git.alpinelinux.org/cgit/user/fab/scripts/tree/alpine-chroot.sh script
 +
* Alpine Linux aarch64 in a chroot on AWS Linux : https://gist.github.com/emolitor/0567e51c0ce04f4b025fc78d2cf0b4f1 script
 +
 
 +
[[Category: Installation]]
 +
[[category: System Administration]]

Latest revision as of 19:17, 17 September 2021

Inside the chroot environment, you can build, debug, and run Alpine packages or develop things. It's the most known way to do so without replacing your system or using a Virtual Machine. This document explains how to set up an Alpine build environment in a chroot under a host Linux distro, that can also be used to install Alpine Linux from a non-Alpine Linux system or live environment.

Requirements

  • Working Linux instalation where to perform all the process
  • Linux kernel 2.6.22, with curl and chroot binary installed
  • target media with at least 100M, 900MB for more complete solution as minimum
  • internet connection

Prerequisites

The variables below:

  • ${chroot_dir} = Should point to the new root directory
  • ${mirror} = Should be replaced with one of the available Alpine Linux mirrors.
  • ${arch} = Should be the cpu architecture like x86 (i386) or amd64(x86_64)..

Set up APK

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

curl -LO ${mirror}/latest-stable/main/${arch}/apk-tools-static-${version}.apk

.apk packages are just gzipped tarballs, you can unpack them 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 -p ${chroot_dir} --initdb add alpine-base

Seting up the chroot

Before you change root to the new directory, you need to create the required devices

Method 1.a Simple way: Using the host's /dev

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

Note: Bind mounts can be made read-only which would limit the chroot from writing to the devices
Method 1.b Manual way: Creating needed nodes
Tango-dialog-warning.png
Warning: Manually creating devices will only provide the ones that have been created


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 you can create the device nodes like this:

Note: Every device can have 15 sub-nodes, you should always increment by 16 for every new device

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/sdb b 8 16 mknod -m 666 ${chroot_dir}/dev/sdb1 b 8 17

Make the process fs and /sys fs available

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

Set up name resolution

A resolv.conf is needed for name resolution:

You can either copy your host's resolv.conf:

cp -L /etc/resolv.conf ${chroot_dir}/etc/

or instead you can create a new one (this example uses OpenDNS):

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

Prepare the APK repositories

Set up APK main repository (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

Tango-dialog-warning.png
Warning: The chroot methods are commonly used to have Alpine installed in a existing system. Because of this, the steps for preparing a bootloader are not included.


Entering your chroot

You then can enter your chroot by running this command as the root user (UID 0).

chroot ${chroot_dir} /bin/ash -l

Preparing init services

If you plan to use your chroot with a init system or setup a new system on another device you should add these services:

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

Troubleshooting

Hardened kernels or alpine as chroot host

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

kernel.grsecurity.chroot_deny_chmod = 0

Then reload the sysctl configuration

sysctl -p

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). The binaries must be built for the architecture that the host runs!

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

apk update

External links