Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dbhi/qus
qemu-user-static (qus) and containers, non-invasive minimal working setups
https://github.com/dbhi/qus
aarch64 arm32v6 arm32v7 arm64v8 binfmt container docker foreign-architectures i386 kernel linuxkit podman ppc64le qemu qemu-user-static register s390x
Last synced: 3 months ago
JSON representation
qemu-user-static (qus) and containers, non-invasive minimal working setups
- Host: GitHub
- URL: https://github.com/dbhi/qus
- Owner: dbhi
- License: other
- Created: 2019-03-02T18:20:27.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2024-10-25T00:51:51.000Z (3 months ago)
- Last Synced: 2024-10-26T13:58:36.167Z (3 months ago)
- Topics: aarch64, arm32v6, arm32v7, arm64v8, binfmt, container, docker, foreign-architectures, i386, kernel, linuxkit, podman, ppc64le, qemu, qemu-user-static, register, s390x
- Language: Python
- Homepage: https://dbhi.github.io/qus
- Size: 2.89 MB
- Stars: 323
- Watchers: 7
- Forks: 17
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: COPYING.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
*qemu-user-static* (**qus**) is a compilation of utilities, examples and references to build and execute OCI images (aka [docker](https://www.docker.com/) images) for foreign architectures using [QEMU](https://www.qemu.org/)'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?](https://github.com/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](https://github.com/dbhi/qus/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](https://dbhi.github.io/qus).
# Usage
> NOTE: Although `docker` is used in these examples, users have reported that other engines such as [podman](https://podman.io/) can also be used. See also [kata-containers/runtime#1280](https://github.com/kata-containers/runtime/issues/1280).
## As a GitHub Action
Run the Action without arguments for registering all the supported interpreters:
```yaml
- uses: dbhi/qus/action@main
```
Optionally, provide a space-separated list of target architectures:
```yaml
- uses: dbhi/qus/action@main
with:
targets: arm aarch64
```
Then, execute foreign binaries and/or containers straightaway!
NOTE: [yaml-multiline.info](https://yaml-multiline.info)
## Setup
The recommended approach is to run the following container:
``` bash
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](https://dbhi.github.io/qus/tests), only `C`, `V`, `I` or `D` will work on Windows).
## Reset
In order to unset the registered formats, and unload the binaries, run:
``` bash
docker run --rm --privileged aptman/qus -- -r
```
## Help
```sh
# 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`](./register.sh) (without an OCI runtime). See either `f`, `F`, `c`, `C`, `v` or `V` in [Tests](https://dbhi.github.io/qus/tests) for examples of these use cases.