HTTP-API
About
The HTTP-API let's you configure, get status information and report data from op5 Monitor by issuing regular HTTP requests.
Basically, you 'visit' an URI, which triggers op5 Monitor to do something, and you get a response telling you what happened.
For more information about the REST API go to https://your-op5-monitor/api/help/
HTTP Status API
The HTTP Status API is used to get the information from op5 Monitor Status GUI. It can give you information about all objects used by the op5 monitor.
Widgets are one place where the HTTP Status API will come handy.
There are only a briefly documentation about that API today. It is included in the product.
Let us say that your monitor server is called op5-monitor you can reach the documentation on the following location:
https://op5-monitor/monitor/Documentation/html/index.html
It is generated by doxygen and contains information like
•namespaces
•structures (classes and methods)
•files
HTTP Configuration API
The configure API is used to manipulate the object configuration used by op5 Monitor. It works against the configure database the same way as the op5 Monitor Configuration tool does.
You may use it to build integrations between op5 Monitor and other third party software.
Let us say that your monitor server is called op5-monitor you can reach the documentation on the following location:
https://op5-monitor/monitor/op5/nacoma/Documentation/html/index.html
It is generated by doxygen and contains information like classes and methods used in the op5 Monitor configuration tool.
HTTP Command API
The command API lets you submit commands to op5 Monitor using the REST API.
Commands
•Acknowledge Host Problem
•Acknowledge Service Problem
•Process Host Check Result
•Process Service Check Result
•Schedule and Propagate Host Downtime
•Schedule and Propagate Triggerd Host Downtime
•Schedule Host Check
•Schedule Host Downtime
•Schedule Service Check
•Schedule Service Downtime
Acknowledge Host Problem
This command is used to acknowledge a host problem.
When a host problem is acknowledged, future notifications about problems are temporarily disabled until the host changes from its current state. If you want acknowledgement to disable notifications until the host recovers, specify the 'sticky' option. Contacts for this host will receive a notification about the acknowledgement, so they are aware that someone is working on the problem. Additionally, a comment will also be added to the host. Make sure to enter your name in the 'author' parameter and fill in a brief description of what you are doing in the 'comment' paramter. If you would like the host comment to remain once the acknowledgement is removed, specify the 'persistent' option. If you do not want an acknowledgement notification sent out to the appropriate contacts, do not specify the 'notify' option.
Acknowledge Service Problem
This command is used to acknowledge a service problem.
When a service problem is acknowledged, future notifications about problems are temporarily disabled until the service changes from its current state. If you want acknowledgement to disable notifications until the service recovers, specify the 'sticky' option. Contacts for this service will receive a notification about the acknowledgement, so they are aware that someone is working on the problem. Additionally, a comment will also be added to the service. Make sure to enter your name in the 'author' parameter and fill in a brief description of what you are doing in the 'comment' parameter. If you would like the service comment to remain once the acknowledgement is removed, specify the 'persistent' option. If you do not want an acknowledgement notification sent out to the appropriate contacts, do not specify the 'notify' option.
Process Host Check Restult
This command is used to submit a passive check result for a host.
Process Service Check Result
This command is used to submit a passive check result for a service. It is particularly useful for resetting security-related services to OK states once they have been dealt with.
Schedule and Propagate Host Downtime
Schedules downtime for a specified host and all of its children (hosts).
If the "fixed" argument is set to one (1), downtime will start and end at the times specified by the "start" and "end" arguments. Otherwise, downtime will begin between the "start" and "end" times and last for "duration" seconds. The "start" and "end" arguments are specified in time_t format (seconds since the UNIX epoch). The specified (parent) host downtime can be triggered by another downtime entry if the "trigger_id" is set to the ID of another scheduled downtime entry. Set the "trigger_id" argument to zero (0) if the downtime for the specified (parent) host should not be triggered by another downtime entry.
Schedule and Propagate Triggerd Host Downtime
Schedules downtime for a specified host and all of its children (hosts).
If the "fixed" argument is set to one (1), downtime will start and end at the times specified by the "start" and "end" arguments. Otherwise, downtime will begin between the "start" and "end" times and last for "duration" seconds. The "start" and "end" arguments are specified in time_t format (seconds since the UNIX epoch). Downtime for child hosts are all set to be triggered by the downtime for the specified (parent) host. The specified (parent) host downtime can be triggered by another downtime entry if the "trigger_id" is set to the ID of another scheduled downtime entry. Set the "trigger_id" argument to zero (0) if the downtime for the specified (parent) host should not be triggered by another downtime entry.
Schedule Host Check
This command is used to schedule the next check of a host.
The monitoring process will re-queue the host to be checked at the time you specify.
Schedule Host Downtime
This command is used to schedule downtime for a host.
During the specified downtime, the monitoring process will not send notifications out about the host. When the scheduled downtime expires, the monitoring process will send out notifications for this host as it normally would. Scheduled downtimes are preserved across program shutdowns and restarts. If you specify the 'fixed' option, the downtime will be in effect between the start and end times you specify. If you do not specify the 'fixed' option, the monitoring process will treat this as "flexible" downtime. Flexible downtime starts when the host goes down or becomes unreachable (sometime between the start and end times you specified) and lasts as long as the duration of time you specify. The 'duration' parameter does not apply for fixed downtime.
Schedule Service Check
This command is used to schedule the next check of a service.
The check will be re-queued to be run at the time you specify.
Schedule Service Downtime
This command is used to schedule downtime for a service.
During the specified downtime, the monitoring process will not send notifications out about the service. When the scheduled downtime expires, the monitoring process will send out notifications for this service as it normally would. Scheduled downtimes are preserved across program shutdowns and restarts. If you specify 'fixed' option, the downtime will be in effect between the start and end times you specify. If you do not specify the 'fixed' option, the monitoring process will treat this as "flexible" downtime. Flexible downtime starts when the service enters a non-OK state (sometime between the start and end times you specified) and lasts as long as the duration of time you specify. The 'duration' parameter does not apply for fixed downtime.
HTTP Report API
The report API can be used to retrieve report data in XML or JSON format.
HTTP Filter API
The filter API can be used to ether retrieve a list of objects from a filter or do a count of objects in a filter.
Query example
To view hosts that are not OK:
https://<op5server>/api/filter/query?query=[hosts]%20state!=0&columns=name,state,acknowledged,has_been_checked
Count example
To get a count of the objects using the same query as above:
https://<op5server>/api/filter/count?query=[hosts]%20state!=0&columns=name,state,acknowledged,has_been_checked
Example
In this example we will create a new host called my_server with one ping service. The IP for my_server is 192.168.0.20
In this example the op5 server is called op5-server, the username is joe and joe’s password is joespassword.
By visiting the https://op5monitor.example.com/api/help/config/host, you get information on how to create a host. This is what needs to be done in PHP:
<?php
$data = json_encode(array(
'address' => '192.168.0.20',
'alias' => 'My Server',
'host_name' => 'my_server'
));
$a_handle = curl_init('https://op5monitor.example.com/api/config/host');
curl_setopt($a_handle, CURLOPT_USERPWD, 'joe:joespassword');
curl_setopt($a_handle, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($a_handle, CURLOPT_POSTFIELDS, $data);
curl_setopt($a_handle, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($a_handle, CURLOPT_SSL_VERIFYPEER, false);
$host = curl_exec($a_handle);
$data = json_encode(array(
'check_command' => 'check_ping',
'service_description' => 'ping',
'host_name' => 'my_server'
));
$a_handle = curl_init('op5-server/api/config/service');
curl_setopt($a_handle, CURLOPT_USERPWD, 'joe:joespassword');
curl_setopt($a_handle, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($a_handle, CURLOPT_POSTFIELDS, $data);
curl_setopt($a_handle, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($a_handle, CURLOPT_SSL_VERIFYPEER, false);
$service = curl_exec($a_handle);
?>
Before the changes are applied, you need to confirm them and then save them so that they become part of your configuration. This can be done in two ways, either by Saving changes in the op5 Monitor GUI, or by adding an additional call via the REST API:
<?php
$a_handle = curl_init('op5-server/api/config/change');
curl_setopt($a_handle, CURLOPT_USERPWD, 'joe:joespassword');
curl_setopt($a_handle, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($a_handle, CURLOPT_SSL_VERIFYPEER, false);
$save = curl_exec($a_handle);
?>
Now, visiting op5-server/api/config/host/my_server in a browser should show you the live configuration.
REST and LDAP
When you have more than one auth module, for example "Local" and "LDAP", you need to specify which to authenticate against. This is done with the dollar character ('$').
Thus, this regular call:
curl -u user:password https://op5monitor.example.com/api/status/host [^]
becomes
curl -u 'user$LDAP:password' https://op5monitor.example.com/api/status/host [^]
or
curl -u 'user$Local:password' https://op5monitor.example.com/api/status/host [^]
Notice how the dollar sign ('$') needs quoting depending on the environment (in bash, it will always need to be quoted).
The first way of calling the API:
curl -u user:password https://op5monitor.example.com/api/status/host [^]
will still work, provided that you want to authenticate against the default driver. The default driver can always be specified from within the GUI: Configure -> Auth Modules.