This article was written for version 7.0 of op5 Monitor, it could work on both lower and higher version if nothing else is stated.
op5 Monitor supports submitting status updates for services and hosts via the HTTP API - known as passive checks in the Nagios/Naemon context.
This enables you to update a service status when a backup job is completed, integrated op5 Monitor with your in-house applications or send updates from the system shell.
In this how-to we will look at updating a service via the command line utility cURL and show you how to integrate something similar in scripts or applications.
- Basic Linux/UNIX knowledge
- Knowledge of service configuration in op5 Monitor
- A op5 Monitor user with permission to submit commands
- Shell access to a system with the cURL utility installed
It is a very good idea to create a dedicated group with only the minimum required privileges for each major type of API request, then create a user for each group. This makes it easier to control how much damage could be done by a script or process calling the API. Each group will need any particular API privileges, as well as all the usual privileges to do a task in the web browser. Here are a couple examples, with a screen shot of both afterward:
- Querying hosts -- this is a read-only task. Thus:
- API Command
- Host View All
- Changing services -- this will write changes, so it will require:
- API Command
- Service View All
- Service Edit All
- Service Command Passive Check
It's also recommended to create a new service template with active checks disabled for passive usage.
The "check_freshness" option can be enabled to run a check command (like "check_dummy" with critical status) if the service/host haven't been updated during the defined time frame:
Runs the check actively if it hasn't been updated during the last hour.
Submitting service status updates with cURL
The cURL command line utility can be used to retrieve and submit information to op5 Monitor's HTTP API.
Using cURL for this purpose is a great fit, since it's installed or available for installation on most operating systems.
The command below will do the following:
- Log in to the HTTP API with the user "status_update" and the password "mysecret"
- Update a service called "Example service" on the host "example_host_1"
- Set the status message to "Example issue has occurred" and the service status to "CRITICAL".
More information about "plugin interface" and status codes can be found here
After executing the command above, you should hopefully retrieve the following message:
If not, verify that you have entered the correct user name and password, have been given adequate permissions and the the service/host name is spelled/capitalized correctly.
When self-signed SSL certificates are used on the op5 Monitor server, you must include the "?insecure" argument - this however not recommended.
The service should now be updated in op5 Monitor:
Including service status updates in a backup script
There are many cases where active monitoring might not be suitable - examples are long running backup and batch jobs.
In this example we will use it in a shell script that's executed by cron, every day at midnight.
It uses a small Python program called "update-status.py", which works similar to the cURL command above, but with some more error handling :