Nagios Notifications

xMatters includes two built-in triggers to initiate flows when xMatters receives signals from Nagios: one for Nagios Host Notifications and one for Nagios Service Notifications. You can include both trigger types on the same canvas if required, but signals from Nagios host notifications will not trigger Nagios service notification flows, and vice versa. The configuration instructions describe how to set up both the Host Notification and Service Notifications triggers for Nagios Core and Nagios XI.

Add the trigger to the canvas

  1. Go to the Triggers tab in the palette, expand the App Triggers section, and then drag either the Nagios Host Notification or Nagios Service Notification trigger onto the canvas.
  2. Double-click the trigger (or click the pencil icon).
  3. Set the authenticating user, and then copy the URL — you'll use this to set up the webhook in Nagios. Alternatively, you can create an integration user to use as the authenticating user.

  4. Click the Flood Control tab to edit the trigger's default flood control settings. For more information about these settings, see Trigger Flood Control.
  5. Click Done.
  6. On the flow canvas, connect the steps you want to run when xMatters receives a request to that URL.

You're now ready to configure Nagios to target the trigger.

Configure Nagios Core to send requests to the trigger URL

The following instructions describe how to configure Nagios Core to send signals to your triggers.

To have Nagios Core send host notifications to the flow trigger, you need to configure a webhook and set it to use the trigger URL.

  1. Go to the location of your Nagios Core configuration files. For example, /opt/nagios/etc.
  2. Create a new file in the configuration folder and name it xmatters.cfg.
  3. Open the new xmatters.cfg file and populate it with configuration information:
    • To use URL Authentication, use the following configuration, replacing <URL_FROM_XMATTERS> with the URL you copied from the Nagios Host Notifications trigger.
      Copy
      define contact {
          contact_name                            xmatters
          service_notification_period             24x7
          host_notification_period                24x7
          service_notification_options            w,u,c,r
          host_notification_options               d,r
          host_notification_commands              notify_xmatters_host
      }

      define command {
          command_name    notify_xmatters_host
          command_line    curl -X POST -H "Content-Type: application/json" -d ' { "OBJECTTYPE": "HOST", "CONTACTGROUPNAME": "$HOSTDISPLAYNAME$", "HOSTDISPLAYNAME": "$HOSTDISPLAYNAME$", "HOSTNAME": "$HOSTNAME$", "HOSTOUTPUT": "$HOSTOUTPUT$", "HOSTSTATE": "$HOSTSTATE$", "LASTHOSTSTATECHANGE": "$LASTHOSTSTATECHANGE$", "NOTIFICATIONAUTHOR": "$NOTIFICATIONAUTHOR$", "NOTIFICATIONCOMMENT": "$NOTIFICATIONCOMMENT$", "NOTIFICATIONTYPE": "$NOTIFICATIONTYPE$", "SHORTDATETIME": "$SHORTDATETIME$" } ' "<URL_FROM_XMATTERS>" 
      }
    • To use Basic Authentication, use the following configuration. Replace <URL_FROM_XMATTERS> with the URL you copied from the trigger, and username:password with the username and password of the authenticating xMatters user.
      Copy
      define contact {
          contact_name                            xmatters
          service_notification_period             24x7
          host_notification_period                24x7
          service_notification_options            w,u,c,r
          host_notification_options               d,r
          host_notification_commands              notify_xmatters_host
      }
       
      define command {
          command_name    notify_xmatters_host
          command_line    curl -X POST -u username:password -H "Content-Type: application/json" -d ' { "OBJECTTYPE": "HOST", "CONTACTGROUPNAME": "$HOSTDISPLAYNAME$", "HOSTDISPLAYNAME": "$HOSTDISPLAYNAME$", "HOSTNAME": "$HOSTNAME$", "HOSTOUTPUT": "$HOSTOUTPUT$", "HOSTSTATE": "$HOSTSTATE$", "LASTHOSTSTATECHANGE": "$LASTHOSTSTATECHANGE$", "NOTIFICATIONAUTHOR": "$NOTIFICATIONAUTHOR$", "NOTIFICATIONCOMMENT": "$NOTIFICATIONCOMMENT$", "NOTIFICATIONTYPE": "$NOTIFICATIONTYPE$", "SHORTDATETIME": "$SHORTDATETIME$" } ' "<URL_FROM_XMATTERS>" 
      }
  4. Add the target names of any recipients you want to notify when the alert fires to the end of the URL.
    • For URL authentication, use an ampersand to attach recipients. For example, if you want to notify Emma Pearson and the on-call members in the group responsible for the Antares service, you'd add &recipients=epearson,antares to the URL.
    • For other authentication types, use a question mark to attach recipients. For example, if you want to notify Barry Gull and the on-call members in the group responsible for the Cassiopeia service, you'd add ?recipients=bgull,cassiopeia to the URL.
    • You must URL-encode any special characters or spaces in the target names.
  5. Save and close the xmatters.cfg file.
  6. Open the nagios.cfg file and go to the Object Configuration Files section.
  7. Add a new line to the section and type the absolute path to the xmatters.cfg file you just created. For example: cfg_file=/path/to/xmatters.cfg.
  8. Save and close the nagios.cfg file.
  9. Navigate to the options folder and open any host definitions that will send alerts to xMatters. Add contacts xmatters to the define host section.

  10. Restart Nagios Core to use the new configuration.

You're ready to use the webhook to trigger automated flows, including steps such as sending alerts and initiating incidents, though we always recommend testing before putting things into use. To test the webhook:

  1. Open Nagios Core and select a host configuration set up to contact xMatters.

  2. Select Forced and add a comment.

  3. Click Commit to send the notification.
  4. If you do not receive the notification in xMatters, check the Nagios log file. If the notification was sent, you'll see the following line: SERVICE NOTIFICATION: xmatters;localhost;PING;CUSTOM (OK);notify_xmatters_host

To have Nagios Core send service notifications to the flow trigger, you need to configure a webhook and set it to use the trigger URL.

  1. Go to the location of your Nagios Core configuration files. For example, /opt/nagios/etc.
  2. Create a new file in the configuration folder and name it xmatters.cfg.
  3. Open the new xmatters.cfg file and populate it with configuration information:
    • To use URL Authentication, use the following configuration, replacing <URL_FROM_XMATTERS> with the URL you copied from the Nagios Service Notifications trigger.
      Copy
      define contact {
              contact_name                            xmatters
              service_notification_period             24x7
              host_notification_period                24x7
              service_notification_options            w,u,c,r
              host_notification_options               d,r
              service_notification_commands           notify_xmatters_service
      }
       
      define command {
              command_name    notify_xmatters_service
              command_line    curl -X POST -H "Content-Type: application/json" -d ' { "OBJECTTYPE": "SERVICE", "HOSTNAME": "$HOSTNAME$", "CONTACTGROUPNAME": "$SERVICEDISPLAYNAME$", "LASTSERVICESTATECHANGE": "$LASTSERVICESTATECHANGE$", "NOTIFICATIONAUTHOR": "$NOTIFICATIONAUTHOR$", "NOTIFICATIONCOMMENT": "$NOTIFICATIONCOMMENT$", "NOTIFICATIONTYPE": "$NOTIFICATIONTYPE$", "SERVICEDESC": "$SERVICEDESC$", "SERVICEOUTPUT": "$SERVICEOUTPUT$", "SERVICESTATE": "$SERVICESTATE$", "SHORTDATETIME": "$SHORTDATETIME$" } ' "<URL_FROM_XMATTERS>"
      }
    • To use Basic Authentication, use the following configuration. Replace <URL_FROM_XMATTERS> with the URL you copied from the trigger, and username:password with the username and password of the authenticating xMatters user.
      Copy
      define contact {
              contact_name                            xmatters
              service_notification_period             24x7
              host_notification_period                24x7
              service_notification_options            w,u,c,r
              host_notification_options               d,r
              service_notification_commands           notify_xmatters_service
      }

      define command {
              command_name    notify_xmatters_service
              command_line    curl -X POST -u username:password -H "Content-Type: application/json" -d ' { "OBJECTTYPE": "SERVICE", "HOSTNAME": "$HOSTNAME$", "CONTACTGROUPNAME": "$SERVICEDISPLAYNAME$", "LASTSERVICESTATECHANGE": "$LASTSERVICESTATECHANGE$", "NOTIFICATIONAUTHOR": "$NOTIFICATIONAUTHOR$", "NOTIFICATIONCOMMENT": "$NOTIFICATIONCOMMENT$", "NOTIFICATIONTYPE": "$NOTIFICATIONTYPE$", "SERVICEDESC": "$SERVICEDESC$", "SERVICEOUTPUT": "$SERVICEOUTPUT$", "SERVICESTATE": "$SERVICESTATE$", "SHORTDATETIME": "$SHORTDATETIME$" } ' "<URL_FROM_XMATTERS>" 
      }
       
  4. Add the target names of any recipients you want to notify when the alert fires to the end of the URL.
    • For URL authentication, use an ampersand to attach recipients. For example, if you want to notify Emma Pearson and the on-call members in the group responsible for the Antares service, you'd add &recipients=epearson,antares to the URL.
    • For other authentication types, use a question mark to attach recipients. For example, if you want to notify Barry Gull and the on-call members in the group responsible for the Cassiopeia service, you'd add ?recipients=bgull,cassiopeia to the URL.
    • You must URL-encode any special characters or spaces in the target names.
  5. Save and close the xmatters.cfg file.
  6. Open the nagios.cfg file and go to the Object Configuration Files section.
  7. Add a new line to the section and type the absolute path to the xmatters.cfg file you just created. For example: cfg_file=/path/to/xmatters.cfg.
  8. Save and close the nagios.cfg file.
  9. Navigate to the options folder and open any service definitions that will send alerts to xMatters. Add contacts xmatters to the define service section.

  10. Restart Nagios Core to use the new configuration.

