API file structure
From ServersCheck Wiki
The API structure file is a standard text file in which you can define as many monitors as you want.
Below is a sample API configuration file for IMAGESTREAM:
name=IMAGESTREAM #name of check as to appear in list
description=Enables you to monitor the Imagestream router
apikey=53616c7465645f5f2e21e6538bcf8e30164fdb591b235772eff719aa1569d50d51ac4fc7a970a304 #This key is issued by ServersCheck supportdetails=Please visit http://support.imagestream.com for support on these devices snmpversion=2c #SNMP v1 or v2 currently supported; for v1 enter 1; v2 enter 2c and 0 means no snmp category=HW # HW: hardware; SW: software specific refresh=180
retry=3
requiredparams=%IP|%Community|%Port
requiredparamsdesc=IP address of Imagestream router|SNMP v1 or v2 Community Name|SNMP port
check1name=Router Alive
check1desc=Verifies if the router is alive
check1type=PING
check1settings=%IP
check1treshold=1
check1compare=gt #gt: returned value is greater than treshold; lt: returned value is less than treshold; eq: returned value equals treshold value
check2name=Router CPU load
check2desc=Monitors the CPU load on the router
check2type=SNMP
check2settings=%IP|%Community|%Port|.1.3.6.1.4.1.2021.10.1.3.1
check2treshold=95
check2compare=gt #gt: returned value is greater than treshold; lt: returned value is less than treshold; eq: returned value equals treshold value
check3name=Bandwidth
check3type=BANDWIDTH
check3settings=%IP|%Community|%Port|
check3desc=Monitors the bandwidth on the router''
File structure detailed
name= This is the name of your API. This name should be unique and identifies your API in the list of monitors
description= The description field holds the text as shown behind the API name in the list of monitors
apikey= If your API is included in the ServersCheck installer, then it will include an encrypted signature. API's signed by ServersCheck are shown first and are supported by ServersCheck. Unsigned API's are not supported.
supportdetails= This text is shown to the user should he have queries regarding the software, API or device being monitored
snmpversion= SNMP version to use. Currently only v1 & v2 are supported. For v1 set value to 1 and for v2 set value to 2c
category= identifies in which category the API is shown. HW will make the API appear in the hardware list, SW in the software list
refresh= how often the monitor is refreshed. Minimum value is 60 (seconds). If empty, then value is 180sec (=3 minutes)
retry= is the number of retries that a check is done prior to considering it down
This was the easy part. Now starts the trick part. How to proceed from here? Best is to define in the software a set of monitors for your application or device for which you want to create an API.
Now open the serverscheck.conf file located in the /conf subdirectory
Locate the lines related to the monitors of the API you want to create.
On there you will find lines similar to following:
BANDWIDTH|X|1250983739|X|3|X|180|X|test@test2.com|X||X|0123456789|X|true|X|true|X||X||X||X||X||X|10.0.0.99<X>public<X>161<X>.1.3.6.1.2.1.2.2.1.10.2<X>.1.3.6.1.2.1.2.2.1.16.2<X>B|X||X|98|X|yes|X|180|X|msn@msn.com|X||X|On each status change|X|test|X||X||X||X||X|<X>|X||X|yes|X|<X><X><X>|X|<X><X>|X||X||X|no|X||X||X||X|Unknown on 10.0.0.99|X|false|X||X||X||X||X||X||X||X||X||X||X||X||X||X|<X>|X||X||X||X||X|BANDWIDTH|X|<X><X><X><X><X><X>|X||X||X||X||X|1250983760
The above example is for a bandwidth monitor. The definition of any monitor is the position 14 of the line where |X| is the delimiter. In the above example this would be:
10.0.0.99<X>public<X>161<X>.1.3.6.1.2.1.2.2.1.10.2<X>.1.3.6.1.2.1.2.2.1.16.2<X>B
My variable values in this above example are:
- IP address
- Community string
- SNMP port
We are going to define those as required parameters. A required parameter is a variable name preceded with the percentage % sign.
requiredparams=%IP|%Community|%Port
Each monitor holds 5 lines:
check1name= is the name of the monitor as shown on the screen
check1desc= is the description of what the monitor does
check1type= is the monitor type to use
check1settings= holds the variables OR predefined values for the monitor. In above example we could just use the variables defined earlier:
check1settings=%IP|%Community|%Port| or we could also already set the SNMP OID's in this case as they are fixed (= the same for any monitor of this API - for example bandwidth on port eth0). check1settings=%IP|%Community|%Port|.1.3.6.1.2.1.2.2.1.10.2|.1.3.6.1.2.1.2.2.1.16.2|B
check1treshold= has as a value the treshold value against which it is being compared
check1compare= gt: returned value is greater than treshold; lt: returned value is less than treshold; eq: returned value equals treshold value
To create the second monitor, repeat above steps and increase the 1 to 2. so check1name would now be check2name. Repeat same for any other monitors you want to define.
The file needs to have the same as in the name= field but in LOWERCASE (!!). So if the first line of your API file reads
name=XYZ then the API file needs to be xyz.conf
Copy the file in the /api subfolder and your API is ready to be used.
