Alpine Linux - User contributions [en]

System Disk Mode

2025-11-26T08:03:08Z

Threshold Wanderer: Adjust the formatting

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Ensure that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If the error message matched in step 4, check whether filesystem modules are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

*If you are using [[Bootloaders#Syslinux|Syslinux]], then ensure that {{Codeline|APPEND root}} line in the file {{Path|/boot/extlinux.conf}} has the appropriate filesystem module <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-load,usb-storage,ext4 quiet
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMeb.

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

Alpine Linux in a chroot

2025-11-26T07:57:10Z

Threshold Wanderer: OpenRC will lock up if you don't include the `firstboot` service

{{TOC right}}

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.

{{Tip|Use [[#alpine-chroot-install script|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 <code>curl</code> and <code>chroot</code> binary installed
* target media with at least 100M, 900MB for more complete solution as minimum
* internet connection

== alpine-chroot-install script ==

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!

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.

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

=== Installation ===

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

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

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

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

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

==== Method 2: Creating needed nodes in the manually ====

{{Warning|Manually creating devices will only provide the ones that have been created}}

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

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

=== Prepare the APK repositories ===

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

=== Entering your chroot ===

Enter your chroot by running this command as the root user (UID 0): {{Cmd|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:
{{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

rc-update add firstboot default}}

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

== 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 <code>chmod</code> from a chroot. Add the following to <code>/etc/sysctl.conf</code>

<code>kernel.grsecurity.chroot_deny_chmod = 0</code>

Then reload the sysctl configuration:

<code>sysctl -p</code>

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

== See also ==

*[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 : 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: System Administration]]