GNU AFFERO GENERAL PUBLIC LICENSEVersion 3, November 2007This work iscopyrighted by OTRS AG, Norsk-Data-Str. 1,61352 Bad Homburg, Germany.Build Date:2013-09-23

Documentation

SystemMonitoringBasic mail interface to System Monitoring Suites. Alsoprovides deeper integration to Nagios (Acknowledge

on lock and Checkscript). Version 2.5.2 Edition

Build Date:

2013-09-23

ii

Table of ContentsPreface ............................................................................................................................... iii1. Feature List .................................................................................................................... 1

1. Control flow ............................................................................................................ 12. System Requirements .................................................................................................... 2

1. Framework .............................................................................................................. 22. Packages ................................................................................................................. 23. Operating System ................................................................................................... 24. Third Party Software ............................................................................................... 2

3. Installation ...................................................................................................................... 31. Admin Interface ...................................................................................................... 32. Command Line ........................................................................................................ 3

4. Configuration .................................................................................................................. 41. Creation of dynamic fields ...................................................................................... 42. FromAddressRegExp ................................................................................................ 43. StateRegExp ............................................................................................................ 44. NewTicketRegExp .................................................................................................... 45. CloseTicketRegExp .................................................................................................. 46. CloseActionState ..................................................................................................... 47. ClosePendingTime ................................................................................................... 48. HostRegExp ............................................................................................................. 49. FreeTextHost ............................................................................................................ 510. ServiceRegExp ...................................................................................................... 511. DefaultService ....................................................................................................... 512. FreeTextService ..................................................................................................... 513. FreeTextState ........................................................................................................ 514. SenderType ........................................................................................................... 515. ArticleType ............................................................................................................ 516. Integration with OTRS Configuration Management ............................................... 5

5. Usage ............................................................................................................................. 61. Title ......................................................................................................................... 6

6. Technical Implementation Details ................................................................................... 77. Filelist ............................................................................................................................. 88. ChangeLog ...................................................................................................................... 99. Contacts ....................................................................................................................... 10

1. OTRS AG ............................................................................................................... 10

iii

PrefaceThis module implements a basic interface to System Monitoring Suites. It works by receivingemail messages sent by a Network Monitoring Suite. New tickets are created in caseof component failures. Once a ticket has been opened messages regarding the effectedcomponent are attached to this ticket. When the component recovers, the ticket state canbe changed or the ticket can be closed.

If an open ticket for a given Host/Service combination exists, all mails concerning thisparticular combination will be attached to the ticket until it's closed.

If you have questions regarding this package, please contact your support team(support@otrs.com) for more information.

1Chapter1.Feature List1.Control flow

The following diagram illustrates how mails are handled by this module and in whichcases they trigger which action. Pretty much all checks are configurable using the regularexpressions given by the parameters listed above.

Mail matches 'FromAddress'?|+-> NO --> Continue with regular mail processing|+-> YES --> Does a ticket with matching Host/Service combination already exist in OTRS? | +-> NO -> Does 'State:' match 'NewTicketRegExp'? | | | +-> NO -> Stop processing this mail | | (silent drop) | | | +-> YES -> Create new ticket, record Host | and Service, attach mail | +-> YES -> Attach mail to ticket -> Does 'State:' match 'CloseTicketRegExp'? | +-> NO -> Continue with regular mail processing | +-> YES -> Change ticket type as configured in 'CloseActionState'

Besides of a few additional sanity checks this is how the SystemMonitoring module treatsincoming mails. By changing the regular expressions it should be possible to adopt it todifferent monitoring systems.

2Chapter2.System Requirements1.Framework

The following OTRS framework is required:

3.3.x

2.Packages

The following packages are required:

None

3.Operating System

This package requires one of the following operating systems:

None

4.Third Party Software

This third party software is required to use this package:

A network monitoring system, such as Nagios, or HP OpenView, or similar, capable ofsending out events via e-mail.

3Chapter3.InstallationThe following instructions explain how to install the package.

1.Admin Interface

Please use the following URL to install the package utilizing the admin interface (please notethat you need to be in the admin group).

http://localhost/otrs/index.pl?Action=AdminPackageManager

2.Command Line

Whenever you cannot use the Admin Interface for whatever reason, you may use thefollowing command line tool ("bin/otrs.PackageManager.pl") instead.

shell> bin/otrs.PackageManager.pl -a install -p /path/to/SystemMonitoring-2.5.2.opm

4Chapter4.ConfigurationTo allow flexible integration between OTRS and a System Monitoring Suite the followingconfiguration options are available. The default values (as shown below) should be suitablefor a standard Nagios installation.

