README.md

qemu-user-static (qus) is a compilation of utilities, examples and references to build and execute OCI images (aka docker images) for foreign architectures using QEMU's user-mode emulation.

• Ready-to-use docker images are provided for each of seven host architectures officially supported by Docker, Inc. or built by official images (docker-library/official-images: Architectures other than amd64?): amd64, i386, arm64v8, arm32v7, arm32v6, s390x and ppc64le.
• Multiple minimal working setups to build and execute arm64v8 containers on amd64 are configured and tested on GitHub Actions. The full flow is public, for other users to learn and adapt these resources to their needs.
• These resources are tested on GNU/Linux and Windows 10 (Docker Desktop). Contributions to test them on other host OSs are welcome!

Find further details at dbhi.github.io/qus.

Usage

NOTE: Although docker is used in these examples, users have reported that other engines such as podman can also be used. See also kata-containers/runtime#1280.

As a GitHub Action

Run the Action without arguments for registering all the supported interpreters:

  - uses: dbhi/qus/action@main

Optionally, provide a space-separated list of target architectures:

  - uses: dbhi/qus/action@main
    with:
      targets: arm aarch64

Then, execute foreign binaries and/or containers straightaway!

NOTE: yaml-multiline.info

Setup

The recommended approach is to run the following container:

docker run --rm --privileged aptman/qus -s -- -p [TARGET_ARCH]

NOTE: since aptman/qus is a manifest, this command works on amd64, arm64v8, arm32v7, arm32v6, i386, s390x or ppc64le hosts.

The required qemu-*-static binaries (which are all included in the image) will be loaded and registered. The container will then exit. From there on, images and/or binaries for foreign architectures can be executed.

Optional argument TARGET_ARCH is the target architecture to be translated through QEMU. If it is omitted, all available targets will be registered and loaded. The supported values are the following:

i386 i486 alpha arm armeb sparc32plus ppc ppc64 ppc64le m68k mips mipsel mipsn32 mipsn32el mips64 mips64el sh4 sh4eb s390x aarch64 aarch64_be hppa riscv32 riscv64 xtensa xtensaeb microblaze microblazeel or1k x86_64

NOTE: sudo privileges on the host are required in order to register binfmt formats. On GNU/Linux, it is possible to execute register.sh directly. On Windows, a container must be used, so that changes are applied to the underlying VM, since no kernel is available on the host (i.e., from the test list, only C, V, I or D will work on Windows).

Reset

In order to unset the registered formats, and unload the binaries, run:

docker run --rm --privileged aptman/qus -- -r

Help

# docker run --rm --privileged aptman/qus -h
Usage: register.sh [--help][--interactive][--list][--static][-- ARGS]

  Wrapper around qemu-binfmt-conf.sh, to configure binfmt_misc to use qemu interpreter

  -h|--help|-help:
      display this usage

  -i|--interactive|-interactive:
      execute all the remaining args with 'sh -c', then exit

  -l|--list|-list:
      list currently registered interpreters

  -s|--static|-static:
      add '--qemu-suffix -static' to ARGS

  -- ARGS:
     arguments for qemu-binfmt-conf.sh

  To register a single static target persistently, use e.g.:

      register.sh -s -- -p aarch64

  To remove all register interpreters and exit, use:

      register.sh -- -r

Bandwidth-efficient procedure

In contexts such as CI pipelines it might be desirable to reduce the required bandwidth. Hence, instead of using aptman/qus images —which include all the binaries for all the supported target architectures—, individual tarballs are available through GitHub Releases. These can be used along with aptman/qus:register images or with register.sh (without an OCI runtime). See either f, F, c, C, v or V in Tests for examples of these use cases.