Skip to content

Repository files navigation

PowerShell Version License: GPL-3.0-or-later CI GitHub Release GitHub Issues GitHub Pull Requests

Icinga for Windows

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).


Architecture Overview

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 secure event::ExecuteCommand check dispatch for Invoke-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) -- Fluent IcingaPlugin check/package framework, public New-IcingaPlugin SDK cmdlet, IcingaThresholds and IcingaUnit engines, 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, and SecureString helpers.

Runtime & Check Execution Flow

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
Loading

Build, Documentation & CI Governance Pipeline

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)"]
Loading

Quick Start

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%';

Writing Custom Plugins (New-IcingaPlugin SDK)

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.


Developer Build & Validation Commands

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;

Documentation Map

General & Governance

Developer Architecture Guides

Auto-Generated Component API Reference


Contributing

Icinga for Windows is an open-source project and welcomes bug reports, feature requests, documentation improvements, and pull requests:

  1. Check the Issue Tracker and Roadmap before starting work.
  2. Follow all code-styling, runspace-isolation, .NOTES, and SPDX licensing rules in docs/Agents/guidelines/01-Instruction.md.
  3. Add a changelog bullet entry under the current unreleased version in docs/General/Changelog.md on every pull request / feature branch (build/Test-ModuleChangelog.ps1).
  4. Verify all build, documentation, styling, memory-leak, and Pester checks pass before opening a Pull Request.

License

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.

Releases

Packages

Contributors

Languages