Merge pull request #135 from Icinga:feature/check_plugin_tcp

Feature: Adds new check plugin Invoke-IcingaCheckTCP

Adds new check plugin Invoke-IcingaCheckCPU to check tcp connections for ports

Author: LordHepipud

config/director/Invoke-IcingaCheckTCP.json

@@ -0,0 +1 @@
+{"DataList":{"IcingaCheckTCP Verbosity":{"list_name":"IcingaCheckTCP Verbosity","originalId":"2","entries":[{"allowed_roles":null,"entry_value":"0","entry_name":"0","format":"string"},{"allowed_roles":null,"entry_value":"1","entry_name":"1","format":"string"},{"allowed_roles":null,"entry_value":"2","entry_name":"2","format":"string"}],"owner":"stein"}},"Command":{"Invoke-IcingaCheckTCP":{"fields":[{"datafield_id":2,"is_required":"n","var_filter":null},{"datafield_id":3,"is_required":"n","var_filter":null},{"datafield_id":4,"is_required":"n","var_filter":null},{"datafield_id":5,"is_required":"n","var_filter":null},{"datafield_id":6,"is_required":"n","var_filter":null},{"datafield_id":7,"is_required":"n","var_filter":null},{"datafield_id":8,"is_required":"n","var_filter":null}],"object_name":"Invoke-IcingaCheckTCP","arguments":{"-C":{"value":"try { Use-Icinga; } catch { Write-Output \u0027The Icinga PowerShell Framework is either not installed on the system or not configured properly. Please check https://icinga.com/docs/windows for further details\u0027; exit 3; }; Exit-IcingaPluginNotInstalled \u0027Invoke-IcingaCheckTCP\u0027; exit Invoke-IcingaCheckTCP","order":"0"},"-Verbosity":{"value":"$IcingaCheckTCP_Object_Verbosity$","order":"6"},"-Warning":{"value":"$IcingaCheckTCP_Object_Warning$","order":"4"},"-Address":{"value":"$IcingaCheckTCP_String_Address$","order":"2"},"-Negate":{"set_if":"$IcingaCheckTCP_Switchparameter_Negate$","set_if_format":"string","order":"99"},"-Critical":{"value":"$IcingaCheckTCP_Object_Critical$","order":"5"},"-NoPerfData":{"set_if":"$IcingaCheckTCP_Switchparameter_NoPerfData$","set_if_format":"string","order":"99"},"-Ports":{"value":{"body":"var arr = macro(\"$IcingaCheckTCP_Array_Ports$\");\r\nif (len(arr) == 0) {\r\nreturn \"@()\";\r\n}\r\nreturn arr.join(\",\");","type":"Function"},"order":"3"}},"imports":["PowerShell Base"],"object_type":"object","vars":{"IcingaCheckTCP_Switchparameter_Negate":false,"IcingaCheckTCP_Switchparameter_NoPerfData":false}},"PowerShell Base":{"methods_execute":"PluginCheck","object_name":"PowerShell Base","vars":{},"is_string":null,"command":"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe","zone":null,"disabled":false,"fields":[],"arguments":{},"imports":[],"object_type":"object","timeout":"180"}},"Datafield":{"7":{"settings":{"visbility":"visible"},"description":"Disables the performance data output of this plugin. Default to FALSE.","caption":"NoPerfData","datatype":"Icinga\\Module\\Director\\DataType\\DataTypeBoolean","originalId":"7","varname":"IcingaCheckTCP_Switchparameter_NoPerfData","format":null},"3":{"settings":{"visbility":"visible"},"description":"A single or a list of ports to check on the target address","caption":"Ports","datatype":"Icinga\\Module\\Director\\DataType\\DataTypeArray","originalId":"3","varname":"IcingaCheckTCP_Array_Ports","format":null},"2":{"settings":{"visbility":"visible"},"description":"The IP address or FQDN of the target host","caption":"Address","datatype":"Icinga\\Module\\Director\\DataType\\DataTypeString","originalId":"2","varname":"IcingaCheckTCP_String_Address","format":null},"4":{"settings":{"visbility":"visible"},"description":"By default the plugin will return [CRITICAL] in case connections to a port are not possible. By setting this argument,\nthe plugin will return [CRITICAL] for successful connections instead","caption":"Negate","datatype":"Icinga\\Module\\Director\\DataType\\DataTypeBoolean","originalId":"4","varname":"IcingaCheckTCP_Switchparameter_Negate","format":null},"6":{"settings":{"visbility":"visible"},"description":"A critical threshold for the connection time in seconds. Allows the usage of unit additions, like 100ms.\n\nAllowed units: ms, s, m, h, d, w, M, y","caption":"Critical","datatype":"Icinga\\Module\\Director\\DataType\\DataTypeString","originalId":"6","varname":"IcingaCheckTCP_Object_Critical","format":null},"5":{"settings":{"visbility":"visible"},"description":"A warning threshold for the connection time in seconds. Allows the usage of unit additions, like 100ms.\n\nAllowed units: ms, s, m, h, d, w, M, y","caption":"Warning","datatype":"Icinga\\Module\\Director\\DataType\\DataTypeString","originalId":"5","varname":"IcingaCheckTCP_Object_Warning","format":null},"8":{"settings":{"datalist":"IcingaCheckTCP Verbosity","behavior":"strict","data_type":"string"},"description":"Changes the behavior of the plugin output which check states are printed:\n0 (default): Only service checks/packages with state not OK will be printed\n1: Only services with not OK will be printed including OK checks of affected check packages including Package config\n2: Everything will be printed regardless of the check state","caption":"Verbosity","datatype":"Icinga\\Module\\Director\\DataType\\DataTypeDatalist","originalId":"8","varname":"IcingaCheckTCP_Object_Verbosity","format":null}}}

