Dokumentation: Integrating OTRS with NAGIOS

The integration works as follows:
When NAGIOS notices a host or service problem it starts a perl-script that sends an Email to OTRS. A Tickets is created by OTRS after recieving the message.
When the problem still exists after some time, NAGIOS calls the script again. This time the script does not send an email to OTRS, but calls a modified copy of GenericAgent (over SSH) to add a note to the existing Ticket. When the problem has vanished NAGIOS calls the script again, which then closes the ticket the same way.

I tried to make the scripts as independent of the OTRS-version as possible, but as I use a modified copy of the GenericAgent.pl there is problably the need to do some minor adjustments to this perl-script when using a different version of OTRS than 1.2.2.

Requirements:
OTRS 1.2.2 (small modification in NagiosGenericAgent.pl might be necessary for other versions)
NAGIOS 1.2 (should work with other Versions too. Nagios only needs to be able to call an external script when notifying OTRS and some nagios-macros are needed)
MailTools from CPAN (on the Nagios Server, I used MailTools-1.65)

Installation Instructions:

A Configuration of the Nagios Server
------------------------------------
1) copy the script otrs_ticket_handler.pl to (e.g.) /usr/lib/nagios/ and make this script executable for the nagios-user
2) define commands that are used for notifications to OTRS (e.g. in /etc/nagios/misccommands.cfg)
# for service notifications 
define command{
        command_name    notify-by-email_otrs
        command_line    /usr/lib/nagios/otrs_ticket_handler.pl -T s -H $HOSTNAME$ -S '$SERVICEDESC$' -s '$SERVICESTATE$' -N '$NOTIFICATIONTYPE$' -n '$NOTIFICATIONNUMBER$' -o '$OUTPUT$' -C '$CONTACTALIAS$' -a '$HOSTADDRESS$'
        }
# for host notifications
define command{
        command_name    host-notify-by-email_otrs
        command_line    /usr/lib/nagios/otrs_ticket_handler.pl -T h -H $HOSTNAME$ -S '__' -s '$HOSTSTATE$' -N '$NOTIFICATIONTYPE$'-n '$NOTIFICATIONNUMBER$' -o '$OUTPUT$' -C '$CONTACTALIAS$' -a '$HOSTADDRESS$'
        }
3) Define a contact (or several contacts) for OTRS notifications (e.g. in /etc/nagios/contacts.cfg)
# alias must be the otrs-queue where the notifications for this contact should go to!!
# 'OTRS' contact definition
  define contact {
        contact_name                    OTRS
        alias                           my_nagios_queue
        service_notification_period     24x7
        host_notification_period        24x7
        service_notification_options    c,r,w,u
        host_notification_options       d,u,r
        service_notification_commands   notify-by-email_otrs
        host_notification_commands      host-notify-by-email_otrs
        email                           dummy@email.address
        }

4) Configure the otrs_ticket_handler.pl script (look at the comments in the script)

5) Allow the NAGIOS server to execute the NagiosGenericAgengt.pl script on the OTRS host:
- create a ssh key pair for the nagios user (e.g. with ssh-keygen)
- add the public key to the ~/.ssh/authorized_keys file of the otrs user on the OTRS host. (if it's not the create the directory and create the authorized_keys file)

B. Configuration of the OTRS server
-----------------------------------
1) create OTRS-queues where the NAGIOS-tickets should appear. The queue names should correspond to the contact aliases from NAGIOS (-> section A. 3) )

2) copy the NagiosGenericAgent.pl script to the OTRS host (e.g. to /opt/otrs/bin/). Make sure that it is executable by the otrs user.

3) configure NagiosGenericAgent.pl (look at the comments!). The settings must correspond to the TicketFreeText settings in Config.pm and otrs_ticket_handler.pl

4) configure OTRS so that it interprets the X-OTRS-Headers in emails that come from the NAGIOS host
e.g in ~otrs/.procmailrc:
# --
# Remove all X-OTRS Header (allow this only for trusted email)
# e. g. from *@example.com
# --
:0 fhw :
* !^From.*my_nagios_host.com
| grep -vi '^X-OTRS-'

5) TicketFreeKey / TicketFreeText configuration in Config.pm
hostname, servicename and host-/service state are stored in these fields.
Use the same settings as in otrs_ticket_handler.pl and NagiosGenericAgent.pl    
    # host name
    $Self->{"TicketFreeKey2"} = {
        'Server' => 'Server',
    };
    # service name
    $Self->{"TicketFreeKey3"} = {
        'Service' => 'Service',
    };
    # host-/service state
    $Self->{"TicketFreeKey4"} = {
        'Service-Status' => 'Service-Status',
        'Server-Status' => 'Server-Status',
    };