Documentation

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

Build Date:
2013-05-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-05-23

Table of Contents
Preface ............................................................................................................................... iii
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. FromAddressRegExp ................................................................................................ 4
2. StateRegExp ............................................................................................................ 4
3. NewTicketRegExp .................................................................................................... 4
4. CloseTicketRegExp .................................................................................................. 4
5. CloseActionState ..................................................................................................... 4
6. ClosePendingTime ................................................................................................... 4
7. HostRegExp ............................................................................................................. 4
8. FreeTextHost ............................................................................................................ 4
9. ServiceRegExp ........................................................................................................ 5
10. DefaultService ....................................................................................................... 5
11. FreeTexyService ..................................................................................................... 5
12. SenderType ........................................................................................................... 5
13. ArticleType ............................................................................................................ 5
14. Integration with OTRS Configuration Management ............................................... 5
5. Contact ........................................................................................................................... 6
1. OTRS AG/OTRS Inc. ................................................................................................. 6
6. Change log ..................................................................................................................... 7

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.
Please contact your commercial support (support@otrs.com) if you have any queries
regarding this document or need further information.

iii

Chapter1.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.2.x

2.Packages
Following packages are required:
None

3.Operating system
Following operating systems are to be considered as dependency:
None

4.Third party software

Following software is required for package operation:
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 show how to install the package. Generally, there are two
possibilities: You can either use the Admin Interface or the command line.
After having successfully completed the installation, please follow the instructions provided
in the chapter "First steps".

1.Admin Interface
Using the following URL you can install, as well as update or uninstall (if necessary), the
package via the Admin Interface (please check whether the user is a member of the Admin
Group before starting.)
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/opm.pl") instead.
shell> bin/opm.pl -a install -p /path/to/SystemMonitoring-2.4.2.opm

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.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'

2.StateRegExp
Regular Expression to extract the state from the message.
Default: '\s*State:\s+(\S+)'

3.NewTicketRegExp
Regular expression for extracted state to trigger a new ticket
Default: 'CRITICAL|DOWN'

4.CloseTicketRegExp
Regular expression for extracted "State" to trigger ticket transition to "CloseActionState".
Default: 'OK|UP'

5.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'

6.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)

7.HostRegExp
Regular expression to extract the affected host.
Default: '\s*Address:\s+(\d+\.\d+\.\d+\.\d+)\s*'

8.FreeTextHost
Free text field index to store the name of the affected host.

Default: '1'

9.ServiceRegExp
Regular expression to extract the affected service.
Default: '\s*Service:\s+(.*)\s*'

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

11.FreeTexyService
Free text field index to store service.
Default: '2'

12.SenderType
Sender type used for creating tickets and attaching notes.
Default: 'system'

13.ArticleType
Article type used to attach follow up emails to existing tickets.
Default: 'note-report'

14.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.Contact
Please direct questions about the SystemMonitoring Module to:

1.OTRS AG/OTRS Inc.

E-mail: enjoy@otrs.com

Chapter6.Change log
2.4.2 / 2013-05-23 21:48:48
Including new handling for TicketID param.

2.4.1 / 2012-11-01 17:14:59

First version for OTRS 3.2.