Documentation

SystemMonitoring
Basic mail interface to System Monitoring Suites. Also
provides deeper integration to Nagios (Acknowledge
on lock and Checkscript). Version 2.5.2 Edition

Build Date:
2013-09-23

GNU AFFERO GENERAL PUBLIC LICENSE

Version 3, November 2007This work is
copyrighted by OTRS AG, Norsk-Data-Str. 1,
61352 Bad Homburg, Germany.Build Date:
2013-09-23

Table of Contents
Preface ............................................................................................................................... iii
1. Feature List .................................................................................................................... 1
1. Control flow ............................................................................................................ 1
2. System Requirements .................................................................................................... 2
1. Framework .............................................................................................................. 2
2. Packages ................................................................................................................. 2
3. Operating System ................................................................................................... 2
4. Third Party Software ............................................................................................... 2
3. Installation ...................................................................................................................... 3
1. Admin Interface ...................................................................................................... 3
2. Command Line ........................................................................................................ 3
4. Configuration .................................................................................................................. 4
1. Creation of dynamic fields ...................................................................................... 4
2. FromAddressRegExp ................................................................................................ 4
3. StateRegExp ............................................................................................................ 4
4. NewTicketRegExp .................................................................................................... 4
5. CloseTicketRegExp .................................................................................................. 4
6. CloseActionState ..................................................................................................... 4
7. ClosePendingTime ................................................................................................... 4
8. HostRegExp ............................................................................................................. 4
9. FreeTextHost ............................................................................................................ 5
10. ServiceRegExp ...................................................................................................... 5
11. DefaultService ....................................................................................................... 5
12. FreeTextService ..................................................................................................... 5
13. FreeTextState ........................................................................................................ 5
14. SenderType ........................................................................................................... 5
15. ArticleType ............................................................................................................ 5
16. Integration with OTRS Configuration Management ............................................... 5
5. Usage ............................................................................................................................. 6
1. Title ......................................................................................................................... 6
6. Technical Implementation Details ................................................................................... 7
7. Filelist ............................................................................................................................. 8
8. ChangeLog ...................................................................................................................... 9
9. Contacts ....................................................................................................................... 10
1. OTRS AG ............................................................................................................... 10

ii

Preface
This module implements a basic interface to System Monitoring Suites. It works by receiving
email messages sent by a Network Monitoring Suite. New tickets are created in case
of component failures. Once a ticket has been opened messages regarding the effected
component are attached to this ticket. When the component recovers, the ticket state can
be changed or the ticket can be closed.
If an open ticket for a given Host/Service combination exists, all mails concerning this
particular 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.

iii

Chapter1.Feature List
1.Control flow
The following diagram illustrates how mails are handled by this module and in which
cases they trigger which action. Pretty much all checks are configurable using the regular
expressions 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 treats
incoming mails. By changing the regular expressions it should be possible to adopt it to
different monitoring systems.

Chapter2.System Requirements
1.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 of
sending out events via e-mail.

Chapter3.Installation
The 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 note
that 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 the
following command line tool ("bin/otrs.PackageManager.pl") instead.
shell> bin/otrs.PackageManager.pl
SystemMonitoring-2.5.2.opm

-a install -p /path/to/

Chapter4.Configuration
To allow flexible integration between OTRS and a System Monitoring Suite the following
configuration options are available. The default values (as shown below) should be suitable
for 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 values
of FreeTextHost, FreeTextService and FreeTextState.

2.FromAddressRegExp
Only mails matching this "From:" address will be considered for this filter. You need to adjust
this 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 the
old status stays, or the name of the new status. Please note, that this state needs to be
configured 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). Please
note that this setting will be ignored by OTRS versions older than 2.2. On these systems the
pending time already associated with the ticket will be used, which may have in surprising
effects. 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*'

9.FreeTextHost
A dynamic field (type ticket) to store the affected host. The field name has to be named
like free text fields (TicketFreeTextField[1..16]) because of downward compatibility. Example
value: '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 free
text 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 free
text 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 configuration
option 'SystemMonitoring::SetIncidentState' is set to 'Yes', a CI with the given host name
is searched in the CI database. If exactly one CI with this name was found, the current
incident state is set automatically according to the incoming mail (Incident / Operational). If
the OTRS::ITSM Configuration Management module is installed and the configuration option
'SystemMonitoring::LinkTicketWithCI' is set to 'Yes', a CI is linked automatically with the
system monitoring incident ticket. This is only possible if a subsequent system monitoring
email arrives!

Chapter5.Usage
1.Title
Details.

Chapter6.Technical Implementation Details

Technical Implementation Details.

Chapter7.Filelist
This 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

Chapter8.ChangeLog
2.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.

Chapter9.Contacts
People who are involved in this implementation.

1.OTRS AG
Accounting: Ren Bakker <sales@otrs.com>, Phone +49 (0)6172 681988 0
Technical: Manuel Hecht, Oliver Roettges <dev-support@otrs.com>, Phone +49 (0)6172
681988 0

10