sensu-plugins-windows 2.2.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: cb4db0eaf8556a99517db61e0d39f4436095cfb6
-  data.tar.gz: aab24efe6b3cd1c0e6a0e6b513bde7d2d78aeec5
+SHA256:
+  metadata.gz: e2c09a015df087022d158773dc055bc71862dac29c00f1d99d4982b980289b6c
+  data.tar.gz: 7c39068ecf25e4123c27741af9addff0ceac3c121a26474b250f1e2fdbbc3df0
 SHA512:
-  metadata.gz: 96c01b64874dd084b3b8f337976b09857f0a819224bf6f9fa4751bb0a52ffb71c11dd0453c9f41645d3b5a3b57649b9043fc4e0afbe48734ac66d2494f47c009
-  data.tar.gz: e3f6e9f4d11aacafc1b25b78bfd25b99d4da1e251535177f5fff833b4fdc55eb122359579e434f47c3745f88d066630bc27f246f290f037b52c5ff564c24411a
+  metadata.gz: 44c6c198d8c0fe28f308983ca9328a0b9de44e773aca7190884c1c5a18fd171f0db214a8f878cffbeaf1e5f346f5ef60dadb439cd41b40dc5711cc9f65a88684
+  data.tar.gz: 23ad80d6943f331720853e9a1ede22f70ad7bc947abd62925b502f7624d1341a2da56ef95e73d1db291b4af4596c34781a35e1ea3543c84f005d069767fe22f7

data/CHANGELOG.md

