18.4 Arch Linux Compatibility Layer

The Arch Linux compatibility layer is built based on the Arch bootstrap image.

Video tutorial: 07-FreeBSD-Arch Linux Compatibility Layer Script Usage Guide

Arch Linux Compatibility Layer

Arch Linux System

The Google Chrome browser is running in the background in the screenshot, so the Arch Linux compatibility layer uses slightly more system resources than the Ubuntu compatibility layer.

Building the Base System

Building the Arch Linux compatibility layer requires handling necessary services and settings first.

Handling Required Services

Linux Service

# service linux enable   # Set the Linux compatibility layer service to start on boot
# service linux start    # Start the Linux compatibility layer service

D-Bus

The desktop environment usually has the D-Bus service already configured. If not installed, please install D-Bus first.

Set the D-Bus service to start on boot:

# service dbus enable

Start the D-Bus service:

# service dbus start

Adjusting the Default Kernel Version of the Linux Compatibility Layer

For rolling distributions, the default kernel version of the Linux compatibility layer is usually low. If built directly, the Arch Linux compatibility layer will prompt FATAL: kernel too old during chroot. Therefore, you need to adjust the declared Linux kernel version in the Linux compatibility layer to a higher version (such as 7.0.11).

View the current kernel version of the Linux compatibility layer:

# sysctl compat.linux.osrelease
compat.linux.osrelease: 5.15.0

Note

You must start the linux service before you can view the current Linux kernel version.

Adjust to a newer version number:

# echo "compat.linux.osrelease=7.0.11" >> /etc/sysctl.conf # Write the kernel version to the sysctl configuration file for persistence
# sysctl compat.linux.osrelease=7.0.11 # Takes effect immediately, no reboot required

References

• Kernel.org. The Linux Kernel Archives[EB/OL]. [2026-03-26]. https://www.kernel.org/. Refer to this entry for the required Linux kernel version number

Mounting File Systems

You also need to mount the necessary file systems. Point the Linux compatibility layer default path to /compat/arch to enable automatic mounting of the relevant file systems.

Take effect immediately:

# sysctl compat.linux.emul_path=/compat/arch

Permanent setting:

# echo "compat.linux.emul_path=/compat/arch" >> /etc/sysctl.conf

Restart the Linux compatibility layer service:

service linux restart

Installing the Bootstrap System

# mkdir -p /compat/arch   # Create the compatibility layer root directory
# fetch https://ftp.sjtu.edu.cn/archlinux/iso/latest/archlinux-bootstrap-x86_64.tar.zst   # Download the Arch Linux bootstrap archive
# tar --use-compress-program=unzstd -xpvf archlinux-bootstrap-x86_64.tar.zst --strip-components=1 -C /compat/arch --numeric-owner   # Extract to /compat/arch, preserving original UID/GID; tar errors can usually be ignored

--strip-components=1 removes the outer path root.x86_64 when extracting the archlinux-bootstrap-x86_64.tar.zst file, extracting directly to the specified path.

Basic Configuration

Initializing the pacman Keyring

# cp /etc/resolv.conf /compat/arch/etc/   # Copy DNS configuration to the Arch compatibility layer from FreeBSD
# chroot /compat/arch /bin/bash           # Switch to the Arch compatibility layer environment
# pacman-key --init                        # Initialize the pacman keyring
# pacman-key --populate archlinux          # Import the official Arch Linux keys

Switching Software Sources

A newly installed Arch does not have a text editor installed; you need to edit the relevant files in FreeBSD to configure Arch Linux's pacman to use the Tsinghua University mirror:

# ee /compat/arch/etc/pacman.d/mirrorlist # At this point, you are in FreeBSD! Add the following line to the top of the file.

Server = https://mirrors.tuna.tsinghua.edu.cn/archlinux/$repo/os/$arch

Enabling DisableSandbox

FreeBSD does not implement the landlock sandbox mechanism; you need to enable DisableSandbox for pacman, otherwise it will trigger the error error: restricting filesystem access failed because landlock is not supported by the kernel!.

Uncomment the DisableSandbox option in the pacman.conf file:

# sed -E -i '' 's/^[[:space:]]*#[[:space:]]*DisableSandbox/DisableSandbox/' /compat/arch/etc/pacman.conf

Check whether it was enabled successfully by searching for the DisableSandbox line and its line number in pacman.conf:

# grep -n 'DisableSandbox' /compat/arch/etc/pacman.conf

References

• Arch Linux Project. pacman.conf(5)[EB/OL]. [2026-03-25]. https://man.archlinux.org/man/pacman.conf.5.en. Explains the purpose and applicable scenarios of the DisableSandbox configuration option.

