nscaweb 0.1.20

A more feature rich alternative than the classic NSCA daemon.

What?

NSCAweb is a Nagios core based monitoring solution addon which allows you to easily submit (passive) host and service checks over http(s) to the Nagios external command file. It aims to be a better,more feature rich alternative than the classic NSCA daemon.

NSCAweb has following features:

• http(s) as transport makes it more friendly in a firewalled environment.

• SSL encryption when desired.

• Supports multiline plugin & performance output.

• Accepts data coming over http or from local named pipes.

• Submit data to many types of destinations: named pipes (nagios.cmd), NSCAweb, NRDP or a file.

• Loadbalance and failover between multiple urls per destination.

• Duplicate and forward passive check results to an “unlimited” amount of destinations.

• Submit messages to 1 destination or all destinations depending on the url messages are send to.

• Simultaneous local and remote delivery.

• Each destination has an independent, dedicated thread and queue.

• Buffering of unavailable destinations and resubmitting when destination comes available to prevent data loss.

• Builtin, multiuser authentication.

• Trivial to submit check results using http post.

• Submit check results in bulk or one by one.

• Use curl as a client from the command line.

Support

Post a message in Google groups: https://groups.google.com/forum/#!forum/nscaweb

Submit bugreports to: https://github.com/smetj/nscaweb/issues

Installation

You can install NSCAweb from https://pypi.python.org/pypi by executing:

$ easy_install nscaweb

Or you can install NSCAweb directly from source when desired:

$ git clone https://github.com/smetj/nscaweb.git $ cd nscaweb $ sudo python setup.py install

Any Python related dependencies should be resolved and installed automatically.

Usage

After installing the package you should have the nscaweb command available.

Starting in foreground. Press ctrl+c to exit:

$ nscaweb debug –config /etc/nscaweb.conf

Starting in background.

$ nscaweb start –config /etc/nscaweb.conf

Stop a background process:

$ nscaweb stop –config /etc/nscaweb.conf

Configuration

The configuration file is in ini style and has 4 sections:

application

The application section controls the behaviour of the daemon itself.

[ "application" ]
    host                = "0.0.0.0"
    port                = "5668"
    pidfile             = "/opt/nscaweb/var/nscaweb.pid"
    sslengine           = "off"
    sslcertificate      = ""
    sslprivatekey       = ""
    queue_quota         = "104857600"

• host

  The IP address NSCAweb should bind to and listen on. By default NSCAweb listens on all interfaces it can find on the machine. This behavior is reached by using the “0.0.0.0” which effectively means listen on all interfaces. If you want to have NSCAweb to listen on a certain ip address, then you can define it here. If you want NSCAweb only to listen on the localhost you can define “127.0.0.1”.

• port

  The port on which NSCAweb should listen. By default NSCAweb listens on port 12345. It can be changed to what makes most sense to your environment.

• pidfile

  The location of the pidfile. The pidfile holds the process number of the NSCAweb daemon when it has been started in background mode. It’s not created when NSCAweb is started in debug mode. The pidfile is used by NSCAweb itself for server control. Do not delete this file while NSCAweb is running in background mode.

• sslengine

  Makes NSCAweb listen to https instead of standard http and encrypt all traffic. The allowed values are “on” and “off”. If you have defined on you need to define the sslcertificate and the sslprivatekey parameters. If you choose off, the sslcertificate and sslprivatekey parameters are ignored.

• sslcertificate

  Defines the place of the sslcertificate. You can create and use self-signed certificates or an official one. You can basically follow any Apache/ssl certificate creation guide to create one.

• sslprivatekey

  Defines the place of the ssl private key. When you’re in the process of creating your certificate you will also have your private key. This is a quite sensitive piece of information. Make sure it’s on a safe place.

• queue_quota

  The value in bytes a queue is allowed to contain before refusing data.

logging

Logging related options

[ "logging" ]
    logfile             = "/var/log/nagios/nscaweb.log"
    enable_syslog       = "1"
    enable_http_logging = "0"

• logfile

  The location of the logfile. If commented, no logfile is created.

• enable_syslog

  If enabled, writes logs to syslog.

• enable_http_logging

  If enabled, includes any http request related logging to the log destination.

pipes

NSCAweb can accept data over named pipe.

[ "pipes" ]
    enable          = "1"
    directory       = "/var/tmp/"

• enable

  When enabled, creates the named pipes.

• directory

  The location of the named pipes.

For each defined destination a corresponding named pipe is created. Submitting data to a named pipe results in that data being send to the corresponding destination. A special “broadcast” named pipe is also created which submits incoming data to all defined destinations.

destinations

A destination is an entry point into NCSAweb and data submitted into it leads to the type and location associated with it. Multiple NSCAweb destinations can be defined. Each destination should have a unique name. The name identifies the destination when submitting data. A destination name is free to choose.

4 different destination types are available:

• local Writes data to a local named pipe.

• nscaweb Writes data to another NSCAweb instance.

• nrdp Writes data to a NRDP receiver

• file Writes data into a file

[ "destinations" ]

    [[ "local" ]]
        enable      = "0"
        type        = "local"
        locations   = "/opt/nagios/var/rw/nagios.cmd"

    [[ "master" ]]
        enable      = "0"
        type        = "nscaweb"
        locations   = "http://server_23.company.local:15668/queue/local"
        username    = "default"
        password    = "changeme"

    [[ "nagiosWithNrdp" ]]
        enable      = "0"
        type        = "nrdp"
        locations   = "http://nagios/nrdp/"
        username    = "default"
        password    = "changeme"
        token       = "mysecrettoken"

    [[ "debugging" ]]
        enable      = "0"
        type        = "file"
        locations   = "/tmp/external_commands.log"

Destination types

local

• locations

  A comma delimited list of named pipe locations.

nscaweb

• locations

  A comma delimited list of urls

• username

  The username to authenticate to the remote NSCAweb instance

• password

  The password to authenticate to the remote NSCAweb instance

nrdp

• locations

  A comma delimited list of urls.

• username

  The username to authenticate to the remote NRDP instance

• password

  The password to authenticate to the remote NRDP instance

• token

  The token used to authenticate to the remote NRDP instance

authentication

The authentication section contains the usernames and passwords used to authenticate to NSCAweb in order to dump data.

[ "authentication" ]
        default         = "6ac371cc3dc9d38cf33e5c146617df75"

This contains a list of username and corresponding password hashes. In this case there’s only 1 user defined with the login name “default” and password “changeme”.

The password is a md5sum. To generate a hash value out of a string you can execute the following:

$ echo changeme|md5sum

Warning: Each NSCAweb installation comes with the default username “default” and password “changeme”. CHANGE IT!.

NSCAweb transport scenario’s

A typical NSCAweb setup looks like this:

From command line to NSCAweb

Sometimes you have to submit a check result (or other command) into Nagios from a remote host. You can do that by simply using curl or wget from command line. In the above diagram, we have server_3 sending check updates to server_4. Server_4 then writes the incoming check results into the Nagios external command pipe.

Following example command does that:

printf “[%lu] PROCESS_SERVICE_CHECK_RESULT;localhost;True 1;2;CRITICAL- Whatevern” $(date +%s) | curl -d username=”default” -d password=”changeme” –data-urlencode input=@- http://localhost:5668/queue

When posting data to the NSCAweb webserver you have to keep 3 fields into account:

• username

• password

• input

The input field should contain 1 or more entries with the same syntax as described below. When you use multiple lines as plugin output then use “\n” to separate those multiple lines. NSCAweb considers each newline as a new command.

Note: Keep in mind that all data you send to NSCAweb needs to be URL encoded. Submit 1 check result to NSCAweb using curl.

Note: Make sure to use a version of curl which supports the ‘–data- urlencode’ parameter.

Note: Make sure that newlines in multiline output are replaced by litteral “n” prior to sending over to NSCAweb.

From NSCAweb to NSCAweb

Let’s say you have 2 Nagios slave machines (diagram server_1 and server_2) which have to forward their results to a central Nagios machine (diagram server_3) you will have to configure following items:

Install NCSAweb on all 3 servers

Nagios on the saves will submit check results to a local NSCAWeb instance, which takes care of transporting the results to the remote NSCAweb instance.

Configure OCHP and OHSP on slaves

See:

• http://nagios.sourceforge.net/docs/3_0/configmain.html#ochp_command

• http://nagios.sourceforge.net/docs/3_0/configmain.html#ocsp_command

Note: Nagios treats everything coming after a “;” as comment. Unfortunately we need the “;” character to compose the check result data we want to forward. Therefor we we have to assign the “;” to a $USER<number>$ value in the resource file. In the below example we havve assigned the “;” value to $USER9$

define command {
        command_name    submit_service_check_result_nscaweb
        command_line    echo "[$TIMET$] PROCESS_SERVICE_CHECK_RESULT$USER9$$HOSTNAME$$USER9$$SERVICEDESC$$USER9$$SERVICESTATEID$$USER9$$SERVICEOUTPUT$|$SERVICEPERFDATA$" >> /var/tmp/server_4
}

define command {
        command_name    submit_host_check_result_nscaweb
        command_line    echo "[$TIMET$] PROCESS_HOST_CHECK_RESULT$USER9$$HOSTNAME$$USER9$$HOSTSTATEID$$USER9$$HOSTOUTPUT$|$HOSTPERFDATA$" >> /var/tmp/server_4
}

Configure NSCAweb on the slave (sender)

In the above example commands we submit the check results into a named pipe called /var/tmp/server_4. Therefor we need the following section in the sending NSCAweb configuration:

[ "destinations" ]

    [[ "server_4" ]]
        enable      = "0"
        type        = "nscaweb"
        locations   = "http://server_4:15668/queue/local"
        username    = "default"
        password    = "changeme"

Configure NSCAweb on the master (receiver)

On the receiving end (server_4) we have NSCAweb writing incoming data into the nagios external command file

[[ "local" ]]
    enable      = "1"
    type        = "local"
    locations   = "/usr/local/nagios/var/rw/nagios.cmd"