Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history 
apply markdownlint suggestions
  • Loading branch information
@sni
sni committed Apr 1, 2024
1 parent 4bca56c commit e7c0ca4
Show file tree
Hide file tree
Showing 14 changed files with 357 additions and 265 deletions.
4 changes: 2 additions & 2 deletions docs/api/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: API
linkTitle: API
title: REST API
linkTitle: REST API
---

SNClient+ comes with a REST API which can be used to run checks or do administrative tasks.
Expand Down
35 changes: 16 additions & 19 deletions docs/checks/external_commands/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ weight: 2000

**Overview:**

The SNClient+ Agent provides a flexible and extensible solution for executing custom scripts and external programs to monitor (plugins) and manage (event handlers) your Windows systems. This guide will walk you through configuring and utilizing this feature, which is equivalent to NSClient++'s `CheckExternalScripts` module.
The SNClient+ agent provides a flexible and extensible solution for executing custom scripts and external programs to monitor (plugins) and manage (event handlers) your Windows systems. This guide will walk you through configuring and utilizing this feature, which is equivalent to NSClient++'s `CheckExternalScripts` module.

### Enabling External Script Integration

To enable the External Script Integration feature in SNClient+, you need to activate it in the config file as follows:
To enable the external script integration feature in SNClient+, you need to activate it in the config file as follows:

```plaintext
```ini
[/modules]
CheckExternalScripts = enabled
```
Expand All @@ -24,15 +24,15 @@ You can add your custom scripts to SNClient+ using either a concise or verbose f

**Concise Format**:

```plaintext
```ini
[/settings/external scripts]
my_check1 = check_custom.bat
my_check2 = myscripts\check_custom.bat
```

**Verbose Format**:

```plaintext
```ini
[/settings/external scripts/scripts/my_check1]
my_check1 = check_custom.bat

Expand All @@ -46,7 +46,7 @@ Both formats achieve the same outcome by adding two new commands, `my_check1` an

You can manage script arguments in two ways: embedding them directly into the command or allowing for argument pass-through. To enable argument pass-through, update the configuration as follows:

```plaintext
```ini
[/settings/external scripts]
allow arguments = true
```
Expand All @@ -55,41 +55,41 @@ allow arguments = true

Below, you'll find a reference section for configuring the External Script Integration feature of SNClient+

**External Script Integration Settings**
#### External Script Integration Settings

- **allow arguments**: Allow or disallow script arguments when executing external scripts. Default is `false`.
- **allow nasty characters**: Permit or restrict certain potentially dangerous characters (```|`&><'"\[]{}```) in arguments. Default is `false`.
- **timeout**: Set the maximum execution time for commands (in seconds). This applies to external commands only, not internal ones.

```plaintext
```ini
[/settings/external scripts]
allow arguments = false
allow nasty characters = false
timeout = 60
```

**Command Aliases**
#### Command Aliases

You can create aliases for existing commands with arguments to simplify usage. Ensure that you don't create loops in alias definitions.

```plaintext
```ini
[/settings/external scripts/aliases/sample-alias]
alias = sample-alias
command = original-command
```

**External Scripts**
#### External Scripts

Define scripts available for execution via the External Script Integration feature. Use the format `command = script arguments`.

