Merge pull request #464 from sonroyaalmerol/qemu-compatibility-mode

Better compatibility for ARM64 hosts

Author: thijsvanloef

Dockerfile

@@ -20,7 +20,7 @@ RUN wget -q https://github.com/gorcon/rcon-cli/archive/refs/tags/v${RCON_VERSION
 FROM cm2network/steamcmd:root as base-amd64
 # Ignoring --platform=arm64 as this is required for the multi-arch build to continue to work on amd64 hosts
 # hadolint ignore=DL3029
-FROM --platform=arm64 thijsvanloef/steamcmd-arm64:root as base-arm64
+FROM --platform=arm64 sonroyaalmerol/steamcmd-arm64:root-2024-02-29 as base-arm64
 
 ARG TARGETARCH
 # Ignoring the lack of a tag here because the tag is defined in the above FROM lines
@@ -109,6 +109,7 @@ ENV HOME=/home/steam \
     DISCORD_POST_SHUTDOWN_MESSAGE="Server has been stopped!" \
     ENABLE_PLAYER_LOGGING=true \
     PLAYER_LOGGING_POLL_PERIOD=5 \
+    ARM_COMPATIBILITY_MODE=false \
     DISABLE_GENERATE_ENGINE=true
 
 COPY ./scripts /home/steam/server/

README.md

@@ -244,6 +244,7 @@ It is highly recommended you set the following environment values before startin
 | DISABLE_GENERATE_ENGINE          | Whether to automatically generate the Engine.ini                                                                                                                                          | true                      | true/false                                                                                                        |
 | ENABLE_PLAYER_LOGGING      | Enables Logging and announcing when players join and leave | true         | true/false |
 | PLAYER_LOGGING_POLL_PERIOD          | Polling period (in seconds) to check for players who have joined or left | 5                      | !0 |
+| ARM_COMPATIBILITY_MODE          | Switches the compatibility layer from Box86 to QEMU when executing steamcmd for server updates. This setting is only applicable for ARM64 hosts. | false                      | true/false |
 
 *highly recommended to set
 

docusaurus/docs/getting-started/configuration/server-settings.md

@@ -59,6 +59,7 @@ It is highly recommended you set the following environment values before startin
 | DISABLE_GENERATE_ENGINE          | Whether to automatically generate the Engine.ini                                                                                                                                          | true                      | true/false                                                                                                        |
 | ENABLE_PLAYER_LOGGING      | Enables Logging and announcing when players join and leave | true         | true/false |
 | PLAYER_LOGGING_POLL_PERIOD          | Polling period (in seconds) to check for players who have joined or left | 5                      | !0 |
+| ARM_COMPATIBILITY_MODE          | Switches the compatibility layer from Box86 to QEMU when executing steamcmd for server updates. This setting is only applicable for ARM64 hosts. | false                      | true/false |
 
 *highly recommended to set
 

docusaurus/docs/known-issues/known-issues.md

@@ -56,6 +56,38 @@ it means that you'll need to look at the following:
 * Firewall settings, make sure that you allow port 8211/udp and 27015/udp through your firewall
 * Make sure you've correctly port forwarded your 8211/udp 27015/udp
 
