Alpine Linux in a chroot: Difference between revisions

Latest revision as of 11:00, 16 June 2025

This page explains how to set up an Alpine Linux chroot environment under a host Linux distro. 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 chroot can also be used to install Alpine Linux from a non-Alpine Linux system or live environment.

Tip: Use alpine-chroot-install script to setup Alpine Linux chroot build environment on any linux host in few seconds.

Prerequisites

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

alpine-chroot-install script

The official alpine-chroot-install script simplifies installation of Alpine Linux build environment on any x86_64 Linux system using chroot. With this script, it takes seconds to prepare a chroot, install fresh Alpine Linux including gcc build environment and execute first command!

The script provides commands to enter-chroot and destroy the chroot. Refer to the documentation page for more information.

Manual set up of chroot

The below variables are used in this page:

${chroot_dir} = Should point to the new root directory(eg./alpine or /var/chroots/alpine)
${mirror} = Should be replaced with one of the available Alpine Linux mirrors.
${arch} = Should be the cpu architecture like x86_64 for current amd64 or x86 for older i386.

Installation

Download the latest apk static package by replacing the variables like ${version} with actual version found on the chosen Download mirror:

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 Linux base installation onto the chroot.

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

Create the required devices

Before you can change root to the new directory i.e ${chroot_dir}, you need to create the required devices

Method 1: 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 2: Creating needed nodes in the manually

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

Entering your chroot

Enter your chroot by running this command as the root user (UID 0):

chroot ${chroot_dir} /bin/ash -l

Using chroot for other purposes

The above chroot method is commonly used to have Alpine Linux installed in a existing system. If you plan to use your chroot for other purposes, then the following steps are needed.

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

Installing bootloader

If you plan to use your chroot to setup a new Alpine Linux system and boot from it, you need a bootloader.

Warning: Bootloaders can be installed only if Alpine Linux chroot was installed to a dedicated partiton mounted at the ${chroot_dir} directory.

If you have a dedicated partition in which the chroot is installed, enter your chroot and follow the steps given in the Syslinux page.

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

@@ Line 1: / Line 1: @@
 {{TOC right}}
-Inside the chroot environment, you can build, debug, and run alpine packages or develop things. It's the most known way to do so if one wants not to trash their main Alpine system.
+This page explains how to set up an Alpine Linux [[Chroot|chroot]] environment under a host Linux distro. 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 chroot can also be used to install Alpine Linux from a non-Alpine Linux system or live environment.
-This document explains how to set up an [[Alpine_newbie#Developer|Alpine build environment]] in a chroot under a host Linux distro, can also be used to install Alpine Linux from a non-Alpine Linux livecd.
+{{Tip|Use [[#alpine-chroot-install script|alpine-chroot-install script]] to setup Alpine Linux chroot build environment on any linux host in few seconds.}}
-== Requirements ==
+== Prerequisites ==
 * Working Linux instalation where to perform all the process
-* Linux kernel 2.6.22, with <code>wget</code> and <code>chroot</code> installed
+* 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 ==
+== alpine-chroot-install script ==
-The variables below:
+The official [https://github.com/alpinelinux/alpine-chroot-install/ alpine-chroot-install] script simplifies installation of Alpine Linux build environment on any x86_64 Linux system using chroot. With this script, it takes seconds to prepare a chroot, install fresh Alpine Linux including gcc build environment and execute first command!
-*'''${chroot_dir}''' = Should point to the chroot directory where you
+The script provides commands to {{ic|enter-chroot}} and {{ic|destroy}} the chroot. Refer to the [https://github.com/alpinelinux/alpine-chroot-install/blob/master/alpine-chroot-install documentation] page for more information.
-*'''${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 ==
+== Manual set up of chroot ==
-Download the latest apk static package (replace <tt>${version}</tt> with actual version):
+The below variables are used in this page:
-{{Cmd|wget ${mirror}/latest-stable/main/${arch}/apk-tools-static-${version}.apk}}
+*'''${chroot_dir}''' = Should point to the new root directory(eg./alpine or /var/chroots/alpine)
+*'''${mirror}''' = Should be replaced with [https://dl-cdn.alpinelinux.org/alpine/MIRRORS.txt one of the available Alpine Linux mirrors].
+*'''${arch}''' =  Should be the cpu architecture like '''x86_64''' for current amd64 or '''x86''' for older i386.
-.apk packages are just gzipped tarballs, unpack using:
+=== Installation ===
-{{Cmd|tar -xzf apk-tools-static-*.apk}}
-== Install the alpine base installation onto the chroot ==
+Download the latest apk static package by replacing the variables like <tt>${version}</tt> with actual version found on the chosen Download mirror: {{Cmd|curl -LO ${mirror}/latest-stable/main/${arch}/apk-tools-static-${version}.apk}}
-{{Cmd|./sbin/apk.static -X ${mirror}/latest-stable/main -U --allow-untrusted --root ${chroot_dir} --initdb add alpine-base}}
+{{ic|.apk}} packages are just gzipped tarballs, you can unpack them using: {{Cmd|tar -xzf apk-tools-static-*.apk}}
-== Set up the chroot ==
+Install the Alpine Linux base installation onto the chroot. {{Cmd|./sbin/apk.static -X ${mirror}/latest-stable/main -U --allow-untrusted -p ${chroot_dir} --initdb add alpine-base}}
-Before made and enter into the chrooted system must be prepared with device nodes and tempfs :
+=== Create the required devices ===
-===== Method 1.A fast way: using bind mount =====
+Before you can change root to the new directory i.e ${chroot_dir}, you need to create the required devices
-{{Note|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}}
+==== Method 1: Using the host's /dev ====
-{{Cmd|mount /dev/ ${chroot_dir}/dev/ --bind
+{{Cmd|mount -o bind /dev ${chroot_dir}/dev}}
-mount -o remount,ro,bind ${chroot_dir}/dev
-}}
-If you need SCSI or R/W access only do the first command, mounting with "ro" makes more secure your chroot.
+{{Note|Bind mounts can be made read-only which would limit the chroot from writing to the devices}}
-===== Method 1.B manual way: creating need nodes =====
+==== Method 2: Creating needed nodes in the manually ====
-{{Warning|Manually creating devices will only provide those representation that you have created.. for auto availability use bind mounts}}
+{{Warning|Manually creating devices will only provide the ones that have been created}}
 {{Cmd|mknod -m 666 ${chroot_dir}/dev/full c 1 7
@@ Line 58: / Line 55: @@
 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
@@ Line 64: / Line 63: @@
 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/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}}
-==== Made available proc and sys fs ====
+=== Make the process fs and /sys fs available ===
 {{Cmd|mount -t proc none ${chroot_dir}/proc
 mount -o bind /sys ${chroot_dir}/sys}}
-==== Make networking resolution access ====
+=== Set up 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/}}
-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):
+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}}
-==== prepare the apk sources software ====
+=== Prepare the APK repositories ===
-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
 echo "${mirror}/${branch}/main" > ${chroot_dir}/etc/apk/repositories}}
-== Mastering your chroot ==
+=== Entering your chroot ===
-The chroot methods are commonly used to have alpine in a portion of a already made directory, not forced to be a entire partion, that means Alpine can be in a very minimal directory indise the same partition of a Debian installed linux inclusively, so that why the chroot process does not included the boot method.
+Enter your chroot by running this command as the root user (UID 0): {{Cmd|chroot ${chroot_dir} /bin/ash -l}}
-So then the following commands will described the need procedures only if the chroot instalation was made to a dedicated partition for and not to a directory inside another linux installed.
+== Using chroot for other purposes ==
-{{Warning|so then by the explained reasons, at this point, Alpine has been succesfully installed onto the chroot directory '''but still not able to boot it'''. }}
+The above chroot method is commonly used to have Alpine Linux installed in a existing system. If you plan to use your chroot for other purposes, then the following steps are needed.
-==== Entering your chroot ====
+=== Preparing init services ===
-Take in consideration that the chroot command are only running as root, no stupid sudo tools are recommended for that.
-{{Cmd|chroot ${chroot_dir} /bin/bash -l}}
-==== Perform init process ====
-Need to add some minimal initscripts to appropriate runlevels:
+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|rc-update add devfs sysinit
 rc-update add dmesg sysinit
@@ Line 130: / Line 114: @@
 rc-update add savecache shutdown}}
+=== Installing bootloader ===
-==== Make bootable the install ====
+If you plan to use your chroot to setup a new Alpine Linux system and boot from it, you need a bootloader.
+{{Warning|Bootloaders can be installed only if Alpine Linux chroot was installed to a dedicated partiton mounted at the <nowiki>${chroot_dir}</nowiki> directory.}} If you have a dedicated partition in which the chroot is installed, [[#Entering your chroot|enter your chroot]] and follow the steps given in the [[Bootloaders#Syslinux|Syslinux]] page.
-WIP:
+== Troubleshooting ==
-{{Warning|Run only this if Alpine was installed to a dedicated partiton mounted at the <nowiki>${chroot_dir}</nowiki> directory, becose at this point, Alpine has been succesfully installed onto the chroot directory '''but still not able to boot it'''. }}
+=== Hardened kernels or alpine as chroot host ===
-{{Cmd|<nowiki>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 you can run <code>chmod</code> from a chroot. Add the following to <code>/etc/sysctl.conf</code>
-Be care of that /dev/sda are the same disk where destination partition was mounted to <nowiki>${chroot_dir}</nowiki>.
-= 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 chroot can run chmod. Add following to <code>/etc/sysctl.conf</code>
 <code>kernel.grsecurity.chroot_deny_chmod = 0</code>
-Then run the following command
+Then reload the sysctl configuration:
 <code>sysctl -p</code>
+=== chroot: cannot run command ' ... Exec format error ===
-== 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!
-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 ==
+=== WARNING: Ignoring APKINDEX.xxxx.tar.gz ===
-Make sure <code>${chroot_dir}/etc/apk/repositories</code> is valid and inside the chroot run:
-<code>apk update</code>
+Make sure <code>${chroot_dir}/etc/apk/repositories</code> is valid and run: {{Cmd|# apk update}}
-= External links =
+== See also ==
-* You can also use script [https://github.com/alpinelinux/alpine-chroot-install/ alpine-chroot-install]
+*[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 in a chroot on Fedora : https://git.alpinelinux.org/cgit/user/fab/scripts/tree/alpine-chroot.sh {{dead link}} script
 * Alpine Linux aarch64 in a chroot on AWS Linux : https://gist.github.com/emolitor/0567e51c0ce04f4b025fc78d2cf0b4f1 script
-[[Category:Installation]]
+[[Category: Installation]]
 [[category: System Administration]]