test, doc, CI: Add tests, CI and documentation for cross-architecture support extension

.github/workflows/ubuntu-tests.yaml

@@ -50,6 +50,7 @@ jobs:
             ninja-build \
             openssl \
             podman \
+            qemu-user-static \
             shellcheck \
             skopeo \
             systemd \
@@ -166,6 +167,14 @@ jobs:
             test/system/230-cdi.bats \
             test/system/250-kerberos.bats \
             test/system/270-rpm.bats \
+            test/system/301-create.bats \
+            test/system/401-ipc.bats \
+            test/system/403-network.bats \
+            test/system/410-ulimit.bats \
+            test/system/420-environment-variables.bats \
+            test/system/430-cdi.bats \
+            test/system/450-kerberos.bats \
+            test/system/470-rpm.bats \
             test/system/501-create.bats \
             test/system/505-enter.bats
         env:

.zuul.yaml

@@ -48,6 +48,17 @@
     pre-run: playbooks/setup-env-restricted.yaml
     run: playbooks/unit-test.yaml
 
+- job:
+    name: system-test-fedora-rawhide-non-native-architecture
+    description: Run Toolbx's non-native architecture system tests in Fedora Rawhide
+    timeout: 7200
+    nodeset:
+      nodes:
+        - name: fedora-rawhide
+          label: cloud-fedora-rawhide
+    pre-run: playbooks/setup-env.yaml
+    run: playbooks/system-test-non-native.yaml
+
 - job:
     name: system-test-fedora-rawhide-commands-options
     description: Run Toolbx's commands-options system tests in Fedora Rawhide
@@ -81,6 +92,17 @@
     pre-run: playbooks/setup-env.yaml
     run: playbooks/system-test-runtime-environment-ubuntu.yaml
 
+- job:
+    name: system-test-fedora-44-non-native-architecture
+    description: Run Toolbx's non-native architecture system tests in Fedora 44
+    timeout: 6300
+    nodeset:
+      nodes:
+        - name: fedora-44
+          label: cloud-fedora-44
+    pre-run: playbooks/setup-env.yaml
+    run: playbooks/system-test-non-native.yaml
+
 - job:
     name: system-test-fedora-44-commands-options
     description: Run Toolbx's commands-options system tests in Fedora 44
@@ -114,6 +136,17 @@
     pre-run: playbooks/setup-env.yaml
     run: playbooks/system-test-runtime-environment-ubuntu.yaml
 
+- job:
+    name: system-test-fedora-43-non-native-architecture
+    description: Run Toolbx's non-native architecture system tests in Fedora 43
+    timeout: 6300
+    nodeset:
+      nodes:
+        - name: fedora-43
+          label: cloud-fedora-43
+    pre-run: playbooks/setup-env.yaml
+    run: playbooks/system-test-non-native.yaml
+
 - job:
     name: system-test-fedora-43-commands-options
     description: Run Toolbx's commands-options system tests in Fedora 43
@@ -147,6 +180,17 @@
     pre-run: playbooks/setup-env.yaml
     run: playbooks/system-test-runtime-environment-ubuntu.yaml
 
+- job:
+    name: system-test-fedora-42-non-native-architecture
+    description: Run Toolbx's non-native architecture system tests in Fedora 42
+    timeout: 6300
+    nodeset:
+      nodes:
+        - name: fedora-42
+          label: cloud-fedora-42
+    pre-run: playbooks/setup-env.yaml
+    run: playbooks/system-test-non-native.yaml
+
 - job:
     name: system-test-fedora-42-commands-options
     description: Run Toolbx's commands-options system tests in Fedora 42
@@ -184,15 +228,19 @@
     periodic:
       jobs:
         - system-test-fedora-rawhide-commands-options
+        - system-test-fedora-rawhide-non-native-architecture
         - system-test-fedora-rawhide-runtime-environment-arch-fedora
         - system-test-fedora-rawhide-runtime-environment-ubuntu
         - system-test-fedora-44-commands-options
+        - system-test-fedora-44-non-native-architecture
         - system-test-fedora-44-runtime-environment-arch-fedora
         - system-test-fedora-44-runtime-environment-ubuntu
         - system-test-fedora-43-commands-options
+        - system-test-fedora-43-non-native-architecture
         - system-test-fedora-43-runtime-environment-arch-fedora
         - system-test-fedora-43-runtime-environment-ubuntu
         - system-test-fedora-42-commands-options
+        - system-test-fedora-42-non-native-architecture
         - system-test-fedora-42-runtime-environment-arch-fedora
         - system-test-fedora-42-runtime-environment-ubuntu
     check:
@@ -201,15 +249,19 @@
         - unit-test-migration-path-for-coreos-toolbox
         - unit-test-restricted
         - system-test-fedora-rawhide-commands-options
+        - system-test-fedora-rawhide-non-native-architecture
         - system-test-fedora-rawhide-runtime-environment-arch-fedora
         - system-test-fedora-rawhide-runtime-environment-ubuntu
         - system-test-fedora-44-commands-options
+        - system-test-fedora-44-non-native-architecture
         - system-test-fedora-44-runtime-environment-arch-fedora
         - system-test-fedora-44-runtime-environment-ubuntu
         - system-test-fedora-43-commands-options
+        - system-test-fedora-43-non-native-architecture
         - system-test-fedora-43-runtime-environment-arch-fedora
         - system-test-fedora-43-runtime-environment-ubuntu
         - system-test-fedora-42-commands-options
+        - system-test-fedora-42-non-native-architecture
         - system-test-fedora-42-runtime-environment-arch-fedora
         - system-test-fedora-42-runtime-environment-ubuntu
     gate:
@@ -218,14 +270,18 @@
         - unit-test-migration-path-for-coreos-toolbox
         - unit-test-restricted
         - system-test-fedora-rawhide-commands-options
+        - system-test-fedora-rawhide-non-native-architecture
         - system-test-fedora-rawhide-runtime-environment-arch-fedora
         - system-test-fedora-rawhide-runtime-environment-ubuntu
         - system-test-fedora-44-commands-options
+        - system-test-fedora-44-non-native-architecture
         - system-test-fedora-44-runtime-environment-arch-fedora
         - system-test-fedora-44-runtime-environment-ubuntu
         - system-test-fedora-43-commands-options
+        - system-test-fedora-43-non-native-architecture
         - system-test-fedora-43-runtime-environment-arch-fedora
         - system-test-fedora-43-runtime-environment-ubuntu
         - system-test-fedora-42-commands-options
+        - system-test-fedora-42-non-native-architecture
         - system-test-fedora-42-runtime-environment-arch-fedora
         - system-test-fedora-42-runtime-environment-ubuntu

doc/toolbox-create.1.md

@@ -4,7 +4,8 @@
 toolbox\-create - Create a new Toolbx container
 
 ## SYNOPSIS
-**toolbox create** [*--authfile FILE*]
+**toolbox create** [*--arch ARCHITECTURE* | *-a ARCHITECTURE*]
+               [*--authfile FILE*]
                [*--distro DISTRO* | *-d DISTRO*]
                [*--image NAME* | *-i NAME*]
                [*--release RELEASE* | *-r RELEASE*]
@@ -90,6 +91,12 @@ confusion.
 
 ## OPTIONS ##
 
+**--arch** ARCHITECTURE, **-a** ARCHITECTURE
+
+Create a Toolbx container for a different architecture ARCHITECTURE than
+the host (e.g., `arm64` on `amd64`). Can be combined with `--distro` and
+`--release`.
+
 **--authfile** FILE
 
 Path to a FILE with credentials for authenticating to the registry for private
@@ -140,6 +147,12 @@ $ toolbox create --distro fedora --release f36
 $ toolbox create --image bar foo
 ```
 
+### Create a Toolbx container for the arm64 architecture
+
+```
+$ toolbox create --arch arm64
+```
+
 ### Create a custom Toolbx container from a custom image that's private
 
 ```

doc/toolbox-enter.1.md

@@ -4,7 +4,8 @@
 toolbox\-enter - Enter a Toolbx container for interactive use
 
 ## SYNOPSIS
-**toolbox enter** [*--distro DISTRO* | *-d DISTRO*]
+**toolbox enter** [*--arch ARCHITECTURE* | *-a ARCHITECTURE*]
+              [*--distro DISTRO* | *-d DISTRO*]
               [*--release RELEASE* | *-r RELEASE*]
               [*CONTAINER*]
 
@@ -29,6 +30,12 @@ analogous to a `podman start` followed by a `podman exec`.
 
 The following options are understood:
 
+**--arch** ARCHITECTURE, **-a** ARCHITECTURE
+
+Enter a Toolbx container for a different architecture ARCHITECTURE than the
+host (e.g., `arm64` on `amd64`). Can be combined with `--distro` and
+`--release`.
+
 **--distro** DISTRO, **-d** DISTRO
 
 Enter a Toolbx container for a different operating system DISTRO than the host.