You're ready to use the webhook to trigger automated flows, including steps such as sending alerts and initiating incidents, though we always recommend testing before putting things into use. To test the webhook:

  1. Open Nagios Core and select a service configuration set up to contact xMatters.
  2. Add a comment, and then click Commit to send the notification.

  3. If you do not receive the notification in xMatters, check the Nagios log file for the following line: SERVICE NOTIFICATION: xmatters;localhost;PING;CUSTOM (OK);notify_xmatters_service

Configure Nagios XI to send requests to the trigger URL

The following instructions describe how to configure Nagios XI to send signals to your triggers.

To have Nagios XI send host notifications to the flow trigger, you need to configure a webhook and set it to use the trigger URL.

  1. In Nagios XI go to Configure, and then select Core Config Manager.
  2. Select Commands from the left-hand sidebar.
  3. Click + Add New to add a command.
  4. On the Command Management page fill in the fields with information about the host:
    • Command Name: notify_xmatters_host
    • Command Line: Paste the configuration information into the command line based on your preferred authentication type.
      • URL Authentication: Replace the <URL_FROM_XMATTERS> with the URL you copied from the Nagios Host Notifications trigger.
        Copy
        curl -X POST -H "Content-Type: application/json" -d ' { "OBJECTTYPE": "HOST", "CONTACTGROUPNAME": "$HOSTDISPLAYNAME$", "HOSTDISPLAYNAME": "$HOSTDISPLAYNAME$", "HOSTNAME": "$HOSTNAME$", "HOSTOUTPUT": "$HOSTOUTPUT$", "HOSTSTATE": "$HOSTSTATE$", "LASTHOSTSTATECHANGE": "$LASTHOSTSTATECHANGE$", "NOTIFICATIONAUTHOR": "$NOTIFICATIONAUTHOR$", "NOTIFICATIONCOMMENT": "$NOTIFICATIONCOMMENT$", "NOTIFICATIONTYPE": "$NOTIFICATIONTYPE$", "SHORTDATETIME": "$SHORTDATETIME$" } ' "<URL_FROM_XMATTERS>"
      • Basic Authentication: Replace <URL_FROM_XMATTERS> with the URL you copied from the trigger, and username:password with the username and password of the authenticating xMatters user.
        Copy
        curl -X POST -u username:password -H "Content-Type: application/json" -d ' { "OBJECTTYPE": "HOST", "CONTACTGROUPNAME": "$HOSTDISPLAYNAME$", "HOSTDISPLAYNAME": "$HOSTDISPLAYNAME$", "HOSTNAME": "$HOSTNAME$", "HOSTOUTPUT": "$HOSTOUTPUT$", "HOSTSTATE": "$HOSTSTATE$", "LASTHOSTSTATECHANGE": "$LASTHOSTSTATECHANGE$", "NOTIFICATIONAUTHOR": "$NOTIFICATIONAUTHOR$", "NOTIFICATIONCOMMENT": "$NOTIFICATIONCOMMENT$", "NOTIFICATIONTYPE": "$NOTIFICATIONTYPE$", "SHORTDATETIME": "$SHORTDATETIME$" } '  "<URL_FROM_XMATTERS>"
    • Command Type: misc command
  5. Add the target names of any recipients you want to notify when the alert fires to the end of the URL.
    • For URL authentication, use an ampersand to attach recipients. For example, if you want to notify Emma Pearson and the on-call members in the group responsible for the Antares service, you'd add &recipients=epearson,antares to the URL.
    • For other authentication types, use a question mark to attach recipients. For example, if you want to notify Barry Gull and the on-call members in the group responsible for the Cassiopeia service, you'd add ?recipients=bgull,cassiopeia to the URL.
    • You must URL-encode any special characters or spaces in the target names.
  6. Click Save.

