Net::NSCA::Client - Send passive checks to Nagios locally and remotely.


This documentation refers to version 0.009002


  use Net::NSCA::Client;

  my $nsca = Net::NSCA::Client->new(
    remote_host => '',

    hostname => '',
    service  => 'MYSQL',
    message  => $plugin_output,
    status   => $Net::NSCA::Client::STATUS_OK,


Send passive checks to Nagios locally and remotely.


This is fully object-oriented, and as such before any method can be used, the constructor needs to be called to create an object to work with.


This will construct a new object.


%attributes is a HASH where the keys are attributes (specified in the "ATTRIBUTES" section).


$attributes is a HASHREF where the keys are attributes (specified in the "ATTRIBUTES" section).


  # Set an attribute

  # Get an attribute
  my $value = $object->attribute_name;


This is the password to use with the encryption.


This is a string of the encryption type. See Net::NSCA::Client::Connection::TLS for the different encryption types.


This is the remote host to connect to. This will default to "$DEFAULT_HOST".


This is the remote port to connect to. This will default to "$DEFAULT_PORT".


This specifies the configuration of the remote NSCA server. See Net::NSCA::Client::ServerConfig for details about using this. Typically this does not need to be specified unless the NSCA server was compiled with customizations.


This is the timeout to use when connecting to the service. This will default to "$DEFAULT_TIMEOUT".



This will remove the encryption password that is currently set.


This will return a Boolean if there is any encryption password.


This will send a report on a service to the remote NSCA server. This method takes a HASH of arguments with the following keys:


This is the hostname of the service that is being reported.


This is the service description of the service that is being reported.


This is the message that the plug in gives to Nagios.


This is the status code to report to Nagios. You will want to use one of the $STATUS_* constants.


The NSCA protocol is currently at version 3. Simply put, the NSCA protocol is very simple from the perspective for the C language. The NSCA program has a C structure that is populated and then sent across the network in raw form.


Currently I cannot find any information on this (it is probably ancient; at least before 2002). This module does not support this protocol version.


This protocol is identical to "NSCA PROTOCOL 3" except that the packet_version is the integer 2 to match the protocol version. The difference between the two protocols is that with version 3, passive host checks were introduced and thus the version had to change otherwise the server would think that the check was for a service with no name.


This protocol version was first introduced in NSCA version 2.2.

Below is the definition of the C structure taken from common.h in NSCA version 2.7.2.

  struct data_packet_struct {
    int16_t   packet_version;
    u_int32_t crc32_value;
    u_int32_t timestamp;
    int16_t   return_code;
    char      host_name[MAX_HOSTNAME_LENGTH];
    char      svc_description[MAX_DESCRIPTION_LENGTH];
    char      plugin_output[MAX_PLUGINOUTPUT_LENGTH];

When the client connects to the server, the server sends a packet with the following C structure taken from common.h in NSCA version 2.7.2.

  struct init_packet_struct {
    char      iv[TRANSMITTED_IV_SIZE];
    u_int32_t timestamp;

The packet is first completely zeroed, and thus made empty. Next, the packet is filled randomly with alpha-numeric characters. The C library actually fills it randomly with ASCII characters between 0x30 and 0x7A. All values are now filled into the structure (only overwriting what needs to be written, keeping randomness intact). The timestamp value is set to the same value that was sent by the server in the initial response and crc32_value is set to all zeros. The CRC32 is calculated for this packet and stored in the packet. Next, the packet in encrypted with the specified method (which MUST be exactly as set in the server) and sent across the network.



When there is no encryption, then the packet is completely unchanged.


This is the obfucated method and so is no encryption. This is merely to attempt to mask the data to make it harder to see. The packet is first XOR'd with the IV that was sent by the server, one byte at a time. Once all bytes from the IV have been used, then it starts again from the first byte of the IV. After this, the packet is then XOR'd with the provided password and the same steps as followed by the IV are followed for the password (byte-per-byte, looping).

All other Encryptions

All other specified encryption methods are performed in cipher feedback (CFB) mode, in one bye blocks (even if the encryption method doesn't actually support being used in one byte block modes.



The is the default host to use when connecting.


This is the default port number to use when connecting to a remote host.


This is the default timeout to use when connecting to a remote host.


This is the status value when a service is OK


This is the status value when a service is WARNING


This is the status value when a service is CRITICAL


This is the status value when a service is UNKNOWN




Douglas Christopher Wilson, <doug at>


Please report any bugs or feature requests to bug-net-nsca-client at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

I highly encourage the submission of bugs and enhancements to my modules.


You can find documentation for this module with the perldoc command.

  perldoc Net::NSCA::Client

You can also look for information at:


Copyright 2009 Douglas Christopher Wilson.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

  • the Artistic License version 2.0.