Home » Categories » Multiple Categories

Nagios Log Server - API Examples

Overview

This KB article provides examples on how to use the application programming interface (API) available in Nagios Log Server. The API has many features that extend the functionality of Nagios Log Server and will be demonstrated here.

 

 

API Access & Key/Token

To use the API your user account needs to be granted API access. A Nagios Log Server administrator is able to grant this via Administration > General > User Management.

A key will then exist for that user account. The user needs to login to Nagios Log Server and in the top right corner click their name. This will present them with their profile and the API Access Key will be displayed, for example 6dbe1548d33f17acb314063477f67d5dd1e18069.

This key is commonly referred to as the token and will for part of the URL request, for example:

http://192.168.4.202/nagioslogserver/index.php/api/system/status?subsystem=logstash&token=6dbe1548d33f17acb314063477f67d5dd1e18069

 

To make this KB article easy to read, the token XXXX will be used.

 

 

Usage

It's best to start off with a simple example. An API call is as simple as accessing a web page. If I point my web browser to the API URL it will return the information in a JSON object.

Here is an example that will get the status of the logstash subsystem:

http://10.25.5.99/nagioslogserver/index.php/api/system/status?subsystem=logstash&token=XXXX

 

The web browser will display something like this:

{"status":"running","pid":"1277","message":"Log collector (logstash) is running."}

 

Some web browser may detect that it is a JSON object and display the information in an easy to read format:

status:    "running"
pid:    "1277"
message:    "Log collector (logstash) is running."

 

However if you are making API calls then it's most likely you require the data in a script so you can manipulate the returned JSON object. This is most commonly done using a CURL XGET request, for example:

curl -XGET 'http://localhost/nagioslogserver/index.php/api/system/status?subsystem=logstash&token=XXXX'

 

The output will be the JSON object:

{"status":"running","pid":"1277","message":"Log collector (logstash) is running."}

 

You will notice in the web browser that the address was http://10.25.5.99/ however the CURL request used http://localhost/ instead. This is because the CURL request was performed locally on the Nagios Log Server in a terminal session. However you can remotely execute the CURL request from another machine using the address.

If you are using SSL/TLS with self signed certificates then you might receive this error when performing a CURL request:

curl: (60) server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none
More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a "bundle"
 of Certificate Authority (CA) public keys (CA certs). If the default
 bundle file isn't adequate, you can specify an alternate file
 using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
 the bundle, the certificate verification probably failed due to a
 problem with the certificate (it might be expired, or the name might
 not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use
 the -k (or --insecure) option.

 

You receive this error because the certificate authority that generated this certificate is unknown and untrusted. You can ignore this by using the -k argument:

curl -k -XGET 'https://localhost/nagioslogserver/index.php/api/system/status?subsystem=logstash&token=XXXX'

 

 

System

Daemons / Services

You can query the status of the logstash or elasticsearch daemons.

logstash

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/status?subsystem=logstash&token=XXXX

 Output:

{"status":"running","pid":"1277","message":"Log collector (logstash) is running."}

 

elasticsearch

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/status?subsystem=elasticsearch&token=XXXX

 Output:

{"status":"running","pid":"1260","message":"Search engine (elasticsearch) is running."}

 

You can stop / start / restart the daemons as well:

stop

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/stop?subsystem=logstash&token=XXXX

 Output:

{"message":"Log collector (logstash) is stopping."}

 

start

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/start?subsystem=logstash&token=XXXX

 Output:

{"message":"Log collector (logstash) is started."}

 

restart

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/restart?subsystem=elasticsearch&token=XXXX

 Output:

{"message":"Search engine (elasticsearch) is restarting."}

 

 

Status

CPU Load

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/cpu_status?token=XXXX

 Output:

{"cpu_usage":2.2}

 

Memory

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/memory_status?token=XXXX

 Output:

{"used_percent":23.110386079391,"swap_percent":100}

 

Root Drive

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/root_drive_status?token=XXXX

 Output:

{"filesystem":0,"size":14530560000,"used":2348800000,"available":12181760000,"percent":16.164552501762}

 

 

Jobs

Get All Jobs

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/get_all_jobs?token=XXXX

 Output:

[{"id":"backup_maintenance","created":"2017-03-07 15:11:57","created_by":null,"modified":null,"modified_by":null,"active":1,"status":"waiting",
"type":"system","node":"global","command":"do_maintenance","args":null,"run_time":1498015111,"frequency":"86400","run_until":null,
"last_run_output":"Maintenance and Backup jobs are being executed","last_run_status":"SUCCESS","last_run_time":"2017-06-20 13:18:31",
"readable_run_time":null,"readable_frequency":null},{"id":"backups","created":"2017-03-07 15:11:57","created_by":null,"modified":null,
"modified_by":null,"active":1,"status":"waiting","type":"system","node":"global","command":"do_backups","args":null,"run_time":1498015111,
"frequency":"86400","run_until":null,"last_run_output":null,"last_run_status":"SUCCESS","last_run_time":"2017-06-20 13:18:31","readable_run_time":null,
"readable_frequency":null},{"id":"AVzDgj8lbuWNSvMZewaF","created":"2017-06-20 13:18:31","created_by":null,"modified":null,"modified_by":null,
"active":1,"status":"completed","type":"user","node":"4c5786bd-1382-44b6-bb67-88a9c0d3e7ea","command":"create_backup","args":null,
"run_time":1497928711,"frequency":null,"run_until":null,"last_run_output":null,"last_run_status":"SUCCESS","last_run_time":"2017-06-20 13:18:35",
"readable_run_time":null,"readable_frequency":null},{"id":"run_update_check","created":"2017-03-07 15:11:57","created_by":null,"modified":null,
"modified_by":null,"active":1,"status":"waiting","type":"system","node":"global","command":"update_check","args":null,"run_time":1498015115,
"frequency":"86400","run_until":null,"last_run_output":null,"last_run_status":"SUCCESS","last_run_time":"2017-06-20 13:18:37","readable_run_time":null,
"readable_frequency":null},{"id":"cleanup_cmdsubsys","created":"2017-03-07 15:11:57","created_by":null,"modified":null,"modified_by":null,"active":1,
"status":"waiting","type":"system","node":"global","command":"cleanup","args":null,"run_time":1498011696,"frequency":"3600","run_until":null,
"last_run_output":null,"last_run_status":"SUCCESS","last_run_time":"2017-06-21 11:21:36","readable_run_time":null,"readable_frequency":null},
{"id":"run_all_alerts","created":"2017-03-07 15:11:57","created_by":null,"modified":null,"modified_by":null,"active":1,"status":"waiting","type":"system",
"node":"global","command":"run_alerts","args":null,"run_time":1498008391,"frequency":"20","run_until":null,"last_run_output":null,"last_run_status":"SUCCESS",
"last_run_time":"2017-06-21 11:26:11","readable_run_time":null,"readable_frequency":null}]

 

Get Job By ID

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/get_job_by_id?id=backups&token=XXXX

 Output:

{"id":"backups","created":"2017-03-07 15:11:57","created_by":null,"modified":null,"modified_by":null,"active":1,"status":"waiting","type":"system",
"node":"global","command":"do_backups","args":null,"run_time":1498015111,"frequency":"86400","run_until":null,"last_run_output":null,
"last_run_status":"SUCCESS","last_run_time":"2017-06-20 13:18:31","readable_run_time":"06\/21\/2017 13:18:31","readable_frequency":"1 day"}

 

 

Users

Get All Users

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/get_users?token=XXXX

 Output:

[{"username":"nagiosadmin","auth_type":"admin","email":"nagiosadmin@domain.local","language":"default","apiaccess":"1",
"apikey":"6dbe1548d33f17acb314063477f67d5dd1e18069","created":"2017-03-07 15:11:56","created_by":0,
"default_dashboard":"\/dashboard\/elasticsearch\/AVqm96tx0ld6yXn0xbao","id":"1"},{"name":"Read Only","username":"readonly",
"email":"readonly@domain.local","apiaccess":"0","apikey":"","auth_type":"user","language":"default","auth_settings":[],"created":"2017-06-21 11:44:41",
"created_by":"1","default_dashboard":"\/dashboard\/elasticsearch\/AVzIUrFTbuWNSvMZe2bq","id":"AVzIUrFjbuWNSvMZe2br"}]

  

 

Config

Verify Config Syntax

URL

http://10.25.5.99/nagioslogserver/index.php/api/system/verify_config_syntax?node=global&token=XXXX

 Output:

{"result":"success","output":["Configuration OK"]}

 

 

 

Final Thoughts

For any support related questions please visit the Nagios Support Forums at:

http://support.nagios.com/forum/

3.5 (2)
Article Rating (2 Votes)
Rate this article
  • Icon PDFExport to PDF
  • Icon MS-WordExport to MS Word
Attachments Attachments
There are no attachments for this article.
Related Articles RSS Feed
Nagios Log Server - Data Backup and Archiving
Viewed 1455 times since Sat, Feb 7, 2015
Nagios Log Server - Using An Output To Create Nagios XI Passive Objects
Viewed 1175 times since Thu, Sep 7, 2017
Nagios Log Server - Architecture and Overview - NWC15
Viewed 1304 times since Mon, Feb 1, 2016
Nagios Log Server - Real Life Experience of Nagios Log Server - NWC15
Viewed 1324 times since Mon, Feb 8, 2016
Nagios Log Server - Overview And Terminology
Viewed 1333 times since Wed, Jan 28, 2015
Nagios Log Server - Jobs Subsystem Architecture
Viewed 1194 times since Fri, Feb 6, 2015
Nagios Log Server - Full Architecture Overview
Viewed 3598 times since Thu, Jun 4, 2015
Nagios Log Server - Log Monitoring and Log Management with Nagios - NWC14
Viewed 1115 times since Thu, Feb 4, 2016
Nagios Log Server - Poller Subsystem Architecture
Viewed 1258 times since Fri, Feb 6, 2015
Nagios Log Server - Configuration Overview
Viewed 1697 times since Sat, Feb 7, 2015