GitHub - ganeshgirase/nagrestconf: Nagios REST Interface

Nagrestconf README

Caution

THIS SOFTWARE IS IN THE ALPHA STAGE.

.1. Latest News

xx Aug 2013 New version 1.158 (SOON)

Page tabs are now dynamic.
Plugins support started.
- Services-Tab plugin added.
- Bulk Tools Services plugin added.
- Bulk Tools Hosts plugin added (in progress).

03 Jul 2013 New version 1.157

Fixes to get GUI working in Internet Explorer 8.

.2. License

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

.3. Screenshots

Hosts page showing an Edit Host dialog.

The Services Tab, Bulk Tools plugin:

More screen shots can be seen in the Nagios Exchange Gallery at:

http://exchange.nagios.org/directory/Addons/APIs/Nagrestconf/gallery

.4. What is Nagrestconf?

'Nagrestconf' is a REST interface and configuration GUI for Nagios.

'Nagrestconf' is written in Bash and PHP.

Specifically, 'Nagrestconf':

allows Nagios configuration files to be written using a REST api.
allows the server to be restarted using the REST api.
provides a configuration Web GUI built on the REST api.

It can be useful for:

Bulk loading
Bulk editing
Automation
Catching common configuration mistakes
Configuration Delegation. This is coarse delegation - per environment.
Distributed monitoring (using mod_gearman).

.5. Features

Supports distributed monitoring with mod_gearman.
- Supports all mod_gearman Common Scenarios including the advanced distributed setup.
- When using the mod_gearman scenario Distributed Setup With Remote Scheduler:
  - Nagrestconf provides the `configuration sync' component.
  - `Testing mode' becomes possible. Testing mode is where some service checks are only visible on the slave worker. When testing is complete, testing-mode can be turned off for that service check and the check will appear in the Master Nagios.
A new concept, service-sets, is introduced. This is where a number of services are defined, and later this definition can be used when creating new hosts. This allows new servers to be added to monitoring using a single REST command.
Many things can be disabled:
- Service checks can be disabled.
- Entire servers can be disabled.
Configurations are versioned using subversion.
Ability to revert to the last-known-good configuration. Useful if lots of changes have been made but the user then decides to back out.
Multi-user. Many people or scripts can make changes and apply configurations simultaneously. This is achieved partly by ensuring that every REST POST command creates a valid configuration, so at any point the configuration can be applied and Nagios won’t be broken.
No database required.
A configuration GUI is included.

.6. TODO

Add more Nagios options, which are supported by REST, to the GUI. (by request)
Add urlencoding to the GUI `Commands' page.
Add plugins support to the GUI to do:
- bulk editing
- switching folders (environments)
- rollback using subversion
Performance enhancements:
- Only create/overwrite host files for those that have been added/edited.

.7. How does it work?

The REST interface

REST queries are received by a PHP script, rest/index.php. This script checks general syntax and options, creates a nagctl command line then runs the `nagctl' script using this command line.

`Nagctl' writes comma delimited format files that will be read by `csv2nag'. It is safe (but not recommended) to edit the `csv' files if the directory is locked first and it is also safe to run `csv2nag' by hand, from the command line. `Nagctl' makes a number of checks and cross-checks to try to ensure a valid Nagios configuration will be created by csv2nag. All the real checks are done here and any errors are passed back to `rest/index.php'.

One REST call, `apply/nagiosconfig', runs the csv2nag script. The only purpose of this script is to read the comma delimited files made by `nagctl' and write the Nagios configuration. `Csv2nag' does not check for a valid Nagios configuration since that is done by `nagctl'.

The configuration GUI

The configuration GUI relies entirely on the REST interface to operate, and hence can be run on a different machine if required.

Configuration Synchronisation

Nagios configurations are stored on each worker and synchronised `up' to the Nagios master. When the Nagios master notices that a subversion repository has changed it will remake the Nagios configuration files for that environment. Many of the configuration items will be `mangled' to stop name collisions. However, note that host names are not `mangled'. It is a requirement that host names are unique accross all Nagios workers. This should be enforced through naming convention - using full DNS names as host names is recommended.

If a configuration needs to be rolled back then it must be done on the Nagios slave worker from the command line and applied, then the configuration will be subversion mirrored 'up'.

                                  ____
            +---------+         _(    )_       +--------+
            | Nagios  |       _(        )_     | Nagios |
            | Master  |<-----(_-  -  -  -_)----| Worker |
            |         |    \   (_ WAN  _)      +--------+
            +---------+     \    (____)            /\
                 ^       svn+ssh                   ||
                 |        \                   REST interface
                 |         \    +---------+        /\   /\
                 '--------------| Nagios  |        ||   ||
                   /            | Worker  |        ||   Web GUI
                  /             +---------+        ||
           Configuration            /\         Automation
           is sent to the           ||
           Master Nagios      REST interface
                                    /\   /\
                                    ||   ||
                                    ||   Web GUI
                                    ||
                                Automation

Nagrestconf components

Program	Language	Description
rest/index.php	PHP	Provides the REST interface and calls 'nagctl'.
'nagctl'	Bash	Writes the CSV .setup files and calls 'csv2nag'.
'csv2nag'	Bash	Writes the Nagios .cfg object files
'restart_nagios'	Bash	Called periodically by cron.
'slc_configure'	Bash	For initial configuration.
nagrestconf/index.php	PHP	A Configuration GUI that uses the REST api.

.8. Requirements

For the Web GUI the following Browsers work: Firefox, Opera, Chrome, Internet Explorer 8, Safari and also the Browsers on Maemo, iPad and Android devices.

Software Requirement	Reason
php	for REST interface and Web GUI. v5.3+ only.
nagios	for checking the configuration. v3+ only.
apache	for serving PHP pages.
subversion	for managing configuration versions.
mod_ssl	for secure communications.
bash	for non-web scripts.
grep	used in the bash scripts.
sed	used in the bash scripts.
gawk	used in the bash scripts.
procmail	for locking with 'lockfile'.

.9. Upgrade

Upgrading from a version < 1.149 to a version >= 1.149

The `command' and `svcdesc' fields are now urlencoded so the `.setup' files need to be converted. Take a backup then do the following, changing the FOLDER variable if necessary.

Note	Only run the following commands ONCE when upgrading to 1.149, otherwise your data will be double-urlencoded!

# Change the FOLDER then copy-paste the rest to the target server.
FOLDER="local"

# Backup the FOLDER
mkdir ~/delme
cp -a /etc/nagios/objects/${FOLDER} ~/delme/

# Set up urlencoding function
urlencode() { arg="$1"; i="0"; while [ "$i" -lt ${#arg} ]; do c=${arg:$i:1}; if [[ "$c" =~ [0-9a-zA-Z_.-] ]]; then echo -n "$c"; elif [[ "$c" = " " ]]; then echo -n "+"; else echo -n "%"; printf "%X" "'$c'"; fi; i=$((i+1)); done; }

# Update the .setup files
FILE="servicesets"
while IFS=, read c1 c2 c3 c4 c5; do echo -n "$c1,$c2,"; urlencode "$c3"; echo -n ","; urlencode "$c4"; echo ",$c5"; done </etc/nagios/objects/${FOLDER}/setup/${FOLDER}_${FILE}.setup >/tmp/${FOLDER}_${FILE}.setup
sed -i "s/%60/%2C/g" /tmp/${FOLDER}_${FILE}.setup
mv -f /tmp/${FOLDER}_${FILE}.setup /etc/nagios/objects/${FOLDER}/setup/${FOLDER}_${FILE}.setup
chown apache: /etc/nagios/objects/${FOLDER}/setup/${FOLDER}_${FILE}.setup
FILE="services"
while IFS=, read c1 c2 c3 c4 c5; do echo -n "$c1,$c2,"; urlencode "$c3"; echo -n ","; urlencode "$c4"; echo ",$c5"; done </etc/nagios/objects/${FOLDER}/setup/${FOLDER}_${FILE}.setup >/tmp/${FOLDER}_${FILE}.setup
sed -i "s/%60/%2C/g" /tmp/${FOLDER}_${FILE}.setup
mv -f /tmp/${FOLDER}_${FILE}.setup /etc/nagios/objects/${FOLDER}/setup/${FOLDER}_${FILE}.setup
chown apache: /etc/nagios/objects/${FOLDER}/setup/${FOLDER}_${FILE}.setup

# Now update nagrestconf

All versions

After the upgrade run `/usr/bin/upgrade_setup_files.sh'. It can be run any number of times and will not harm data if it is run unnecessarily.

.10. Install

.10.1. Prebuilt Packages

Get the relevant RPM for Centos/Redhat from Sourceforge at:

https://sourceforge.net/projects/nagrestconf/files/

Debian install packages are also available.

.10.2. Install Using Prebuilt Packages

DEBIAN, CENTOS & REDHAT

Do not install on an existing Nagios server. Use the following procedure after freshly installing the Operating System with a minimal set of packages.

Install the prebuilt package downloaded from Sourceforge. For example:

# On Debian:
apt-get update
gdebi nagrestconf_1.157_all.deb

# On Centos/Redhat:
yum install nagrestconf-1.157-1.noarch.rpm

Configure the system:

Use the two helper scripts nagrestconf_install and slc_configure. A sample configuration is also included in the system doc/ directories. For example:
```
# On Centos/Redhat
cd /etc/
mv nagios/ nagios.orig
cp -a /usr/share/doc/nagrestconf-1*/initial-config/ nagios

# On Centos/Redhat/Debian
nagrestconf_install -a
slc_configure --folder=local
```
Test the installation with:
```
# On Centos/Redhat
htpasswd -bc /etc/nagios/htpasswd.users nagiosadmin a_password

# On Centos/Redhat/Debian
bash /usr/share/doc/nagrestconf*/bulk-loading/REST_setup_local.sh
```
Then check that it can be seen and edited in the 'Nagrestconf' GUI by pointing a supported Web Browser at `http://localhost/nagrestconf'.

If something goes wrong then there are configuration files in the directory '/etc/nagrestconf' that might need correcting.

.11. Install From Source

Refer to the debian or redhat packaging files.

.12. REST Examples

Please look at the 'REST_setup_local.sh' script located in the bulk-loading/ document directory. This script shows how a complete monitoring configuration can be made using the REST interface.

More examples are in the sections `REST Commands' and `Object Definitions and Options' below.

