NSCA
Prev | Chapter 10. Additional software | Next

## NSCA

Introduction

Nagios Service Check Acceptor (or NSCA for short) is an addon to transmit check results from one system to another. It consists of two modules: the sender (send_nsca) and the receiver (nsca). The data is sent in a secure manner. Despite its name host check results are transmitted as well.

Figure 10.3. NSCA

NSCA is running as a daemon on the Icinga server. It listens for information sent from remote machines using the send_nsca program (on Unix/Linux machines) or NSClient++ (often used on Windows machines). The data will be encrypted using the method specified in send_nsca.cfg (or nsc.ini in the case of NSClient++). The daemon will validate the data in a *very* basic manner by decrypting the information using the password which is stored in the local nsca.cfg file. If the data looks like it was encrypted using the same password then the daemon will try to output the data as external commands into the local Icinga command pipe.

The following instructions are mainly based on the README included in the NSCA package.

Prerequisites

- Icinga should be up and running

- check_external_commands = 1 should be set in `icinga.cfg`

- command_check_interval = <n>[s] should be set in `icinga.cfg`

- log_passive_checks = 1 should be set in `icinga.cfg` while testing, otherwise there will be no messages about incoming passive checks

- libmcrypt and libmcrypt-devel packages are installed (which may be named similar depending on the distribution used), otherwise use one of the following commands to install the packages:

       #> apt-get install libmcrypt libmcrypt-devel # Debian / Ubuntu
       #> yum install libmcrypt libmcrypt-devel     # RHEL / Fedora / CentOS
       #> zypper install libmcrypt libmcrypt-devel  # SLES / OpenSuSE (or use Yast instead)

Download and compile

| Note
Instead of installing NSCA from scratch you may want to use a package which might be available for your OS. Please take a look at the table of packages. If you are planning to install from source then please use the official release tarball.

| Important
Please don't use git snapshots unless you have an issue which might be solved in the current developer version.

The maximum length of data to be transmitted is set to 2,048 bytes, the maximal length of plugin output is set to 512 bytes. If that is not sufficient then you have to alter the appropriate value in `icinga-nsca/include/common.h`.

     #define MAX_INPUT_BUFFER        2048    /* max size of most buffers we use */
     #define MAX_PLUGINOUTPUT_LENGTH 512

Please keep in mind that you have to recompile the programs if you change this values at a later stage.

Due to the setting of the following define in include/common.h (in Icinga core) the max. value cannot exceed 8,192 bytes.

     #define MAX_EXTERNAL_COMMAND_LENGTH             8192    /* max length of an external command */

After setting the owner change to the newly created directory and call configure and make

     #> chown -R icinga icinga-nsca
     #> cd icinga-nsca
     #> ./configure
     #> make all

Afterwards two programs (send and send_nsca) are created in the `src` directory.

| Caution

If the libmcrypt packages are not found "./configure" will complain but will NOT end with a non-zero return code so please check config.log using

     #> grep mcrypt.h: config.log

This command should return no lines.

If the libmcrypt modules are not found, the user or group deviate from "icinga" or the port to be used is not the default 5667 you can use several options to specify different values. Call "`./configure -h`" to see the options available.

After changing to "nsca_tests" you can try to execute "./runtests". Please note that these tests require several Perl modules described in the README file.

Customise

The sample-config directory contains `nsca.cfg` and `send_nsca.cfg`. At least the settings of the directives "password" and "encryption_method" / "decryption_method" should be reviewed/altered before copying the files. Remember to set the same password in all copies of these config files. If you want to have different passwords on different remote servers you have to run multiple nsca daemons on the Icinga server listening on different ports. This doesn't work if you start the daemon using inetd/xinetd.

First test

Switch to the Icinga user and run a first test

     #> su - icinga
     $> cd /usr/src/icinga-nsca/src
     $> ./nsca -c ../sample-config/nsca.cfg
     $> echo -e "A\tB\tC\tD\n" | ./send_nsca -H localhost -c ../sample-config/send_nsca.cfg
     $> exit