archlinuxcn Repository Configuration

Configure the Arch Linux CN repository to use the Tsinghua University mirror:

# nano /etc/pacman.conf # Add the following two lines to the bottom of the file.

[archlinuxcn]
Server = https://mirrors.tuna.tsinghua.edu.cn/archlinuxcn/$arch

Install the Arch Linux CN repository keyring:

# pacman -S archlinuxcn-keyring

Tip

The step ==> Locally signing trusted keys in keyring... may take ten minutes or longer. Please be patient.

Use pacman to install the base system, development tools, text editor nano, AUR helper yay, and WenQuanYi font wqy-zenhei:

# pacman -S base base-devel nano yay wqy-zenhei

You also need to uninstall fakeroot and install fakeroot-tcp, otherwise AUR cannot be used. This defect is documented in Problem with fakeroot and qemu.

Install the fakeroot-tcp tool using pacman:

# pacman -S fakeroot-tcp # It will ask whether to uninstall fakeroot; please confirm and uninstall.

Locale Settings

Hint

Without this setting, graphical programs in Arch Linux will not be able to use Chinese input methods.

Edit the /etc/locale.gen file and remove the comment # in front of zh_CN.UTF-8 UTF-8.

Generate the system locale:

# locale-gen

Shell Script

The script content is as follows:

#!/bin/sh

BASE_URL="https://ftp.sjtu.edu.cn/archlinux/iso/latest"
rootdir=/compat/arch

url="${BASE_URL}/archlinux-bootstrap-x86_64.tar.zst"
BOOTSTRAP=archlinux-bootstrap-x86_64.tar.zst
SHAFILE="${BASE_URL}/sha256sums.txt"

LinuxKernel=7.0.11

echo "Starting Arch Linux installation..."

echo "Checking required modules..."

# Linux compat
if [ "$(sysrc -n linux_enable)" != "YES" ]; then
    echo "Linux module is not enabled. Enable it now? (Y|n)"
    read answer
    case $answer in
        [Nn][Oo]|[Nn])
            echo "Linux module not enabled"
            exit 1
            ;;
        *)
            service linux enable
            ;;
    esac
fi

service linux start

# dbus
if ! command -v dbus-daemon >/dev/null 2>&1; then
    echo "dbus-daemon not found. Install D-Bus? [Y|n]"
    read answer
    case $answer in
        [Nn][Oo]|[Nn])
            exit 2
            ;;
        *)
            pkg install -y dbus
            ;;
    esac
fi

if [ "$(sysrc -n dbus_enable)" != "YES" ]; then
    echo "Enable D-Bus now? (Y|n)"
    read answer
    case $answer in
        [Nn][Oo]|[Nn])
            exit 2
            ;;
        *)
            service dbus enable
            ;;
    esac
fi

service dbus start

echo "compat.linux.osrelease=${LinuxKernel}"
sysctl compat.linux.osrelease=${LinuxKernel}

if ! grep -q '^compat.linux.osrelease=' /etc/sysctl.conf 2>/dev/null; then
    echo "compat.linux.osrelease=${LinuxKernel}" >> /etc/sysctl.conf
else
    sed -i '' "s|^compat.linux.osrelease=.*|compat.linux.osrelease=${LinuxKernel}|" /etc/sysctl.conf
fi

# bootstrap + checksum + resume + retry
echo "Downloading bootstrap..."

fetch -r -o "${BOOTSTRAP}" "${url}"

[ -f sha256sums.txt ] || fetch -o sha256sums.txt "${SHAFILE}"

verify_checksum() {
    EXPECTED=$(awk "/${BOOTSTRAP}/{print \$1}" sha256sums.txt)
    ACTUAL=$(sha256 -q "${BOOTSTRAP}")

    echo "File: ${BOOTSTRAP}"
    echo "Expected SHA256: ${EXPECTED}"
    echo "Actual SHA256:   ${ACTUAL}"

    if [ -z "$EXPECTED" ]; then
        echo "Checksum not found in sha256sums.txt"
        return 1
    fi

    if [ "$EXPECTED" != "$ACTUAL" ]; then
        return 1
    fi

    return 0
}

echo "Verifying checksum..."

if ! verify_checksum; then
    echo "First verification failed. Removing file and retrying..."

    rm -f "${BOOTSTRAP}"

    echo "Redownloading bootstrap..."
    fetch -r -o "${BOOTSTRAP}" "${url}"

    echo "Re-verifying checksum..."

    if ! verify_checksum; then
        echo "Checksum failed after retry."
        exit 1
    fi