.13. Status

All Nagios directives are now implemented in the REST interface. A smaller set of Nagios directives are supported in the Web GUI.

1. COOK BOOK

1.1. Using CURL

TODO

Interesting curl options:

--key KEY
--socks4 IP:PORT
-u USER:PASS

Method 1: Use a `.netrc' file

cat <EnD >>~/.netrc
machine 1.2.3.4 login nagrestconf password thepassword
EnD

cat <EnD >>env1.conf
OPTS="-n"
IP=1.2.3.4
FOLDER="env1"
EnD

Method 2: Don’t Use a `.netrc' file

cat <EnD >>env1.conf
OPTS="-u nagrestconf:thepassword"
IP=1.2.3.4
FOLDER="env1"
EnD

Test

# Load the conf file made above
source env1.conf

# RAW output
curl $OPTS -kn https://$IP/rest/show/hosts'?json=\{"folder":"'$FOLDER'"\}'

# PRETTY output
curl $OPTS -kn https://$IP/rest/show/hosts'?json=\{"folder":"'$FOLDER'"\}' | JSON.sh -b | grep ',"name"'

TODO

1.2. Deleting Environments

There is no way to delete an entire environment using the REST interface. An environment is initially added using 'slc_configure' on the Worker Nagios, and 'dcc_configure' on the Master Nagios.

To disable an environment, or `Folder', so it disappears from Nagios:

Stop the Worker server.

Either shutdown the server or stop Nagios and associated services.
Edit `/etc/nagios/nagios.cfg' on the Master.
- Find the `cfg_dir=' line containing the folder name and comment it out.
- Restart Nagios with `/etc/init.d/nagios restart'.

At this point the environment is disabled and will no longer show in the Master Nagios GUI, but it can be easily re-enabled. However, It may be necessary to completely delete an environment. This could be due to:

An aborted/erroneous Worker installation.
To reinstall from scratch.
Because it is no longer required.

To completely delete an environment:

On the Worker.
- Either shutdown the server or stop Nagios and associated services.
- Delete the `/etc/nagios' directory.
On the Master.
- Find the `cfg_dir=' line, in `/etc/nagios/nagios.cfg', containing the folder name and delete it.
- Restart Nagios with `/etc/init.d/nagios restart'.
- Delete the similarly named directory in `/etc/nagios/repos/folder_name' and `/etc/nagios/objects/folder_name'.

1.3. Export Service Sets

Service sets can be really useful for automation but there is no `import' or `export' feature. It’s easy to create service sets in the GUI, but how can they be exported?

Solution 1: Copy the `.setup' file

This will work but bypasses REST and introduces the risk of making mistakes, such as incorrect file permissions, or accidental overwrites etc., but is easier than the REST method.

Steps:

Simply copy the `/etc/nagios/objects/<FOLDER>/setup/<FOLDER>_servicesets.setup' file to the other server, changing the name of the file to match the new FOLDER.

Ensure the file is owned by the user that runs Apache, then view and apply using the nagrestconf GUI.

Solution 2: Export to a file and use REST

This has the additional benefit of being able to update many servers from a central location and allows REST to check each entry before adding.

Steps:

Run the following command on the Nagios Worker that holds the service sets that need exporting, changing the FOLDER variable only:

FOLDER="local"; FILE="/etc/nagios/objects/$FOLDER/setup/${FOLDER}_servicesets.setup"; \
( echo "N=-1"; cat $FILE | while IFS=, read a b c d e; do echo $a; done | sort -u | \
while read a; do echo -en "serviceset_name[++N]=\"$a\"\nserviceset_svctemplate[N]="; \
echo -e "\"std_stmpl\"\nserviceset[N]='"; grep "^$a," $FILE | while IFS=, read a1 b1 c1 \
d1 e1; do echo '\"'"$c1"'\",\"svcdesc\":\"'"$d1"'\",\"template\":\"'"$b1"'\"'; done; echo "'"; \
done ) | sed 's/%22/%5C%22/g' >~/script_vars

The bash command above creates configuration variables that can appended to a configuration script so copy `~/script_vars' to a linux box.

On the linux box create a configuration file and append `~/script_vars' to it, but change `MASTER_NAGIOS_IP' to the IP address of the Master Nagios:

# Go to the home directory
cd

# Create a configuration stub
cat <<EnD >worker.conf
# CURL OPTS
OPTS="-u nagrestconf:a_password"

# IP: The ip address of the remote worker
IP=MASTER_NAGIOS_IP

# FOLDER: the folder name to work in on the remote worker
FOLDER="pvlive"

# DELETE: 1 - delete existing config, 0 - don't
DELETE=1

EnD

# Append the generated service set config
cat ~/script_vars >>worker.conf

Now apply the configuration to the remote Nagios Worker using a script:

cat <<EnD >replace_servicesets.sh
#!/bin/bash
# Uncomment the following line to show the commands without running them.
#curl() { :; }
[[ -z $1 ]] && {
    echo "Usage: `basename $0` CONFFILE"
    exit 0
}
[[ ! -r $1 ]] && {
    echo "$1 unreadable."
    exit 0
}
. $1
if [[ $DELETE -eq 1 ]]; then
echo "-----------------------------------------------------------"
echo "- Delete EVERYTHING"
echo "-----------------------------------------------------------"
echo
    echo curl $OPTS  -knX POST \
        -d "'json={\"folder\":\"$FOLDER\", \"name\":\".*\",
                  \"svcdesc\":\".*\"}'" \
        https://${IP}/rest/delete/servicesets
    curl $OPTS  -knX POST \
        -d "json={\"folder\":\"$FOLDER\", \"name\":\".*\",
                  \"svcdesc\":\".*\"}" \
        https://${IP}/rest/delete/servicesets
    echo
fi
echo
echo "-----------------------------------------------------------"
echo "- Add Service Sets"
echo "-----------------------------------------------------------"
echo
for i in `seq 0 $((${#serviceset[*]}-1))`; do
    while read j; do
        [[ -z $j || $j == "#"* ]] && continue
        # Allow use of a custom service template
        if ( echo "$i" | grep -qs "template\":" ); then
        echo curl $OPTS  -knX POST \
            -d "'json={\"folder\":\"$FOLDER\",
            \"name\":\"${serviceset_name[$i]}\",
            \"command\":$j}'" https://${IP}/rest/add/servicesets
        curl $OPTS  -knX POST \
            -d "json={\"folder\":\"$FOLDER\",
            \"name\":\"${serviceset_name[$i]}\",
            \"command\":$j}" https://${IP}/rest/add/servicesets
        else
        echo curl $OPTS  -knX POST \
            -d "'json={\"folder\":\"$FOLDER\",
            \"name\":\"${serviceset_name[$i]}\",
            \"template\":\"${serviceset_svctemplate[$i]}\",
            \"command\":$j}'" https://${IP}/rest/add/servicesets
        curl $OPTS  -knX POST \
            -d "json={\"folder\":\"$FOLDER\",
            \"name\":\"${serviceset_name[$i]}\",
            \"template\":\"${serviceset_svctemplate[$i]}\",
            \"command\":$j}" https://${IP}/rest/add/servicesets
        fi
        echo
    done < <( echo "${serviceset[$i]}" | sed "s/qUoTe/'/g" )
done
echo
EnD

# Make it runnable
chmod +x replace_servicesets.sh

# And, run it...
./replace_servicesets.sh worker.conf

The progress can be watched by refreshing the `Service Sets' page in the nagrestconf GUI on the remote worker.

2. WALK-THROUGHS

2.1. Single Server from Scratch (Redhat/Centos 5)

These instructions are for creating a single, stand-alone, Nagios server that will be configured using nagrestconf. On modest hardware it should be able to monitor up to around 500 servers.

The server can be created in a partitioned system using a chroot/systemd-nspawn/lxc environment if necessary, for production or test purposes.

First, install the Centos/RedHat 5.x operating system, then:

Set up Yum to use the EPEL and smorg repositories:

wget -O - http://www.smorg.co.uk/repo/stable/rhel5/smorg.repo > /etc/yum.repos.d/smorg.repo
rpm -ivh http://mirror.bytemark.co.uk/fedora/epel/5/i386/epel-release-5-4.noarch.rpm

Install all required software:

yum install nagrestconf nagios-www

Optionally bulk-install plugins (with the check_any patch included):

yum install smorg-nagios-plugins smorg-nagios-plugins-extra smorg-nrpe smorg-nrpe-plugin

Create the base Nagios configuration from the nagrestconf sample:

cd /etc/
mv nagios/ nagios.dist
cp -a /usr/share/doc/nagrestconf-1*/initial-config/ nagios
nagrestconf_install -a
slc_configure --folder=local

Create a test configuration using REST:

bash /usr/share/doc/nagrestconf-1.*/bulk-loading/REST_setup_local.sh

Manually restart Nagios (in case crond is not running):

rm /tmp/nagios_restart_request
/usr/bin/restart_nagios

Create a Nagios password:

htpasswd -bc /etc/nagios/htpasswd.users nagiosadmin a_decent_password
/etc/init.d/httpd restart

Now connect to http://127.0.0.1/nagrestconf and configure the server. Use ssh port forwarding to connect to the nagrestconf GUI if necessary, or configure Apache in `/etc/httpd/conf.d/nagrestconf.conf'.

2.2. Distributed Monitoring from Scratch

TODO - incomplete/unchecked…

In this scenario, nagrestconf provides the `configuration sync' component mentioned in the mod_gearman documentation, Distributed Setup With Remote Scheduler, using the dup_server option. For historical reference the dup_server option was originally added to mod_gearman by the author of nagrestconf.

Setting up a distributed environment involves:

Choosing short `folder' names for each environment.