```plaintext
```ini
[/settings/external scripts/scripts/sample-script]
command = custom_script.bat
```

Scipts with an extension of .bat, .ps1 and .exe (Windows) or .sh and no extension at all (Unix) can be defined as follows.

```
```ini
check_dummy = check_dummy.bat
check_dummy_ok = check_dummy.ps1 0 "i am ok"
check_dummy_critical = check_dummy.exe 2 "i am critical"
Expand All @@ -104,12 +104,11 @@ restart_service = NET START "$ARG1$"
If your scripts are located within the `${scripts}` folder, you can specify them using relative paths, as demonstrated in the examples. SNClient+ will automatically obtain the absolute path for these scripts and use it for execution. Prior to running the scripts, SNClient+ configures the working directory to be ${shared-dir}.

**Wrapped Scripts**
#### Wrapped Scripts
Specify script templates used to define script commands. These templates are expanded by scripts located in the Wrapped Scripts section. Use `%SCRIPT%` to represent the actual script and `%ARGS%` for any provided arguments.
```plaintext
```ini
[/settings/external scripts/wrappings]
vbs = cscript.exe /nologo %SCRIPT% %ARGS%
bat = cmd /c %SCRIPT% %ARGS%
Expand All @@ -122,6 +121,4 @@ check_dummy_wrapped_ok = check_dummy.bat 0 "i am ok wrapped"
check_dummy_wrapped_critical = check_dummy.vbs 2 "i am critical wrapped"
```
Other than with NSClient++ you don't need to use wrapping for Powershell scripts.
---

**Note:** Unlike NSClient++, you don't need to use wrapping for Powershell scripts.
44 changes: 22 additions & 22 deletions docs/checks/filter/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,32 +20,32 @@ ex.:

To combine multiple filter you can use logical operator and brackets.

| Operator | Alias | Description |
| -------- | ------| ----------- |
`and` | `&&` | Logical **and** operator
`or` | `\|\|` | Logical **or** operator
| Operator | Alias | Description |
| -------- | -------| ----------- |
| `and` | `&&` | Logical **and** operator |
| `or` | `\|\|` | Logical **or** operator |

ex.:

(status = 'started' or status = 'pending') and usage > 5%

## Operator

| Operator | Alias | Types | Description |
| -------- | ---------------------- | --------| ----------- |
`=` | `==`, `is`, `eq` | Strings, Numbers | Matches on **exact equality**, ex.: `status = 'started'`
`!=` | `is not`, `ne` | Strings, Numbers | Matches if value is **not exactly equal**. ex.: `5 != 3`
`like` | | Strings | Matches if value contains the condition (**substring match**), ex.: `status like "pend"`
`unlike` | `not like` | Strings | Matches if value does **not contain** the **substring**, ex.: `status unlike "stopped"`
`ilike` | | Strings | Matches a **case insensitive substring**, ex.: `name ilike "WMI"`
`not ilike` | | Strings | Matches if a **case insensitive substring** cannot be found, ex.: `name not ilike "WMI"`
`~` | `regex`, `regexp` | Strings | Performs a **regular expression** match, ex.: `status ~ '^pend'`
`!~` | `not regex`, `not regexp` | Strings | Performs a **inverse regular expression** match, ex.: `status !~ 'stop'`
`~~` | `regexi`, `regexpi` | Strings | Performs a **case insensitive regular expression** match, ex.: `status ~~ '^pend'`. An alternative way is to use `//i` as in `status ~ /^pend/i`
`!~~` | `not regexi`, `not regexpi` | Strings | Performs a **inverse case insensitive regular expression** match, ex.: `status !~~ 'stop'`
`<` | `lt` | Numbers | Matches **lower than** numbers, ex.: `usage < 5%`
`<=` | `le` | Numbers | Matches **lower or equal** numbers, ex.: `usage <= 5%`
`>` | `gt` | Numbers | Matches **greater than** numbers, ex.: `usage > 5%`
`>=` | `ge` | Numbers | Matches **greater or equal** numbers, ex.: `usage >= 5%`
`in` | | Strings | Matches if element **is in list** ex.: `status in ('start', 'pending')`
`not in` | | Strings | Matches if element **is not in list** ex.: `status not in ('stopped', 'starting')`
| Operator | Alias | Types | Description |
| ----------- | --------------------------- | --------| ----------- |
| `=` | `==`, `is`, `eq` | Strings, Numbers | Matches on **exact equality**, ex.: `status = 'started'` |
| `!=` | `is not`, `ne` | Strings, Numbers | Matches if value is **not exactly equal**. ex.: `5 != 3` |
| `like` | | Strings | Matches if value contains the condition (**substring match**), ex.: `status like "pend"` |
| `unlike` | `not like` | Strings | Matches if value does **not contain** the **substring**, ex.: `status unlike "stopped"` |
| `ilike` | | Strings | Matches a **case insensitive substring**, ex.: `name ilike "WMI"` |
| `not ilike` | | Strings | Matches if a **case insensitive substring** cannot be found, ex.: `name not ilike "WMI"` |
| `~` | `regex`, `regexp` | Strings | Performs a **regular expression** match, ex.: `status ~ '^pend'` |
| `!~` | `not regex`, `not regexp` | Strings | Performs a **inverse regular expression** match, ex.: `status !~ 'stop'` |
| `~~` | `regexi`, `regexpi` | Strings | Performs a **case insensitive regular expression** match, ex.: `status ~~ '^pend'`. An alternative way is to use `//i` as in `status ~ /^pend/i` |
| `!~~` | `not regexi`, `not regexpi` | Strings | Performs a **inverse case insensitive regular expression** match, ex.: `status !~~ 'stop'` |
| `<` | `lt` | Numbers | Matches **lower than** numbers, ex.: `usage < 5%` |
| `<=` | `le` | Numbers | Matches **lower or equal** numbers, ex.: `usage <= 5%` |
| `>` | `gt` | Numbers | Matches **greater than** numbers, ex.: `usage > 5%` |
| `>=` | `ge` | Numbers | Matches **greater or equal** numbers, ex.: `usage >= 5%` |
| `in` | | Strings | Matches if element **is in list** ex.: `status in ('start', 'pending')` |
| `not in` | | Strings | Matches if element **is not in list** ex.: `status not in ('stopped', 'starting')` |
122 changes: 68 additions & 54 deletions docs/checks/perfconfig/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,21 @@
---
title: Perfomance Data Configuration
title: Performance Data Configuration
---