fi

echo "Checksum OK"
rm -f sha256sums.txt

mkdir -p "${rootdir}"

tar --use-compress-program=unzstd -xpvf "${BOOTSTRAP}" --strip-components=1 -C "${rootdir}" --numeric-owner 2>&1 | grep -v "Error exit delayed from previous errors"

rm -f "${BOOTSTRAP}"

# emulation path
sysctl compat.linux.emul_path="${rootdir}"

if ! grep -q '^compat.linux.emul_path=' /etc/sysctl.conf 2>/dev/null; then
    echo "compat.linux.emul_path=${rootdir}" >> /etc/sysctl.conf
else
    sed -i '' "s|^compat.linux.emul_path=.*|compat.linux.emul_path=${rootdir}|" /etc/sysctl.conf
fi

echo "compat.linux.emul_path=$(sysctl -n compat.linux.emul_path)"

service linux restart

# initial config
echo "Continue initial Arch setup? [Y|n]"
read answer
case $answer in
    [Nn][Oo]|[Nn])
        exit 0
        ;;
esac

grep -q "nameserver 223.5.5.5" "${rootdir}/etc/resolv.conf" 2>/dev/null || \
    echo "nameserver 223.5.5.5" >> "${rootdir}/etc/resolv.conf"

grep -q "nameserver 223.6.6.6" "${rootdir}/etc/resolv.conf" 2>/dev/null || \
    echo "nameserver 223.6.6.6" >> "${rootdir}/etc/resolv.conf"

chroot "${rootdir}" /bin/bash -c "pacman-key --init"
chroot "${rootdir}" /bin/bash -c "pacman-key --populate archlinux"

cp "${rootdir}/etc/pacman.d/mirrorlist" "${rootdir}/etc/pacman.d/mirrorlist.bak"

{
    echo 'Server = https://mirrors.cernet.edu.cn/archlinux/$repo/os/$arch'
    cat "${rootdir}/etc/pacman.d/mirrorlist.bak"
} > "${rootdir}/etc/pacman.d/mirrorlist"

rm -f "${rootdir}/etc/pacman.d/mirrorlist.bak"

echo '[archlinuxcn]' >> "${rootdir}/etc/pacman.conf"
echo 'Server = https://mirrors.ustc.edu.cn/archlinuxcn/$arch' >> "${rootdir}/etc/pacman.conf"

echo '[arch4edu]' >> "${rootdir}/etc/pacman.conf"
echo 'SigLevel = Never' >> "${rootdir}/etc/pacman.conf"
echo 'Server = https://mirrors.tuna.tsinghua.edu.cn/arch4edu/$arch' >> "${rootdir}/etc/pacman.conf"
chroot "${rootdir}" /bin/bash -c "useradd -G wheel -m ykla"
echo 'ALL ALL=(ALL:ALL) NOPASSWD: ALL' >> "${rootdir}/etc/sudoers"
chroot "${rootdir}" /bin/bash -c "mv /usr/share/libalpm/hooks/21-systemd-tmpfiles.hook    /usr/share/libalpm/hooks/21-systemd-tmpfiles.hook.disabled"

sed -i '' 's/^[#[:space:]]*DisableSandbox/DisableSandbox/' "${rootdir}/etc/pacman.conf"

chroot "${rootdir}" /bin/bash -c "pacman -Syyu --noconfirm"
chroot "${rootdir}" /bin/bash -c "pacman -S --noconfirm archlinuxcn-keyring"


chroot "${rootdir}" /bin/bash -c "pacman -S --noconfirm yay base base-devel nano wqy-zenhei"

chroot "${rootdir}" /bin/bash -c "pacman -Syu libunwind libedit --noconfirm --overwrite '*'"

chroot "${rootdir}" /bin/bash -c "pacman -Rdd fakeroot --noconfirm && pacman -S --noconfirm fakeroot-tcp"

echo 'zh_CN.UTF-8 UTF-8' >> "${rootdir}/etc/locale.gen"
chroot "${rootdir}" /bin/bash -c "locale-gen"

echo "Base System ready."
echo "chroot ${rootdir} /bin/bash"

References

• FreeBSD Project. linux(4)[EB/OL]. [2026-03-25]. https://man.freebsd.org/cgi/man.cgi?query=linux&sektion=4. This document provides a detailed introduction to the technical principles and configuration methods of the FreeBSD Linux compatibility layer.
• Arch Linux Project. Installation guide[EB/OL]. [2026-03-25]. https://wiki.archlinux.org/title/Installation_guide. This document provides the standard installation process guide for Arch Linux.