Nagios XI integration with xMatters (version 3.0)

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

Contents

Introduction

Configure xMatters

Configure the integration agent

Configure Nagios

Test the integration

Download resources

Introduction

This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Nagiox XI.

Nagios XI is a software application that IT staff configure to monitor critical IT infrastructure components. More simply stated, Nagios XI is a tool that provides monitoring and alerting services for servers, switches, applications and services, potentially across different operating systems. Nagios can generate an event when things go wrong and then a second event when the problem has been resolved.

The concepts of host and service are distinct within Nagios:

  • A host can be defined by its name, IP address, and few other parameters.
  • A service is a process or application that exists on a host.

Behind a service is a check program configured to run some tests at a predefined internal.  The test results are reported back to Nagios via an Exit Code: 

  • Exit code 0 means the test was okay = green;
  • Exit code 1 means warning = yellow;
  • Exit code 2 means critical = red; and,
  • Exit code 3 for unknown = orange.

For detail on parent-child relationships in Nagios, please reference the following post on the Nagios community:

http://community.nagios.org/2009/08/23/nagios-establishing-parent-child-relationship-is-both-easy-and-required/comment-page-1/

How it works

The previously available version of the integration, Nagios integration 2.0, was a simple one-way integration with Nagios outbound to xMatters, and used an xMatters event handler in Nagios to make a direct REST API call to xMatters for Host Events and Service Events.  The 3.0 version integration allows for two-way capability using the xMatters integration agent. 

From Nagios to xMatters

In Nagios, event handlers are optional system commands (scripts or executables) that are run whenever a host or service state change occurs.  For example, global host and service event handlers are run for every host or service state change that occurs, immediately prior to any host- or service-specific event handler that may be run. For more detail refer to the Nagios documentation:
 https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/eventhandlers.html

The xMatters Event Handler in Nagios makes a command line call via APClient.bin, passing the required parameters to submit an event via the integration agent to xMatters.  The updated xMatters Event Handler PHP file is included in the integration package.  

From xMatters to Nagios

The recommended approach from Nagios to communicate and acknowledge back and/or make updates (add comments etc.) to the Nagios event, is to use external commands.  For reference see:
 http://support.nagios.com/forum/viewtopic.php?f=6&t=30367 

Callbacks from xMatters can be configured to communicate event status, message delivery, and responses back to the integration agent for processing. In the response processing, the integration agent catches the call back in the response handler and creates a command file that will be run by Nagios to make updates back to the events in Nagios.

Nagios External Command reference:
https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/extcommands.html

Available External Commands:
http://old.nagios.org/developerinfo/externalcommands/commandlist.php

This integration uses the following external commands:

  • ACKNOWLEDGE_HOST_PROBLEM
  • ACKNOWLEDGE_SVC_PROBLEM
  • ADD_HOST_COMMENT
  • ADD_SVC_COMMENT

Integration created and supplied by Jeremy Watkins.

Download the integration package

To begin, download the integration archive attached to this article and extract it to a location on your local machine. Some of the instructions in this article will reference specific folders within the extracted integration archive. 

Configure xMatters

The first step in setting up your integration is to configure xMatters.

Create a REST API user

This integration requires a REST API user to authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but not update administrative settings. The best way to create a user for this integration is to have a dedicated "REST Web Service User" role that includes the permissions and capabilities. If this role does not exist in your deployment, you will need to create it, or ask your xMatters Client Success Manager to create it for you. (For detailed procedures about creating the role, see Authentication and Permissions.)

In the following example, this role is named "REST Web Service User".

To create a REST API user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click the Add New User icon.
  3. Enter the appropriate information for your new user.
  4. Assign the user to the REST Web Service User role.
  5. Click Save.
  6. On the next page, set the web login ID and password. 
Make a note of these details; you will need them when configuring other parts of this integration.

Create users and groups to receive notifications

Create users and groups that will receive notifications. Rules can be configured in Nagios to associate a host event or service event with a group or user. The group or user associated with an event must match the name of a group or user in xMatters. A Nagios administrator will need to configure to associate the correct user/group in Nagios upon event creation for both host and service events.

You can also create multiple groups and users at once using the EPIC feature. 

Import the communication plan

The next step is to import the communication plan.

To import the communication plan:

  1. In the target xMatters system, on the Developer tab, click Import Plan.
  2. Click Browse, and then locate the following file within the extracted integration archive:
/components/xMatters/NagiosXI.zip
  1. Click Import Plan.
  2. Once the communication plan has been imported, click Plan Disabled to enable the plan.
  3. In the Edit drop-down list, select Forms.
  4. For the Host Notifications and Service Notifications forms, in the Not Deployed drop-down list, click Create Event Web Service.
    • After you create the web service, the drop-down list label will change to Web Service Only.
  5. For each form, in the Web Service Only drop-down list, click Permissions.
  6. Enter the REST API user you created above, and then click Save Changes.

Accessing web service URLs

To get the web service URL for a form, in the Web Service Only drop-down list, click Access Web Service URL. Copy the highlighted URL at the top of the dialog box.

Note: The Access Web Service URL option appears twice in the drop-down menu. Ensure that you click the option just below Create Event Web Service.

You'll need these URLs when you configure the rest of the integration.

Create integration services

This integration uses two integration services that need to be created on the "applications" event domain.

