]po[ ITSM Icinga2 Integration

Error: includelet 'en:hive_module_itsm' unknown

Icinga2  is an enterprise-class systems monitoring solutions for hosts, services, and networks released under an Open Source license. Together the two systems cover the entire process chain of ITIL complient IT Services Management:

Creating a Ticket

  • Incident detection - Icinga2 detects a malfunction
  • Icinga2 integration - ]po[ receives the Icinga2 email and creates an incident ticket for the specified configuration item.

Working with the Ticket

  • Incident management - ]po[ starts a workflow for the ticket, depending on the ticket type.
    The workflow includes information about where to queue the ticket and whether a customer sign-off is necessary or not.
  • Problem management - IT staff can "escalates" the incident by creating a problem ticket, which in turn starts is own workflow and queue assignations.
  • Configuration management - all tickets are associated with the affected configuration item, allowing users to track the incident history per CI. ]po[ can parse the Icinga2 configuration files (icinga2.conf and the contents of the /objects/ folder in Icinga2 2.0) in order to synchronize the Icinga2 CIs with the ]po[ CIs. Future versions of ]po[ will also be able to create Icinga2 configuration files.
  • Knowledge management - all comments and other text related to tickets are stored in the ]po[ full-text search engine and accessible for users with access rights to the specific ticket.

Closing the Ticket

  • A recovery mail from Icinga2 automatically closes the ticket.
  • Alternatively, the CVS integration may close the ticket if a CVS or SVN commit includes a comment of type "fixed #123".

Integration With Other Modules

  • Timesheet management - ]po[ tickets are linked with the timesheet management, so that all participants can log hours against tickets
  • Financial management - time and material spent on tickets are summed up a the SLA level and allow the organization to bill customers the provided services
  • Release management - changes in CVS or SVN are automatically re

Icinga2 Integration Overview

The Icinga2 integration is based on the following components:

  • A locally running Postfix instance receives emails (possibly imported via fetchmail) and delivers them to ~/Maildir/new/
  • An OpenACS "acs-mail-lite" process scans ~/Maildir every few minutes
  • ]po['s "intranet-icinga2" package receives callbacks from acs-mail-lite, parses the Icinga2 subject line and extracts extract all important variables (host, service, status etc.):
  • ]po[ check is there is already an open ticket for the specified host/service and add the current message to the existing ticket
  • If necessary, ]po[ generates a new host and/or service as "Configuration Items" in the configuration database.
  • Alternatively, ]po[ can also parse the Icinga2 configuration files and import all hosts and services into the ConfDB.

Icinga2 Configuration Setup

Please follow these steps in order to setup/debug your Icinga2 integration.

  1. Icinga2 detects an incident and sends an email:
    Please configure your Icinga2 "contacts.cfg" to include "projop@localhost" for notifications (we assume that ]project-open[ is running as user "projop" at the same computer where Icinga2 is running).
    To verify: Please check /var/log/mail or /var/log/maillog to see if notification emails are sent out correctly.

  2. Please configure Postfix SMTP agent to receive email on the computer running ]project-open[:
    Please configure the SMTP agent on the computer running ]po[ to deliver local mails in "Maildir" format. Please note that not all SMTP agents can deliver in "Maildir" format (Sendmail is a prominente example). In this case, please change to Postfix or QMail. You may have to use a mailbox and "fetchmail" if Icinga2 and ]po[ are running on different computers.
    To verify: Please check in /web/projop/Maildir/new/ that every Icinga2 mail creates a new file.

  3. Configure "acs-mail-lite" to parse Icinga2 notifications:
    "acs-mail-lite" is an OpenACS/]po[ package that is capable of handing incoming mail and to distribute mail events to the "intranet-icinga2" package. Please go to Admin -> Parameters and configure the "BounceMailDir" parameter of acs-mail-lite to match your Maildir ("/web/projop/Maildir"). Then go to Admin -> Interactive Shell and execute the command "acs_mail_lite::load_mails".
    To verify: Please check log file for debugging output: "tail -f ~/log/error.log | grep 'load_mail_dir'". You should see several lines, the last one of them like this:
    [<Date>][<ID>][-conn0-] Notice: acs_mail_lite::load_mail_dir: Calling: 'im_icinga2_acs_mail_lite_callback -to projop@localhost -from icinga@projop.project-open.net -subject {...} -body {...}

    If you don't see this last line: Please make sure you have installed intranet-icinga2 >= 3.4.0.7.5 and the latest version of acs-mail-lite.

  4. Check that intranet-icinga2 parses the Icinga2 alert:
    The procedure im_icinga2_process_alert in ~/packages/intranet-icinga2/tcl/intranet-icinga2.procs.tcl  is responsible for parsing the Icinga2 messages and creating helpdesk tickets and configuration items. It is unlikely to cause trouble if the Icinga2 mails have been received correctly by acs-mail-lite.
    To verify: Please go to Helpdesk to check for new tickets, and go to Conf Items to check if a new server has been created plus a sub-item representing the Icinga2 service.

References

Maturity 

  • Active and Stable

Related Modules


Package Documentation

Procedure Files

tcl/intranet-icinga2-callback-procs.tcl       Library for Icinga2 interface callback implementations 
tcl/intranet-icinga2-parser-procs.tcl       Parsing the Icinga2 file format 
tcl/intranet-icinga2-procs.tcl        

Procedures

callback::acs_mail_lite::incoming_email::impl::icinga2       Implementation of the interface acs_mail_lite::incoming_email for Icinga2 events. 
im_icinga2_acs_mail_lite_callback       This procedure is called from the callback acs_mail_lite::load_mails every time there is an email with a suitable Icinga2 header. 
im_icinga2_conf_item_type_generic_router        
im_icinga2_conf_item_type_http_service        
im_icinga2_conf_item_type_linux_server        
im_icinga2_create_confdb       Creates configuration items from a Icinga2 configuration 
im_icinga2_file_to_lines       Reads a file and returns a list of lines without single-line comments and empty lines. 
im_icinga2_find_open_ticket       Checks whether there is a ticket open for the given host+service and returns 0 otherwise. 
im_icinga2_get_host_by_name       Returns the conf_id of the host with the given name 
im_icinga2_get_host_by_name_cached       Returns the conf_id of the host with the given name 
im_icinga2_get_service_by_name       Returns the conf_id of the service with the given name 
im_icinga2_get_service_by_name_cached       Returns the conf_id of the service with the given name 
im_icinga2_get_type_id_from_host_info       Tries to determine a suitable "Intranet Conf Item Type" for the given Icinga2 host. 
im_icinga2_lines_to_statements       Takes a list of Icinga2 lines, determines multi-line statements and returns a list of statements. 
im_icinga2_log       Writes Str to ns_log and ns_write 
im_icinga2_process_alert       This procedure is called from the callback acs_mail_lite::incoming_email every time there is an email with a suitable Icinga2 header. 
im_icinga2_statement       Extracts a single statement from the lines and returns a hash with: - ctr: The new counter where to continue and - statement: The statement 
im_icinga2_statement_apply       Defines a new host, service or notification 
im_icinga2_statement_object       Defines a new host, service or notification 
im_icinga2_statement_object_attributes       Extracts an attribute hash from an object's definition 
im_icinga2_statement_object_host       Defines a new host. 
im_icinga2_statement_object_service       Defines a new service. 
im_icinga2_statements_to_confdb       Takes a list of Icinga2 statements and creates configuration database entries for hosts and services. 

SQL Files

sql/postgresql/intranet-icinga2-create.sql        
sql/postgresql/intranet-icinga2-drop.sql        

Content Pages

www/
      import-icinga2-confitems.tcl Parses the Icinga2 configuration file and creates ConfItems in the ]po[ ConfDB
      index.adp
      index.tcl Main page for Icinga2 integration
 

 

  Contact Us
  Project Open Business Solutions S.L.

Calle Aprestadora 19, 12o-2a

08902 Hospitalet de Llobregat (Barcelona)

Spain

 Tel Europe: +34 609 953 751
 Tel US: +1 415 200 2465
 Mail: info@project-open.com