diff --git a/doc/10-Icinga-Plugins.md b/doc/10-Icinga-Plugins.md index f65fe1b3..9576681d 100644 --- a/doc/10-Icinga-Plugins.md +++ b/doc/10-Icinga-Plugins.md @@ -31,6 +31,7 @@ icinga> icinga { Invoke-IcingaCheckCPU -Warning 20 -Critical 40 -Core _Total -Th * [Invoke-IcingaCheckDiskHealth](plugins/20-Invoke-IcingaCheckDiskHealth.md) * [Invoke-IcingaCheckEventlog](plugins/06-Invoke-IcingaCheckEventlog.md) * [Invoke-IcingaCheckFirewall](plugins/07-Invoke-IcingaCheckFirewall.md) +* [Invoke-IcingaCheckFreePartitionSpace](plugins/27-Invoke-IcingaCheckFreePartitionSpace.md) * [Invoke-IcingaCheckHTTPStatus](plugins/25-Invoke-IcingaCheckHTTPStatus.md) * [Invoke-IcingaCheckICMP](plugins/08-Invoke-IcingaCheckICMP.md) * [Invoke-IcingaCheckMemory](plugins/09-Invoke-IcingaCheckMemory.md) diff --git a/doc/plugins/27-Invoke-IcingaCheckFreePartitionSpace.md b/doc/plugins/27-Invoke-IcingaCheckFreePartitionSpace.md new file mode 100644 index 00000000..7ed539d9 --- /dev/null +++ b/doc/plugins/27-Invoke-IcingaCheckFreePartitionSpace.md @@ -0,0 +1,60 @@ + +# Invoke-IcingaCheckFreePartitionSpace + +## Description + +Checks how much space on a partition is free. + +Invoke-IcingaCheckFreePartition returns either 'OK', 'WARNING' or 'CRITICAL', based on the thresholds set. +e.g 'C:' is at 8% usage, WARNING is set to 60, CRITICAL is set to 80. In this case the check will return OK. + +The plugin will return `UNKNOWN` in case partition data (size and free space) can not be fetched. This is +normally happening in case the user the plugin is running with does not have permissions to fetch this +specific partition data. + +More Information on https://github.com/Icinga/icinga-powershell-plugins + +## Permissions + +To execute this plugin you will require to grant the following user permissions. + +### WMI Permissions + +* Root\Cimv2 + +### Performance Counter + +* LogicalDisk(*)\% free space + +### Required User Groups + +* Performance Monitor Users + +## Arguments + +| Argument | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| Warning | Object | false | | Used to specify a Warning threshold. This can either be a byte-value type like '10GB' or a %-value, like '10%' | +| Critical | Object | false | | Used to specify a Critical threshold. This can either be a byte-value type like '10GB' or a %-value, like '10%' | +| Include | Array | false | @() | Used to specify an array of partitions to be included. If not set, the check expects that all not excluded partitions should be checked. e.g. 'C:','D:' | +| Exclude | Array | false | @() | Used to specify an array of partitions to be excluded. e.g. 'C:','D:' | +| IgnoreEmptyChecks | SwitchParameter | false | False | Overrides the default behaviour of the plugin in case no check element is left for being checked (if all elements are filtered out for example). Instead of returning `Unknown` the plugin will return `Ok` instead if this argument is set. | +| NoPerfData | SwitchParameter | false | False | Disables the performance data output of this plugin | +| SkipUnknown | SwitchParameter | false | False | Allows to set Unknown partitions to Ok in case no metrics could be loaded. | +| Verbosity | Int32 | false | 0 | Changes the behavior of the plugin output which check states are printed: 0 (default): Only service checks/packages with state not OK will be printed 1: Only services with not OK will be printed including OK checks of affected check packages including Package config 2: Everything will be printed regardless of the check state 3: Identical to Verbose 2, but prints in addition the check package configuration e.g (All must be [OK]) | +| ThresholdInterval | Object | | | Change the value your defined threshold checks against from the current value to a collected time threshold of the Icinga for Windows daemon, as described [here](https://icinga.com/docs/icinga-for-windows/latest/doc/service/10-Register-Service-Checks/). An example for this argument would be 1m or 15m which will use the average of 1m or 15m for monitoring. | + +## Examples + +### Example Command 1 + +```powershell +Invoke-IcingaCheckFreePartitionSpace -Warning 5GB -Critical 2GB +``` + +### Example Output 1 + +```powershell +[OK]: Check package "Free Partition Space" is [OK]| 'partition_c'=7493583000B;5368709120:;2147483648:;0;29485960000 +``` + diff --git a/icinga-powershell-plugins.psd1 b/icinga-powershell-plugins.psd1 index 53462165..1918b8da 100644 Binary files a/icinga-powershell-plugins.psd1 and b/icinga-powershell-plugins.psd1 differ diff --git a/plugins/Invoke-IcingaCheckFreePartitionSpace.psm1 b/plugins/Invoke-IcingaCheckFreePartitionSpace.psm1 new file mode 100644 index 00000000..052a23f3 --- /dev/null +++ b/plugins/Invoke-IcingaCheckFreePartitionSpace.psm1 @@ -0,0 +1,142 @@ +<# +.SYNOPSIS + Checks how much space on a partition is free. +.DESCRIPTION + Invoke-IcingaCheckFreePartition returns either 'OK', 'WARNING' or 'CRITICAL', based on the thresholds set. + e.g 'C:' is has 8% free, WARNING is set to 60, CRITICAL is set to 80. In this case the check will return OK. + + The plugin will return `UNKNOWN` in case partition data (size and free space) can not be fetched. This is + normally happening in case the user the plugin is running with does not have permissions to fetch this + specific partition data. + + More Information on https://github.com/Icinga/icinga-powershell-plugins +.FUNCTIONALITY + This module is intended to be used to check how much free there is on an partition. + Based on the thresholds set the status will change between 'OK', 'WARNING' or 'CRITICAL'. The function will return one of these given codes. + + The plugin will return `UNKNOWN` in case partition data (size and free space) can not be fetched. This is + normally happening in case the user the plugin is running with does not have permissions to fetch this + specific partition data. +.ROLE + ### WMI Permissions + + * Root\Cimv2 + + ### Performance Counter + + * LogicalDisk(*)\% free space + + ### Required User Groups + + * Performance Monitor Users +.EXAMPLE + PS>Invoke-IcingaCheckFreePartitionSpace -Warning 5GB -Critical 2GB + [OK]: Check package "Free Partition Space" is [OK] + | 'partition_c'=7493583000B;5368709120:;2147483648:;0;29485960000 +.PARAMETER Warning + Used to specify a Warning threshold. This can either be a byte-value type like '10GB' + or a %-value, like '10%' +.PARAMETER Critical + Used to specify a Critical threshold. This can either be a byte-value type like '10GB' + or a %-value, like '10%' +.PARAMETER Exclude + Used to specify an array of partitions to be excluded. + e.g. 'C:','D:' +.PARAMETER Include + Used to specify an array of partitions to be included. If not set, the check expects that all not excluded partitions should be checked. + e.g. 'C:','D:' +.PARAMETER IgnoreEmptyChecks + Overrides the default behaviour of the plugin in case no check element is left for being checked (if all elements are filtered out for example). + Instead of returning `Unknown` the plugin will return `Ok` instead if this argument is set. +.PARAMETER SkipUnknown + Allows to set Unknown partitions to Ok in case no metrics could be loaded. +.PARAMETER NoPerfData + Disables the performance data output of this plugin +.PARAMETER Verbosity + Changes the behavior of the plugin output which check states are printed: + 0 (default): Only service checks/packages with state not OK will be printed + 1: Only services with not OK will be printed including OK checks of affected check packages including Package config + 2: Everything will be printed regardless of the check state + 3: Identical to Verbose 2, but prints in addition the check package configuration e.g (All must be [OK]) +.INPUTS + System.String +.OUTPUTS + System.String +.LINK + https://github.com/Icinga/icinga-powershell-plugins +.NOTES +#> + +function Invoke-IcingaCheckFreePartitionSpace() +{ + param( + $Warning = $null, + $Critical = $null, + [array]$Include = @(), + [array]$Exclude = @(), + [switch]$IgnoreEmptyChecks = $FALSE, + [switch]$NoPerfData = $FALSE, + [switch]$SkipUnknown = $FALSE, + [ValidateSet(0, 1, 2, 3)] + [int]$Verbosity = 0 + ); + + $Disks = Get-IcingaPhysicalDiskInfo; + $DiskPackage = New-IcingaCheckPackage -Name 'Free Partition Space' -Verbose $Verbosity -IgnoreEmptyPackage:$IgnoreEmptyChecks -OperatorAnd -AddSummaryHeader; + + foreach ($disk in $Disks.Values) { + + foreach ($partitions in $disk.PartitionLayout.Keys) { + $partition = $disk.PartitionLayout[$partitions]; + $ProcessPartition = $TRUE; + + if ([string]::IsNullOrEmpty($partition.DriveLetter)) { + continue; + } + + if ($disk.DriveReference.ContainsKey($partition.DriveLetter) -eq $FALSE) { + continue; + } + + $PartitionId = $disk.DriveReference[$partition.DriveLetter]; + + if ($partitions -ne $PartitionId) { + continue; + } + + foreach ($entry in $Include) { + $ProcessPartition = $FALSE; + if ($entry.Replace(':', '').Replace('\', '').Replace('/', '').ToLower() -eq $partition.DriveLetter.Replace(':', '').ToLower()) { + $ProcessPartition = $TRUE; + break; + } + } + foreach ($entry in $Exclude) { + if ($entry.Replace(':', '').Replace('\', '').Replace('/', '').ToLower() -eq $partition.DriveLetter.Replace(':', '').ToLower()) { + $ProcessPartition = $FALSE; + break; + } + } + + if ($ProcessPartition -eq $FALSE) { + continue; + } + + $IcingaCheck = New-IcingaCheck -Name ([string]::Format('Partition {0}', $partition.DriveLetter)) -Value $partition.FreeSpace -Unit 'B' -Minimum 0 -Maximum $partition.Size -NoPerfData:$SetUnknown -BaseValue $partition.Size; + + if ([string]::IsNullOrEmpty($partition.FreeSpace) -Or [string]::IsNullOrEmpty($partition.Size)) { + if ($SkipUnknown -eq $FALSE) { + [void]$IcingaCheck.SetUnknown('No disk size and/or free space available', $TRUE) + } else { + [void]$IcingaCheck.SetOk('No disk size and/or free space available', $TRUE) + } + } else { + [void]$IcingaCheck.WarnIfLowerThan($Warning).CritIfLowerThan($Critical) + } + + $DiskPackage.AddCheck($IcingaCheck); + } + } + + return (New-IcingaCheckResult -Check $DiskPackage -NoPerfData $NoPerfData -Compile); +}