Doc en SystemMonitoring

(1)

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

(2)

ii

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

(3)

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 ([email protected]) for more information.

(4)

1

Chapter 1. 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.

(5)

Chapter 2. 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.

(6)

3

Chapter 3. 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 -a install -p /path/to/ SystemMonitoring-2.5.2.opm

(7)

Chapter 4. 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: '[email protected]'

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.

(8)

5

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!

(9)

Chapter 5. Usage

1. Title

(10)

7

Chapter 6. Technical Implementation Details

(11)

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

(12)

9

Chapter 8. ChangeLog

2.5.2 / 2013-09-23 20:24:08

• Updated documentation.

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

(13)

Chapter 9. Contacts

People who are involved in this implementation.

1. OTRS AG

Accounting: René Bakker <[email protected]>, Phone +49 (0)6172 681988 0

Technical: Manuel Hecht, Oliver Roettges <[email protected]>, Phone +49 (0)6172 681988 0