Each Nagios Worker will host a single environment in a single `folder'. The Nagios Master will prefix many items with the `folder' name, for example, all host group names will be prefixed with the `folder' name, and this will be shown in the Nagios GUI on the Master Nagios. For this reason try to keep `folder' names as short as possible.
Building the Master Nagios.
- Building the Master Nagios.
  
  OR
- Building the Master Nagios in a Chroot
Building the Worker Nagios (repeat as necessary).

2.2.1. Building the Master Nagios

TODO - incomplete/unchecked…

The backup and high-availability features of a virtual infrastructure could allow for a single Master Nagios.

                  IP x                  IP x
                    /                      \
               |___/                        \___|
               |                                |  results are sent to the master nagios
               |   Thruk GUI could be used to   |  servers using the gearman protocol
               |   provide an enhanced but      |             /
               |   familiar nagios GUI          |       |    /
 Client   ==>  |              \                 |       +---<-----< nagios worker 1 >
 access   ==>  |        +--------------+        |       |
 to the   ==>  |        | Master       |        |       +---<-----< nagios worker 2 >
 Web GUI  ==>  |--->----| Nagios       |        |---<---|
               |        |              |        |       +---<-----< nagios worker .. >
               |        |              |---<----|       |
               |        +--------------+        |       +---<-----< nagios worker N >
               |                                |       |       \
               |                                |                \
               |                                |   nagrestconf sends configuration to
               |                                |   master nagios using subversion
                                                    mirroring.

The Worker Nagios, which sends the service check results to the Master Nagios, needs to be created. Building the Worker consists of four main steps:

Install software
Test the installed software
Configure Apache
Configure the system

Install software

Set up Yum to use the EPEL and smorg repositories:

wget -O - http://www.smorg.co.uk/repo/stable/rhel5/smorg.repo > /etc/yum.repos.d/smorg.repo
rpm -ivh http://mirror.bytemark.co.uk/fedora/epel/5/i386/epel-release-5-4.noarch.rpm

Log on to the new Nagios virtual machine and install the software.

ssh user@$NEWSERVER
sudo su -
yum install nagrestconf smorg-gearmand mod_gearman nagios-www \
            smorg-nagios-plugins smorg-nagios-plugins-extra \
            smorg-nrpe smorg-nrpe-plugin nsca pnp4nagios \
            php53-gd mk-livestatus

Test the Installed Software

Don’t skip this step as it also sets up some files ready for the `real' install later on.

Make a brand new Nagios configuration using the nagrestconf sample.

cd /etc/
mv nagios/ nagios.dist
cp -a /usr/share/doc/nagrestconf-1*/initial-config/ nagios
nagrestconf_install -a --dcc
slc_configure --folder=local

Create a simple test configuration using REST from the example in the nagrestconf docs.

bash /usr/share/doc/nagrestconf-1.*/bulk-loading/REST_setup_local.sh

Add a nagiosadmin user with password set to nagiosadmin. This is just for testing.

htpasswd -bc /etc/nagios/htpasswd.users nagiosadmin nagiosadmin

And now allow anyone to connect without authenticating.

sed -i 's/\([[:space:]]*\)\(Allow from .*\)/\1#\2\n\1Allow from all/' /etc/httpd/conf.d/nagrestconf.conf
/etc/init.d/httpd restart

Connect to http://NEWSERVER/nagrestconf/ using a Web Browser and the nagrestconf GUI should be shown with two server entries and a fully working test configuration.

Connect to http://NEWSERVER/nagios and check that it works, using the user nagiosadmin with password nagiosadmin.

Once nagios and nagrestconf are verified working continue to the next section.

Configure Apache

This is an example HTTP daemon configuration to restrict access to secure HTTP with Basic authentication only.

cat >/etc/httpd/conf.d/nagios.conf <<EnD
ScriptAlias /nagios/cgi-bin "/usr/lib64/nagios/cgi"

<Directory "/usr/lib64/nagios/cgi">
   SSLRequireSSL
   Options ExecCGI
   AllowOverride None
   Order allow,deny
   Allow from all
#  Order deny,allow
#  Deny from all
#  Allow from 127.0.0.1
   AuthName "Nagios Access"
   AuthType Basic
   AuthUserFile /etc/nagios/htpasswd.users
   Require valid-user
</Directory>

Alias /nagios "/usr/share/nagios"

<Directory "/usr/share/nagios">
   SSLRequireSSL
   Options None
   AllowOverride None
   Order allow,deny
   Allow from all
#  Order deny,allow
#  Deny from all
#  Allow from 127.0.0.1
   AuthName "Nagios Access"
   AuthType Basic
   AuthUserFile /etc/nagios/htpasswd.users
   Require valid-user
</Directory>
EnD
cat >/etc/httpd/conf.d/nagrestconf.conf <<EnD
Alias /nagrestconf "/usr/share/nagrestconf/htdocs/nagrestconf"

<Directory /usr/share/nagrestconf/htdocs/nagrestconf/>

  SSLRequireSSL

  # Only allow from the local host
  #Order deny,allow
  #Deny from all
  #Allow from 127.0.0.1

  AllowOverride All

  # Require authentication
  AuthName "Nagrestconf Access"
  AuthType Basic
  AuthUserFile /etc/nagios/nagrestconf.users
  Require valid-user

</Directory>
EnD
cat >/etc/httpd/conf.d/rest.conf <<EnD
Alias /rest /usr/share/nagrestconf/htdocs/rest

<Directory /usr/share/nagrestconf/htdocs/rest/>

  SSLRequireSSL

  # Only allow from the local host
  #Order deny,allow
  #Deny from all
  #Allow from 127.0.0.1

  AllowOverride All

  # Require authentication
  AuthName "REST Access"
  AuthType Basic
  AuthUserFile /etc/nagios/rest.users
  Require valid-user

</Directory>
EnD

Activate the new httpd configuration

/etc/init.d/httpd restart

Configure the system

Delete the 'local' configuration created previously and copy the nagrestconf example configuration again.

/etc/init.d/nagios stop
cd /etc
rm -rf nagios
cp -av /usr/share/doc/nagrestconf-1*/initial-config.dcc/ nagios

Optionally create a new `/etc/nagios/cgi.cfg' - this allows any authenticated to use the gui in read/write mode, except the `nagios' user, who has read-only access.

cat >/etc/nagios/cgi.cfg <<EnD
main_config_file=/etc/nagios/nagios.cfg
physical_html_path=/usr/share/nagios
url_html_path=/nagios
show_context_help=0
use_pending_states=1
use_authentication=1
use_ssl_authentication=0
authorized_for_system_information=nagiosadmin
authorized_for_configuration_information=nagiosadmin
authorized_for_system_commands=nagiosadmin
authorized_for_all_services=*
authorized_for_all_hosts=*
authorized_for_all_service_commands=*
authorized_for_all_host_commands=*
authorized_for_read_only=nagios
default_statusmap_layout=5
default_statuswrl_layout=4
ping_syntax=/bin/ping -n -U -c 5 $HOSTADDRESS$
refresh_rate=90
result_limit=100
escape_html_tags=0
action_url_target=_blank
notes_url_target=_blank
lock_author_names=1
EnD

Comment out existing livestatus broker_module line and add a new one.

sed -n 's/\(broker_module=.*livestatus\.o.*\)/#\1/p' /etc/nagios/nagios.cfg
echo 'broker_module=/usr/lib64/mk-livestatus/livestatus.o /var/log/nagios/rw/live' \
    >>/etc/nagios/nagios.cfg

Comment out existing broker_module lines and append new lines.

# LIVESTATUS
sed -i 's/\(broker_module=.*livestatus\.o.*\)/#\1/' /etc/nagios/nagios.cfg
# MOD_GEARMAN
sed -i 's/\(broker_module=.*mod_gearman\.o.*\)/#\1/' /etc/nagios/nagios.cfg
echo 'broker_module=/usr/lib64/mod_gearman/mod_gearman.o config=/etc/mod_gearman/mod_gearman_neb.conf' \
    >>/etc/nagios/nagios.cfg

Mod_gearman adjustments (Change 'the_shared_key' to the correct key).

sed -i 's/^key=.*/key=the_shared_key/' \
    /etc/mod_gearman/mod_gearman_neb.conf \
    /etc/mod_gearman/mod_gearman_worker.conf
sed -i 's/^eventhandler=.*/eventhandler=no/' \
    /etc/mod_gearman/mod_gearman_neb.conf
sed -i 's/^services=.*/services=no/' \
    /etc/mod_gearman/mod_gearman_neb.conf
sed -i 's/^hosts=.*/hosts=no/' \
    /etc/mod_gearman/mod_gearman_neb.conf

Add the initial users.

htpasswd -c /etc/nagios/rest.users nagrestconf
htpasswd -c /etc/nagios/htpasswd.users nagiosadmin
htpasswd -b /etc/nagios/htpasswd.users nagios nagios
htpasswd -c /etc/nagios/nagrestconf.users your_userid

Make sure things are set to start up on initial boot.

chkconfig nrpe on
chkconfig gearmand on
chkconfig nagios on
chkconfig httpd on
chkconfig mod_gearman_worker off

Configure as a Nagios Master.

sed -i 's/\(^#*DCC=.*\)/\DCC=1/' /etc/nagrestconf/csv2nag.conf

Restart everything.

/etc/init.d/httpd restart
/etc/init.d/gearmand restart
/etc/init.d/mod_gearman_worker stop
/etc/init.d/nagios restart

Final Steps

Due to the change in security settings the nagrestconf GUI will not work, and '/etc/nagrestconf/nagrestconf.ini' will need editing. Edit 'nagrestconf.ini' and check that the nagrestconf GUI works.

Check that the following crontabs are present using 'crontab -l'.

* * * * * /usr/bin/update_nagios
*/10 * * * * /usr/bin/auto_reschedule_nagios_check

Ensure the RPM added the extra sudoers entries to /etc/sudoers:

Defaults:%nagios !requiretty
%nagios ALL = NOPASSWD: /usr/sbin/nagios -v *, /usr/bin/csv2nag -y all

Continue on to `Building the Worker Nagios (Redhat/Centos 5)' below to complete the configuration.

2.2.2. Building the Master Nagios in a Chroot

When installed on physical hardware, a `chroot’ed system could simplify high-availability failover for the Master Nagios - A shared disk, or DRBD, could be used to protect against hardware failure.

              _.-----._
            .- shared  -.
            |-_ disk  _-|
            `._~-----~_.'
              |"-----"|
              |       X
    +----------+    +----------+
    | Master   |    | Failover |
    | Nagios   |----| Partner  |
    |          |    |          |
    +----------+    +----------+
    ____________________________ IP x
        ^
        |
   check results
        |              +------+
        |     /     +-------+ |
        '--<-|   +--------+ | |   Worker Nagios servers
              \  | Worker | |-+   at other Data Centres.
                 | Nagios |-+
                 +--------+

   IP x - An IP address for use by the Master or Failover

TODO

Continue on to `Building the Worker Nagios (Redhat/Centos 5)' below to complete the configuration.

