Repository files navigation

qemu-user-static (qus) is a compilation of utilities, examples and references to build and execute OCI images (akadocker images) for foreign architectures usingQEMU'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 andppc64le.
• Multiple minimal working setups to build and executearm64v8 containers onamd64 are configured and tested onGitHub 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 atdbhi.github.io/qus.

NOTE: Althoughdocker is used in these examples, users have reported that other engines such aspodman can also be used. See alsokata-containers/runtime#1280.

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@mainwith:targets:arm aarch64

Then, execute foreign binaries and/or containers straightaway!

NOTE:yaml-multiline.info

The recommended approach is to run the following container:

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

NOTE: sinceaptman/qus is a manifest, this command works onamd64,arm64v8,arm32v7,arm32v6,i386,s390x orppc64le hosts.

The requiredqemu-*-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 argumentTARGET_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 registerbinfmt formats.On GNU/Linux, it is possible to executeregister.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 thetest list, onlyC,V,I orD will work on Windows).

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

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

# docker run --rm --privileged aptman/qus -hUsage: 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',thenexit  -l|--list|-list:      list currently registered interpreters  -s|--static|-static:      add'--qemu-suffix -static' to ARGS  -- ARGS:     argumentsfor 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

In contexts such as CI pipelines it might be desirable to reduce the required bandwidth. Hence, instead of usingaptman/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 withaptman/qus:register images or withregister.sh (without an OCI runtime). See eitherf,F,c,C,v orV inTests for examples of these use cases.