Now that the host is configured, create a contact to connect the configurations.

  1. Select Contacts from the left-hand sidebar.
  2. Click + Add New to add a new contact.
  3. Give the contact a unique and easy to find name. For example, xMatters.
  4. Go to the Alert Settings tab and set the Manage Host Notification Commands to notify_xmatters_host
  5. Click Save.
  6. Add the xMatters contact to any host definitions that will send alerts to xMatters.

You're ready to use the webhook to trigger automated flows, including steps such as sending alerts and initiating incidents, though we always recommend testing before putting things into use. To test the webhook:

  1. View a host or service you've configured to contact xMatters.
  2. Select the Advanced tab, and then select Send custom notification.

  3. Select Forced, add a comment, then click Submit.

  4. If you do not receive the notification in xMatters, check the Nagios Event Log to ensure the notification was sent.

To have Nagios XI send service notifications to the flow trigger, you need to configure a webhook and set it to use the trigger URL.

  1. In Nagios XI, go to Configure, and then select Core Config Manager.
  2. Select Commands from the left-hand sidebar.
  3. Click + Add New to add a command.
  4. On the Command Management page, fill in the following information about the service:
    • Command Name: notify_xmatters_service
    • Command Line: Paste the configuration information into the command line based on your preferred authentication type.
      • URL Authentication: Replace the <URL_FROM_XMATTERS> with the URL you copied from the Nagios Service Notifications trigger.
        Copy
        curl -X POST -H "Content-Type: application/json" -d ' { "OBJECTTYPE": "SERVICE", "HOSTNAME": "$HOSTNAME$", "CONTACTGROUPNAME": "$SERVICEDISPLAYNAME$", "LASTSERVICESTATECHANGE": "$LASTSERVICESTATECHANGE$", "NOTIFICATIONAUTHOR": "$NOTIFICATIONAUTHOR$", "NOTIFICATIONCOMMENT": "$NOTIFICATIONCOMMENT$", "NOTIFICATIONTYPE": "$NOTIFICATIONTYPE$", "SERVICEDESC": "$SERVICEDESC$", "SERVICEOUTPUT": "$SERVICEOUTPUT$", "SERVICESTATE": "$SERVICESTATE$", "SHORTDATETIME": "$SHORTDATETIME$" } ' "<URL_FROM_XMATTERS>"
      • Basic Authentication: Replace <URL_FROM_XMATTERS> with the URL you copied from the trigger, and username:password with the username and password of the authenticating xMatters user.
        Copy
        curl -X POST -u username:password -H "Content-Type: application/json" -d ' { "OBJECTTYPE": "SERVICE", "HOSTNAME": "$HOSTNAME$", "CONTACTGROUPNAME": "$SERVICEDISPLAYNAME$", "LASTSERVICESTATECHANGE": "$LASTSERVICESTATECHANGE$", "NOTIFICATIONAUTHOR": "$NOTIFICATIONAUTHOR$", "NOTIFICATIONCOMMENT": "$NOTIFICATIONCOMMENT$", "NOTIFICATIONTYPE": "$NOTIFICATIONTYPE$", "SERVICEDESC": "$SERVICEDESC$", "SERVICEOUTPUT": "$SERVICEOUTPUT$", "SERVICESTATE": "$SERVICESTATE$", "SHORTDATETIME": "$SHORTDATETIME$" } ' "<URL_FROM_XMATTERS>"
    • Command Type: misc command
  5. Add the target names of any recipients you want to notify when the alert fires to the end of the URL.
    • For URL authentication, use an ampersand to attach recipients. For example, if you want to notify Emma Pearson and the on-call members in the group responsible for the Antares service, you'd add &recipients=epearson,antares to the URL.
    • For other authentication types, use a question mark to attach recipients. For example, if you want to notify Barry Gull and the on-call members in the group responsible for the Cassiopeia service, you'd add ?recipients=bgull,cassiopeia to the URL.
    • You must URL-encode any special characters or spaces in the target names.
  6. Click Save.

Now that the service is configured, create a contact to connect the configurations.

  1. Select Contacts from the left-hand sidebar.
  2. Click + Add New to add a new contact.
  3. Give the contact a unique and easy to find name. For example, xMatters.
  4. Go to the Alert Settings tab and set the Manage Service Notification Commands to notify_xmatters_service.
  5. Click Save.
  6. Add the xMatters contact to any service definitions that will send alerts to xMatters.

You're ready to use the webhook to trigger automated flows, including steps such as sending alerts and initiating incidents, though we always recommend testing before putting things into use. To test the webhook:

  1. View a service you've configured to contact xMatters.
  2. Select the Advanced tab and select Send custom notification.

  3. Add a comment, then click Submit.

  4. If you do not receive the notification in xMatters, check the Nagios Event Log to ensure the notification was sent.

Outputs

The following outputs apply to both Nagios Core and Nagios XI.

The Nagios Host Notification trigger has the following outputs you can use as inputs to steps further along the flow.

Label

 Description

Recipients

 List of targeted recipients. Recipients are set by adding a recipients query parameter to the trigger URL when you configure the webhook in Nagios.
Signal Mode Determines the path the flow will take, based on the value of Host State parameter.
Signal ID Key or identifier used to terminate or correlate signals.
Contact Group Name Name of the Nagios group this contact belongs to.
Host Display Name Alternate display name for the host.
Host Name Short name for the host.
Host Output First line of text output from the last host check.
Host State

Current state of the host. Valid values are:

  • UP
  • DOWN
  • UNREACHABLE
Last Host State Change Time the host last changed state.
Notification Author Author of the notification.
Notification Comment Comment on the notification provided by the author.
Notification Type Type of the notification in Nagios.
Object Type

Type of object. Valid values are: 

  • Service (for Service Notifications) 
  • Host (for Host Notifications)
Raw Request JSON representation of the request. You can parse the raw request if you need additional details beyond the standard outputs.

The Nagios Service Notification trigger has the following outputs you can use as inputs to steps further along the flow.

Label

 Description

Recipients

 List of targeted recipients. Recipients are set by adding a recipients query parameter to the trigger URL when you configure the webhook in Nagios.
Signal Mode Determines the path the flow will take, based on the value of Service State parameter.
Signal ID Key or identifier used to terminate or correlate signals.
Contact Group Name Name of the Nagios group this contact belongs to.
Host Name Short name for the host.
Last Service State Change Time the service last changed state.
Notification Author Author of the notification.
Notification Comment Comment on the notification provided by the authors.
Notification Type Type of the notification in Nagios.
Object Type

Type of object. Valid values are: 

  • Service
  • Host
Service Description Description of the service
Service Output First line of the text output from the last service check.
Service State Current state of the service in Nagios.
Timestamp Time the notification was sent from Nagios.
Raw Request JSON representation of the request. You can parse the raw request if you need additional details beyond the standard outputs.