2.2.3. Building the Worker Nagios (Redhat/Centos 5)

The Worker Nagios, which sends the service check results to the Master Nagios, needs to be created. Building the Worker consists of four main steps:

Install software
Test the installed software
Configure Apache
Configure the system

Install software

Set up Yum to use the EPEL and smorg repositories:

wget -O - http://www.smorg.co.uk/repo/stable/rhel5/smorg.repo > /etc/yum.repos.d/smorg.repo
rpm -ivh http://mirror.bytemark.co.uk/fedora/epel/5/i386/epel-release-5-4.noarch.rpm

Log on to the new Nagios virtual machine and install the software.

ssh user@$NEWSERVER
sudo su -
yum install nagrestconf smorg-gearmand-server mod_gearman nagios-www \
            smorg-nagios-plugins smorg-nagios-plugins-extra \
            smorg-nrpe smorg-nrpe-plugin MySQL-shared-compat

Test the Installed Software

Don’t skip this step as it also sets up some files ready for the `real' install later on.

Make a brand new Nagios configuration using the nagrestconf sample.

cd /etc/
mv nagios/ nagios.dist
cp -a /usr/share/doc/nagrestconf-1*/initial-config/ nagios
nagrestconf_install -a
slc_configure --folder=local

Create a simple test configuration using REST from the example in the nagrestconf docs.

bash /usr/share/doc/nagrestconf-1.*/bulk-loading/REST_setup_local.sh

Add a nagiosadmin user with password set to nagiosadmin. This is just for testing.

htpasswd -bc /etc/nagios/htpasswd.users nagiosadmin nagiosadmin

And now allow anyone to connect without authenticating.

sed -i 's/\([[:space:]]*\)\(Allow from .*\)/\1#\2\n\1Allow from all/' /etc/httpd/conf.d/nagrestconf.conf
/etc/init.d/httpd restart

Connect to http://NEWSERVER/nagrestconf/ using a Web Browser and the nagrestconf GUI should be shown with two server entries and a fully working test configuration.

Connect to http://NEWSERVER/nagios and check that it works, using the user nagiosadmin with password nagiosadmin.

Once nagios and nagrestconf are verified working continue to the next section.

Configure Apache

This is an example HTTP daemon configuration to restrict access to secure HTTP with Basic authentication only.

cat >/etc/httpd/conf.d/nagios.conf <<EnD
ScriptAlias /nagios/cgi-bin "/usr/lib64/nagios/cgi"

<Directory "/usr/lib64/nagios/cgi">
   SSLRequireSSL
   Options ExecCGI
   AllowOverride None
   Order allow,deny
   Allow from all
#  Order deny,allow
#  Deny from all
#  Allow from 127.0.0.1
   AuthName "Nagios Access"
   AuthType Basic
   AuthUserFile /etc/nagios/htpasswd.users
   Require valid-user
</Directory>

Alias /nagios "/usr/share/nagios"

<Directory "/usr/share/nagios">
   SSLRequireSSL
   Options None
   AllowOverride None
   Order allow,deny
   Allow from all
#  Order deny,allow
#  Deny from all
#  Allow from 127.0.0.1
   AuthName "Nagios Access"
   AuthType Basic
   AuthUserFile /etc/nagios/htpasswd.users
   Require valid-user
</Directory>
EnD
cat >/etc/httpd/conf.d/nagrestconf.conf <<EnD
Alias /nagrestconf "/usr/share/nagrestconf/htdocs/nagrestconf"

<Directory /usr/share/nagrestconf/htdocs/nagrestconf/>

  SSLRequireSSL

  # Only allow from the local host
  #Order deny,allow
  #Deny from all
  #Allow from 127.0.0.1

  AllowOverride All

  # Require authentication
  AuthName "Nagrestconf Access"
  AuthType Basic
  AuthUserFile /etc/nagios/nagrestconf.users
  Require valid-user

</Directory>
EnD
cat >/etc/httpd/conf.d/rest.conf <<EnD
Alias /rest /usr/share/nagrestconf/htdocs/rest

<Directory /usr/share/nagrestconf/htdocs/rest/>

  SSLRequireSSL

  # Only allow from the local host
  #Order deny,allow
  #Deny from all
  #Allow from 127.0.0.1

  AllowOverride All

  # Require authentication
  AuthName "REST Access"
  AuthType Basic
  AuthUserFile /etc/nagios/rest.users
  Require valid-user

</Directory>
EnD

Activate the new httpd configuration

/etc/init.d/httpd restart

Configure the system

Delete the 'local' configuration created previously and copy the nagrestconf example configuration again.

/etc/init.d/nagios stop
cd /etc
rm -rf nagios
cp -av /usr/share/doc/nagrestconf-1*/initial-config/ nagios

Optionally create a new `/etc/nagios/cgi.cfg' - this allows any authenticated to use the gui in read/write mode, except the `nagios' user, who has read-only access.

cat >/etc/nagios/cgi.cfg <<EnD
main_config_file=/etc/nagios/nagios.cfg
physical_html_path=/usr/share/nagios
url_html_path=/nagios
show_context_help=0
use_pending_states=1
use_authentication=1
use_ssl_authentication=0
authorized_for_system_information=nagiosadmin
authorized_for_configuration_information=nagiosadmin
authorized_for_system_commands=nagiosadmin
authorized_for_all_services=*
authorized_for_all_hosts=*
authorized_for_all_service_commands=*
authorized_for_all_host_commands=*
authorized_for_read_only=nagios
default_statusmap_layout=5
default_statuswrl_layout=4
ping_syntax=/bin/ping -n -U -c 5 $HOSTADDRESS$
refresh_rate=90
result_limit=100
escape_html_tags=0
action_url_target=_blank
notes_url_target=_blank
lock_author_names=1
EnD

Comment out existing broker_module lines and append new lines.

# LIVESTATUS
sed -i 's/\(broker_module=.*livestatus\.o.*\)/#\1/' /etc/nagios/nagios.cfg
# MOD_GEARMAN
sed -i 's/\(broker_module=.*mod_gearman\.o.*\)/#\1/' /etc/nagios/nagios.cfg
echo 'broker_module=/usr/lib64/mod_gearman/mod_gearman.o config=/etc/mod_gearman/mod_gearman_neb.conf' \
    >>/etc/nagios/nagios.cfg
# PNP4NAGIOS
sed -i 's/\(broker_module=.*npcdmod\.o.*\)/#\1/' /etc/nagios/nagios.cfg

Mod_gearman adjustments (Change 'the_shared_key' to the correct key).

sed -i 's/^key=.*/key=the_shared_key/' \
    /etc/mod_gearman/mod_gearman_neb.conf \
    /etc/mod_gearman/mod_gearman_worker.conf

Add the initial users.

htpasswd -c /etc/nagios/rest.users nagrestconf
htpasswd -c /etc/nagios/htpasswd.users nagiosadmin
htpasswd -b /etc/nagios/htpasswd.users nagios nagios
htpasswd -c /etc/nagios/nagrestconf.users your_userid

Make sure things are set to start up on initial boot.

chkconfig nrpe on
chkconfig gearmand on
chkconfig mod_gearman_worker on
chkconfig nagios on
chkconfig httpd on

Point the worker at the Master Nagios. Change `MASTER_NAGIOS_IP' to the IP address of the Master Nagios.

MASTER_IP_ADDR=MASTER_NAGIOS_IP
sed -i 's/\(^#dupserver=.*\)/\1\ndupserver=$MASTER_IP_ADDR:4730/' /etc/mod_gearman/mod_gearman_worker.conf
sed -i 's/\(^#dcc=.*\)/\1\ndcc=$MASTER_IP_ADDR/' /etc/nagrestconf/restart_nagios.conf
/etc/init.d/mod_gearman_worker restart

Optional - If the Master Nagios is running in a chroot allow svn and ssh to use the chroot port.

# ONLY DO THIS IF THE MASTER IS IN A CHROOT
# Add 'tun1 = ssh -p 2222' to the '[tunnels]' section in '~/.subversion/config'.
cat <<EnD >>/etc/nagrestconf/restart_nagios.conf
SSH=tun1
SSH_OPTS="-p 2222"
EnD

Make sure auto-login works. For security, only a limited number of commands should be allowed to be executed using the svnsync account on the Nagios Master.

ssh -p 2222 svnsync@MASTER_NAGIOS ls /

A root directory listing MUST succeed before running slc_configure below.

Log onto the Master Nagios normally as root now and run the following code, supplying the new folder (environment) name when asked, then log out.

chroot /var/nagios dcc_configure
sed -i 's/\(<Location.*\/thruk>\)/\1\n    SSLOptions +FakeBasicAuth +StdEnvVars\n    SSLRequireSSL/' \
    /var/nagios/etc/httpd/conf.d/thruk.conf

Go back to the new Nagios Worker.

Add the new environment supplying the new folder (environment) name when asked.

slc_configure --usedcc

Set up all the custom service-sets, contacts, etc. in a customised `REST_setup_local.sh' script then run it. A few variables at the top of the script will need changing now that extra security has been added.

cd
bash ./REST_setup_local.sh

Restart everything.

/etc/init.d/httpd restart
/etc/init.d/gearmand restart
/etc/init.d/mod_gearman_worker restart
/etc/init.d/nagios restart

Final Steps

Due to the change in security settings the nagrestconf GUI will not work, and '/etc/nagrestconf/nagrestconf.ini' will need editing. Edit 'nagrestconf.ini' and check that the nagrestconf GUI works.

Check that the following crontabs are present using 'crontab -l'.

* * * * * /usr/bin/test -e /tmp/nagios_restart_request && ( /bin/rm /tmp/nagios_restart_request; /usr/bin/restart_nagios; )
*/10 * * * * /usr/bin/auto_reschedule_nagios_check

Ensure the RPM added the extra sudoers entries to /etc/sudoers:

Defaults:%nagios !requiretty
%nagios ALL = NOPASSWD: /usr/sbin/nagios -v *, /usr/bin/csv2nag -y all

2.3. Puppet Integration

TODO - For ideas see: nagrestconf-from-puppet-yaml

3. TROUBLE-SHOOTING

3.1. Using in Linux Containers, Systemd-nspawn or Chroots

