wimcast

Build Windows images for Foreman on Linux.

wimcast turns Windows ISOs into a Foreman-ready HTTP tree of per-edition WIM files. It is a drop-in replacement for WIMan / GenerateWIM.ps1, running unprivileged on Linux: no Windows host, no root, no mount(2), no FUSE, no ADK.

sources/<arch>/<name>/*.iso   -->   finalized/<arch>/<name>/
                                        sources/
                                          boot.wim
                                          ServerStandard.wim
                                          ServerDatacenter.wim
                                          images.ini
                                          drivers/...
                                        wimboot
                                        bootmgr, bootmgr.efi
                                        boot/boot.sdi, boot/bcd
                                        build.json

Why wimcast

Quick start

uv tool install wimcast   # or: pipx install wimcast

wimcast doctor                 # check prerequisites (safe, installs nothing)
wimcast probe sources/         # inspect your ISOs before building
wimcast build sources/         # build the finalized/ tree
ls finalized/                  # ready to serve over HTTP

That's it. Three commands from zero to a deployable tree.

Installation

uv tool install wimcast
# or: pipx install wimcast
# or: python3.12 -m pip install --user wimcast

Debian/Ubuntu:

sudo apt install wimtools
uv tool install wimcast   # pycdlib is installed as a dependency

wimcast doctor tells you exactly what is missing, and whether it is required or only conditional.

Deploy to Foreman

The full walkthrough (deployment repo, CI pipeline, web server, Foreman setup with Ansible) is in docs/foreman-integration.md.

The 30-second version:

1. Create a deployment repo with your ISOs:

   deploy-repo/
     sources/<arch>/<name>/*.iso     # your ISOs
     .gitlab-ci.yml                  # copy ci/examples/deploy-pipeline.yml
     wimcast.toml                    # optional, see ci/examples/wimcast.toml
   

2. Configure 4 CI/CD variables: WEB_SERVER, WEB_SERVER_URL, WEB_SERVER_USER, SSH_PRIVATE_KEY_B64.

3. Push: the pipeline runs init -> build -> deploy -> verify and your finalized/ tree lands on your web server.

4. Configure Foreman (media, OS, provisioning template): see the Ansible playbook in docs/foreman-integration.md.

Ready-to-copy files:

Commands

Global flags: --version, --config <path>, -v/--verbose.

Configuration

wimcast.toml in the working directory, all values optional. A missing file yields the defaults; an invalid value is an error.

[winpe]
source = "iso"          # "iso" (default): boot.wim index 1 from the ISO
# source = "file"       # externally prepared WinPE (e.g. ADK-built)
# path   = "assets/boot-winpe-amd64.wim"
# sha256 = "..."
iso_index = 1           # boot.wim index to export as WinPE base

[editions]
allowed = []            # substring match on image name; e.g. ["Standard", "Datacenter"]

[output]
filename_scheme = "installationtype"   # or "editionid" or "install"

[wimboot]
version = "2.9.0"       # pinned version, verified by checksum
# sha256 = "..."        # required for an unpinned version; overrides the built-in digest

[jobs]
cpu = 0                 # concurrent wimlib-imagex calls (0 = auto-detect)

[cache]
directory = ".cache"    # content-addressed store; unset = no cache

[tools]
wimlib_imagex = "wimlib-imagex"   # override binary path if not in PATH
sevenzip = "7z"                   # ISO fallback backend

wimboot is downloaded once from the pin's GitHub release and then cached. The built-in SHA-256 is checked before use; override [wimboot] sha256 to pin a different release, including offline mirrors.

Requirements

Drivers

• boot.wim (WinPE): INF trees from winpe/drivers/ are added into the WIM under \Drivers\ and loaded with drvload in startnet.cmd before wpeinit.
• install.wim (installed OS): the driver tree is published into finalized/<arch>/<name>/sources/drivers/ and applied at deploy time by dism /image:W:\ /add-driver /recurse inside WinPE. Offline injection into install.wim needs DISM, so it is not done on Linux.

Windows versions

Supported target: Windows Server 2016/2019/2022/2025 and Windows 10/11 (amd64). wimcast probe reports the backend actually used per ISO; the live test matrix is maintained in docs/compatibility.md.

Non-goals (deliberate)

• Offline update integration (.msu/.cab): updates/ is warned about and ignored. Patching happens after deployment (Ansible/WSUS/GPO).
• Offline driver injection into install.wim: drivers are published as a tree and injected by DISM inside WinPE at deploy time.
• ISO authoring: the output is an HTTP tree, not bootable media.

Contributing

See CONTRIBUTING.md: architecture, module map, quality gates, conventions, release process.

License

MIT