1.Creation of dynamic fields

A requirement to get a working module is to use existing dynamic fields for the defined valuesof FreeTextHost, FreeTextService and FreeTextState.

2.FromAddressRegExp

Only mails matching this "From:" address will be considered for this filter. You need to adjustthis setting to the from address your System Monitoring Suite uses for outgoing mails.

Default: 'sysmon@mysystem.com'

3.StateRegExp

Regular Expression to extract the state from the message.

Default: '\s*State:\s+(\S+)'

4.NewTicketRegExp

Regular expression for extracted state to trigger a new ticket

Default: 'CRITICAL|DOWN'

5.CloseTicketRegExp

Regular expression for extracted "State" to trigger ticket transition to "CloseActionState".

Default: 'OK|UP'

6.CloseActionState

New status for ticket when service recovers. This can be either "OLD" in which case theold status stays, or the name of the new status. Please note, that this state needs to beconfigured in your OTRS installation as valid state. If the state you set here does not exist,the ticket state will not be altered.

Default: 'closed successful'

7.ClosePendingTime

Pending time in seconds for 'Pending...' statuses. (Ignored for other status types). Pleasenote that this setting will be ignored by OTRS versions older than 2.2. On these systems thepending time already associated with the ticket will be used, which may have in surprisingeffects. It's recommended not to use 'Pending...' states with OTRS prior to 2.2.

Default: '60*60*24*2' (2 days)

8.HostRegExp

Regular expression to extract the affected host.

Default: '\s*Address:\s+(\d+\.\d+\.\d+\.\d+)\s*'

59.FreeTextHost

A dynamic field (type ticket) to store the affected host. The field name has to be namedlike free text fields (TicketFreeTextField[1..16]) because of downward compatibility. Examplevalue: '1' for TicketFreeTextField1.

Default: '1'

10.ServiceRegExp

Regular expression to extract the affected service.

Default: '\s*Service:\s+(.*)\s*'

11.DefaultService

Default for "Service"; used if no service can be extracted, i.e. if host goes DOWN/UP.

Default: 'Host'

12.FreeTextService

A dynamic field (type ticket) to store the service. The field name has to be named like freetext fields (TicketFreeTextField[1..16]) because of downward compatibility. Example value: '2'for TicketFreeTextField2.

Default: '2'

13.FreeTextState

A dynamic field (type article) to store the state. The field name has to be named like freetext fields (ArticleFreeTextField[1..16]) because of downward compatibility. Example value:'1' for ArticleFreeTextField1.

Default: '1'

14.SenderType

Sender type used for creating tickets and attaching notes.

Default: 'system'

15.ArticleType

Article type used to attach follow up emails to existing tickets.

Default: 'note-report'

16.Integration with OTRS Configuration Management

If the OTRS::ITSM Configuration Management module is installed and the configurationoption 'SystemMonitoring::SetIncidentState' is set to 'Yes', a CI with the given host nameis searched in the CI database. If exactly one CI with this name was found, the currentincident state is set automatically according to the incoming mail (Incident / Operational). Ifthe OTRS::ITSM Configuration Management module is installed and the configuration option'SystemMonitoring::LinkTicketWithCI' is set to 'Yes', a CI is linked automatically with thesystem monitoring incident ticket. This is only possible if a subsequent system monitoringemail arrives!

6Chapter5.Usage1.Title

Details.

7Chapter6.Technical Implementation DetailsTechnical Implementation Details.

8Chapter7.FilelistThis list shows all included files and the referring permissions.

(644) doc/en/SystemMonitoring.xml

(755) bin/otrs.NagiosCheck.pl

(644) Kernel/Config/Files/SystemMonitoring.xml

(644) Kernel/Config/NagiosCheck.pm.example

(644) Kernel/System/PostMaster/Filter/SystemMonitoring.pm

(644) Kernel/System/Ticket/Event/NagiosAcknowledge.pm

(644) scripts/test/SystemMonitoring.t

(644) scripts/test/sample/SystemMonitoring1.box

(644) scripts/test/sample/SystemMonitoring2.box

(644) var/packagesetup/SystemMonitoring.pm

9Chapter8.ChangeLog2.5.2 / 2013-09-23 20:24:08

Updated documentation.

2.5.1 / 2013-09-05 01:32:55

First version for OTRS 3.2.x.

10

Chapter9.ContactsPeople who are involved in this implementation.

1.OTRS AG

Accounting: Ren Bakker , Phone +49 (0)6172 681988 0

Technical: Manuel Hecht, Oliver Roettges , Phone +49 (0)6172681988 0