Configuration Files

The usual way of passing arguments and options (parameters) to the checks is through commandline parameters like --service="Site Check", -w 60 or --show-problems.

The latest versions of our tools (e.g. Check NetApp-REST v1.1.0) offer an alternative way through a configuration file in toml-format:

service = "Site Check",
warning = 60,
show-problems = true

TOML is a file format for configuration files. Its syntax is mostly identical to INI-files, which we use for the auth-file but allows us to write lists as well, which we need here.

The configuration via config-files is a very powerful feature aimed at experienced administrators who have to manage really large configurations. For small and medium installations please stick to the standard way of using commandline parameters since they are easier to understand and safer to use. Please read the following documentation before you start to use the --config parameter.

Basics

Format: As already mentioned, we support configuration-files in TOML-format.

Filename and path: The file’s name and location can be freely chosen and has no default. The extension must be .toml.

Example

./check_netapp_health -H filer --config=/opt/plugins/.../health.toml

All other parameters are now in health.toml. eg;

include = "~^subsystem"
alarm-limit = "WARNING"

The above combination, traditionally typed on the commandline only, would be:

$ ./check_netapp_health -H filer --include="~^subsystem" --alarm-limit=WARNING

Use Cases

There are several use-cases for this feature.

Use Case: Long Lists

Especially Checks with --include / --exclude lists can get really long and error-prone, eg;

./check_netapp_shelfenv cool -H filer --exclude="shelf10 cool2" --exclude="shelf30 cool4" --exclude="shelf33 cool4" ...

can be written better as:

./check_netapp_shelfenv cool -H filer --config=/usr/local/.../coolerlist.toml

with coolerlist.toml being:

exclude = [
    'shelf10 cool2',
    'shelf30 cool4',
    'shelf33 cool4',
]
...

Use Case: Global excludes

In almost every setup there is an exclude of some sort. Mostly specific volumes, snapshots or ports which are not used. Now configuration files offer an easier way to make these excludes, so that you do not have to change the checks every time a change in this exclude list occurs, eg;

/usr/local/.../etc/excludes/aggregates.toml:

exclude = [
    "~^aggr0",
]

/usr/local/.../etc/excludes/volumes.toml:

exclude = [
    "VeeamAUX$",
    "~\.tmp$",
]

/usr/local/.../etc/excludes/ports.toml:

exclude = [
    "e0a",
    "0f",
]

These exclude-files can than be used in several, different checks like this:

./check_netapp_netport -H myfiler --config=/usr/local/.../etc/excludes/ports.toml

Use Case: Default Override

Many parameters, like --storedir or --license-dir have a default. If your monitoring system has a different directory structure, you have to explicitly set these parameters for each check. This will make command lines really long and confusing, eg;

./check_netapp_node uptime --license-dir=/opt/plugins/custom/symon/netapp-rest/etc -H 192.168.0.211 --authfile=/opt/plugins/custom/symon/netapp-rest/etc/netapp_credentials --storedir=/opt/netapp_data/

Given a file /opt/plugins/.../etc/defaults.toml with this content …

license-dir = "/opt/plugins/custom/symon/netapp-rest/etc"
authfile = "/opt/plugins/custom/symon/netapp-rest/etc/netapp_credentials"
storedir = "/opt/netapp_data/"

… the above commandline could be written as:

./check_netapp_node uptime --config=/opt/plugins/.../etc/defaults.toml -H 192.168.0.211

Mixing more than one Configuration File

Having multiple configuration-files per command is possible. The number is not limited. Conflicts between the files and the commandline-parameters are solved in the following order:

  1. The files (e.g. --config=defaults.toml --config=excludes.toml, ...) are read from left to right as they appear on the commandline.

  2. Each file is read top down.

  3. The commandline-parameters are read last.

Given that order, the parameters last occurrence overrides any earlier occurrence.

In other words:

  • A parameter later (lower) in a file will override a parameter which was seen earlier (higher) in the same file.

  • A parameter in one file overrides the same parameter in another file, if the other file has been referenced earlier (left-side) on the commandline.

  • A parameter on the commandline overrides anything else.

List-elements from list-parameters are not added to existing lists! See the chapter Special Cases and Gotchas below.

Special Cases and Gotchas

Subcommands

Checks with subcommands, like check_netapp_ems support configuration-files per subcommand. In other words: You can not write the subcommand itself into the configuration file.

./check_netapp_ems event-rate -H myfiler --config=/opt/plugins/custom/netapp-rest/ems-eventrate.toml

All other parameters are now in ems-eventrate.toml, eg;

name = "wafl.vol.autoSize.done"
rate = "per_day"

The above combination, traditionally typed on the commandline only, would be:

$ ./check_netapp_ems event-rate -H filer --name=wafl.vol.autoSize.done --rate=per_day

List Elements

Whereas on the commandline lists like multiple excludes are written as simple repetitions of the parameters name, inside of configuration-files lists are written as a single list-element.

List-Element Example

This part of a command line …

--exclude=vol0 --exclude=~^tmp --exclude=faa345

… written inside of a configuration File …

exclude = [
    "vol0",
    "~^tmp",
    "faa345",
]

Single-Element Lists

A list with only one element can be written either as …

exclude = [
    "~vol0$",
]

or …

exclude = "~vol0$"

The latter is shorter whereas the first is easier to extend and less prone of errors.

List-Element Gotcha

This configuration-file …

exclude = "~vol0$"
exclude = "~^tmp"
exclude = "faa345"

… would exclude the faa345 volume only! The last occurrence of the exclude-parameter overrides any earlier occurrence.

Quoting Regular Expressions

Most regular expressions can be either double- or single-quoted. The line exclude = "~vol0$" will work as well as exclude = '~vol0$'. In case of a backslash like in exclude=~\.BAK single quotes are required, since the backslash has its own meaning in TOML.

exclude = '~vol0$' # ok
exclude = "~vol0$" # also ok
exclude = "~\.BAK" # will NOT work!
exclude = '~\.BAK' # ok