+## Only ARM64 hosts with 4k page size is supported
+
+This error occurs when the container detects that the host kernel does not have a 4k page size,
+which is required for the emulation used for ARM64 architecture. The container relies on this specific page
+size for proper execution.
+
+If the host kernel does not have a 4k page size, you have a couple of alternatives:
+
+* **Download server files in a different machine**: The 4k page size limitation is only applicable for steamcmd
+ARM emulation. You may try initializing the container in a fully supported machine (AMD64 or ARM64 with 4k page size)
+and let it download the server files with `UPDATE_ON_BOOT` enabled. Make sure to disable `UPDATE_ON_BOOT` in the
+problematic machine to prevent steamcmd from executing.
+
+* **Change/Modify Kernel**: You can consider changing the kernel of your host machine to one that supports a 4k page size.
+  * The Raspberry Pi 5 with Raspberry Pi OS has an easy [switch](https://github.com/raspberrypi/bookworm-feedback/issues/107#issuecomment-1773810662).
+
+* **Switch OS**: Another option is to switch OS to ones shipped with 4k page size kernels.
+  * Debian and Ubuntu are known working Linux distros.
+
+* **Run within a VM**: Another option is to run the container within a virtual machine (VM) that is configured
+  with a kernel supporting a 4k page size. By doing so, you can ensure compatibility and proper execution of the
+  container.
+
+## /usr/local/bin/box86: cannot execute binary file: Exec format error (ARM64 hosts)
+
+This means that the Docker host is unable to run AArch32 binaries such as Box86 without an additional
+compatibility layer which is the case for Apple Silicon.
+
+Docker Desktop solves this by running its containers inside a VM (QEMU) with a compatible kernel.
+However, if you're unable to use Docker Desktop, then try setting `ARM_COMPATIBILITY_MODE` to `true`.
+This will switch the container from using Box86 to QEMU when running steamcmd.
+
 ## FAQ
 
 [A useful FAQ that gets updated regularly](https://gist.github.com/Toakan/3c78a577c21a21fcc5fa917f3021d70e#file-palworld-server-faq-community-md)

scripts/helper_install.sh

@@ -113,6 +113,16 @@ UpdateRequired() {
 }
 
 InstallServer() {
+  # Get the architecture using dpkg
+  architecture=$(dpkg --print-architecture)
+
+  # Get host kernel page size
+  kernel_page_size=$(getconf PAGESIZE)
+
+  # Check kernel page size for arm64 hosts before running steamcmd
+  if [ "$architecture" == "arm64" ] && [ "$kernel_page_size" != "4096" ]; then
+    LogWarn "WARNING: Only ARM64 hosts with 4k page size is supported when running steamcmd. Expect server installation to fail."
+  fi
 
   if [ -z "${TARGET_MANIFEST_ID}" ]; then
     DiscordMessage "Install" "${DISCORD_PRE_UPDATE_BOOT_MESSAGE}" "in-progress"

scripts/start.sh

@@ -15,13 +15,12 @@ cd /palworld || exit
 # Get the architecture using dpkg
 architecture=$(dpkg --print-architecture)
 
-# Get host kernel page size
-kernel_page_size=$(getconf PAGESIZE)
+if [ "$architecture" == "arm64" ] && [ "${ARM_COMPATIBILITY_MODE,,}" = true ]; then
+    LogInfo "ARM compatibility mode enabled"
+    export DEBUGGER="/usr/bin/qemu-i386-static"
 
-# Check kernel page size for arm64 hosts before running steamcmdac
-if [ "$architecture" == "arm64" ] && [ "$kernel_page_size" != "4096" ]; then
-    LogError "Only ARM64 hosts with 4k page size is supported."
-    exit 1
+    # Arbitrary number to avoid CPU_MHZ warning due to qemu and steamcmd
+    export CPU_MHZ=2000
 fi
 
 IsInstalled
@@ -46,8 +45,26 @@ fi
 if [ "$architecture" == "arm64" ]; then
     # create an arm64 version of ./PalServer.sh
     cp ./PalServer.sh ./PalServer-arm64.sh
-    # shellcheck disable=SC2016
-    sed -i 's|\("$UE_PROJECT_ROOT\/Pal\/Binaries\/Linux\/PalServer-Linux-Test" Pal "$@"\)|LD_LIBRARY_PATH=/home/steam/steamcmd/linux64:$LD_LIBRARY_PATH box64 \1|' ./PalServer-arm64.sh
+
+    pagesize=$(getconf PAGESIZE)
+    box64_binary="box64"
+
+    case $pagesize in
+        8192)
+            LogInfo "Using Box64 for 8k pagesize"
+            box64_binary="box64-8k"
+            ;;
+        16384)
+            LogInfo "Using Box64 for 16k pagesize"
+            box64_binary="box64-16k"
+            ;;
+        65536)
+            LogInfo "Using Box64 for 64k pagesize"
+            box64_binary="box64-64k"
+            ;;
+    esac
+    
+    sed -i "s|\(\"\$UE_PROJECT_ROOT\/Pal\/Binaries\/Linux\/PalServer-Linux-Test\" Pal \"\$@\"\)|LD_LIBRARY_PATH=/home/steam/steamcmd/linux64:\$LD_LIBRARY_PATH $box64_binary \1|" ./PalServer-arm64.sh
     chmod +x ./PalServer-arm64.sh
     STARTCOMMAND=("./PalServer-arm64.sh")
 else