Ensure some dev files exist:

ln -s /proc/self/fd /dev/fd
cd /dev
MAKEDEV stdin
MAKEDEV stdout
MAKEDEV stderr

3.2. Gotchas

TODO - GUI won’t allow some changes to the Nagios configuration where dependencies are used - have to remove them using REST first.

4. REFERENCE

4.1. REST Commands

The URL is in the general form 'https://<HOST>/rest/<COMMAND>/<COMMANDARG>'.

Valid COMMANDS are check, show, add, delete, modify, restart, apply and pipecmd.

COMMAND options are added to the HTTP GET or POST query string in the form 'json={"option":"value"[,"option":"value"]…}'.

GET requests are for operations that don’t modify data.

https://<HOST>/rest/
- check/
  - nagiosconfig json={"folder":"<name>"[,"verbose":"true"]}
- show/
  - hosttemplates json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - servicetemplates json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - hosts json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - services json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - servicesets json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - servicegroups json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - hostgroups json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - contacts json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - contactgroups json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - timeperiods json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - commands json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - servicedeps json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - hostdeps json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - serviceesc json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - hostesc json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - serviceextinfo json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}
  - hostextinfo json={"folder":"<name>"[,"filter":"<regex>"][,"column":"<integer>"][,"<option>":"<value>"]*}

POST requests are for operations that might modify data or state.

https://<HOST>/rest/
- add/
  - hosttemplates json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicetemplates json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hosts json={"folder":"<name>"[,"<option>":"<value>"]*}
  - services json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicesets json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicegroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostgroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - contacts json={"folder":"<name>"[,"<option>":"<value>"]*}
  - contactgroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - timeperiods json={"folder":"<name>"[,"<option>":"<value>"]*}
  - commands json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicedeps json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostdeps json={"folder":"<name>"[,"<option>":"<value>"]*}
  - serviceesc json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostesc json={"folder":"<name>"[,"<option>":"<value>"]*}
  - serviceextinfo json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostextinfo json={"folder":"<name>"[,"<option>":"<value>"]*}
- delete/
  - hosttemplates json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicetemplates json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hosts json={"folder":"<name>"[,"<option>":"<value>"]*}
  - services json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicesets json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicegroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostgroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - contacts json={"folder":"<name>"[,"<option>":"<value>"]*}
  - contactgroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - timeperiods json={"folder":"<name>"[,"<option>":"<value>"]*}
  - commands json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicedeps json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostdeps json={"folder":"<name>"[,"<option>":"<value>"]*}
  - serviceesc json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostesc json={"folder":"<name>"[,"<option>":"<value>"]*}
  - serviceextinfo json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostextinfo json={"folder":"<name>"[,"<option>":"<value>"]*}
- modify/
  - hosttemplates json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicetemplates json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hosts json={"folder":"<name>"[,"<option>":"<value>"]*}
  - services json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicesets json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicegroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostgroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - contacts json={"folder":"<name>"[,"<option>":"<value>"]*}
  - contactgroups json={"folder":"<name>"[,"<option>":"<value>"]*}
  - timeperiods json={"folder":"<name>"[,"<option>":"<value>"]*}
  - commands json={"folder":"<name>"[,"<option>":"<value>"]*}
  - servicedeps json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostdeps json={"folder":"<name>"[,"<option>":"<value>"]*}
  - serviceesc json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostesc json={"folder":"<name>"[,"<option>":"<value>"]*}
  - serviceextinfo json={"folder":"<name>"[,"<option>":"<value>"]*}
  - hostextinfo json={"folder":"<name>"[,"<option>":"<value>"]*}
- restart/
  - nagios json={"folder":"<name>"}
- apply/
  - nagiosconfig json={"folder":"<name>"[,"verbose":"true"]}
  - nagioslastgoodconfig json={"folder":"<name>"}
- pipecmd/
  - enablehostsvcchecks json={"folder":"<name>","name":"<hostname>}
  - disablehostsvcchecks json={"folder":"<name>","name":"<hostname>" [,"comment","<comment>"]}
  - enablesvccheck json={"folder":"<name>","name":"<hostname>, "svcdesc":"<Service Description>" [,"comment","<comment>"]}
  - disablesvccheck json={"folder":"<name>","name":"<hostname>" "svcdesc":"<Service Description>" [,"comment","<comment>"]}
  - schedhstdowntime json={"folder":"<name>","name":"<hostname>,"starttime":"<unixtime>","endtime":"unixtime" [,"flexible":"<0|1>","duration":"<minutes>","author":"<name>","comment","<comment>"]}
  - delhstdowntime json={"folder":"<name>","name":"<hostname>,"svcdesc":"<Service Description>" [,"comment","<comment>"]}
  - schedhstsvcdowntime json={"folder":"<name>","name":"<hostname>","svcdesc":"<Service Description>" [,"comment","<comment>"]}
  - delhstsvcdowntime json={"folder":"<name>","name":"<hostname>","svcdesc":"<Service Description>" [,"comment","<comment>"]}
  - schedsvcdowntime json={"folder":"<name>","name":"<hostname>","svcdesc":"<Service Description>" [,"comment","<comment>"]}
  - delsvcdowntime json={"folder":"<name>","name":"<hostname>","svcdesc":"<Service Description>" [,"comment","<comment>"]}

4.2. Object Definitions and Options

Refer to the Nagios object definitions documentation for more information about individual options in the following tables. It can be found at the following URL:

http://nagios.sourceforge.net/docs/3_0/objectdefinitions.html

4.2.1. Listings of all Valid REST Options

The `Column' number in the following tables relate to the column number in the database files on the nagios server. These are comma delimited files used by 'csv2nag' to create the nagios configuration files.

Key for the `Flags' column:

\'U' - The option is Unimplemented.
\'R' - A required field.
\'K' - A key field. Required to uniquely identify an entry.
\'L' - A list field. Lists consist of zero or more items separated by spaces.
\'C' - A compound field: <name>|<value>[,<name>|<value>]…
\'X' - Not available in the Web front-end.
\'M' - Name mangling is applied to a passive-only nagios server. (Where the DCC variable is set to `1' in /etc/nagrestconf/csv2nag.conf.)

The `REST variable name' column lists the option names that can be used in the `json=' part of the query. These names are used in place of `<option>' shown in the `Rest Commands' section above.

Note	Many examples use `JSON.sh', which can be found here: https://github.com/dominictarr/JSON.sh

4.2.2. contacts

Column	Description	Flags	REST variable name	Nagios argument name
1.	Contact name	RKM	name	contact_name
2.	Use	RM	use	use
3.	Alias pretty name	R	alias	alias
4.	Email address		emailaddr	email
5.	Service notification period	RM	svcnotifperiod	service_notification_period
6.	Service notification options	LR	svcnotifopts	service_notification_options
7.	Service notification commands	LRM	svcnotifcmds	service_notification_commands
8.	Host notification period	RM	hstnotifperiod	host_notification_period
9.	Host notification options	LR	hstnotifopts	host_notification_options
10.	Host notification commands	LRM	hstnotifcmds	host_notification_commands
11.	Can submit commands		cansubmitcmds	can_submit_commands
12.	Disable	U	disable
13.	Service notification enabled	X	svcnotifenabled	service_notifications_enabled
14.	Host notification enabled	X	hstnotifenabled	host_notifications_enabled
15.	Pager	X	pager	pager
16.	Address1	X	address1	address1
17.	Address2	X	address2	address2
18.	Address3	X	address3	address3
19.	Address4	X	address4	address4
20.	Address5	X	address5	address5
21.	Address6	X	address6	address6
22.	Retain status info	X	retainstatusinfo	retain_status_information
23.	Retain non-status info	X	retainnonstatusinfo	retain_nonstatus_information
24.	Contact groups	XLM	contactgroups	contactgroups

Examples

Show all 'contacts' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/contacts?json=\{"folder":"local"\}' \
| JSON.sh -b

Delete ALL contacts (contacts that are referenced elsewhere in the configuration will not be deleted):

curl -knX POST -d 'json={"folder":"local","name":".*"}' https://127.0.0.1/rest/delete/contacts

Use a loop to add a number of contacts:

CONTACTS="
user1,User One,[email protected]
user2,User Two,[email protected]
"
echo "$CONTACTS" | \
while IFS="," read name alias emailaddr; do
curl -knX POST \
  -d "json={\"folder\":\"local\",
         \"name\":\"$name\",
         \"alias\":\"$alias\",
         \"emailaddr\":\"$emailaddr\",
         \"svcnotifperiod\":\"24x7\",
         \"svcnotifopts\":\"w u c r\",
         \"svcnotifcmds\":\"notify-service-by-email\",
         \"hstnotifperiod\":\"24x7\",
         \"hstnotifopts\":\"d u r\",
         \"hstnotifcmds\":\"notify-host-by-email\",
         \"cansubmitcmds\":\"\"}" \
https://127.0.0.1/rest/add/contacts
done

4.2.3. contactgroups

Column	Description	Flags	REST variable name	Nagios argument name
1.	Contact group name	RKM	name	contactgroup_name
2.	Alias pretty name	R	alias	alias
3.	Members list	RLM	members	members
4.	Disable	U	disable

Examples

Show all 'contactgroups' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/contactgroups?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.4. hosts

Column	Description	Flags	REST variable name	Nagios argument name
1.	Host name	RK	name	host_name
2.	Alias	R	alias	alias
3.	IP Address	R	ipaddress	address
4.	Host Template	RM	template	use
5.	Shown Hostgroup	LM	hostgroup	hostgroups
6.	Contact	LM	contact	contacts
7.	Contact Group	LM	contactgroups	contact_groups
8.	Active checks		activechecks	active_checks_enabled
9.	Service Set		servicesets	N/A
10.	Disable [0,1,2]		disable	N/A
11.	Display name		displayname	display_name
12.	Parents	LXM	parents	parents
13.	Check command	XM	command	check_command
14.	Initial state	X	initialstate	initial_state
15.	Max check attempts		maxcheckattempts	max_check_attempts
16.	Check interval	X	checkinterval	check_interval
17.	Retry interval	X	retryinterval	retry_interval
18.	Passive checks enabled	X	passivechecks	passive_checks_enabled
19.	Check period	XM	checkperiod	check_period
20.	Obsess over host	X	obsessoverhost	obsess_over_host
21.	Check freshness	X	checkfreshness	check_freshness
22.	Freshness threshold	X	freshnessthresh	freshness_threshold
23.	Event handler	X	eventhandler	event_handler
24.	Event handler enabled	X	eventhandlerenabled	event_handler_enabled
25.	Low flap threshold	X	lowflapthresh	low_flap_threshold
26.	High flap threshold	X	highflapthresh	high_flap_threshold
27.	Flap detection enabled	X	flapdetectionenabled	flap_detection_enabled
28.	Flap detection options	LX	flapdetectionoptions	flap_detection_options
29.	Process perf data	X	processperfdata	process_perf_data
30.	Retain status information		retainstatusinfo	retain_status_information
31.	Retain nonstatus information		retainnonstatusinfo	retain_nonstatus_information
32.	Notification interval	X	notifinterval	notification_interval
33.	First notification delay	X	firstnotifdelay	first_notifdelay
34.	Notification period	XM	notifperiod	notification_period
35.	Notification opts	LX	notifopts	notification_options
36.	Notifications enabled	X	notifications_enabled	notifications_enabled
37.	Stalking options	LX	stalkingoptions	stalking_options
38.	Notes	X	notes	notes
39.	Notes url	X	notes_url	notes_url
40.	Icon image	X	icon_image	icon_image
41.	Icon image alt	X	icon_image_alt	icon_image_alt
42.	Vrml image	X	vrml_image	vrml_image
43.	Statusmap image	X	statusmap_image	statusmap_image
44.	2d coords	X	coords2d	2d_coords
45.	3d coords	X	coords3d	3d_coords
46.	Action url	X	action_url	action_url

Examples

Show all hosts and attributes:

curl -kn 'https://127.0.0.1/rest/show/hosts?json=\{"folder":"local"\}' \
| JSON.sh -b

Show only the host names beginning with 'tx':

curl -kn 'https://127.0.0.1/rest/show/hosts?json=\{"folder":"local","filter":"tx.*"\}'
| JSON.sh -b | grep '\[[0-9]\+,0,'

4.2.5. hosttemplates

Column	Description	Flags	REST variable name	Nagios argument name
1.	Name	RKM	name	name
2.	Use	RM	use	use
3.	Contacts	LM	contacts	contacts
4.	Contact groups	LM	contactgroups	contact_groups
5.	Normal check interval	U	normchecki	normchecki
6.	Check interval	R	checkinterval	check_interval
7.	Retry interval	R	retryinterval	retry_interval
8.	Notification period	RM	notifperiod	notification_period
9.	Notification option	L	notifopts	notification_options
10.	Disable	U	disable
11.	Check period	RM	checkperiod	check_period
12.	Max check attempts	R	maxcheckattempts	max_check_attempts
13.	Check command	M	checkcommand	check_command
14.	Notification interval	R	notifinterval	notification_interval
15.	Passive checks enabled	X	passivechecks	passive_checks_enabled
16.	Obsess over host	X	obsessoverhost	obsess_over_host
17.	Check freshness	X	checkfreshness	check_freshness
18.	Freshness threshold	X	freshnessthresh	freshness_threshold
19.	Event handler	X	eventhandler	event_handler
20.	Event handler enabled	X	eventhandlerenabled	event_handler_enabled
21.	Low flap threshold	X	lowflapthresh	low_flap_threshold
22.	High flap threshold	X	highflapthresh	high_flap_threshold
23.	Flap detection enabled	X	flapdetectionenabled	flap_detection_enabled
24.	Flap detection options	LX	flapdetectionoptions	flap_detection_options
25.	Process perf data	X	processperfdata	process_perf_data
26.	Retain status information	X	retainstatusinfo	retain_status_information
27.	Retain nonstatus information	X	retainnonstatusinfo	retain_nonstatus_information
28.	First notification delay	X	firstnotifdelay	first_notifdelay
29.	Notifications enabled	X	notifications_enabled	notifications_enabled
30.	Stalking options	LX	stalkingoptions	stalking_options
31.	Notes	X	notes	notes
32.	Notes url	X	notes_url	notes_url
33.	Icon image	X	icon_image	icon_image
34.	Icon image alt	X	icon_image_alt	icon_image_alt
35.	Vrml image	X	vrml_image	vrml_image
36.	Statusmap image	X	statusmap_image	statusmap_image
37.	2d coords	X	coords2d	2d_coords
38.	3d coords	X	coords3d	3d_coords
39.	Action url	X	action_url	action_url

Examples

Show all 'hosttemplates' and attributes:

curl -kn 'https://127.0.0.1/rest/show/hosttemplates?json=\{"folder":"local"\}' \
| JSON.sh -b

Set the action_url for the host template:

curl -knX POST -d 'json={"folder":"local","name":"std_htmpl",
       "action_url":"/pnp4nagios/graph?host=$HOSTNAME$"}' \
       https://127.0.0.1/rest/modify/hosttemplates

4.2.6. services

Column	Description	Flags	REST variable name	Nagios argument name
1.	Name	RK	name	host_name
2.	Service template	RM	template	use
3.	Service command	RM	command	check_command
4.	Service description	RK	svcdesc	service_description
5.	Service groups	L	svcgroup	servicegroups
6.	Contacts	LM	contacts	contacts
7.	Contact groups	LM	contactgroups	contact_groups
8.	Freshness threshold (auto)*		freshnessthresh	N/A
9.	Active checks enabled		activechecks	active_checks_enabled
10.	Custom variables	C	customvars	N/A
11.	Disable[0,1,2]		disable
12.	Display name	X	displayname	display_name
13.	Is volatile	X	isvolatile	is_volatile
14.	Initial state	X	initialstate	initial_state
15.	Max check attempts		maxcheckattempts	max_check_attempts
16.	Check interval		checkinterval	check_interval
17.	Retry interval		retryinterval	retry_interval
18.	Passive checks enabled		passivechecks	passive_checks_enabled
19.	Check period	XM	checkperiod	check_period
20.	Obsess over service	X	obsessoverservice	obsess_over_service
21.	Freshness threshold (manual)		manfreshnessthresh	freshness_threshold
22.	Check Freshness		checkfreshness	check_freshness
23.	Event handler	X	eventhandler	event_handler
24.	Event handler enabled	X	eventhandlerenabled	event_handler_enabled
25.	Low flap threshold	X	lowflapthresh	low_flap_threshold
26.	High flap threshold	X	highflapthresh	high_flap_threshold
27.	Flap detection enabled	X	flapdetectionenabled	flap_detection_enabled
28.	Flap detection options	LX	flapdetectionoptions	flap_detection_options
29.	Process perf data	X	processperfdata	process_perf_data
30.	Retain status information		retainstatusinfo	retain_status_information
31.	Retain nonstatus information		retainnonstatusinfo	retain_nonstatus_information
32.	Notification interval	X	notifinterval	notification_interval
33.	First notification delay	X	firstnotifdelay	first_notifdelay
34.	Notification period	XM	notifperiod	notification_period
35.	Notification opts	LX	notifopts	notification_options
36.	Notifications enabled	X	notifications_enabled	notifications_enabled
37.	Stalking options	LX	stalkingoptions	stalking_options
38.	Notes	X	notes	notes
39.	Notes url	X	notes_url	notes_url
40.	Action url	X	action_url	action_url
41.	Icon image	X	icon_image	icon_image
42.	Icon image alt	X	icon_image_alt	icon_image_alt
43.	Vrml image	X	vrml_image	vrml_image
44.	Statusmap image	X	statusmap_image	statusmap_image
45.	2d coords	X	coords2d	2d_coords
46.	3d coords	X	coords3d	3d_coords

* Freshness thresh (auto) also sets check_command to no-checks-received, active_checks_enabled to 0 (depending on whether the host is a dcc or not), passive_checks_enabled to 1 and check_freshness to 1. Use manfreshnessthresh to restrict to only setting the freshness_threshold.

Examples

Show all 'services' and attributes:

curl -kn 'https://127.0.0.1/rest/show/services?json=\{"folder":"local"\}' \
| JSON.sh -b

Show all host names that have a 'Disks' service description (column 4)

curl -kn 'https://127.0.0.1/rest/show/services?json=\{"folder":"local","column":"4","filter":"Disks"\}' \
| JSON.sh -b | grep '\[[0-9]\+,0,'

Change a service attribute for every host:

 # Create a list of hosts
 curl -kn 'https://127.0.0.1/rest/show/hosts?json=\{"folder":"local"\}' \
  | JSON.sh -b \
  | sed -n 's/\[[0-9]\+,0,.*][[:space:]]*["]*\([^"]*\).*/\1/p \
  >list1

 # Modify the attribute on each host in a loop
 # All key fields must be supplied - there are two key fields for the 'services' table,
 # name and svcdesc (the host name and service description).
 # In this example the `command' is changed for every host
 cat list1 | while read host; do curl -knX POST -d 'json={"folder":"local",
   "name":"'$host'","svcdesc":"Disk space",
   "command":"check_disk!10%!5%"}' \
 https://127.0.0.1/rest/modify/services; done

4.2.7. servicesets

Column	Description	Flags	REST variable name	Nagios argument name
1.	Serviceset name	RK	name	N/A
2.	Service template	R	template	use
3.	Service command	R	command	check_command
4.	Service description	RK	svcdesc	service_description
5.	Service groups	L	svcgroup	servicegroups
6.	Contacts	L	contacts	contacts
7.	Contact groups	L	contactgroups	contact_groups
8.	Freshness threshold (auto)*		freshnessthresh	N/A
9.	Active checks		activechecks	active_checks_enabled
10.	Custom variables	C	customvars	N/A
11.	Disable	U	disable
12.	Display name	X	displayname	display_name
13.	Is volatile	X	isvolatile	is_volatile
14.	Initial state	X	initialstate	initial_state
15.	Max check attempts	X	maxcheckattempts	max_check_attempts
16.	Check interval	X	checkinterval	check_interval
17.	Retry interval	X	retryinterval	retry_interval
18.	Passive checks enabled	X	passivechecks	passive_checks_enabled
19.	Check period	X	checkperiod	check_period
20.	Obsess over service	X	obsessoverservice	obsess_over_service
21.	Freshness threshold (manual)	X	manfreshnessthresh	freshness_threshold
22.	Check Freshness	X	checkfreshness	check_freshness
23.	Event handler	X	eventhandler	event_handler
24.	Event handler enabled	X	eventhandlerenabled	event_handler_enabled
25.	Low flap threshold	X	lowflapthresh	low_flap_threshold
26.	High flap threshold	X	highflapthresh	high_flap_threshold
27.	Flap detection enabled	X	flapdetectionenabled	flap_detection_enabled
28.	Flap detection options	LX	flapdetectionoptions	flap_detection_options
29.	Process perf data	X	processperfdata	process_perf_data
30.	Retain status information	X	retainstatusinfo	retain_status_information
31.	Retain nonstatus information	X	retainnonstatusinfo	retain_nonstatus_information
32.	Notification interval	X	notifinterval	notification_interval
33.	First notification delay	X	firstnotifdelay	first_notifdelay
34.	Notification period	X	notifperiod	notification_period
35.	Notification opts	LX	notifopts	notification_options
36.	Notifications enabled	X	notifications_enabled	notifications_enabled
37.	Stalking options	LX	stalkingoptions	stalking_options
38.	Notes	X	notes	notes
39.	Notes url	X	notes_url	notes_url
40.	Action url	X	action_url	action_url
41.	Icon image	X	icon_image	icon_image
42.	Icon image alt	X	icon_image_alt	icon_image_alt
43.	Vrml image	X	vrml_image	vrml_image
44.	Statusmap image	X	statusmap_image	statusmap_image
45.	2d coords	X	coords2d	2d_coords
46.	3d coords	X	coords3d	3d_coords

* Freshness thresh (auto) also sets check_command to no-checks-received, active_checks_enabled to 0 (depending on whether the host is a dcc or not), passive_checks_enabled to 1 and check_freshness to 1. Use manfreshnessthresh to restrict to only setting the freshness_threshold.

Examples

Show all 'servicesets' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/servicesets?json=\{"folder":"local"\}' \
| JSON.sh -b

Show only the name of all 'servicesets':

curl -kn 'https://127.0.0.1/rest/show/servicesets?json=\{"folder":"local"\}' \
 | JSON.sh -b \
 | sed -n 's/\[[0-9]\+,0,.*][[:space:]]*["]*\([^"]*\).*/\1/p' \
 | sort -u

Change a serviceset attribute for every serviceset:

 # Create a list of 'servicesets'
 curl -kn 'https://127.0.0.1/rest/show/servicesets?json=\{"folder":"local"\}' \
  | JSON.sh -b \
  | sed -n 's/\[[0-9]\+,0,.*][[:space:]]*["]*\([^"]*\).*/\1/p' \
  | sort -u \
  >list1

 # Modify the attribute on each serviceset in a loop
 # In this example the `command' is changed for every serviceset
 cat ~/list1 | while read name; do curl -knX POST -d 'json={"folder":"local",
  "name":"'$name'",
  "svcdesc":"Disk space",
  "command":"check_disk!10%!5%"}' \
  https://127.0.0.1/rest/modify/servicesets; \
 done

4.2.8. servicetemplates

Column	Description	Flags	REST variable name	Nagios argument name
1.	Name	RKM	name	name
2.	Use	XM	use	use
3.	Contacts	LM	contacts	contacts
4.	Contact groups	LM	contactgroups	contact_groups
5.	Notification options	L	notifopts	notification_options
6.	Check interval	R	checkinterval	check_interval
7.	Normal check interval	U	normchecki	normchecki
8.	Retry interval	R	retryinterval	retry_interval
9.	Notification interval	R	notifinterval	notification_interval
10.	Notification period	RM	notifperiod	notification_period
11.	Disable	U	disable
12.	Check period	RM	checkperiod	check_period
13.	Max check attempts	R	maxcheckattempts	max_check_attempts
14.	Freshness threshold (auto)*		freshnessthresh	N/A
15.	Active checks		activechecks	active_checks_enabled
16.	Custom variables	C	customvars
17.	Is volatile	X	isvolatile	is_volatile
18.	Initial state	X	initialstate	initial_state
19.	Passive checks enabled	X	passivechecks	passive_checks_enabled
20.	Obsess over service	X	obsessoverservice	obsess_over_service
21.	Freshness threshold (manual)	X	manfreshnessthresh	freshness_threshold
22.	Check Freshness	X	checkfreshness	check_freshness
23.	Event handler	X	eventhandler	event_handler
24.	Event handler enabled	X	eventhandlerenabled	event_handler_enabled
25.	Low flap threshold	X	lowflapthresh	low_flap_threshold
26.	High flap threshold	X	highflapthresh	high_flap_threshold
27.	Flap detection enabled	X	flapdetectionenabled	flap_detection_enabled
28.	Flap detection options	LX	flapdetectionoptions	flap_detection_options
29.	Process perf data	X	processperfdata	process_perf_data
30.	Retain status information	X	retainstatusinfo	retain_status_information
31.	Retain nonstatus information	X	retainnonstatusinfo	retain_nonstatus_information
32.	First notification delay	X	firstnotifdelay	first_notifdelay
33.	Notifications enabled	X	notifications_enabled	notifications_enabled
34.	Stalking options	LX	stalkingoptions	stalking_options
35.	Notes	X	notes	notes
36.	Notes url	X	notes_url	notes_url
37.	Action url	X	action_url	action_url
38.	Icon image	X	icon_image	icon_image
39.	Icon image alt	X	icon_image_alt	icon_image_alt
40.	Vrml image	X	vrml_image	vrml_image
41.	Statusmap image	X	statusmap_image	statusmap_image
42.	2d coords	X	coords2d	2d_coords
43.	3d coords	X	coords3d	3d_coords

* Freshness thresh (auto) also sets check_command to no-checks-received, active_checks_enabled to 0 (depending on whether the host is a dcc or not), passive_checks_enabled to 1 and check_freshness to 1. Use manfreshnessthresh to restrict to only setting the freshness_threshold.

Examples

Show all 'servicetemplates' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/servicetemplates?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.9. commands

Column	Description	Flags	REST variable name	Nagios argument name
1.	Command name	RKM	name	command_name
2.	Command line	R	command	command_line
3.	Disable	U	disable	N/A

Examples

Show all 'commands' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/commands?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.10. hostgroups

Column	Description	Flags	REST variable name	Nagios argument name
1.	Hostgroup name	RKM	name	hostgroup_name
2.	Alias	R	alias	alias
3.	Disable		disable	N/A
4.	Members	LX	members	members
5.	Hostgroup members	LXM	hostgroupmembers	hostgroup_members
6.	Notes	X	notes	notes
7.	Notes url	X	notes_url	notes_url
8.	Action url	X	action_url	action_url

Examples

Show all 'hostgroups' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/hostgroups?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.11. servicegroups

Column	Description	Flags	REST variable name	Nagios argument name
1.	Servicegroup name	RK	name	servicegroup_name
2.	Alias	R	alias	alias
3.	Disable	U	disable	N/A
4.	Members	LX	members	members
5.	Servicegroup members	LX	servicegroupmembers	servicegroup_members
6.	Notes	X	notes	notes
7.	Notes url	X	notes_url	notes_url
8.	Action url	X	action_url	action_url

Examples

Show all 'servicegroups' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/servicegroups?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.12. timeperiods

Column	Description	Flags	REST variable name	Nagios argument name
1.	Timeperiod name	RKM	name	timeperiod_name
2.	Alias	R	alias	alias
3.	Freestyle time definition	C	definition
4.	Timeperiod to exclude	LM	exclude	exclude
5.	Disable	U	disable	N/A
6.	Freestyle time exception	CXM	exception

Examples

Show all 'timeperiods' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/timeperiods?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.13. servicedeps

Column	Description	Flags	REST variable name	Nagios argument name
1.	Dependent host name	RKX	dephostname	dependent_host_name
2.	Dependent hostgroup name	KXM	dephostgroupname	dependent_hostgroup_name
3.	Dependent service description	RKX	depsvcdesc	dependent_service_description
4.	Host name	RKX	hostname	host_name
5.	Hostgroup name	KXM	hostgroupname	hostgroup_name
6.	Service description	RKX	svcdesc	service_description
7.	Inherits parent	X	inheritsparent	inherits_parent
8.	Execution failure criteria	LX	execfailcriteria	execution_failure_criteria
9.	Notification failure criteria	LX	notiffailcriteria	notification_failure_criteria
10.	Dependency period	XM	period	dependency_period
11.	Disable	X	disable	N/A

Note	Rows 1,2,4 and 5 are not lists in REST as they are in a Nagios configuration file. One of rows 1 and 2 plus one of rows 4 and 5 are required.

Examples

Show all 'servicedeps' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/servicedeps?json=\{"folder":"local"\}' \
| JSON.sh -b

When a bunch of hosts go down the check latency and number of parallel running jobs increases due to failing checks taking longer to exit. To help alleviate this it might be worth making all services on all hosts depend on the PING service residing on each host. Note that this is a lengthy operation.

# Create a list of host names + services
curl -kn 'https://127.0.0.1/rest/show/services?json=\{"folder":"local"\}' \
| JSON.sh -b | grep '\[[0-9]\+,[03],' | sed 's/^[^ ]\+][[:space:]]*//' | tr -d \" \
| sed '$!N;s/\n/ /' >list

# Exclude PING. (Not strictly necessary as REST will not allow adding the
# circular dependency.)
sed -i '/PING$/d' list

# Use the lists to create the dependencies
# Note that you can't use the much simpler "depsvcdesc":"* !PING", sorry.
while read HNAME SVC; do
curl -knX POST -d 'json={"folder":"local",
       "hostname":"'$HNAME'",
       "svcdesc":"PING",
       "dephostname":"'$HNAME'",
       "depsvcdesc":"'"$SVC"'",
       "execfailcriteria":"w u c"}'
       https://127.0.0.1/rest/add/servicedeps
done < list

4.2.14. hostdeps

Column	Description	Flags	REST variable name	Nagios argument name
1.	Dependent host name	RKX	dephostname	dependent_host_name
2.	Dependent hostgroup name	KXM	dephostgroupname	dependent_hostgroup_name
3.	Host name	RKX	hostname	host_name
4.	Hostgroup name	KXM	hostgroupname	hostgroup_name
5.	Inherits parent	RX	inheritsparent	inherits_parent
6.	Execution failure criteria	LRX	execfailcriteria	execution_failure_criteria
7.	Notification failure criteria	LRX	notiffailcriteria	notification_failure_criteria
8.	Dependency period	RXM	period	dependency_period
9.	Disable	UX	disable	N/A

Note	Columns 1 and 2 are not lists in REST as they are in a Nagios configuration file.

Examples

Show all 'hostdeps' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/hostdeps?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.15. serviceescalation

Column	Description	Flags	REST variable name	Nagios argument name
1.	Host name	KRX	hostname	host_name
2.	Hostgroup name	XM	hostgroupname	hostgroup_name
3.	Service description	KRX	svcdesc	service_description
4.	Contacts	LRXM	contacts	contacts
5.	Contact groups	LRM	contactgroups	contact_groups
6.	First notification	RX	firstnotif	first_notification
7.	Last notification	RX	lastnotif	last_notification
8.	Notification interval	RX	notifinterval	notification_interval
9.	Escalation period	XM	period	escalation_period
10.	Escalation options	LX	escopts	escalation_options
11.	Disable	X	disable	N/A

Examples

Show all 'serviceescalation' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/serviceescalation?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.16. hostescalation

Column	Description	Flags	REST variable name	Nagios argument name
1.	Host name	KRX	hostname	host_name
2.	Hostgroup name	XM	hostgroupname	hostgroup_name
3.	Contacts	LRXM	contacts	contacts
4.	Contact groups	LRM	contactgroups	contact_groups
5.	First notification	RX	firstnotif	first_notification
6.	Last notification	RX	lastnotif	last_notification
7.	Notification interval	RX	notifinterval	notification_interval
8.	Escalation period	XM	period	escalation_period
9.	Escalation options	LX	escopts	escalation_options
10.	Disable	X	disable	N/A

Examples

Show all 'hostescalation' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/hostescalation?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.17. serviceextinfo

Column	Description	Flags	REST variable name	Nagios argument name
1.	Host name	RX	hostname	host_name
2.	Service description	X	svcdesc	service_description
3.	Notes	X	notes	notes
4.	Notes url	X	notes_url	notes_url
5.	Action url	X	action_url	action_url
6.	Icon image	X	icon_image	icon_image
7.	Icon image alt	X	icon_image_alt	icon_image_alt
8.	Disable	X	disable	N/A

Examples

Show all 'serviceextinfo' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/serviceextinfo?json=\{"folder":"local"\}' \
| JSON.sh -b

4.2.18. hostextinfo

Column	Description	Flags	REST variable name	Nagios argument name
1.	Host name	RX	hostname	host_name
2.	Notes	X	notes	notes
3.	Notes url	X	notes_url	notes_url
4.	Action url	X	action_url	action_url
5.	Icon image	X	icon_image	icon_image
6.	Icon image alt	X	icon_image_alt	icon_image_alt
7.	Vrml image	X	vrml_image	vrml_image
8.	Statusmap image	X	statusmap_image	statusmap_image
9.	2d coords	X	coords2d	2d_coords
10.	3d coords	X	coords3d	3d_coords
11.	Disable	X	disable	N/A

Examples

Show all 'hostextinfo' entries and attributes:

curl -kn 'https://127.0.0.1/rest/show/hostextinfo?json=\{"folder":"local"\}' \
| JSON.sh -b

Set action_url for a host:

curl -knX POST -d 'json={"folder":"local",
       "hostname":"linhst2",
       "action_url":"/pnp4nagios/graph?host=$HOSTNAME$"}' \
       https://127.0.0.1/rest/add/hostextinfo

Set action_url for ALL hosts. Note that it would probably be better to set the action_url in the host template or for each host.

# Create a list of hosts
curl -kn 'https://127.0.0.1/rest/show/hosts?json=\{"folder":"local"\}' \
| JSON.sh -b | grep '\[[0-9]\+,0,' | sed 's/^[^ ]\+][[:space:]]*//' | tr -d \" >list1

# Use the list to create hostextinfo entries
while read HNAME x; do
curl -knX POST -d 'json={"folder":"local",
       "hostname":"'$HNAME'",
       "action_url":"/pnp4nagios/graph?host=$HOSTNAME$"}'
       https://127.0.0.1/rest/add/hostextinfo
