{section}
{column}

h1. Introduction

The probes available in the Petals internals and components are able to send JMX notifications when they detect a defect. These notifications can be sent to Nagios with a dedicated monitoring command of Petals CLI that receive JMX notifications and write them in the channel of Nagios passive checks.

{gliffy:name=Nagios passive checks|size=L|align=center|version=2}

The daemon *{{petals-cli-nagios}}* listen JMX notifications coming from Petals ESB nodes using a dedicated Petals CLI command. When it receives a JMX notification, it formats and prints an external command for Nagios. The host and service emitting the JMX notification are transformed into Nagios host and Nagios service through a mapping file.

{warning}In this documentation, the term "Allocated threads" must be understood as "Active threads", see [PETALSDISTRIB-37|https://jira.petalslink.com/browse/PETALSDISTRIB-37]. This naming error will be fixed in the next version.{warning}

{column}
{column:width=350px}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. Installation

These integration of Petals ESB, Petals CLI and Nagios is available on Debian-based system and is packaged as a Debian package: {{petals-cli-cmd-monitoring-so-nagios}}.
{tip}To run on other operating system, we need your contribution to port the daemon script wrapping Petals CLI on this operating system.{tip}
See [petalscli211:Installing Petals CLI using the Debian packages] to get more information on this Debian package.

h1. Configuration

Once your Nagios installation is configured to accept external commands, you must verify in {{/etc/petals-cli/petals-cli-nagios}} that the expected Nagios pipe file is set according to your Nagios installation. The default value is the one associated to the Debian package of Nagios.

To add a new defect subscription to sent to Nagios:
# create a new file in the directory {{/etc/petals-cli/nagios-subscriptions-available}} from the template {{/etc/petals-cli/nagios-subscriptions-available/nagios-subscription-template}}:
{code}
# JMX connection information to the Petals ESB container
#
host=localhost
port=7700
username=petals
password=petals

# The subscription object and its arguments
#
subscription-object=petals-bc-soap
extra-args=-n petals-bc-soap -t file:///etc/petals-cli/nagios-mapping-rules.properties
{code}
where the first part is the required JMX connection information to establish a communication with a Petals ESB container, and the second part is dedicated to the wanted component emitting defects.
# configure the file {{/etc/petals-cli/nagios-mapping-rules.properties}} to map the hosts and services declared into Nagios with your Petals ESB installation,
#* the Nagios host is to associate to the defect emitter (see [defect details|#defect_details]),
#* the Nagios service is to associate to the defect identifier (see [defect details|#defect_details]).
Example of configuration for the BC SOAP and the Nagios configuration defined [here|Monitoring Petals ESB with Nagios]:
{code}
# Example for a Petals BC SOAP running on a Petals ESB node declared as petals-esb-node-1 in Nagios.
emitter.petals-bc-soap@localhost=petals-esb-node-1
name.org.ow2.petals.bc.soap.httpserver.threadpool.exhausted=BC SOAP - HTTP Server - Current allocated threads
name.org.ow2.petals.component.framework.process.message.acceptor.pool.thread.dead=BC SOAP - Current MEX acceptor threads
name.org.ow2.petals.component.framework.process.message.processor.thread.pool.exhausted=BC SOAP - Current MEX processor threads
name.org.ow2.petals.component.framework.process.message.processor.object.pool.exhausted=BC SOAP - Current MEX processor objects
{code}
# you can test your defect subscription using the script {{/usr/bin/petals-cli-nagios}} run with the Nagios system user:
{code}
> sudo -u nagios /usr/bin/petals-cli-nagios <your-defect-subscription-file>
{code}
or at a lower level using directly Petals CLI that prints defect on the standard output instead of into the Nagios pipe file (here to get defects of a Petals BC Soap):
{code}
> petals-cli -c -- moniting -s petals-bc-soap -- -n petals-bc-soap -t file:///etc/petals-cli/nagios-mapping-rules.properties
[1379337251] PROCESS_SERVICE_CHECK_RESULT;petals-esb-node-1;org.ow2.petals.component.framework.process.message.processor.thread.pool.exhausted;2;The thread pool of message exchange processors is exhausted !
[1379337252] PROCESS_SERVICE_CHECK_RESULT;petals-esb-node-1;org.ow2.petals.component.framework.process.message.processor.thread.pool.exhausted;2;The thread pool of message exchange processors is exhausted !
{code}
# once your defect subscription is working, just create a link into the directory {{/etc/petals-cli/nagios-subscriptions-enable}}, and restart the service {{petals-cli-nagios}}.

{anchor:defect_details}
h1. Supported defects