# Nagios Json Plugin This is a generic plugin for Nagios which checks json values from a given HTTP endpoint against argument specified rules and determines the status and performance data for that service. ### Installation #### Requirements * Nagios * Python Assuming a standard installation of Nagios, the plugin can be executed from the machine that Nagios is running on. ```bash cp check_http_json.py /usr/local/nagios/libexec/plugins/check_http_json.py chmod +x /usr/local/nagios/libexec/plugins/check_http_json.py ``` Add the following service definition to your server config (`localhost.cfg`): ``` define service { use local-service host_name localhost service_description check_command } ``` Add the following command definition to your commands config (`commands.config`): ``` define command{ command_name command_line /usr/bin/python /usr/local/nagios/libexec/plugins/check_http_json.py -H : -p [-e|-q|-l|-g ] [-e ] } ``` More info about options in Usage. ### CLI Usage Executing `./check_http_json.py -h` will yield the following details: ``` usage: check_http_json.py [-h] -H HOST [-p PATH] [-e [KEY_LIST [KEY_LIST ...]]] [-q [KEY_VALUE_LIST [KEY_VALUE_LIST ...]]] [-l [KEY_LTE_LIST [KEY_LTE_LIST ...]]] [-g [KEY_GTE_LIST [KEY_GTE_LIST ...]]] [-m [METRIC_LIST [METRIC_LIST ...]]] [-d] Nagios plugin which checks json values from a given endpoint against argument specified rules and determines the status and performance data for that service optional arguments: -h, --help show this help message and exit -H HOST, --host HOST Host. -p PATH, --path PATH Path. -e [KEY_LIST [KEY_LIST ...]], --key_exists [KEY_LIST [KEY_LIST ...]] Checks existence of these keys to determine status. -q [KEY_VALUE_LIST [KEY_VALUE_LIST ...]], --key_equals [KEY_VALUE_LIST [KEY_VALUE_LIST ...]] Checks equality of these keys and values (key,value key2,value2) to determine status. -l [KEY_LTE_LIST [KEY_LTE_LIST ...]], --key_lte [KEY_LTE_LIST [KEY_LTE_LIST ...]] Checks that these keys and values (key,value key2,value2) are less than or equal to the returned json value to determine status. -g [KEY_GTE_LIST [KEY_GTE_LIST ...]], --key_gte [KEY_GTE_LIST [KEY_GTE_LIST ...]] Checks that these keys and values (key,value key2,value2) are greater than or equal to the returned json value to determine status. -m [METRIC_LIST [METRIC_LIST ...]], --key_metric [METRIC_LIST [METRIC_LIST ...]] Gathers the values of these keys (key,UnitOfMeasure,Min,Max,WarnRange,CriticalRange) for Nagios performance data. More information about Range format and units of measure for nagios can be found at https://nagios- plugins.org/doc/guidelines.html Additional formats for this parameter are: (key), (key,UnitOfMeasure), (key,UnitOfMeasure,Min,Max). -d, --debug Debug mode. ``` More info about Nagios Range format and Units of Measure can be found at [https://nagios-plugins.org/doc/guidelines.html](https://nagios-plugins.org/doc/guidelines.html). ### Docker Info Example Plugin #### Description Let's say we want to use `check_http_json.py` to read from Docker's `/info` HTTP API endpoint with the following parameters: ##### Connection information * Host = 127.0.0.1:4243 * Path = /info ##### Rules for "aliveness" * Verify that the key `Containers` exists in the outputted JSON * Verify that the key `IPv4Forwarding` has a value of `1` * Verify that the key `Debug` has a value less than or equal to `2` * Verify that the key `Images` has a value greater than or equal to `1` * If any of these criteria are not met, report a WARNING to Nagios ##### Gather Metrics * Report value of the key `Containers` with a MinValue of 0 and a MaxValue of 1000 as performance data * Report value of the key `Images` as performance data * Report value of the key `NEventsListener` as performance data * Report value of the key `NFd` as performance data * Report value of the key `NGoroutines` as performance data * Report value of the key `SwapLimit` as performance data #### Service Definition `localhost.cfg` ``` define service { use local-service host_name localhost service_description Docker info status checker check_command check_docker } ``` #### Command Definition with Arguments `commands.cfg` ``` define command{ command_name check_docker command_line /usr/bin/python /usr/local/nagios/libexec/plugins/check_http_json.py -H 127.0.0.1:4243 -p info -e Containers -q IPv4Forwarding,1 -l Debug,2 -g Images,1 -m Containers,,0,1000 Images NEventsListener NFd NGoroutines SwapLimit } ``` #### Sample Output ``` OK: Status OK.|'Containers'=1;0;1000 'Images'=11;0;0 'NEventsListener'=3;0;0 'NFd'=10;0;0 'NGoroutines'=14;0;0 'SwapLimit'=1;0;0 ``` ### Docker Container Monitor Example Plugin `check_http_json.py` is generic enough to read and evaluate rules on any HTTP endpoint that returns JSON. In this example we'll get the status of a specific container using it's ID which camn be found by using the list containers endpoint (`curl http://127.0.0.1:4243/containers/json?all=1`). ##### Connection information * Host = 127.0.0.1:4243 * Path = /containers/2356e8ccb3de8308ccb16cf8f5d157bc85ded5c3d8327b0dfb11818222b6f615/json ##### Rules for "aliveness" * Verify that the key `ID` exists and is equal to the value `2356e8ccb3de8308ccb16cf8f5d157bc85ded5c3d8327b0dfb11818222b6f615` * Verify that the key `State.Running` has a value of `True` #### Service Definition `localhost.cfg` ``` define service { use local-service host_name localhost service_description Docker container liveness check check_command check_my_container } ``` #### Command Definition with Arguments `commands.cfg` ``` define command{ command_name check_my_container command_line /usr/bin/python /usr/local/nagios/libexec/plugins/check_http_json.py -H 127.0.0.1:4243 -p /containers/2356e8ccb3de8308ccb16cf8f5d157bc85ded5c3d8327b0dfb11818222b6f615/json -q ID,2356e8ccb3de8308ccb16cf8f5d157bc85ded5c3d8327b0dfb11818222b6f615 State.Running,True } ``` #### Sample Output ``` WARNING: Status check failed, reason: Value True for key State.Running did not match. ``` The plugin threw a warning because the Container ID I used on my system has the following State object: ``` u'State': {... u'Running': False, ... ``` If I change the command to have the parameter -q parameter `State.Running,False`, the output becomes: ``` OK: Status OK. ```