Sometimes you might want to tweak performance data and therefore all checks
support the `perf-conf` argument to apply tweaks to them.

## Syntax

check_plugin perf-config="selector(key:value;...)"
```bash
check_plugin perf-config="selector(key:value;...)"
```

For example:

check_drivesize "perf-config=used(unit:G) used %(ignored:true)"
```bash
check_drivesize "perf-config=used(unit:G) used %(ignored:true)"
```

This will convert used disk space bytes into gigabytes. It als removes the percent
performance data from the output completely.
Expand All @@ -20,23 +24,27 @@ performance data from the output completely.

The following keys are available:

| Key | Value | Description |
| -------- | ------| ----------- |
`ignored` | `true` or `false` | Remove the performance value from the list if true.
`prefix` | `string` | Change the prefix to something else.
`suffix` | `string` | Change the suffix to something else.
`unit` | `string` | Change the unit to something else.
`magic` | `number` | Apply magic factor to performance data.
| Key | Value | Description |
| --------- | ------------------| ----------- |
| `ignored` | `true` or `false` | Remove the performance value from the list if true. |
| `prefix` | `string` | Change the prefix to something else. |
| `suffix` | `string` | Change the suffix to something else. |
| `unit` | `string` | Change the unit to something else. |
| `magic` | `number` | Apply magic factor to performance data. |

## Selector

The perf-conf selector supports wildcards, so something like this will work:

check_plugin perf-config="*(unit:G)"
```bash
check_plugin perf-config="*(unit:G)"
```

The snclient will use the options in order and apply the first matching configuration, so for ex.:

check_plugin perf-config="used(ignored:true) *(unit:G)"
```bash
check_plugin perf-config="used(ignored:true) *(unit:G)"
```

will hide `used` performance data and apply unit G to everything else.

Expand All @@ -50,63 +58,69 @@ The base unit `B` for bytes can be converted into more human readable units.

A common pattern is `*(unit:G)` to simply convert all performance data into gigabytes.

check_plugin perf-config="*(unit:G)"
```bash
check_plugin perf-config="*(unit:G)"
```

You can choose from these units:

| Unit | Description |
| ---- | ----------- |
K | KByte
KB | KByte
KiB | KiByte
Kb | KiByte
KI | KiByte
M | MByte
MB | MByte
MiB | MiByte
Mb | MiByte
MI | MiByte
G | GByte
GB | GByte
GiB | GiByte
Gb | GiByte
GI | GiByte
T | TByte
TB | TByte
TiB | TiByte
Tb | TiByte
TI | TiByte
P | PByte
PB | PByte
PiB | PiByte
Pb | PiByte
PI | PiByte
E | EByte
EB | EByte
EiB | EiByte
Eb | EiByte
EI | EiByte
| K | KByte |
| KB | KByte |
| KiB | KiByte |
| Kb | KiByte |
| KI | KiByte |
| M | MByte |
| MB | MByte |
| MiB | MiByte |
| Mb | MiByte |
| MI | MiByte |
| G | GByte |
| GB | GByte |
| GiB | GiByte |
| Gb | GiByte |
| GI | GiByte |
| T | TByte |
| TB | TByte |
| TiB | TiByte |
| Tb | TiByte |
| TI | TiByte |
| P | PByte |
| PB | PByte |
| PiB | PiByte |
| Pb | PiByte |
| PI | PiByte |
| E | EByte |
| EB | EByte |
| EiB | EiByte |
| Eb | EiByte |
| EI | EiByte |

### Seconds / Duration

Durations with the base unit `s` for seconds can be converted into the following units:

| Unit | Description |
| ---- | ----------- |
ms | milliseconds
s | seconds
m | minutes
h | hours
d | days
w | weeks
y | years
| Unit | Description |
| ---- | ------------ |
| ms | milliseconds |
| s | seconds |
| m | minutes |
| h | hours |
| d | days |
| w | weeks |
| y | years |

For example convert the uptime to days:

check_uptime "perf-config=*(unit:d)"
```bash
check_uptime "perf-config=*(unit:d)"
```

### Percent

All performance data which have at least a value and a min and max value can be converted to percent.

check_plugin perf-config="*(unit:%)"
```bash
check_plugin perf-config="*(unit:%)"
```
22 changes: 15 additions & 7 deletions docs/checks/syntax/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,17 @@ Supported macro variants:

Example:

check_memory 'detail-syntax=%(type) = %(used)/%(size) (%(used_pct)%)'
```bash
check_memory 'detail-syntax=%(type) = %(used)/%(size) (%(used_pct)%)'
```

All macros can also make use of [macro operators](../../configuration/#macro-operators).

For example, the default output applies floating point format to make the output more readable:

check_memory 'detail-syntax=%(type) = %(used)/%(size) (%(used_pct | fmt=%.1f)%)'
```bash
check_memory 'detail-syntax=%(type) = %(used)/%(size) (%(used_pct | fmt=%.1f)%)'
```

The list of available macros for each check is available in the help page of each check.
Another way is to run the check with `-vv` verbose mode, which prints the list details
Expand All @@ -48,14 +52,18 @@ as well.

Conditionals can be used to support different output based on expressions.

The basic syntax is `{{ IF <expression> }}...{{ ELSIF <expression> }}...{{ ELSE }}...{{ END }}`.
The basic syntax is:

{{ IF <expression> }}...{{ ELSIF <expression> }}...{{ ELSE }}...{{ END }}

Example:

check_service \
service=sshd \
detail-syntax='%(name) - {{ IF state == running }}memory: %(rss:h)B cpu: %(cpu:fmt=%.1f)% - age: %(created:age:duration){{ else }}service is $(state){{ end }}' \
show-all
```bash
check_service \
service=sshd \
detail-syntax='%(name) - {{ IF state == running }}memory: %(rss:h)B cpu: %(cpu:fmt=%.1f)% - age: %(created:age:duration){{ else }}service is $(state){{ end }}' \
show-all
```

That way, in case of errors a useful message can be displayed and performance details otherwise.

Expand Down
Loading

0 comments on commit e7c0ca4

Please sign in to comment.