Building and Packaging the Linuxfabrik Monitoring Plugins¶
Target audience: the release manager who cuts the next Linuxfabrik Monitoring Plugins release, and contributors who need to reproduce a build locally.
Outputs per release:
- Windows (ZIP of compiled plugins, and a signed MSI) for x86_64 only. Published to https://download.linuxfabrik.ch/monitoring-plugins/.
- Source-only zip for all operating systems. Published to the download server as well.
The RPM and DEB packages for Linux are built in Linuxfabrik/packaging and published to the Linuxfabrik repository at https://repo.linuxfabrik.ch/. Their build recipes and the supported distributions are documented there.
Publishing a GitHub release starts every build. There is no build on push.
Release Flow¶
Publishing the GitHub release vX.Y.Z (see the release checklist) is the
only manual step besides the two SignPath approvals:
GitHub release vX.Y.Z published
└── lf-release.yml
├── create-source-zip.sh # lfmp-X.Y.Z-1.source.noarch.zip
├── dispatch upstream-release # to Linuxfabrik/packaging
└── lf-build-windows-x86_64.yml # on main, publish: lfmp-X.Y.Z-1.signed-{compiled,packaged}.windows.x86_64.zip
Linuxfabrik/packaging # RPM and DEB, `testing` channel, then `release`
001-p-repo51: publish-downloads.sh # every 15 minutes, to download.linuxfabrik.ch
lf-release.ymlbuilds the source zip from the tag and attaches it to the release, together with a build provenance attestation. It also sendsupstream-releaseto Linuxfabrik/packaging, which opens the version bump right away instead of at its next hourly check, builds the packages and publishes them to thetestingchannel of the Linuxfabrik repository. They are promoted toreleasethere, after seven days by default.lf-release.ymlthen startslf-build-windows-x86_64.ymlas a run onmainwithpublish, which builds the tag: the origin verification of the SignPath signing policy only accepts builds from the branchmain, andverify-version.shmakes sure the tag is reachable from there. The workflow compiles the Windows plugins of the tag and builds the MSI withcreate-wxs.shfrommain, so a rebuild of an older release gets the current MSI definition. Each of the two SignPath signing requests waits up to two hours for an approval; SignPath mailsinfo@when one is pending. The signed ZIP and MSI are attached to the release, with an attestation each.- On the repository server,
build/publish-downloads.shruns from a systemd timer. It picks up new zips from the releases, checks each against its attestation, adds the.sha256and the detached GPG signature.asc, and points thelfmp-latest.*links at the latest release. A prerelease never becomes latest, and nothing is deleted there.
A failed or broken build is repeated under the next iteration, with a manual
run of the same workflow: lf-release.yml with package-iteration, and
lf-build-windows-x86_64.yml with package-iteration and publish. Release
assets are never replaced.
Patch Release for a Security Fix¶
A security fix in a bundled dependency (a Dependabot security update of a
lockfile, or a lib release) reaches the packages and the zips only with a
release. It goes out as a patch release vX.Y.(Z+1) from main, at most once
a week: every release builds the Windows plugins as well, which takes about an
hour and two SignPath approvals. Only when main carries changes that must not
go out yet, the patch release is cut from a branch off the last tag with the fix
cherry-picked.
Overview¶
| Platform | Arch | GitHub workflow | Runner | Outputs | Signed |
|---|---|---|---|---|---|
| Windows | x86_64 | lf-build-windows-x86_64.yml |
windows-2025 |
.zip, .msi |
yes (SignPath.io) |
Windows aarch64 is not built today.
Windows Binaries and MSI¶
Windows is built on a single GitHub-hosted windows-2025 runner with Python
3.13. Every plugin that carries a .windows marker file is compiled with
Nuitka (--standalone, --msvc=latest) into its own directory. The results
are packaged twice: once as a ZIP of the compiled trees, once as an MSI that
installs them under C:\Program Files\ICINGA2\sbin\linuxfabrik\. Both
artifacts are signed by SignPath before they leave the runner.
How it is built on GitHub¶
lf-build-windows-x86_64.yml
├── debug.sh # env dump
├── compile-multiple.sh # loops plugins, calls compile-one.sh
│ ├── verify-version.sh # checkout must contain vLFMP_VERSION
│ └── compile-one.sh # python3 -m nuitka --standalone
├── SignPath submit-signing-request # signs the compiled ZIP
├── create-wxs.sh # emits lfmp.wxs
├── wix.exe build # .wxs -> .msi
└── SignPath submit-signing-request # signs the MSI
For a published release, lf-release.yml starts it to build all plugins of
the tag as iteration 1. A manual run takes the inputs compile-plugins (optional, space-separated allowlist;
empty means all plugins), version, package-iteration and publish: without
publish it builds main and keeps the result as workflow artifacts, with
publish it builds the tag vX.Y.Z and attaches the zips to that release.
compile-multiple.sh runs verify-version.sh first, so a checkout that
predates or diverges from the vLFMP_VERSION tag fails the build instead of
compiling outdated code under a newer version label. Set
LFMP_SKIP_VERSION_CHECK=1 to bypass this for an intentional build of an
untagged development checkout.
Code Signing¶
Free code signing is provided by SignPath.io under the open-source program, with a certificate issued by the SignPath Foundation (thank you).
Signed files are .dll, .exe, .pyd and .msi. Two SignPath
artifact-configuration-slugs are used:
compiled: the ZIP of Nuitka-built plugin directories.packaged: the final MSI.
Both use the release-signing policy. The SignPath project is
monitoring-plugins under organization-id
35067665-5434-42c5-9fa2-4c750069f161. The workflow waits for SignPath to
return each signed artifact before proceeding.
Reproducing a Release Build Locally¶
Compiling a single plugin on a Windows developer box is supported. Producing the final MSI locally is not: the workflow drives SignPath, and signing requires the Linuxfabrik project credentials.
Prerequisites:
- Git Bash (the
build/*.shscripts assume bash). - Python 3.13, on
PATHaspython3. - Visual Studio 2022 Build Tools (supplies MSVC, required by Nuitka
--msvc=latest). python3 -m pip install --upgrade ordered-set Nuitka.python3 -m pip install --require-hashes --requirement lockfiles/py313-windows/requirements.txtfrom the monitoring-plugins repository root. ThepyXXdirectory underlockfiles/matches the Python version the Windows build is pinned to (3.13 today).- The plugin must carry a
.windowsmarker file. Plugins without it are skipped bycompile-one.sh.
To compile one plugin:
export LFMP_DIR_REPOS=/c/Users/<you>/lfmp/repos
export LFMP_DIR_COMPILED=/c/Users/<you>/lfmp/compiled
mkdir -p "$LFMP_DIR_COMPILED"
git clone https://github.com/Linuxfabrik/monitoring-plugins.git "$LFMP_DIR_REPOS/monitoring-plugins"
bash "$LFMP_DIR_REPOS/monitoring-plugins/build/compile-one.sh" check-plugins cpu-usage
# result: $LFMP_DIR_COMPILED/check-plugins/cpu-usage/ (unsigned)
For a full dry run of the compilation step, call
compile-multiple.sh instead; it loops over every plugin the workflow would
build. It runs verify-version.sh first, so export LFMP_VERSION (with the
matching vLFMP_VERSION tag reachable from HEAD) or prefix the call with
LFMP_SKIP_VERSION_CHECK=1. The MSI and the signing steps have no local
fallback, so stop there.
Appendix: Packaging Decisions¶
Why Nuitka Instead of PyInstaller (Windows)¶
Benchmark, December 2024, compiling disk-usage with each tool and running
it 500 times:
| Platform | Python | Build tool | Mode | Size (MB) | 500 runs (s) | VirusTotal |
|---|---|---|---|---|---|---|
| Rocky 8 | 3.9 | Nuitka | --standalone |
19.7 | 15.706 | |
| Rocky 8 | 3.9 | PyInstaller | --onedir |
13.7 | 19.392 | |
| Rocky 8 | 3.9 | Nuitka | --onefile |
7.9 | 33.339 | |
| Rocky 8 | 3.9 | PyInstaller | --onefile |
6.4 | 45.838 | |
| WinSrv 2022 | 3.12 | Nuitka (msvc) | --standalone |
22.3 | 31.560 | 2/71 |
| WinSrv 2022 | 3.12 | Nuitka (gcc) | --standalone |
23.4 | 29.570 | 4/72 |
| WinSrv 2022 | 3.12 | PyInstaller | --onedir |
16.7 | 51.476 | 13/71 |
| WinSrv 2022 | 3.12 | Nuitka (msvc) | --onefile |
6.67 | 253.006 | 15/72 |
| WinSrv 2022 | 3.12 | Nuitka (gcc) | --onefile |
6.83 | 243.167 | 24/71 |
| WinSrv 2022 | 3.12 | PyInstaller | --onefile |
17.1 | 462.180 | 7/72 |
Takeaways:
- Nuitka
--standaloneis the fastest runtime option on both platforms (1.2x-1.7x over PyInstaller--onedir), at the cost of 30-45% more on-disk size. - Onefile builds pay a per-run self-extraction tax that makes them 3x to 10x slower than their onedir counterparts. For a plugin that runs every 10-60 seconds, this is disqualifying.
- On Windows, Nuitka
--standalonewith MSVC has the lowest Windows Defender / VirusTotal false-positive rate we measured (2/71). gcc is close behind (4/72). Onefile builds are flagged noticeably more often.
The benchmark has not been re-run against Python 3.13 (our current build target); ratios there may have shifted.
Why Python 3.13 (Not 3.14) on Windows¶
Nuitka 4.0 (current stable) lists Python 3.14 as experimental and explicitly
not production-ready. Official support covers Python 3.4 through 3.13. We
build with --standalone --msvc=latest, both paths where partial 3.14 support
in Nuitka tends to surface first. Until Nuitka declares 3.14 stable, the
Windows workflow stays pinned to 3.13.
This has no security impact: actions/setup-python@v6 resolves
python-version: '3.13' to the latest 3.13.x patch release at build time,
so each release picks up the bundled OpenSSL update from upstream CPython.