@@ -6,6 +6,16 @@ Which is based on [Keep A Changelog](http://keepachangelog.com/)
 
 ## [Unreleased]
 
+## [2.3.0] - 2017-11-12
+### Added
+- new check: `powershell/check-multi-template/check-processes.ps1` (@absolutejam)
+- new check `powershell/check-multi-template/check-services.ps1` (@absolutejam)
+- new check `powershell/check-multi-template/check-multi-template.ps1` (@absolutejam)
+- new check `powershell/check-multi-template/check-iscsi.ps1` (@absolutejam)
+- new check `powershell/check-multi-template/check-focusedprocess.ps1` (@absolutejam)
+- new check: `powershell/check-multi-template/check-adapters.ps1` (@absolutejam)
+- documentation `powershell/check-multi-template/README.md` (@absolutejam)
+
 ## [2.2.1] - 2017-09-25
 ### Changed
 - update changelog guidelines location (@majormoses)
@@ -125,6 +135,7 @@ Which is based on [Keep A Changelog](http://keepachangelog.com/)
 - Initial release
 
 [Unreleased]: https://github.com/sensu-plugins/sensu-plugins-Windows/compare/2.2.1...HEAD
+[2.3.0]: https://github.com/sensu-plugins/sensu-plugins-Windows/compare/2.2.1...2.3.0
 [2.2.1]: https://github.com/sensu-plugins/sensu-plugins-Windows/compare/2.2.0...2.2.1
 [2.2.0]: https://github.com/sensu-plugins/sensu-plugins-Windows/compare/2.1.0...2.2.0
 [2.1.0]: https://github.com/sensu-plugins/sensu-plugins-Windows/compare/2.0.0...2.1.0

data/bin/powershell/check-multi-template/README.md

@@ -0,0 +1,177 @@
+# check-multi-template
+
+A Sensu Powershell template.
+
+## Overview
+
+The `check-multi-template` is designed to provide a single base template for
+PowerShell plugins, reducing uneccessary boilerplate and providing a base set of
+features and expecations that make it easier to write checks. In particular, the
+plugins based upon the template can consume multiple items to be checked - 
+Please see *Paramaters* heading for more info.
+
+The template itself can be copied, altered and used directly, but it is more 
+effective to import it and use it as a template.
+
+## Usage
+
+Take a look at any of the other checks in this directory (eg. 
+`check-adapters.ps1`), and you will see they all include the following elements:
+
+  - **Parameter block** - Arguments provided from the CLI. Please see 
+  *Parameters* heading for more info.
+  - **Template import** - Dot source import of the template from the same folder
+  as the plugin. This imports all of of the default options and all functions.
+  - **CheckOptions hashtable** - Configuration for the check. Overrides defaults
+  from the template.
+  - **Call to `Invoke-Main` function** - Along with the parameters to be 
+  consumed, eg.
+  `Invoke-Main -CriticalItems $CriticalAdapters -ImportantItems $ImportantAdapters`
+
+## Features
+
+The crux of the template logic comes from simply comparing the values in arrays -
+ one consisting of values that have been passed in via. command-line arguments,
+the other consisting of items in a specific state.
+
+If you look in the function `Invoke-Main`, you will see 3 main steps in 
+determining service health:
+
+  - Compare all items passed in via. CLI parameters (`ImportantItems` & 
+  `CriticalItems`) against `BaseItems` array. This first checks to see if any of
+  the items are missing. This can be disabled by changing 
+  `$CheckOptions.CheckMissing` to `$False`.
+
+  - Compare `ImportantItems` against `FailedItems` array.
+
+  - Compare `CriticalItems` against `FailedItems` array.
+
+And these arrays are populated via. the scriptblocks (Anonymous functions) in
+`$CheckOptions`. For example, the scriptblocks used in `check-adapters` are:
+
+```powershell
+'ScriptBlockBaseItems' = {
+    Get-NetAdapter |
+    Select-Object -ExpandProperty Name
+}
+
+'ScriptBlockFailedItems' = {
+    Get-NetAdapter |
+    Where-Object { $_.Status -ne 'Up' } |
+    Select-Object -ExpandProperty Name
+}
+```
+
+As you can see, the `ScriptBlockBaseItems` simply gets all network adapters on
+the machine and then expands the `Name` property.
+
+The `ScriptBlockFailedItems` simply does the same, but only for adapters with
+a state not equal to 'Up'.
+
+Now, we compare our CLI parameters against these, and if any of the items we
+passed in are present in `FailedItems`, the script will flag it according to
+whether it was part of the `CriticalItems` or `ImportantItems` parameter.
+
+### Inverting the logic
+
+The logic can be reversed but changing `$CheckOptions.Inverse` to `$True`,
+meaning that the script will check to see if `ImportantItems` and 
+`CriticalItems` are *absent* from `FailedItems`.
+
+An example of this being used is in `check-iscsi.ps1` as it checks to see if
+any of the IQNs passed in at the CLI are *absent* from the list of all sessions.
+
+**NOTE:** Inverting the logic will automatically disable the 'missing' check.
+
+### Parameters
+
+Most of the examples will have parameters equivalent to the template's 
+`CriticalItems` and `ImportantItems` parameters (eg. `check-adapters.ps1` has 
+`CriticalAdapters` and `ImportantAdapters`) which allows the plugin to provide 
+a different return value based on whether items were flagged as 'critical' or
+'important'.
+
+  > **NOTE:** The highest severity result is taken for the final check result. 
+  > This means that if both items in `ImportantItems` and items in 
+  > `CriticalItems` are flagged as in a failed state, the overall status will be
+  > `CRITICAL:` (Exit code `2`). All failed items will still be shown in the 
+  > check output with their respective importance levels.
+
+Additionally, there is some extra processing done in the parameters to
+accommodate for multiple instances of Sensu's token substitution. Here is an
+excerpt from the help provided in the template detailing this:
+
+> Sensu check token substitution:
+>   Because this check is designed to make full use of Sensu's check token 
+>   substitution (https://sensuapp.org/docs/latest/reference/checks.html#check-token-substitution)
+>   feature, some special considerations have been taken for how the arguments are parsed.
+> 
+>   The main parameters support a list of of comma-separated strings.
+>     eg. -CriticalItems 'value1','value2'
+>   They also accepts accept a single string with comma-separated values.
+>     eg. -param1 'value1,value2'
+>   ...or you can mix & match the two and all of the values will be merged.
+>     eg. -param1 'value1','value2,value3'
+>   Additionally, any use of the word 'None' will be ignored.
+>     eg. -param1 'value1','None,value2','None'
+> 
+>   This is because Sensu's client attribute substitution tokens only work with 
+>   flat strings, but by supporting both of the above methods, it allows the use
+>   of multiple values within a single check/client attribute AND multiple
+>   different client/check attributes to be used. Additionally, because 'None'
+>   is ignored, it allows the user to provide a default value in the check 
+>   token substitution, as not to throw an error if the value is missing.
+> 
+> Token substitution example:
+>   Check attribute 'check_attr'   = "alpha,bravo"
+>   Client attribute 'client_attr' = "charlie,delta"
+> 
+>     powershell.exe -File check.ps1 -param1 ":::check_attr|None:::",":::missing_attr|None:::",":::client_attr|None:::"
+>     
+>   Which evaluates to:
+> 
+>     powershell.exe -File check.ps1 -param "alpha,bravo","None","charlie,delta"
+> 
+>   The script then strips any instances of 'None' and processes the 
+>   comma-separated string as single flat array.
+
+Here is an example of real-world usage:
+
+```json
+{
+  "checks": {
+    "services-running": {
+      "command": "powershell.exe -noprofile -noninteractive -executionpolicy bypass -nologo -file C:\\\\opt\\\\sensu\\\\check-scripts\\\\check-services.ps1 -criticalservices \":::vars.services.critical|None:::,:::vars.services.critical_group|None:::,:::vars.services.critical_all|None:::\" -importantservices \":::vars.services.important|None:::,:::vars.services.important_group|None:::,:::vars.services.important_all|None:::\"",
+      "description": "Checks the status of services",
+      "handlers": [
+        "default"
+      ],
+      "interval": 60,
+      "occurrences": 3,
+      "subscribers": [
+        "winservers"
+      ]
+    }
+  }
+}
+```
+
+And within the host's `client.json`:
+
+```json
+...
+  "vars": {
+      "services": {
+          "critical": "criticalA,criticalB",
+          "critical_group": "criticalC",
+          "critical_all": "criticalD,criticalE",
+          "important": "importantA,importantB",
+          "important_all": "importantD,serviceE"
+      }
+  }
+```
+
+These values are populated by my config-management tool, and it allows me to 
+specify values for the host, the host's group (eg. webservers) and all hosts
+without Sensu having any issues. As you can see, `important_group` is missing,
+but that will simply be substituted with `None` as per the check definition.

data/bin/powershell/check-multi-template/check-adapters.ps1

@@ -0,0 +1,115 @@
+#
+#  check-adapters.ps1
+#
+# DESCRIPTION:
+#   This plugin checks that the specified network adapters are up.
+#
+#   It accepts the '-CriticalAdapters' and '-ImportantAdapters' parameters to 
+#   provide different status level outputs and also checks if the items passed 
+#   are missing completely. Please see the '-Help' parameter, under the 'Sensu 
+#   check token substitution' header for more info on some extra parsing 
+#   features.
+#   
+#   It is built atop check-multi-template.ps1 as an example, and can be easily
+#   adapted to check other things.
+#
+# OUTPUT:
+#   Missing example:
+#     CheckNetworkAdapter CRITICAL:
+#       The following adapters are missing:
+#         - Ethernet
+#
+#   OK example: 
+#     CheckNetworkAdapter OK:
+#       All interfaces are up.
+#
+#   WARN example:
+#     CheckNetworkAdapter WARN:
+#       The following important adapters are down:
+#         - OOB MANAGEMENT
+#
+#   CRITICAL example:
+#     CheckNetworkAdapter CRITICAL:
+#       The following critical adapters are down:
+#         - CLUSTER HEARTBEAT
+#       The following important adapters are down:
+#         - OOB MANAGEMENT
+#
+# PLATFORMS:
+#   Windows
+#
+# DEPENDENCIES:
+#
+# USAGE:
+#   Please run this check with the '-help' parameter for more info.
+#
+# NOTES:
+#
+# LICENSE:
+#   Copyright 2016 James Booth <james@absolutejam.co.uk>
+#   Released under the same terms as Sensu (the MIT license); see LICENSE for 
+#   details.
+#
+
+
+[CmdletBinding()]
+Param(
+  # Network adapters to check. If any are not 'up', they will return a
+  # CRITICAL (2) status. 
+  [Parameter(
+    Mandatory = $False
+  )]
+  [string]$CriticalAdapters,
+  
+  # Network adapters to check. If any are not 'up', they will return a
+  # WARNING (1) status. 
+  [Parameter(
+    Mandatory = $False
+  )]
+  [string]$ImportantAdapters,
+
+  # Display help about this check.
+  [switch]$Help
+)
+
+# Import template
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+. "$here\check-multi-template.ps1"
+
+# Override check options
+$CheckOptions = @{
+    'CheckName' = 'CheckNetworkAdapter'
+    'MessageOK' = 'All interfaces are up.'
+    'MessageImportant' = 'The following important adapters are down:'
+    'MessageCritical' = 'The following critical adapters are down:'
+    'MessageMissing' = 'The following adapters are missing:'
+    'MessageNoneSpecified' = 'No adapters specified.'
+    'MissingState' = 2
+
+    'ScriptBlockBaseItems' = {
+        Get-NetAdapter |
+        Select-Object -ExpandProperty Name
+    }
+
+    'ScriptBlockMatchItems' = {
+        Get-NetAdapter |
+        Where-Object { $_.Status -ne 'Up' } |
+        Select-Object -ExpandProperty Name
+    }
+
+    'CheckHelp' = @'
+Checks whether any specified network adapters are not 'up'.
+
+Arguments:
+  -CriticalAdapters    A string of comma-separated network adapters
+  -ImportantAdapters   A string of comma-separated network adapters
+  -Help                Show help
+
+Example usage:
+  powershell.exe -file check-adapters.ps1 -criticaladapters "CLUSTER NETWORK" -warningadapters"MONITORING NETWORK"
+
+'@
+}
+
+# Run!
+Invoke-Main -CriticalItems $CriticalAdapters -ImportantItems $ImportantAdapters

data/bin/powershell/check-multi-template/check-focusedprocess.ps1

@@ -0,0 +1,102 @@
+#
+#  check-focusedprocess.ps1
+#
+# DESCRIPTION:
+#   This plugin checks the focused process.
+#
+#   It accepts the '-Process' parameter.
+#   
+# OUTPUT:
+#   OK example:
+#     FocusedProcess OK:
+#       <name> is focused.
+#
+#  CRITICAL example:
+#    FocusedProcess CRITICAL:
+#      The following process is not focused:
+#        - <name>
+#
+# PLATFORMS:
+#   Windows
+#
+# DEPENDENCIES:
+#
+# USAGE:
+#   Please run this check with the '-help' parameter for more info.
+#
+# NOTES:
+#
+# LICENSE:
+#   Copyright 2016 James Booth <james@absolutejam.co.uk>
+#   Released under the same terms as Sensu (the MIT license); see LICENSE for 
+#   details.
+#
+
+
+[CmdletBinding()]
+Param(
+  # Process to check. If not the focused process, return CRITICAL (2) status. 
+  [Parameter(
+    Mandatory = $False
+  )]
+  [string]$Process,
+
+  # Display help about this check.
+  [switch]$Help
+)
+
+# Import template
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+. "$here\check-multi-template.ps1"
+
+# Override check options
+$CheckOptions = @{
+    'CheckName' = 'FocusedProcess'
+    'MessageOK' = "$Process is focused."
+    'MessageCritical' = 'The following process is not focused:'
+    'MessageNoneSpecified' = 'No process specified.'
+    'CheckMissing' = $False
+    'Inverse' = $True
+    'ScriptBlockMatchItems' = {
+        Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public class UserWindows {
+    [DllImport("user32.dll")]
+    public static extern IntPtr GetForegroundWindow();
+}
+"@
+    
+        try {            
+            $ActiveHandle = [UserWindows]::GetForegroundWindow()            
+            $Process = Get-Process |
+                       Where-Object { $_.MainWindowHandle -eq $activeHandle } 
+            $Process | 
+            Select-Object -ExpandProperty ProcessName
+            #Select-Object ProcessName,
+            #              @{ N="AppTitle"; E= {($_.MainWindowTitle)} }            
+        } catch {            
+            Throw "Failed to get active Window details. More Info: $_"
+        }
+    }
+
+    'CheckHelp' = @'
+Checks the currently focussed process on a machine. This is useful for machines
+such as digital signage that should always have a dedicated process displayed.
+
+Arguments:
+  -Process    The process name that should be focused.
+  -Help       Show help
+
+Example usage:
+  powershell.exe -file check-focusedprocess.ps1 -process "chrome"
+
+'@
+}
+
+if ((Format-ParamArray -Param $Process).Count -gt 1) {
+    Throw 'Only accepts a single process'
+}
+
+# Run!
+Invoke-Main -CriticalItems $Process

data/bin/powershell/check-multi-template/check-iscsi.ps1

@@ -0,0 +1,114 @@
+#
+#  check-iscsi.ps1
+#
+# DESCRIPTION:
+#   This plugin checks that the specified iSCSI sessions are connected.
+#
+#   It accepts the '-CriticalIQNs and '-ImportantIQNs' parameters to provide
+#   different status level outputs and also checks if the items passed are 
+#   missing completely. Please see the '-Help' parameter, under the 'Sensu 
+#   check token substitution' header for more info on some extra parsing 
+#   features.
+#   
+#   It is built atop check-multi-template.ps1 as an example, and can be easily 
+#   adapted to check other things.
+#
+# OUTPUT:
+#   OK example:
+#     CheckIscsi OK:
+#       All iSCSI sessions are connected.
+#
+#  WARN example:
+#    CheckIscsi WARN:
+#      The following important sessions are not connected:
+#        - iqn.2001-05.com.equallogic:4-42a846-3d3bb3c30-9140000001255ddf-vol01
+#
+#  CRITICAL example:
+#    CheckIscsi CRITICAL:
+#      The following critical sessions are not connected:
+#        - iqn.2001-05.com.equallogic:4-42a846-3d3bb3c30-9140000001255ddf-vol01
+#
+#    CheckIscsi CRITICAL:
+#      The following critical sessions are not connected:
+#        - iqn.2001-05.com.equallogic:4-42a846-3d3bb3c30-9140000001255ddf-vol01
+#      The following important sessions are not connected:
+#        - iqn.2001-05.com.equallogic:4-42a846-3d3bb3c30-9140000001255ddf-vol02
+#
+# PLATFORMS:
+#   Windows
+#
+# DEPENDENCIES:
+#
+# USAGE:
+#   Please run this check with the '-help' parameter for more info.
+#
+# NOTES:
+#
+# LICENSE:
+#   Copyright 2016 James Booth <james@absolutejam.co.uk>
+#   Released under the same terms as Sensu (the MIT license); see LICENSE for 
+#   details.
+#
+
+
+[CmdletBinding()]
+Param(
+  # Target IQNs to check. If any are not connected, they will return a
+  # CRITICAL (2) status. 
+  [Parameter(
+    Mandatory = $False
+  )]
+  [string]$CriticalIQNs,
+  
+  # Target IQNs to check. If any are not connected, they will return a
+  # WARNING (1) status. 
+  [Parameter(
+    Mandatory = $False
+  )]
+  [string]$ImportantIQNs,
+
+  # Display help about this check.
+  [switch]$Help
+)
+
+# Import template
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+. "$here\check-multi-template.ps1"
+
+# Override check options
+$CheckOptions = @{
+    'CheckName' = 'CheckIscsi'
+    'MessageOK' = 'All iSCSI sessions are connected.'
+    'MessageImportant' = 'The following important sessions are not connected:'
+    'MessageCritical' = 'The following critical sessions are not connected:'
+    'MessageMissing' = 'The following sessions are missing:'
+    'MessageNoneSpecified' = 'No IQNs specified.'
+    'MissingState' = 2
+    'Inverse' = $True
+
+    'ScriptBlockBaseItems' = {
+        Get-IscsiSession |
+        Select-Object -ExpandProperty TargetNodeAddress
+    }
+
+    'ScriptBlockMatchItems' = {
+        Get-IscsiSession |
+        Select-Object -ExpandProperty TargetNodeAddress
+    }
+
+    'CheckHelp' = @'
+Checks whether any specified iSCSI sessions are not connected.
+
+Arguments:
+  -CriticalIQNs    A string of comma-separated iSCSI IQNs
+  -ImportantIQNs   A string of comma-separated iSCSI IQNs
+  -Help            Show help
+
+Example usage:
+  powershell.exe -file check-iscsi.ps1 -criticaliqns "iqn..." -warningiqns "iqn..."
+
+'@
+}
+
+# Run!
+Invoke-Main -CriticalItems $CriticalIQNs -ImportantItems $ImportantIQNs