Data source programs

The writing and installation of a data source program is not difficult. Any Linux-supported script and program language can be used. The program is best stored in the ~/local/bin/ directory, where it will always be found automatically without the need to specify a data path.

The following first, very basic example is called myds and it generates simple, fictional monitoring data. Instead of integrating a new transport path, it generates the monitoring data itself. These consist of one section <<<df>>>, which contains the information for a single file system, and which has a size of 100 kB and the name My_Disk. It is coded as a shell script of three lines:

Don’t forget to make the program executable:

Now create a test host in the Setup – e.g., myserver125. This does not require an IP address. In order to avoid Checkmk attempting to resolve myserver125 via DNS, set IP address family to No IP.

Next add a rule in the Setup > Agents > Other integrations > Individual program call instead of agent access rule set which applies to this host, and enter myds as an executable program:

When you now go to the host’s service configuration in the Setup GUI, exactly one service ready to start monitoring should be listed:

Add this service into the monitoring, activate the changes, and your first data source program will be running. For a test, as soon as you alter the data being generated by the program the My_Disk file system’s next check will immediately show this.

If something is not functioning correctly, the host’s configuration can be checked by entering cmk -D in the command line and see if your rule has taken effect:

With a cmk -d you can trigger the retrieval of the agent data as well as the execution of your program:

A duplicated -v should generate a message that your program will be invoked:

The program in our example actually works, but is not very useful as it always produces the same data, regardless of which host it is invoked for.

A real program that, for example, retrieves data via HTTP from somewhere, requires at least the name of the host from where it should retrieve the data. By coding $HOSTNAME$ as a placeholder in the command line you can allow this to be transferred:

In this example the program myds receives the host name as its first argument. The following program example produces this for testing in the form of a local check. Via $1 it takes the first argument and saves it for use as an overview in the $HOST_NAME variable. This will then be inserted into the local check’s plug-in output:

The service discovery will then find a new service of the local type, in the output from which the host name will be seen:

From here it is only a small step to a real data source program that, for example, retrieves data over HTTP using the curl command. The following placeholders are permitted in a data source program’s command line:

If you have a dual-monitoring using IPv4 and IPv6, the following macros may be interesting for you:

Regardless of your actual occupation in IT—​much of your time will be spent dealing with errors and problems. Data source programs are not spared these. Especially for programs that provide data over networks it is unrealistic to expect them to be error-free.

In order that Checkmk can communicate an error to your program in an orderly way, the following apply:

If a data source program fails,

We can modify the above example so that it simulates an error. With the redirection >&2 the text will be diverted to stderr, and exit 1 sets the program’s exit code to 1:

As a Check_MK service it will look like this:

Should you be writing your program as a shell script, right at the beginning you can code the set -e option:

As soon as an instruction produces an error (i.e., exit code not 0), the shell immediately stops and issues the exit code 1. You have thus a generic error handling and must not check every single instruction for success.