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
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."}
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}
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"}
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"}]
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/
Article ID: 596
Created On: Tue, Jun 13, 2017 at 11:39 PM
Last Updated On: Mon, Feb 26, 2018 at 5:56 PM
Authored by: tlea
Online URL: https://support.nagios.com/kb/article/nagios-log-server-api-examples-596.html