> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-18-linux-compatibility-layer/di-18.4-jie-arch-linux-jian-rong-ceng.md).

# 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](https://www.bilibili.com/video/BV1wg4y1w7QV)

![Arch Linux Compatibility Layer](/files/G3uIgia0KWUs8Uz2oCML)

![Arch Linux System](/files/lXTVeGAl21UxjU9cStx8)

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

```sh
# 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:

```sh
# service dbus enable
```

Start the D-Bus service:

```sh
# 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:

```sh
# 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:

```sh
# 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:

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

Permanent setting:

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

Restart the Linux compatibility layer service:

```sh
service linux restart
```

### Installing the Bootstrap System

```sh
# 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

```sh
# 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:

```sh
# 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:

```sh
# 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:

```sh
# 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:

```sh
# 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:

```sh
# 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:

```sh
# 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](https://archlinuxarm.org/forum/viewtopic.php?t=14466).

Install the fakeroot-tcp tool using pacman:

```sh
# 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:

```sh
# locale-gen
```

## Shell Script

The script content is as follows:

```sh
#!/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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.bsdcn.org/ask/flat/chapter-18-linux-compatibility-layer/di-18.4-jie-arch-linux-jian-rong-ceng.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.