Nagios XI API Questions

[brandondash]

1. I don't see any mention of an endpoint to configure commands via the API (only hosts and services). Is this by design, or am I missing it somewhere?
2. What happens if I create a service using a command that doesn't exist? I assume it errors out. Why not expose a list of available commands?
3. I don't see any update functionality. Do we necessarily have to delete then create?
4. Follow-on to the previous question: I assume we do not have access to unique identifiers. Is that correct? It looks like host_name+service_name is unique (based on the delete documentation). Is that correct?
5. Why are services tied to hosts in the config API? They certainly aren't tied to hosts in the web interface. I can make a service without ever touching hosts. That doesn't make sense to me. Can you explain?
6. I see you can create hostgroups and servicegroups, but you can't actually assign hosts or services to them? What's the point of that?

Honestly the more I look at this the more I think I must have incomplete documentation or something. Help!

[jomann]

The documentation is missing a few use cases but currently that is the extent of the API right now. Unfortunately, due to the extensive configuration options it's hard to allow every type of configuration. However, if you ever need to update an advanced configuration that isn't directly allowed right now via the API you can use the config/import endpoint which would allow you to import a full config define section.

To answer each individual question:

1. In XI 5.5.x you should see a see a section on commands. You can create (and update by overriding) commands from the config/commands endpoint if the system shows it in the help section.
2. It should still work. It should make a stub command, since that is how the CCM imports work. Listing items from the CCM in the config endpoint is on the roadmap.
3. You do not have to delete to update, you just have to do a POST to the same hostname or hostname+servicename combo with only the values that you want changed.
4. At this time there are no unique identifiers but in the future, it is likely to be added. The hostname and hostname+servicename are unique.
5. Typically services that aren't directly tied to hosts means it's a more advanced configuration. The API doesn't have the functionality right now to deal with those kinds of configurations, but it is on the roadmap.
6. You can assign hosts/services to host groups and service groups just like you would in a normal config. It says "** All normal hostgroup directives are able to be used like normal core config definition files." which means the members value can be passed in as a variable. You can see the definition here: https://assets.nagios.com/downloads/nag ... #hostgroup

The API is being actively updated and in future versions new features, more documentation, and better ease of use will all be incorporated.

[ssax]

In addition to what jomann posted, since I have it typed up I'll include my answer as well.

1. The ability to add commands through the API was added to XI version 5.5.0, what version are you running?

Code: Select all

Added commands (core), scheduleddowntime, auth servers into system API backend -JO

From here: https://www.nagios.com/downloads/nagios-xi/change-log/

2. It will create the service but it will fail verification when trying to apply config like so:

Code: Select all

Error: Service check command 'check_NOTEXIST!3000,80%!5000,100%' specified in service 'PING' for host 'testapihost' not defined anywhere! 

3. If the host/service exists it will update/replace it.

4. Correct.

5. Services need to be attached to a host to be useful, they can also be attached to a hostgroup but the API doesn't currently support that this time.

6. You can assign hosts to hostgroups by using adding &members=host1,host2 to your call. You can assign services to your servicegroup the same way by adding &members=host1,service_description1,host2,service_description2.

Underneath the API section of most of the entries you will see this as well, most options should be available:

Code: Select all

** All normal XXX directives are able to be used like normal core config definition files.

All the API documentation is built into the Help section of XI.

Thank you

[brandondash]

1. The ability to add commands through the API was added to XI version 5.5.0, what version are you running?

Nagios XI 5.4.13. Looks like I'll have to start the long paperwork process of requesting an upgrade.

However, if you ever need to update an advanced configuration that isn't directly allowed right now via the API you can use the config/import endpoint which would allow you to import a full config define section.

This is worth looking into as well.

Thanks both of you!

[lmiltchev]

@brandondash, let us know if it is OK to close this topic. Thank you!

[brandondash]

Yes, please close. All questions have been answered. Thanks again.

[scottwilkerson]

Yes, please close. All questions have been answered. Thanks again.

Great! Locking