Icinga for Windows (v27.0.0) is a unified, multi-threaded PowerShell monitoring platform and native Icinga 2 agent runtime for Windows Server and Windows client hosts.
All subsystems -- background daemons, the native Icinga 2 JSON-RPC protocol stack, the HTTPS REST API, the performance counter engine, and built-in or custom monitoring plugins -- coordinate through a single synchronized $Global:IcingaForWindows runtime state partitioned into Public (shared thread-safe queues and configuration), Private (runspace-local worker context), and Protected (environment metadata).
Icinga for Windows is organized into focused, single-function source files under src/ that compile into two BOM-less UTF-8 runtime artifacts (lib/IcingaForWindows.Classes.ps1 and lib/IcingaForWindows.Kernel.ps1):
- Core (
Runtime,Threading,Logging,ErrorHandling) -- Runspace pool thread management (New-Thread,Start-ThreadHouseKeeper), structured logging queue (Write-LoggingEntry), garbage collection, and semantic internal return codes (Set-InternalExitCodes). - Core Network (
TCPStack,RestApi,WebSocket,AccessControl) -- TLS 1.2+ socket management, multi-worker HTTPS REST API (Start-RestApiDaemon), persistent WebSocket client workers (Start-ModuleWebSocketDaemon), and role-based access control. - Icinga Protocol (
IcingaProtocol) -- Native Icinga 2 JSON-RPC netstring listener/connector (Start-IcingaAgent) and secureevent::ExecuteCommandcheck dispatch forInvoke-IcingaCheck*cmdlets and approved external binaries/scripts inside$env:ProgramData\IcingaForWindows\Binaries. - Performance Counter Engine (
PerformanceCounter) -- Dedicated background daemon (Start-IcingaPerformanceCounterDaemon), category-level bulk snapshots, static AST counter pre-warming at startup, and automatic inline session fallback. - Monitoring Plugins & Public SDK (
Plugins,Classes) -- FluentIcingaPlugincheck/package framework, publicNew-IcingaPluginSDK cmdlet,IcingaThresholdsandIcingaUnitengines, OS data providers (Disk,FileSystem,Process,ScheduledTask), and nine built-in monitoring checks (CPU,Directory,Memory,PartitionSpace,PerfCounter,Process,ScheduledTask,Service,Uptime). - Configuration, Security & Tools (
Config,Security,Tools) -- Approved-path filesystem wrappers, Windows PowerShell 5.1 memory-safe JSON serialization (ConvertFrom-ModuleJson/ConvertTo-ModuleJson), unit conversion, natural sorting, andSecureStringhelpers.
flowchart TD
Icinga2["Icinga 2 Parent / Master Node"] <-->|"TLS JSON-RPC Netstrings (5665)"| Proto["IcingaProtocol Daemon & Workers"]
ApiClient["HTTPS / Automation Client"] <-->|"TLS HTTP REST / WebSocket"| Rest["RestApi & WebSocket Workers"]
subgraph Runtime["Icinga for Windows Runtime ($Global:IcingaForWindows)"]
Proto --> State[("Synchronized State<br/>Public | Private | Protected")]
Rest --> State
Pool["Runspace Thread Pool & HouseKeeper"] --> State
Log["Logging & GC Daemons"] --> State
PerfDaemon["PerformanceCounter Daemon<br/>(Warm Handles & Category Snapshots)"] <--> State
end
Proto -->|"event::ExecuteCommand"| Dispatcher["Command Resolver & Dispatcher"]
Dispatcher -->|"Invoke-IcingaCheck*"| SDK["New-IcingaPlugin Fluent SDK<br/>(IcingaPlugin + IcingaThresholds)"]
Dispatcher -->|"Approved Binaries Only"| Bin["External .exe / .cmd / .ps1<br/>(ProgramData/IcingaForWindows/Binaries)"]
SDK --> Providers["OS Data Providers<br/>(Disk, FileSystem, Process, ScheduledTask, CIM)"]
SDK <-->|"Zero-Sleep Counter Reads"| PerfDaemon
flowchart LR
Src["src/<br/>(Classes, Public, Private)"] --> Compiler["build/Build-ModuleProject.ps1"]
Compiler --> Lib["lib/IcingaForWindows.{Classes,Kernel}.ps1<br/>(UTF-8 without BOM + SPDX)"]
Src --> DocGen["build/Build-ModuleDocs.ps1<br/>(-Strict $true)"]
DocGen --> ApiDocs["docs/Icinga.*.md & docs/index.md"]
Src --> Gates["CI Static & Governance Gates"]
Gates --> PSSA["Invoke-ScriptAnalysis.ps1<br/>(PSScriptAnalyzer)"]
Gates --> Style["Test-ModuleCodeStyling.ps1<br/>(Style, Scope & SPDX)"]
Gates --> Changelog["Test-ModuleChangelog.ps1<br/>(PR Changelog & Roadmap)"]
Gates --> Leak["Test-ModuleDaemonMemoryLeak.ps1<br/>(AST Loop & IDisposable)"]
Lib --> Pester["build/Invoke-ModuleTests.ps1<br/>(Pester 5+ Unit Tests)"]
Requirements: Windows PowerShell 5.1 or PowerShell 7.5+ on Windows Server / Windows 11. For local development and unit testing, the module also imports cleanly on Linux and macOS via the $env:ProgramData home-directory fallback.
# Import the Icinga for Windows module
Import-Module IcingaForWindows -Force -Global;
# Initialize the runtime in the current session and start background daemons (alias: ifw)
Use-IcingaForWindows -NoNewShell -LogLevel 'Info' -RunBackgroundDaemons;
# Run built-in monitoring plugins interactively
Invoke-IcingaCheckCPU -Warning '80' -Critical '95';
Invoke-IcingaCheckMemory -Warning '85%' -Critical '95%';
Invoke-IcingaCheckPartitionSpace -Warning '80%' -Critical '90%';External modules and custom check scripts build checks through the exported New-IcingaPlugin cmdlet without referencing internal PowerShell class literals directly:
function Invoke-IcingaCheckCustomQueue()
{
param (
[string]$Warning = $null,
[string]$Critical = $null,
[int]$Verbosity = 0,
[switch]$NoPerfData = $false
);
$Package = New-IcingaPlugin -Name 'Message Queues';
$Package.SetNoPerfData($NoPerfData).SetVerbose($Verbosity).Commit();
$QueueCheck = New-IcingaPlugin -Name 'Orders Queue' -Value 42 -Unit 'c';
$QueueCheck.Warning($Warning).Critical($Critical).CheckRange().Commit();
$Package.AddCheck($QueueCheck).Commit();
return $Package.Compile();
}See the Custom Plugin Developer Guide for full details on composite packages, units, thresholds, error handling, and unit testing.
Compiled files under lib/ and API reference pages (docs/Icinga.*.md, docs/index.md) are auto-generated -- never edit them by hand.
# 1. Compile src/ -> lib/ and run AST daemon memory-leak validation
.\build\Build-ModuleProject.ps1 -SkipTests -TestDaemonMemoryLeaks;
# 2. Regenerate strict Markdown API documentation (verifies .NOTES + SPDX across all functions)
.\build\Build-ModuleDocs.ps1 -Strict $true;
# 3. Validate repository-wide PowerShell code styling, function scope, and SPDX headers
.\build\Test-ModuleCodeStyling.ps1;
# 4. Validate Changelog.md and Roadmap.md (enforces changelog entries on non-main branches)
.\build\Test-ModuleChangelog.ps1;
# 5. Run PSScriptAnalyzer static analysis
.\build\Invoke-ScriptAnalysis.ps1 -FailOn 'Warning';
# 6. Execute the Pester unit test suite
.\build\Invoke-ModuleTests.ps1;- Changelog · Roadmap
- Code, Architecture & Documentation Ruleset (
01-Instruction.md) - Knowledgebase (
IWKB001xxx)
- Threading & Runspace Class Isolation · Daemon Memory-Leak Prevention
- Icinga 2 Check & Binary Execution Pipeline
- Performance Counter Architecture · Performance Counter Developer Guide
- Plugin Architecture & Concepts ·
IcingaPluginReference · Result & Error Objects · Custom Plugin Developer Guide
- API Reference Index -- Complete index of all public cmdlets and private helpers
- Monitoring & Protocol: Monitoring Checks · Plugin SDK (
Plugins.Lib) · Icinga Protocol · Performance Counter - OS Data Providers: Disk · FileSystem · Process · ScheduledTask
- Core Runtime & Network: Runtime · Threading · Logging · Error Handling · TCP Stack · REST API · WebSocket · Access Control
- Platform Utilities: Configuration · Security · Tools
Icinga for Windows is an open-source project and welcomes bug reports, feature requests, documentation improvements, and pull requests:
- Check the Issue Tracker and Roadmap before starting work.
- Follow all code-styling, runspace-isolation,
.NOTES, and SPDX licensing rules indocs/Agents/guidelines/01-Instruction.md. - Add a changelog bullet entry under the current unreleased version in
docs/General/Changelog.mdon every pull request / feature branch (build/Test-ModuleChangelog.ps1). - Verify all build, documentation, styling, memory-leak, and Pester checks pass before opening a Pull Request.
Icinga for Windows is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for the full license text.