/ 
Net-NSCA-Client-0.009002
River stage zero No dependents
/ Net::NSCA::Client

NAME

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

VERSION

This documentation refers to version 0.009002

SYNOPSIS

use Net::NSCA::Client;

my $nsca = Net::NSCA::Client->new(
  remote_host => 'nagios.example.net',
);

$nsca->send_report(
  hostname => 'web1.example.net',
  service  => 'MYSQL',
  message  => $plugin_output,
  status   => $Net::NSCA::Client::STATUS_OK,
);

DESCRIPTION

Send passive checks to Nagios locally and remotely.

CONSTRUCTOR

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.

new

This will construct a new object.

new(%attributes)

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

new($attributes)

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

ATTRIBUTES

# Set an attribute
$object->attribute_name($new_value);

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

encryption_password

This is the password to use with the encryption.

encryption_type

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

remote_host

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

remote_port

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

server_config

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.

timeout

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

METHODS

clear_encryption_password

This will remove the encryption password that is currently set.

hsa_encryption_password

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

send_report

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

hostname

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

service

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

message

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

status

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

SPECIFICATION

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.

NSCA PROTOCOL 1

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

NSCA PROTOCOL 2

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.

NSCA PROTOCOL 3

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.

Encryption

None

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

XOR

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.

CONSTANTS

$DEFAULT_HOST

The is the default host to use when connecting.

$DEFAULT_PORT

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

$DEFAULT_TIMEOUT

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

$STATUS_OK

This is the status value when a service is OK

$STATUS_WARNING

This is the status value when a service is WARNING

$STATUS_CRITICAL

This is the status value when a service is CRITICAL

$STATUS_UNKNOWN

This is the status value when a service is UNKNOWN

DEPENDENCIES

SEE ALSO

AUTHOR

Douglas Christopher Wilson, <doug at somethingdoug.com>

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-net-nsca-client at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-NSCA-Client. 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.

SUPPORT

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

perldoc Net::NSCA::Client

You can also look for information at:

LICENSE AND COPYRIGHT

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.