To create the integration services:

  1. In xMatters, on the Developer tab, click Event Domains.
  2. In the Event Domains list, click the applications link.
  3. On the Event Domain Details page, in the Integration Services section, click the Add New link.
  4. On the Integration Service Details page, in the Name field, type nagios-host and then click Save.
  5. Click the Add New link again.
  6. On the Integration Service Details page, in the Name filed, type nagios-service and then click Save.

Configure the xMatters integration agent

Now that you've configured xMatters On-Demand, it's time to configure the integration agent

The installation instructions below assume you already have a working xMatters integration agent.  If this is a new installation and you have not yet deployed the integration agent please follow this link to download, deploy, and configure:

Integration Agent for xMatters 5.x & xMatters On-Demand

Install the package

The installation package contains all that you need to configure the Nagios XI integration.

To install the package:

  1. Within the extracted integration archive, navigate to:
    /components/xMatters Integration Agent
  2. Copy the contents of this folder to the installation directory of the integration agent: for example: C:\integrationagent-5.1.5
    • This folder is referred to as <IAHOME> in the remainder of the instructions.
  3. Open the <IAHOME>/conf/IAConfig.xml file and add the following line to the "service-configs" section:
    <path>integrationservices/applications/nagios/nagios_host.xml</path>
    <path>integrationservices/applications/nagios/nagios_service.xml</path>
  4. Save and close the file.
  5. Open the configuration_host.js file found in the <IAHOME>\integrationservices\applications\nagios folder and add or set the values for the following variables:
WEB_SERVICE_URL The web service URL of the "Host Notifications" communication plan form (see Accessing web service URLs, above).
INITIATOR The User ID of the REST API user you created in xMatters.
PASSWORD

Path and filename of the password file containing the encrypted REST API user's password.

For more information about creating this file, refer to the xMatters integration agent guide.

CALLBACKS Specify the types of callbacks you want xMatters to include when sending updates to the integration agent; valid values are "status", "deliveryStatus", and "response".
  1. Save and close the file.
  2. Open the configuration_service.js file found in the <IAHOME>\integrationservices\applications\nagios folder and add or set the values for the following variables:
WEB_SERVICE_URL The web service URL of the "Service Notifications" communication plan form (see Accessing web service URLs, above).
INITIATOR The User ID of the REST API user you created in xMatters.
PASSWORD

Path and filename of the password file containing the encrypted REST API user's password.

For instructions on how to configure this file, see "Setting password files", below.

CALLBACKS Specify the types of callbacks you want xMatters to include when sending updates to the integration agent; valid values are "status", "deliveryStatus", and "response".
  1. Save and close the file.
  2. Restart the integration agent.

Setting password files

This integration includes encrypted files, located in the <IAHOME>\conf folder, that store the passwords for the REST API user. You will need to update (or create) the file with the correct password for the REST API user you created above.

To configure the REST API user password:

  1. Open a command prompt and navigate to <IAHOME>\bin.
  2. Run the following command, where <new_password> is the password for the INITIATOR user specified in the <IAHOME>\integrationservices\nagios\configuration.js file, and <old_password> is the existing password (the default for a newly installed integration is "password"):
iapassword.bat --new <new_password> --old <old_password> --file conf/.initiatorpasswd

For more information about working with the iapassword command, and creating password files, refer to the xMatters integration agent guide.

You can now configure the passwords for the integration services.

  1. Open the <IAHOME>\integrationservices\applications\nagios\nagios_host.xml file.
  2. Add (or locate and uncomment) the following constants section, and make sure the <file> tag indicates the correct encrypted password file:
   <constants>
      <encrypted-constant name="xmpassword" type="string" overwrite="true">
        <file>conf/.initiatorpasswd</file>
      </encrypted-constant>
   </constants>
  1. Save and close the file.
  2. Open the <IAHOME>\integrationservices\applications\nagios\nagios_service.xml file.
  3. Add (or locate and uncomment) the following constants section, and make sure the <file> tag indicates the correct encrypted password file:
   <constants>
      <encrypted-constant name="xmpassword" type="string" overwrite="true">
        <file>conf/.initiatorpasswd</file>
      </encrypted-constant>
   </constants>
  1. Save and close the file.

Configure the integration

Now that you've configured xMatters to integrate with your system, it's time to configure your system to integrate with xMatters. 

Installing the xMatters component in Nagios

Log in to the Nagios XI user interface and navigate to Admin > Manage Components:

On the Manage Components screen, select the components\NagiosXI\xmatters.zip file in the extracted integration archive, and then click Upload Component:

The xMatters Event Handlers component will appear:

The connection settings for the event handler ARE NOT USED for the xMatters Nagios 3.0 Integration.

IMPORTANT NOTE

The URL, Username, Password, and Recipient specified in Nagios via the Nagis XI User Interface for the Event Handler are NOT USED by this integration. These are legacy fields from the xMatters Nagios 2.0 integration.

For the xMatters Nagios 3.0 integration, the PHP has been updated to make a direct call to the integration agent. The Nagios Admin will need to update the event handler to specify the correct path for the integration agent. The integration agent is manually configured via the configure*.js and XML files to specify the form and user name.

Test the integration

To test the integration, generate a test host or service event in Nagios that matches the defined trigger criteria for the corresponding event handler, and then:

  1. Verify the group/user associated with the event in Nagios.
  2. Validate that a corresponding event was submitted via the integration agent to xMatters.
  3. Wait for the user/group to be notified by xMatters.
  4. Reply to the message with an 'Acknowledge' response.

xMatters will send an update to Nagios with response details:

Download resources

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk