REST Tutorial

The REST interface supports all Nagios options available for object files.

This tutorial will guide the reader through setting up an additional host using the REST interface.

The Working Environment

Set up a Nagios and Nagrestconf server using one of the Installation Guides and be sure to import the backup configuration file as shown in the guide.

Download the tool, nrcq, from https://github.com/mclarkson/nrcq.

Either copy nrcq to the Nagios server and use the tool there, or use the tool from your workstation to access nagrestconf remotely.

If using nrcq on the Nagios server, ensure it is executable with 'chmod +x nrcq', and copy it to the system PATH, for example, 'sudo cp nrcq /usr/local/bin/'.

If using your workstation to connect remotely, use 'ssh' to forward local packets to the remote Nagios server. For example, on a Linux or Mac workstation you would type something similar to:

sudo ssh -L 80:127.0.0.1:80 user@nagios-server

Then, in either case, the URL to use in nrcq will be http://localhost/rest.

There are a few different ways to set up remote api access but using one of the previous methods allows this tutorial to always use the same URL.

Test the API

Now that everything is set up it's time to test that nrcq works, then the tutorial can begin.

First we'll try retrieving a list of hosts. Type:

nrcq http://localhost/rest show/hosts

If everything is working then the output should be:

    name:localhost
    alias:localhost
    ipaddress:127.0.0.1
    template:hsttmpl-local
    hostgroup:mgmt
    activechecks:1
    servicesets:local-checks
    disable:0

No more output will be shown for the rest of this tutorial.

REST Commands

The REST interface is quite simple with only a few commands (or endpoints).

To see a list of all commands type, 'nrcq -L'.

Some entries will be shown in a condensed form, such as:

show|add|modify|delete/hosts

That line means that the endpoints shown next are all valid:

show/hosts
add/hosts
modify/hosts
delete/hosts

The nrcq tool also shows all the options for each endpoint along with the required fields, prefixed with a star.

For example, to view the valid options for the hosts table, type:

nrcq -l hosts

Add a Host

To add a new host all required options must be supplied to the 'add/hosts' command. The required options are marked with 'R' in the tables in the reference documentation, and prefixed with a star, '*', by 'nrcq -l ENDPOINT'.

To add a new host named 'newserver'.

nrcq http://localhost/rest add/hosts -d 'name:newserver'

This will produce a descriptive error message since the required options weren't added. The correct command is:

nrcq http://localhost/rest add/hosts \
    -d name:newserver \
    -d alias:newserver \
    -d ipaddress:1.2.3.4 \
    -d template:hsttmpl-local

If the previous command is run again an error message will be ouput because the host already exists, and having two hosts with the same name is an error.

Look at the new host in the nagrestconf Web interface and it will have no services attached to it. The easiest way to add services is to create a service set first, then name the service set when adding the host. This will be shown next.

Delete Host

The host will need to be deleted before it can be added with services from a service set, since only newly created hosts get service sets applied to them. To delete the host:

nrcq http://localhost/rest delete/hosts -d name:newserver

Then add it again but use one of the existing service sets:

nrcq http://localhost/rest add/hosts \
    -d name:newserver \
    -d alias:newserver \
    -d ipaddress:1.2.3.4 \
    -d template:hsttmpl-local \
    -d servicesets:example-lin

Using the nagrestconf Web interface it can be seen that 'newserver' exists but this time with a bunch of services attached to it.

The new host, 'newserver' won't appear in the Nagios Web interface until the changes are applied. Use the commands 'apply', 'check' then 'restart' to do this:

nrcq http://localhost/rest apply/nagiosconfig

nrcq http://localhost/rest check/nagiosconfig

nrcq http://localhost/rest restart/nagios

The previous commands produce minimal output. The 'apply' and 'check' commands can show more information, useful if there was an error, by using the 'verbose' option:

nrcq http://localhost/rest apply/nagiosconfig -d verbose:true

nrcq http://localhost/rest check/nagiosconfig -d verbose:true

nrcq http://localhost/rest restart/nagios

Modify a Host

The host does not belong to a host group. The following command will add it to the 'mgmt' host group:

nrcq http://localhost/rest modify/hosts -d name:newserver -d hostgroup:mgmt

This could have been added when the host was created by adding 'hostgroup:mgmt' to the list of options in the 'add/hosts' command.

The configuration can be applied as before by using 'apply', 'check', then 'restart', or by using the nagrestconf Web interface.

Finally, to delete the value of an option, use the minus sign, '-'. For example, to delete the host group we just added, type:

nrcq http://localhost/rest modify/hosts -d name:newserver -d hostgroup:-

That's It!

This tutorial has demonstrated adding, modifying, and deleting a host. Every configuration change follows the same format so that's pretty much all there is to know about the REST interface. It's all more of the same steps for each table (services, hostgroups, commands, etc) and will involve a bit of trial and error.