NagiosXI has a REST API that can be used to add, edit and remove objects from the configuration. Full details of the configuration and use of this can be found on your installation at: http://nagiosserver.domain.com/nagiosxi/help/?xiwindow=api.php (or you can find it through the Advanced Configuration menu).
Each user has an APIKey which can also be found via the REST API page on Nagios, its a unique key to each user and is required to access the REST API and manipulate objects.
Its worth noting that at the time of writing the REST API on NagiosXI (5.11.2) is not the most fully featured API, but assuming you ensure that you have host and service templates already configured, you can fairly easily add hosts and attach services.
The other point is that the API is not declarative, well, it does not appear to be. What this means in practice is you can’t just feed API requests in any order, if you which to attach a service to a host, the host must already been created within the configuration; i.e. not like how say AWS CloudFormation works.
Using the REST API to Add Hosts and Services
In this example we will be adding a new host called bigbertha to be monitored with a directly attached service Uptime in addition to the Ping check it inherits from its host group. We will be making use of inheritance to set the vast majority of the settings thus reducing the amount we need to pass in the CURL command to the API, this inheritance will also mean the host is automatically applied a “Ping” service check that is inherited because of its membership of a host group.
| host_name | bigbertha | |
|---|---|---|
| address | 192.168.10.10 | |
| use | generic-host-ping | Template to use to inherit all the host check settings. |
| hostgroups | network-device | |
| parents | edge-switch1,edge-switch2 | |
| alias | Generic Linux Server |
The CURL URL that is needed to be passed is shown below, as you can see the directives within the string match the names used within the NagiosXI configuration files and are separated by an ampersand (&) character. You’ll notice the API key has been replaced with <APIKEY> for security reasons, you would substitute your own key or the APIKey above to add configuration from an automated script. Notice the “force=1” appended to the end, this is required for the API to accept the registration for the new host with some of the required configuration directives missing (i.e. the ones that the template gives it) the CCM can’t figure that out at the point of the API adding the configuration so without using “force=1” it would throw an error; its worth noting however that it means that if you do have an invalid configuration, your config might be accepted but will fail being applied and will need fixing first.
Step 1 – Add the Host
Note: If you need to skip the per-item config verification add force=1 to the config API request. This is especially helpful when applying an object that uses a template and may be inheriting one of the required parameters such as check_command which the CCM verification will not know about. Warning: This can cause the applied config to fail if not used properly, i.e it won’t sanity check what you are putting into the configuration as you are putting it in.
The following API call (using CURL) will create the host bigbertha and attach the relevant template and host group.
curl -XPOST -k "https://nagioserver.domain.com/nagiosxi/api/v1/config/host?apikey=<APIKEY>&pretty=1" -d "host_name=bigbirtha&address=192.168.10.10&use=generic-host-ping&hostgroups=network-device&parents=edge-switch1,edge-switch2&alias=General Linux Server&force=1"
Step 2 – Add the Uptime Service
We can now configure service for the host, again using the same principles, you create a service with a host_name, service_description and use the “use” directive to apply a template (with all the settings), finally you configure the check_command, the arguments you might pass appear as a single line, all the exclamation marks need escaping though.
TIP: If you want to know what this string might look like click on the floppy disk icon against a host or service to see how it is represented in the NagiosXI configuration files, then work back from there.
curl -XPOST -k "https://nagiosserver.domain.com/nagiosxi/api/v1/config/service?apikey=<APIKEY>&pretty=1" -d "host_name=bigbertha&service_description=Uptime&use=generic-service&check_command=check_by_ssh\!1\!/opt/nagios/monitor-plugins/check_disk -w 80 -c 90 -p /\!nagios\!\!\!\!\!&force=1"Step 3 – Apply and Check the Configuration
If you are working from a scripted process, checking the configuration is not necessary because the code you are entering is unlikely to be incorrect. You can apply the “applyconfig=1” directive to the end of the above string if you wish, but if you want to apply config separately, e.g. when you have created a load of host and service checks and want to apply them in one go, you can use the following:
curl -XPOST "https://nagiosserver.domain.com/nagiosxi/api/v1/system/applyconfig?apikey=<APIKEY>"Bulk Create
To bulk create you can wrap the command within a BASH script, if required you can check for success on completion of the command. It is recommended however to add a short wait between each command if you are bulk adding items to give time for the insert to work, perhaps with a “sleep”.
Additionally by not including the “applyconfig”, you are essentially making changes in a batch, which then you can then apply with another REST API call, or via the GUI and they are all applied in one go.
It is also crucial that you check that the added configuration is valid before committing, especially when using the “&force=1” option that does not mandate a check of the configuration on each addition/change/removal.