This should return the message "1 data packet(s) sent to host successfully.". In the first place it only means that send_nsca and nsca are able to communicate with each other on the local host using the sample config files as it works perfectly without a running Icinga instance. But it is important nevertheless: If this test fails then there is no sense in continuing. Instead verify the settings in nsca.cfg and send_nsca.cfg. Check for messages in your syslog (e.g. `/var/log/messages`) as well.

If the prerequisites are fulfilled then you should see some warnings in `icinga.log` complaining that host "A" and service "B" are not found in the Icinga configuration. This means that nsca has sufficient permissions to write to the Icinga command file. Check if the nsca daemon and Icinga are running with different users if there are no messages in icinga.log. If there are no messages check the setting of log_passive_checks in `icinga.cfg`.

Install

"make install" will do nothing (yet) so you have to copy some files to new locations. The following commands will copy the nsca module to the directory where the Icinga binary is located and the config file to the Icinga config folder. We assume that you installed Icinga using one of the quickstart guides.

     #> cp -p nsca /usr/local/icinga/bin/
     #> cp ../sample-config/nsca.cfg /usr/local/icinga/etc/

- nsca daemon

  If you choose to use xinetd the daemon will be started automatically. Otherwise you have to start the daemon manually after switching to the Icinga user (which you might have done already during "First test")

       #> su - icinga
       $> /usr/local/icinga/bin/nsca -c /usr/local/icinga/etc/nsca.cfg

- inetd/xinetd

  If you want the daemon to be started by (x)inetd you have to extend /etc/services, alter/copy another file and restart (x)inetd. Don't forget to stop the nsca daemon you started during "First test".

  | Note
  The setting of "server_port" specified in nsca.cfg is ignored when you use inetd/xinetd.

       #> kill < /var/run/nsca.pid
       #> echo "nsca 5667/tcp # NSCA" >> /etc/services

  Depending on the superserver which is installed on your system there are three alternatives

  - inetd WITH tcpwrappers

    Add entries to your /etc/hosts.allow and /etc/hosts.deny file to enable TCP wrapper protection for the nsca service. This is optional, although highly recommended. Add "nsca stream tcp nowait <user> /usr/sbin/tcpd <nsca-binary> -c <nsca-cfg> --inetd" to /etc/inetd.conf, e.g.

         #> echo "nsca stream tcp nowait icinga /usr/sbin/tcpd /usr/local/icinga/bin/nsca -c /usr/local/icinga/etc/nsca.cfg --inetd" >> /etc/inetd.conf
         #> /etc/init.d/inetd restart

  - inetd WITHOUT tcpwrappers

    Add "nsca stream tcp nowait <user> <nsca-binary> -c <nsca-cfg> --inetd" to /etc/inetd.conf, e.g.

         #> echo "nsca stream tcp nowait icinga /usr/local/icinga/bin/nsca -c /usr/local/icinga/etc/nsca.cfg --inetd" >> /etc/inetd.conf
         #> /etc/init.d/inetd restart

  - xinetd

    Consider editing the config file nsca.xinetd in the sample-config folder and replacing <ipaddress1>... by the IP addresses of your client machines (where send_nsca will be running). This only works if xinetd was compiled with support for tcpwrappers. If you are running DHCP then this will not work and you should delete this line.

    Add entries to your /etc/hosts.allow and /etc/hosts.deny file to enable TCP wrapper protection for the nsca service. This is optional, although highly recommended. Copy the file to your xinetd folder

         #> cp -p ../sample-config/nsca.xinetd /etc/xinetd.d/
         #> /etc/init.d/xinetd restart

Remote system(s)

You're done on the local system but apparently send_nsca has to be copied to the remote system(s).

Please note that you have to compile send_nsca for the platform it should run upon so you might have to install the libmcrypt packages and configure/make as described above on multiple servers.

Copy files

You're free where to place binary and config file. We assume that you have a directory structure similar to the Icinga server

     #> scp -p <Icinga server>:/usr/local/icinga-nsca/src/send_nsca /usr/local/icinga/bin/
     #> scp -p <Icinga server>:/usr/local/icinga-nsca/sample-config/send_nsca.cfg /usr/local/icinga/etc/

Second test

Now you can rerun the test on the remote system(s)

     #> su - icinga
     $> echo -e "A\tB\tC\tD\n" | /usr/local/icinga/bin/send_nsca -H <Icinga server> -c /usr/local/icinga/etc/send_nsca.cfg