config/director/Plugins_Bundle.json

@@ -0,0 +1,51 @@
+object CheckCommand "Invoke-IcingaCheckTCP" {
+    import "PowerShell Base"
+
+    arguments += {
+        "-C" = {
+            value = "try { Use-Icinga; } catch { Write-Output 'The Icinga PowerShell Framework is either not installed on the system or not configured properly. Please check https://icinga.com/docs/windows for further details'; exit 3; }; Exit-IcingaPluginNotInstalled 'Invoke-IcingaCheckTCP'; exit Invoke-IcingaCheckTCP"
+            order = 0
+        }
+        "-Verbosity" = {
+            description = "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"
+            value = "$IcingaCheckTCP_Object_Verbosity$"
+            order = 6
+        }
+        "-Warning" = {
+            description = "A warning threshold for the connection time in seconds. Allows the usage of unit additions, like 100ms.  Allowed units: ms, s, m, h, d, w, M, y"
+            value = "$IcingaCheckTCP_Object_Warning$"
+            order = 4
+        }
+        "-Address" = {
+            description = "The IP address or FQDN of the target host"
+            value = "$IcingaCheckTCP_String_Address$"
+            order = 2
+        }
+        "-Negate" = {
+            set_if = "$IcingaCheckTCP_Switchparameter_Negate$"
+            order = 99
+        }
+        "-Critical" = {
+            description = "A critical threshold for the connection time in seconds. Allows the usage of unit additions, like 100ms.  Allowed units: ms, s, m, h, d, w, M, y"
+            value = "$IcingaCheckTCP_Object_Critical$"
+            order = 5
+        }
+        "-NoPerfData" = {
+            set_if = "$IcingaCheckTCP_Switchparameter_NoPerfData$"
+            order = 99
+        }
+        "-Ports" = {
+            description = "A single or a list of ports to check on the target address"
+            value = {{
+                var arr = macro("$IcingaCheckTCP_Array_Ports$");
+                if (len(arr) == 0) {
+                return "@()";
+                }
+                return arr.join(",");
+            }}
+            order = 3
+        }
+    }
+    vars.IcingaCheckTCP_Switchparameter_Negate = false
+    vars.IcingaCheckTCP_Switchparameter_NoPerfData = false
+}

config/icinga/Invoke-IcingaCheckTCP.conf

@@ -216,7 +216,7 @@ object CheckCommand "Invoke-IcingaCheckICMP" {
 
     arguments += {
         "-WarningPl" = {
-            description = "Treshold on which the plugin will return 'WARNING' for possible packet loss in %"
+            description = "Threshold on which the plugin will return 'WARNING' for possible packet loss in %"
             value = "$IcingaCheckICMP_Object_WarningPl$"
             order = 4
         }
@@ -226,7 +226,7 @@ object CheckCommand "Invoke-IcingaCheckICMP" {
             order = 6
         }
         "-Warning" = {
-            description = "Treshold on which the plugin will return 'WARNING' for the response time in ms"
+            description = "Threshold on which the plugin will return 'WARNING' for the response time in ms"
             value = "$IcingaCheckICMP_Object_Warning$"
             order = 2
         }
@@ -254,7 +254,7 @@ object CheckCommand "Invoke-IcingaCheckICMP" {
             order = 99
         }
         "-Critical" = {
-            description = "Treshold on which the plugin will return 'CRITICAL' for the response time in ms"
+            description = "Threshold on which the plugin will return 'CRITICAL' for the response time in ms"
             value = "$IcingaCheckICMP_Object_Critical$"
             order = 3
         }
@@ -263,7 +263,7 @@ object CheckCommand "Invoke-IcingaCheckICMP" {
             order = 99
         }
         "-CriticalPl" = {
-            description = "Treshold on which the plugin will return 'CRITICAL' for the response time in ms"
+            description = "Threshold on which the plugin will return 'CRITICAL' for the response time in ms"
             value = "$IcingaCheckICMP_Object_CriticalPl$"
             order = 5
         }
@@ -438,6 +438,58 @@ object CheckCommand "Invoke-IcingaCheckUpdates" {
     vars.IcingaCheckUpdates_Switchparameter_NoPerfData = false
 }
 
+object CheckCommand "Invoke-IcingaCheckTCP" {
+    import "PowerShell Base"
+
+    arguments += {
+        "-C" = {
+            value = "try { Use-Icinga; } catch { Write-Output 'The Icinga PowerShell Framework is either not installed on the system or not configured properly. Please check https://icinga.com/docs/windows for further details'; exit 3; }; Exit-IcingaPluginNotInstalled 'Invoke-IcingaCheckTCP'; exit Invoke-IcingaCheckTCP"
+            order = 0
+        }
+        "-Verbosity" = {
+            description = "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"
+            value = "$IcingaCheckTCP_Object_Verbosity$"
+            order = 6
+        }
+        "-Warning" = {
+            description = "A warning threshold for the connection time in seconds. Allows the usage of unit additions, like 100ms.  Allowed units: ms, s, m, h, d, w, M, y"
+            value = "$IcingaCheckTCP_Object_Warning$"
+            order = 4
+        }
+        "-Address" = {
+            description = "The IP address or FQDN of the target host"
+            value = "$IcingaCheckTCP_String_Address$"
+            order = 2
+        }
+        "-Negate" = {
+            set_if = "$IcingaCheckTCP_Switchparameter_Negate$"
+            order = 99
+        }
+        "-Critical" = {
+            description = "A critical threshold for the connection time in seconds. Allows the usage of unit additions, like 100ms.  Allowed units: ms, s, m, h, d, w, M, y"
+            value = "$IcingaCheckTCP_Object_Critical$"
+            order = 5
+        }
+        "-NoPerfData" = {
+            set_if = "$IcingaCheckTCP_Switchparameter_NoPerfData$"
+            order = 99
+        }
+        "-Ports" = {
+            description = "A single or a list of ports to check on the target address"
+            value = {{
+                var arr = macro("$IcingaCheckTCP_Array_Ports$");
+                if (len(arr) == 0) {
+                return "@()";
+                }
+                return arr.join(",");
+            }}
+            order = 3
+        }
+    }
+    vars.IcingaCheckTCP_Switchparameter_Negate = false
+    vars.IcingaCheckTCP_Switchparameter_NoPerfData = false
+}
+
 object CheckCommand "Invoke-IcingaCheckPerfcounter" {
     import "PowerShell Base"
 
@@ -757,7 +809,7 @@ object CheckCommand "Invoke-IcingaCheckDiskHealth" {
             order = 5
         }
         "-DiskReadSecCritical" = {
-            description = "Critical treshold for disk Reads/sec is the rate of read operations on the disk."
+            description = "Critical threshold for disk Reads/sec is the rate of read operations on the disk."
             value = "$IcingaCheckDiskHealth_Object_DiskReadSecCritical$"
             order = 7
         }
@@ -780,7 +832,7 @@ object CheckCommand "Invoke-IcingaCheckDiskHealth" {
             order = 99
         }
         "-DiskWriteSecWarning" = {
-            description = "Warning theeshold for disk Writes/sec is the rate of write operations on the disk."
+            description = "Warning threshold for disk Writes/sec is the rate of write operations on the disk."
             value = "$IcingaCheckDiskHealth_Object_DiskWriteSecWarning$"
             order = 8
         }

config/icinga/Plugins_Bundle.conf

@@ -31,6 +31,7 @@ To test thresholds with different input values, you can use the Framework Cmdlet
 * [Invoke-IcingaCheckScheduledTask](plugins/19-Invoke-IcingaCheckScheduledTask.md)
 * [Invoke-IcingaCheckService](plugins/13-Invoke-IcingaCheckService.md)
 * [Invoke-IcingaCheckStoragePool](plugins/21-Invoke-IcingaCheckStoragePool.md)
+* [Invoke-IcingaCheckTCP](plugins/23-Invoke-IcingaCheckTCP.md)
 * [Invoke-IcingaCheckTimeSync](plugins/18-Invoke-IcingaCheckTimeSync.md)
 * [Invoke-IcingaCheckUpdates](plugins/14-Invoke-IcingaCheckUpdates.md)
 * [Invoke-IcingaCheckUptime](plugins/15-Invoke-IcingaCheckUptime.md)

doc/10-Icinga-Plugins.md

@@ -7,13 +7,14 @@ documentation before upgrading to a new release.
 
 Released closed milestones can be found on [GitHub](https://github.com/Icinga/icinga-powershell-plugins/milestones?state=closed).
 
-## 1.4.0 (pending)
+## 1.4.0 (2021-03-02)
 
 [Issue and PRs](https://github.com/Icinga/icinga-powershell-plugins/milestone/5?closed=1)
 
 ### Enhancements
 
-* [#134](https://github.com/Icinga/icinga-powershell-plugins/pull/134) Adds autoloading for plugin information to standardize the development and projects and fixes plenty of spelling/code styling errosr
+* [#134](https://github.com/Icinga/icinga-powershell-plugins/pull/134) Adds autoloading for plugin information to standardize the development and projects and fixes plenty of spelling/code styling errors
+* [#135](https://github.com/Icinga/icinga-powershell-plugins/pull/135) Adds new check plugin `Invoke-IcingaCheckTCP`
 
 ### Bugfixes
 

doc/31-Changelog.md

@@ -0,0 +1,69 @@
+
+# Invoke-IcingaCheckTCP
+
+## Description
+
+Checks the connection for an address and a range of ports and fetches the connection status
+including the time require to connect.
+
+Invoke-IcingaCheckTCP connects to a provided address and a single or a range of ports and determines if the
+connection was successful or not. In addition the time for a successful connection is measured.
+
+By default the plugin will return [CRITICAL] if the connection is not possible, can how ever be changed by the
+`-Negate` argument which will return [CRITICAL] if the connection is possible.
+
+In addition you can measure the connection time and alert by using `-Warning` or `-Critical`.
+
+## Permissions
+
+No special permissions required.
+
+## Arguments
+
+| Argument | Type | Required | Default | Description |
+| ---      | ---  | ---      | ---     | ---         |
+| Address | String | false |  | The IP address or FQDN of the target host |
+| Ports | Array | false | @() | A single or a list of ports to check on the target address |
+| Negate | SwitchParameter | false | False | By default the plugin will return [CRITICAL] in case connections to a port are not possible. By setting this argument, the plugin will return [CRITICAL] for successful connections instead |
+| Warning | Object | false |  | A warning threshold for the connection time in seconds. Allows the usage of unit additions, like 100ms.  Allowed units: ms, s, m, h, d, w, M, y |
+| Critical | Object | false |  | A critical threshold for the connection time in seconds. Allows the usage of unit additions, like 100ms.  Allowed units: ms, s, m, h, d, w, M, y |
+| NoPerfData | SwitchParameter | false | False | Disables the performance data output of this plugin. Default to FALSE. |
+| Verbosity | Object | 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 |
+
+## Examples
+
+### Example Command 1
+
+```powershell
+Invoke-IcingaCheckTCP -Address 'example.com' -Ports 443, 80, 5665, 3001;
+```
+
+### Example Output 1
+
+```powershell
+[CRITICAL] Check package "TCP Connections" - [CRITICAL] example.com:3001 Status \_ [CRITICAL] Check package "example.com:3001" \_ [CRITICAL] example.com:3001 Status: Value "Not Connected" is not matching threshold "Connected" | 'port_80_time'=0.029526s;; 'port_80_status'=1;;1 'port_5665_status'=1;;1 'port_5665_time'=0.012666s;; 'port_3001_status'=0;;1 'port_3001_time'=21.041116s;; 'port_443_time'=0.353218s;; 'port_443_status'=1;;1
+```
+
+### Example Command 2
+
+```powershell
+Invoke-IcingaCheckTCP -Address 'example.com' -Ports 443, 80, 5665, 3001 -Negate;
+```
+
+### Example Output 2
+
+```powershell
+[CRITICAL] Check package "TCP Connections" - [CRITICAL] example.com:443 Status, example.com:5665 Status, example.com:80 Status\_ [CRITICAL] Check package "example.com:443"\_ [CRITICAL] example.com:443 Status: Value "Connected" is not matching threshold "Not Connected"\_ [CRITICAL] Check package "example.com:5665"\_ [CRITICAL] example.com:5665 Status: Value "Connected" is not matching threshold "Not Connected"\_ [CRITICAL] Check package "example.com:80"\_ [CRITICAL] example.com:80 Status: Value "Connected" is not matching threshold "Not Connected"| 'port_80_time'=0.017343s;; 'port_80_status'=1;;0 'port_5665_status'=1;;0 'port_5665_time'=0.013514s;; 'port_3001_status'=0;;0 'port_3001_time'=21.039489s;; 'port_443_time'=0.332817s;; 'port_443_status'=1;;0
+```
+
+### Example Command 3
+
+```powershell
+Invoke-IcingaCheckTCP -Address 'example.com' -Ports 443, 80, 5665, 3001 -Warning 100ms -Critical 200ms;
+```
+
+### Example Output 3
+
+```powershell
+[CRITICAL] Check package "TCP Connections" - [CRITICAL] example.com:3001 Status, example.com:3001 Time, example.com:443 Time\_ [CRITICAL] Check package "example.com:3001"\_ [CRITICAL] example.com:3001 Status: Value "Not Connected" is not matching threshold "Connected"\_ [CRITICAL] example.com:3001 Time: Value "21.038106s" is greater than threshold "0.2s"\_ [CRITICAL] Check package "example.com:443"\_ [CRITICAL] example.com:443 Time: Value "0.249976s" is greater than threshold "0.2s"| 'port_80_time'=0.017512s;0.1;0.2 'port_80_status'=1;;1 'port_5665_status'=1;;1 'port_5665_time'=0.013497s;0.1;0.2 'port_3001_status'=0;;1 'port_3001_time'=21.038106s;0.1;0.2 'port_443_time'=0.249976s;0.1;0.2 'port_443_status'=1;;1
+```