You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/100-General/10-Changelog.md
+1
Original file line number
Diff line number
Diff line change
@@ -24,6 +24,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
24
24
### Enhancements
25
25
26
26
*[#383](https://github.com/Icinga/icinga-powershell-framework/pull/383) Moves the components REST-Api [icinga-powershell-restapi](https://icinga.com/docs/icinga-for-windows/latest/restapi/doc/01-Introduction/) and API-Checks [icinga-powershell-apichecks](https://icinga.com/docs/icinga-for-windows/latest/apichecks/doc/01-Introduction/) directly into the Framework
27
+
*[#389](https://github.com/Icinga/icinga-powershell-framework/pull/389) Adds developer tools for easier start and management of development custom extensions for Icinga for Windows
27
28
*[#392](https://github.com/Icinga/icinga-powershell-framework/pull/392) Adds support to read logs from Windows EventLog while using `Read-IcingaAgentLogFile`
28
29
*[#393](https://github.com/Icinga/icinga-powershell-framework/pull/393) Adds generic reader function `Read-IcingaWindowsEventLog`, allowing to read any EventLog as stream on the console and adds in addition `Read-IcingaForWindowsLog` for reading Icinga for Windows specific logs
This guide will introduce you on how to write custom PowerShell modules (described as Icinga for Windows components) and how certain aspects of the architecture work.
4
+
5
+
## PowerShell Module Architecture
6
+
7
+
Each single PowerShell module has to be installed inside a module directory of Windows. You can view a list of current available locations by using `$Env:PSModulePath`. By default, we are going to use the directory `C:\Program Files\WindowsPowerShell\Modules`.
8
+
9
+
### Folder Structure
10
+
11
+
To create a new module, you can create a custom folder within the PowerShell module folder. This folder is the namespace of your module and is required for later creating the `RootModule` and `Manifest`.
12
+
13
+
Within your module folder, you are free to create as many sub-directories as you want and place script and module files there, which are shipped and used by your module.
14
+
15
+
### Manifest And RootModule
16
+
17
+
To provide all basic information, you will require to create at least a `Manifest` file, which has the file ending `.psd1`. The name of the file has to match the folder name you choose as namespace for your module in the previous section.
18
+
19
+
Our `RootModule` is using the file ending `.psm1` and can use the same name as your folder, but is not required to, as long as a valid `.psd1` file is present. Within our manifest, we can define the path on where the `.psm1` can be found.
20
+
21
+
### Nested Modules
22
+
23
+
While writing your own module, you will add additional code and possible different files to your project. By adding additional `.psm1` files for easier loading of functions, we can use the `NestedModules` attribute within our `.psd1` file, to add them to our known module list.
24
+
25
+
Please note that it is only required to use the relative path, starting with `.\` to use the root directory of your module as base.
26
+
27
+
Lets assume we have the following file structure:
28
+
29
+
```text
30
+
module
31
+
|_ plugin.psd1
32
+
|_ plugin.psm1
33
+
|_ provider
34
+
|_ custom_provider.psm1
35
+
|_ plugin
36
+
|_ custom_plugin.psm1
37
+
```
38
+
39
+
In this case, our `NestedModules` variable within our `.psd1` file requires the following values
40
+
41
+
```powershell
42
+
NestedModules = @(
43
+
'.\provider\custom_provider.psm1',
44
+
'.\provider\custom_plugin.psm1'
45
+
)
46
+
```
47
+
48
+
## Using Icinga for Windows Dev Tools
49
+
50
+
Maintaining the entire structure above seems to be complicated at the beginning, especially when considering to update the `NestedModules` section whenever you make changes. To mitigate this, Icinga for Windows provides a bunch of Cmdlets to help with the process
51
+
52
+
### Create New Components
53
+
54
+
To create new components, you can use the command `New-IcingaForWindowsComponent`. It will create a new PowerShell module inside the same module directory, were you installed the Framework itself.
55
+
56
+
The command ships with a bunch of configurations to modify the created `.psd1` in addition, with a different author, copyright, and so on. the most important arguments how ever are `Name` and `ComponentType`.
57
+
58
+
| Argument | Type | Description |
59
+
| --- | --- | --- |
60
+
| Name | String | The name of your Icinga for Windows component. This will create a new module in the following syntax: `icinga-powershell-{name}`|
61
+
| ComponentType | String | The type of component you want to create for Icinga for Windows with different base-modules and code available to get started quickly. Available types: `plugins`, `apiendpoint`, `daemon`, `library`|
62
+
| OpenInEditor | Switch | Will directly open the module after creation inside an editor for editing |
63
+
64
+
### Publish/Update Components
65
+
66
+
Once you have started to write your own code, you can use the Cmdlet `Publish-IcingaForWindowsComponent` to update the `NestedModules` attribute inside the `.psd1` file automatically, including the documentation in case the module is of type plugin.
67
+
68
+
In addition, you ca create a `.zip` file for this module which can be integrated directly into the [Repository Manager](..\120-Repository-Manager\01-Add-Repositories.md). By default, created `.zip` files will be created in your home folder, the path can how ever be changed while executing the command.
69
+
70
+
| Argument | Type | Description |
71
+
| --- | --- | --- |
72
+
| Name | String | The name of your Icinga for Windows component to update information from |
73
+
| ReleasePackagePath | String | The path on where the `.zip` file will be created in. Defaults to the current users home folder |
74
+
| CreateReleasePackage | Switch | This will toggle the `.zip` file creation of the specified package |
75
+
76
+
### Testing Your Component
77
+
78
+
In order to validate if your module can be loaded and is working properly, you can use the command `Test-IcingaForWindowsComponent`. In addition to an import check, it will also validate the code styling and give you an overview if and how many issues there are with your code.
79
+
80
+
By default, only a summary of possible issues is added to the output, you can how ever use an argument flag to print a list of possible found issues, allowing you to resolve them more easily.
81
+
82
+
| Argument | Type | Description |
83
+
| --- | --- | --- |
84
+
| Name | String | The name of your Icinga for Windows component to test |
85
+
| ShowIssues | Switch | Prints a list of all possible found issues into the console |
86
+
87
+
### Open Components
88
+
89
+
A quick and easy way for opening components inside an editor is to use the command `Open-IcingaForWindowsComponentInEditor`. You simply require to specify the name of the component and the editor is opening.
90
+
91
+
At the moment, only [Visual Studio Code](https://code.visualstudio.com/) is supported. More editors will follow in the future.
92
+
93
+
| Argument | Type | Description |
94
+
| --- | --- | --- |
95
+
| Name | String | The name of your Icinga for Windows component to open |
96
+
| Editor | String | Allows to specify, which editor the component should be opened with. Supported values: `code`|
Copy file name to clipboardExpand all lines: doc/900-Developer-Guide/01-New-IcingaCheck.md
+13-12
Original file line number
Diff line number
Diff line change
@@ -26,11 +26,12 @@ For performance metrics you can provide a `Unit` to ensure your graphing is disp
26
26
| --- | --- | --- | --- |
27
27
| Name | String | * | The unique name of each check within a plugin. Will be display in the check output. |
28
28
| Value | Object | * | The value all comparison is done with. In general this should be a `Numeric` or `String` value |
29
+
| BaseValue | Object | * | A value from which a dynamic percentage result is calculated from, by including the current value. Could for example be the maximum size of a partition |
29
30
| Unit | Units || Specify the unit for a value to display graph properly |
30
31
| Minimum | String || The minimum value which is displayed on your graphs |
31
32
| Maximum | String || The maximum value which is displayed on your graphs |
32
33
| BaseValue | Object || Sets a base value for the check which allows to use dynamic `%` usage on thresholds. The base value will calculate the `%` value from the current value, allowing generic `%` monitoring |
33
-
| ObjectExists | Bool || If you are using values coming from objects, like Services, you can use this argument to determin if the object itself exist or not. In case it doesn't, you will receive a proper output on the check result |
34
+
| ObjectExists | Bool || If you are using values coming from objects, like Services, you can use this argument to determine if the object itself exist or not. In case it doesn't, you will receive a proper output on the check result |
34
35
| Translation | Hashtable || In case you want to map values to certain descriptions, you can place a hashtable at this argument which will then map the value to the description on the check result. For example this would apply to service running states |
35
36
| LabelName | String || Allows to override the default label name generated based on the `-Name` argument to a custom name. Please ensure to remove any special characters manually, as the name set here is the exact name for the label |
36
37
| NoPerfData | Switch || Disables Performance Data output for this check object |
For most parts it is recommended to use the `OutOfRange` functions for `warning` and `critical` checks as the user is able to dynamicly set the range with the arguments of the plugins. For string values the `Like` and `Match` functions should be used.
82
+
For most parts it is recommended to use the `OutOfRange` functions for `warning` and `critical` checks as the user is able to dynamically set the range with the arguments of the plugins. For string values the `Like` and `Match` functions should be used.
82
83
83
84
#### Recommended functions
84
85
85
86
| Function | Parameters | Description | Example |
86
87
| --- | --- | --- | --- |
87
-
| WarnOutOfRange | Warning | This will make use of the Icinga Threshhold handling, like `10`, `~:10`, `@10:20` and properly return the correct ok / warning state of the plugin | $IcingaCheck.WarnOutOfRange(10) | Out-Null |
88
-
| CritOutOfRange |Critial| This will make use of the Icinga Threshhold handling, like `10`, `~:10`, `@10:20` and properly return the correct ok / critical state of the plugin | $IcingaCheck.CritOutOfRange(10) | Out-Null |
88
+
| WarnOutOfRange | Warning | This will make use of the Icinga Threshold handling, like `10`, `~:10`, `@10:20` and properly return the correct ok / warning state of the plugin | $IcingaCheck.WarnOutOfRange(10) | Out-Null |
89
+
| CritOutOfRange |Critical| This will make use of the Icinga Threshold handling, like `10`, `~:10`, `@10:20` and properly return the correct ok / critical state of the plugin | $IcingaCheck.CritOutOfRange(10) | Out-Null |
89
90
| WarnIfLike | Warning | Will return warning in case the input is `like` the value | $IcingaCheck.WarnIfLike('\*running\*') |
90
91
| WarnIfNotLike | Warning | Will return warning in case the input is `not like` the value | $IcingaCheck.WarnIfNotLike('\*running\*') |
91
92
| WarnIfMatch | Warning | Will return warning in case the input is `matching` the value | $IcingaCheck.WarnIfMatch('running') |
92
93
| WarnIfNotMatch | Warning | Will return warning in case the input is `not matching` the value | $IcingaCheck.WarnIfNotMatch('running') |
93
-
| CritIfLike |Critial| Will return critical in case the input is `like` the value | $IcingaCheck.CritIfLike('\*running\*') |
94
-
| CritIfNotLike |Critial| Will return critical in case the input is `not like` the value | $IcingaCheck.CritIfNotLike('\*running\*') |
95
-
| CritIfMatch |Critial| Will return critical in case the input is `matching` the value | $IcingaCheck.CritIfMatch('running') |
96
-
| CritIfNotMatch |Critial| Will return critical in case the input is `not matching` the value | $IcingaCheck.CritIfNotMatch('running') |
94
+
| CritIfLike |Critical| Will return critical in case the input is `like` the value | $IcingaCheck.CritIfLike('\*running\*') |
95
+
| CritIfNotLike |Critical| Will return critical in case the input is `not like` the value | $IcingaCheck.CritIfNotLike('\*running\*') |
96
+
| CritIfMatch |Critical| Will return critical in case the input is `matching` the value | $IcingaCheck.CritIfMatch('running') |
97
+
| CritIfNotMatch |Critical| Will return critical in case the input is `not matching` the value | $IcingaCheck.CritIfNotMatch('running') |
97
98
98
99
#### All other functions
99
100
@@ -107,10 +108,10 @@ For most parts it is recommended to use the `OutOfRange` functions for `warning`
107
108
| WarnIfGreaterEqualThan | Warning | Will return warning in case the input is `greater or equal` than the value | $IcingaCheck.WarnIfGreaterEqualThan(10) |
108
109
| CritIfBetweenAndEqual | Min, Max | Will return critical in case the input is `between or equal` the `min` and `max` value | $IcingaCheck.CritIfBetweenAndEqual(10, 20) |
109
110
| CritIfBetween | Min, Max | Will return critical in case the input is between the `min` and `max` value | $IcingaCheck.CritIfBetween(10, 20) |
110
-
| CritIfLowerThan |Critial| Will return critical in case the input is `lower` than the value | $IcingaCheck.CritIfLowerThan(10) |
111
-
| CritIfLowerEqualThan |Critial| Will return critical in case the input is `lower or equal` than the value | $IcingaCheck.CritIfLowerEqualThan(10) |
112
-
| CritIfGreaterThan |Critial| Will return critical in case the input is `greater` than the value | $IcingaCheck.CritIfGreaterThan(10) |
113
-
| CritIfGreaterEqualThan |Critial| Will return critical in case the input is `greater or equal` than the value | $IcingaCheck.CritIfGreaterEqualThan(10) |
111
+
| CritIfLowerThan |Critical| Will return critical in case the input is `lower` than the value | $IcingaCheck.CritIfLowerThan(10) |
112
+
| CritIfLowerEqualThan |Critical| Will return critical in case the input is `lower or equal` than the value | $IcingaCheck.CritIfLowerEqualThan(10) |
113
+
| CritIfGreaterThan |Critical| Will return critical in case the input is `greater` than the value | $IcingaCheck.CritIfGreaterThan(10) |
114
+
| CritIfGreaterEqualThan |Critical| Will return critical in case the input is `greater or equal` than the value | $IcingaCheck.CritIfGreaterEqualThan(10) |
0 commit comments