This as well should return the message "1 data packet(s) sent to host successfully." and there should be warnings in icinga.log on the Icinga server similar to the ones mentioned above. If there are no messages check the setting of log_passive_checks in `icinga.cfg`.

Troubleshooting

If the daemon is not permitted to write to the command pipe then the data will be lost! You should run the daemon using the same user you specified for Icinga.

If the object (host and/or service) is not included in the running configuration then the data will be rejected.

Host name (and service description, if applicable) are case sensitive and have to match the definition in Icinga.

Check if you specified the same password in nsca.cfg and send_nsca.cfg. Otherwise the transmission will fail.

Check if you used the same encryption/decryption method. Otherwise the transmission will fail.

Check if your firewall setting allow the communication on the port specified (default is 5667)

If you are using xinetd check if the IP address(es) specified after "only_from=" match to the remote system(s) or remove this line (and restart xinetd)

Activate "debug=1" in `nsca.cfg`, restart the daemon (if applicable) and look for messages in the syslog / `nsca.log`.

Security

There are some security implications with allowing remote clients to provide check results to Icinga. Because of this, you have the option of encrypting the packets that the NSCA client sends to the NSCA daemon. Read the SECURITY file for more information on the security risks of running NSCA, along with an explanation of what kind of protection the encryption provides you.

Operation

send_nsca is used to send the check results from the remote host to the Icinga server. The syntax differs depending on the object type. To submit service check information use

<host_name>[tab]<svc_description>[tab]<return_code>[tab]<plugin_output>[newline]

where:

<host_name>=short name of the host that the service is associated with (as defined in the host_name directive of the service definition)

<svc_description>=description of the service (as defined in the service_description directive of the service definition)

<return_code>=numeric return code (0,1,2,3 as explained here)

<plugin_output>=output from host/service check

Host check information is submitted in a similiar fashion - just leave out the service description:

<host_name>[tab]<return_code>[tab]<plugin_output>[newline]

Integration into Icinga

So far you only created some prerequisites for running passive checks but didn't define any host or service actually using the functionality.

Although you only receive check results you still need to specify the "check_command" directive in your definitions. There is a plugin called "check_dummy" which can be used for this purpose. You may have to add a command definition if it's not already included. The second argument is optional and might contain an explanatory text.

     define command{
        command_name check_dummy
        command_line $USER1$/check_dummy $ARG1$ $ARG2$
        }

You may want to create a service template. The host template might look similiar to that (just replace "service" by "host")

     define service{
        use                     generic-service   ; template to inherit from
        name                    passive-service   ; name of this template
        active_checks_enabled   0                 ; no active checks
        passive_checks_enabled  1                 ; allow passive checks
        check_command           check_dummy!0     ; use "check_dummy", RC=0 (OK)
        check_period            24x7              ; check active all the time
        check_freshness         0                 ; don't check if check result is "stale"
        register                0                 ; this is a template, not a real service
        }

Using the template above the service definition might look like

     define service{
        use                     passive-service   ; template to inherit from
        host_name               remotehost        ; host where send_nsca is located
        service_description     Diskspace         ; service to be checked
        }

Restart Icinga to include the definitions in your running configuration

     #> /etc/init.d/icinga restart

Change to your remote host, switch to the Icinga user and execute send_nsca replacing <Icinga server> by the IP address of the server running Icinga

     #> su - icinga
     $> echo -e "remotehost\tDiskspace\t0\t/var=78%\n" | /usr/local/icinga/bin/send_nsca -H <Icinga server> -c /usr/local/icinga/etc/send_nsca.cfg

Please keep in mind to specify the host name and service description exactly as defined in your Icinga definition (because the processing is case sensitive). Otherwise you'll get messages in icinga.log that the object could not be found. If there are no messages check the setting of log_passive_checks in `icinga.cfg`.

After a short while you should see messages in icinga.log showing that the information submitted was processed. You should see the information in the classic UI as well turning the service state from "Pending" to "OK" and containing the data you specified.

Prev | Up | Next
NRPE | Home | Chapter 11. Development

© 2009-2011 Icinga Development Team, http://www.icinga.org