QEMU Containers for Windows
This project contains patches and build scripts to create binary distributions of the software for running containers on Windows using QEMU virtualization. It started in the scope of the discussion of the issue in Podman project.
The aim is to maintain rebuilds with a minimal set of changes to all needed projects and later to archive it or this project would become an instruction on how to build that kind of setup using released versions.
All thanks goes and attribution stays with the authours of the great pieces of software, which made this project possible in the first place.
The build and setup scripts in this repository are licensed under Apache-2.0 license, but the patches and the original software being patched and rebuilt keeps its original license in effect. This project doesn't change how the rebuilt software is licensed.
This is built for relatively fresh Windows systems, which has unix domain sockets support. The suport was announced starting with Windows 10 Insiders build in late 2017: https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/ It will also require Hyper-V support by default.
Ordered alphabetically
docker-cli- Githubdockercommand line interface;docker-compose- Github orchestration tool for containers;gocat- Github multipurpose networking relay;gvisor-tap-vsock- Github the tool to provide networking for accessing containers from Windows;OpenSSH- home page SSH connectivity tool fork from Powershell Github;Podman- home page and Github free and open source container runtime;Podman Desktop- home page and Github GUI companion to Podman;QEMU- home page and Github (mirror) free and open source feature rich machine emulator;Zlib- home page compression library.
Version v27.3.1. Rebuilt for Windows amd64 platform.
Version v2.30.1. Rebuilt for Windows amd64 platform.
Built from HEAD of the development branch. Added patch with updated dependencies.
Version bundled with Podman is used
Version v9.5.0.0 with 1 patch from Powershell OpenSSH fork PRs:
- Add support for AF_UNIX PowerShell/openssh-portable#674
Version 5.3.0-dev with 3 patch sets:
- Enable compilation for Windows on parts of QEMU machine provider
- Implement QEMU Podman machine on Windows
- Improve platform specific URL handling in podman compose for machines containers/podman#23827
Should be installed via official setup mechanism.
Starting from version 0.0.18 of qcw it is possible to use with official windows builds of QEMU (including msys2).
Version 9.1.1 with 3 patch sets from QEMU mailing list:
- hw/9pfs: Add 9pfs support for Windows https://lists.gnu.org/archive/html/qemu-devel/2023-02/msg05533.html;
- WHPX: Add support for device backed memory regions https://lists.gnu.org/archive/html/qemu-devel/2022-07/msg04837.html;
- Windows installer: keep dependency cache https://lists.gnu.org/archive/html/qemu-devel/2023-01/msg03125.html.
Version 1.3 with 2 patches from main after release and from Powershell fork:
- Add vc17 support
- Set Multibyte character set and spectre mitigation
It is packaged the way similar to official builds, one can just follow official installation instructions. Changed from official buids are considered unstable and discouraged to be used on their own. This is why no additional manual is provided.
Download installation packages of the release. Install QEMU and Podman using their installers. Then install
qcw-utils in the desired directory by opening powershell shell and executing
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/arixmkii/qcw/main/qcw-utils.ps1'))
(each release will have tagged version of this utility as well if
one wants more control over tools version). One will have preconfigured shell launchers under .\qcw-utils\shells\
when installation completes. When using podman-default.bat one needs to configure machine provider in
%APPDATA%\containers\containers.conf setting provider = "qemu" or provider = "wsl" inside [machine] section.
Then run the Podman machine init command as one would do with all other Podman installations. The catch is to give 2 mandatory config overrides:
podman machine init -v ""All other options (except virtfs volume mounts) from QEMU on Linux should work the same way, so, one should be able to tweak the machine to the needed performance requirements.
File system mounts on Windows are unsupported since Podman QEMU had switched to virtiofsd for providing access to host file
system. Virtiofs in general and virtiofsd server specifically are currently usupported on Windows. It should be possible to
re-add older implementation with 9p filesystem back for Windows, but it is not really viable before QEMU adds finalized
9p support in their Windows builds.
Then run the machine as normal
podman machine startThen start the first container with
podman run -d --rm -p 8080:80 nginxAnd test it with curl
curl http://localhost:8080One needs to install latest Podman Desktop (v0.0.12 or newer) to use it with QEMU machine. Running Podman Desktop as
usual (not from either of shells) will launch application ready to connect to the machine with the provider specified in
containers.conf file. Launching application from provided shell, will select QEMU or WSL flavor of Podman machine
matching the behavior of the command line tool.
To run Podman Desktop call this inside shell (" are important because of the app name having whitespace):
"Podman Desktop"It is possible to run Podman with QEMU machine inside Hyper-V VM with nested virtualization enabled. On how to enable nested virtualization one should follow official MS guide. It is users responsibility to allocated enough resources for the VM to host a Podman machine of the expected size. If VM is configured correctly and the HW requirements for nested vitrualization are met, then workflow to run Podman machine should be the same as on bare metal (the performance is expected to be worse to some extent, because it runs inside a VM).
If one has access to Docker Desktop it is possible to use binaries distributed by the software to connect them to
Podman. Alternatively it is possible to download pre-built binaries of the CLI and compose plugin from releases page.
After downloading and unpacking binaries one should make the tools discoverable inside %PATH%. To make docker
recognize the plugin it is recommended to put it into a well-known location like %USERPROFILE%\.docker\cli-plugins.
This step is not needed if Docker Desktop is used as this configures everythign on your behalf.
Using podman compose, when docker-compose is discoverable:
podman compose up --waitUsing docker compose one needs to provide DOCKER_HOST value with named pipe from
podman machine inspect --format {{.ConnectionInfo.PodmanPipe.Path}} converted to URL compatible address:
\\.\pipe\podman-machine-default would become npipe:////./pipe/podman-machine-default
set DOCKER_HOST=npipe:////./pipe/podman-machine-default
docker compose up --waitTBD
The patch used to enable 9pfs is a work in progress. Some of the functionality is missing or is unstable:
- it is impossible to enumerate content of directories containing Windows symlinks;
- it is impossible to enumerate content of directories containing Windows Unix domain socket records;
- non determenistic access denied could be thrown on file overwrites because of some internal races.
There could be leftovers in %TEMP%\podman, which prevents QEMU or gvproxy startup. Solution is to shutdown machine
and then clean up this location manually before starting again.
There is no way to use file system mounts in Podman with QEMU on Windows hosts.
TBD