@@ -59,6 +66,12 @@ $ toolbox enter --distro fedora --release f36
 $ toolbox enter foo
 ```
 
+### Enter the default Toolbx container based on the arm64 architecture
+
+```
+$ toolbox enter --arch arm64
+```
+
 ## SEE ALSO
 
 `toolbox(1)`, `toolbox-run(1)`, `podman(1)`, `podman-exec(1)`,

doc/toolbox-init-container.1.md

@@ -4,7 +4,9 @@
 toolbox\-init\-container - Initialize a running container
 
 ## SYNOPSIS
-**toolbox init-container** *--gid GID*
+**toolbox init-container** *--arch ID*
+                       *--arch-emulator-path PATH*
+                       *--gid GID*
                        *--home HOME*
                        *--home-link*
                        *--media-link*
@@ -48,10 +50,27 @@ On some host operating systems, important paths like `/home`, `/media` or
 paths inside the container match those on the host, to avoid needless
 confusion.
 
+When the container's architecture differs from the host, the entry point
+configures QEMU user-mode emulation inside the container. It validates that
+QEMU emulation is functional, mounts a sandboxed `binfmt_misc` filesystem, and
+registers the QEMU interpreter with the `C` (credential) flag for transparent
+emulation of non-native architecture binaries.
+
 ## OPTIONS ##
 
 The following options are understood:
 
+**--arch** ID
+
+The container's architecture ID. When it differs from the host, additional
+configuration of cross-architecture QEMU emulation is performed during
+initialization.
+
+**--arch-emulator-path** PATH
+
+Register an emulator using binfmt_misc with PATH as the interpreter for a
+non-native architecture container.
+
 **--gid** GID
 
 Pass GID as the user's numerical group ID from the host to the Toolbx

doc/toolbox-run.1.md

@@ -4,7 +4,8 @@
 toolbox\-run - Run a command in an existing Toolbx container
 
 ## SYNOPSIS
-**toolbox run** [*--container NAME* | *-c NAME*]
+**toolbox run** [*--arch ARCHITECTURE* | *-a ARCHITECTURE*]
+            [*--container NAME* | *-c NAME*]
             [*--distro DISTRO* | *-d DISTRO*]
             [*--preserve-fds N*]
             [*--release RELEASE* | *-r RELEASE*]
@@ -26,6 +27,12 @@ to a `podman start` followed by a `podman exec`.
 
 The following options are understood:
 
+**--arch** ARCHITECTURE, **-a** ARCHITECTURE
+
+Run command inside a Toolbx container for a different architecture ARCHITECTURE
+than the host (e.g., `arm64` on `amd64`). Can be combined with `--distro` and
+`--release`.
+
 **--container** NAME, **-c** NAME
 
 Run command inside a Toolbx container with the given NAME. This is useful when
@@ -103,6 +110,12 @@ $ toolbox run --distro fedora --release f36 emacs
 $ toolbox run --container foo uptime
 ```
 
+### Run uname inside the default Toolbx container for the arm64 architecture
+
+```
+$ toolbox run --arch arm64 uname -m
+```
+
 ## SEE ALSO
 
 `toolbox(1)`, `podman(1)`, `podman-exec(1)`, `podman-start(1)`

doc/toolbox.1.md

@@ -72,6 +72,21 @@ fedora |\<release\> or f\<release\> eg., 36 or f36
 rhel   |\<major\>.\<minor\> eg., 8.5
 ubuntu |\<YY\>.\<MM\> eg., 22.04
 
+## Cross-architecture containers support
+
+Toolbx supports creating and using containers for a different CPU architecture
+than the host through QEMU user-mode emulation. This allows, for example,
+running an `arm64` container on an `amd64` host for cross-compilation or
+testing. Cross-architecture containers are created and used through the
+`--arch` flag accepted by `toolbox create`, `toolbox enter` and `toolbox run`.
+The following architectures are supported:
+
+Architecture |Accepted values
+-------------|---------------------------
+arm64        |arm64, aarch64
+ppc64le      |ppc64le
+amd64        |amd64, x86\_64
+
 ## USAGE
 
 ### Create a Toolbx container:

playbooks/dependencies-fedora.yaml

@@ -33,6 +33,7 @@
       - openssl
       - pkgconfig(bash-completion)
       - podman
+      - qemu-user-static
       - shadow-utils-subid-devel
       - skopeo
       - systemd

playbooks/system-test-non-native.yaml

@@ -0,0 +1,29 @@
+#
+# Copyright © 2026 Red Hat, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+---
+- hosts: all
+  tasks:
+    - include_tasks: build.yaml
+
+    - name: Run the non-native architecture system tests
+      command: bats --filter-tags non-native ./test/system
+      environment:
+        TMPDIR: '/var/tmp'
+        TOOLBX: '/usr/local/bin/toolbox'
+        TOOLBX_TEST_SYSTEM_TAGS: 'non-native'
+      args:
+        chdir: '{{ zuul.project.src_dir }}'