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.

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.

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.

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.

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.

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.

"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/

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.

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/

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.

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.

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.

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]

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.