done < list1

Delete ALL hostextinfo entries:

curl -knX POST -d 'json={"folder":"local","hostname":".*"}'
       https://127.0.0.1/rest/delete/hostextinfo

4.2.19. enablehostsvcchecks

Enables active checks for the host then enables all passive and active service checks for the host. The following nagios pipe commands are sent:

ENABLE_HOST_CHECK
ENABLE_PASSIVE_SVC_CHECKS
ENABLE_SVC_CHECK

Column	Description	Flags	REST variable name	Nagios argument name
N/a.	Host name	RX	name	N/A

Examples

4.2.20. disablehostsvcchecks

Disables active checks for the host then disables all passive and active service checks for the host. Status is changed to green for the host and all of its service checks and the comment is set. The following nagios pipe commands are sent:

DISABLE_HOST_CHECK
DISABLE_HOST_SVC_CHECKS
PROCESS_SERVICE_CHECK_RESULT   <-- Sets the comment and service status
... 10 second sleep ...
DISABLE_PASSIVE_SVC_CHECKS

Column	Description	Flags	REST variable name	Nagios argument name
N/a.	Host name	RX	name	N/A
N/a.	Comment for the Nagios GUI	X	comment	N/A

Examples

4.2.21. enablesvccheck

Enables an individual service check and optionally sets a comment otherwise the default comment will be used: "Un-disabled via REST. Check scheduled.". The following nagios pipe commands are sent:

ENABLE_PASSIVE_SVC_CHECKS
ENABLE_SVC_CHECK
PROCESS_SERVICE_CHECK_RESULT

Column	Description	Flags	REST variable name	Nagios argument name
N/a.	Host name	RX	name	N/A
N/a.	Service description	RX	svcdesc	N/A
N/a.	Comment for the Nagios GUI	X	comment	N/A

Examples

4.2.22. disablesvccheck

Disables an individual service check and optionally sets a comment otherwise the default comment will be used: "Disabled via REST interface.". The following nagios pipe commands are sent:

DISABLE_SVC_CHECK
PROCESS_SERVICE_CHECK_RESULT
DISABLE_PASSIVE_SVC_CHECKS

Column	Description	Flags	REST variable name	Nagios argument name
N/a.	Host name	RX	name	N/A
N/a.	Service description	RX	svcdesc	N/A
N/a.	Comment for the Nagios GUI	X	comment	N/A

Examples

4.2.23. schedhstdowntime

Schedule fixed or flexible downtime for a host. The following nagios pipe commands are sent:

SCHEDULE_HOST_DOWNTIME

Column	Description	Flags	REST variable name	Nagios argument name
N/a.	Host name	RX	name	N/A
N/a.	Start time [unix time]	RX	starttime	N/A
N/a.	End time [unix time]	RX	endtime	N/A
N/a.	Flexible downtime [0\|1]	X	flexible	N/A
N/a.	Duration (flexible downtime in minutes)	X	duration	N/A
N/a.	Comment for the Nagios GUI*	X	comment	N/A
N/a.	Author	X	author	N/A

* If comment is not supplied then the default comment, ``Scheduled via the REST interface.'', is used.

Examples

Schedule 1 hour of fixed downtime for `ahst2', starting from now.

curl -knX POST -d 'json={
   "folder":"local",
   "name":"ahst2",
   "starttime":"'`date +%s -d now`'",
   "endtime":"'`date +%s -d "now + 1 hour"`'"}'
   http://127.0.0.1/rest/pipecmd/schedhstdowntime

4.2.24. delhstdowntime

Delete all scheduled downtime for a host. The following nagios pipe commands are sent:

DEL_HOST_DOWNTIME

Column	Description	Flags	REST variable name	Nagios argument name
N/a.	Host name	RX	name	N/A

Examples

Get rid of all host downtime associated with `ahst2'.

curl -knX POST -d 'json={
   "folder":"local",
   "name":"ahst2" }'
   http://127.0.0.1/rest/pipecmd/delhstdowntime

Name		Name	Last commit message	Last commit date
Latest commit History 314 Commits
SOURCES/nagrestconf-1		SOURCES/nagrestconf-1
SPECS		SPECS
NEWS.asciidoc		NEWS.asciidoc
README.asciidoc		README.asciidoc
hudson_rpm_build.sh		hudson_rpm_build.sh

ganeshgirase/nagrestconf

Folders and files

Latest commit

History

Repository files navigation

Nagrestconf README

.1. Latest News

.2. License

.3. Screenshots

.4. What is Nagrestconf?

.5. Features

.6. TODO

.7. How does it work?

.8. Requirements

.9. Upgrade

.10. Install

.10.1. Prebuilt Packages

.10.2. Install Using Prebuilt Packages

.11. Install From Source

.12. REST Examples

.13. Status

1. COOK BOOK

1.1. Using CURL

1.2. Deleting Environments

1.3. Export Service Sets

2. WALK-THROUGHS

2.1. Single Server from Scratch (Redhat/Centos 5)

2.2. Distributed Monitoring from Scratch

2.2.1. Building the Master Nagios

Install software

Test the Installed Software

Configure Apache

Configure the system

2.2.2. Building the Master Nagios in a Chroot

2.2.3. Building the Worker Nagios (Redhat/Centos 5)

Install software

Test the Installed Software

Configure Apache

Configure the system

2.3. Puppet Integration

3. TROUBLE-SHOOTING

3.1. Using in Linux Containers, Systemd-nspawn or Chroots

3.2. Gotchas

4. REFERENCE

4.1. REST Commands

4.2. Object Definitions and Options

4.2.1. Listings of all Valid REST Options

4.2.2. contacts

Examples

4.2.3. contactgroups

Examples

4.2.4. hosts

Examples

4.2.5. hosttemplates

Examples

4.2.6. services

Examples

4.2.7. servicesets

Examples

4.2.8. servicetemplates

Examples

4.2.9. commands

Examples

4.2.10. hostgroups

Examples

4.2.11. servicegroups

Examples

4.2.12. timeperiods

Examples

4.2.13. servicedeps

Examples

4.2.14. hostdeps

Examples

4.2.15. serviceescalation

Examples

4.2.16. hostescalation

Examples

4.2.17. serviceextinfo

Examples

4.2.18. hostextinfo

Packages