| SysOrb Network Monitoring System Administrator's Guide: For version 4.6.0 | ||
|---|---|---|
| Prev | Chapter 8. SysOrb Agent Configuration | Next |
If the built-in checks of the SysOrb Agent does not suffice for you particular setup, you may write extension scripts that can perform the check.
You can write these scripts in any language you desire. The only requirement is that the script must deliver the result of the check to the SysOrb Agent in one of two ways.
If the check is either good or bad, the script must tell the SysOrb agent by the exit code. A non-zero exit code indicates a bad result, while an exit code of zero indicates a good result. How exit with specific exit codes depends on the script language used.
If the check can return a numeric value within some range, it must output that value decimally to standard output on a line like: "Result: 1234". Note that the colon must be present, and that the Agent is case sensitive. The SysOrb Agent will parse the output from the script, putting any line not conforming to the above format into the agent log file.
The custom checks that an Agent is able to execute is configured using a file on the machine running the SysOrb Agent. It may have been more convenient to be able to do it from the web interface, but that would open serious security risks, as any SysOrb user, with capabilities to configure checks, would be able to have the agent execute arbitrary shell commands.
In order to use custom checks you must first tell the SysOrb Agent where to find the custom check configuration file. On non-windows systems this is done by adding a line like
custom_chk_conf=/etc/sysorb/custom.conf
to the agent configuration file (usually located in /etc/sysorb/agent.conf). On Windows you must open the SysOrb Configuration utility located in Start menu->Programs->SysOrb->SysOrb Configuration. In the configuration tree choose SysOrb Agent->Configuration files->Custom checks and enter the path where you are going to put the new configuration file.
After changing this path, the Agent must be restarted, but wait until you have put something into the new file.
You must edit the new file custom.conf in order to configure which custom checks the agent can perform. The format of the file is most easily illustrated with a few examples of custom checks:
New to 4.4: it is now possible to get extended result description from boolean check: just add result_pattern string to the check config with appropriate pattern. Then this description will be displayed in the check result.
Example 8-1. Good/bad check
# Comment lines begin with #
[check name]
command=/path/to/the/execfile parameters
timeout=10
The value between [ and ] gives the name of the check. command is the command sent to the shell, so normal shell expansion works. The timeout parameter is optional, and the default value is 10 seconds. Please note that the SysOrb Agent stops processing other tasks (ordinary checks and communication with the server) while a custom check is carried out, so timeout shouldn't be more than half of the checkin frequency for that agent.
Example 8-2. Numeric integer check
[check name]
type=integer
unit=kB
command=/path/to/the/execfile parameters
timeout=10
The line type=integer tells the SysOrb Agent, that this is a numeric integer check, that will output a line on the form Result: 1234, the unit property tells the agent, that the numeric output should be interpreted as a number of kilobytes. This information is passed along to the SysOrb Server, to allow putting units on the Y-axis in graphs and elsewhere.
Example 8-3. Numeric real check
[check name]
type=real
unit=s
command=/path/to/the/execfile parameters
timeout=10
The line type=real tells the SysOrb Agent, that this is a numeric check, that will output a line on the form Result: 12.03, the unit property tells the agent, that the numeric output should be interpreted as a number of kilobytes. This information is passed along to the SysOrb Server, to allow putting units on the Y-axis in graphs and elsewhere.
Example 8-4. Differential numeric integer check
[check name]
type=diff_integer
unit=kB/s
command=/path/to/the/execfile parameters
timeout=10
The line type=diff_integer tells the SysOrb Agent, that this script outputs an integer like a numeric integer check. For each pair of successive invocations, the SysOrb agent will subtract the two results, and divide the difference with the elapsed time. This is useful if your script for instance outputs the number of bytes which have passed through an interface since some fixed point in time, but you want the check to show the number of bytes per second passing through right now.
Example 8-5. Differential numeric real check
[check name]
type=diff_integer
unit=kB/s
command=/path/to/the/execfile parameters
timeout=10
The line type=diff_real tells the SysOrb Agent, that this script outputs an real like a numeric real check. For each pair of successive invocations, the SysOrb agent will subtract the two results, and divide the difference with the elapsed time. This is useful if your script for instance outputs the number of bytes which have passed through an interface since some fixed point in time, but you want the check to show the number of bytes per second passing through right now.
Whenever you edit this file, you must push open a web interface and push on the tab on the Configure page for the host in question. You do not need to restart the SysOrb Agent, unless you have changed the location of this file.
Sometimes you do not write the script yourself, and there is no easy way of having it output its result on a line like Result: 1234. In that case you can instruct the SysOrb Agent to look for the result in lines containing other text. You do that by means of a POSIX regular expression. The syntax of regular expression can be found at: http://www.opengroup.org/onlinepubs/007908799/xbd/re.html
Example 8-6. Script outputting Response time: 1234 ms
[resp_time]
type=integer
command=measure-command
result_pattern=^Response time: ([[:digit:]]+) ms$
timeout=10
The result_pattern must contain exactly one set of parentheses enclosing the pattern matching the numerical result of the check.
Example 8-7. Count the number of files in /tmp
[temp_count]
type=integer
command=find /tmp -maxdepth 1 | wc -l
result_pattern=([[:digit:]]+)
timeout=10
This result_pattern will match any line containing numerical characters. The SysOrb Agent will then pick the first line containing numbers, and if there are more than one number on that line, the leftmost of them.