icinga2-email-summary

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
   • Configuration
   • Execution
4. License
5. Contact

About The Project

This Python script uses the Icinga2 API to retrieve all problematic hosts and services and bundles this information in one email, that can then be sent to the assigned users. The native Icinga2 emails in contrast, are sent individually for every configured event (e.g. a host goes down).

Getting Started

Prerequisites

Make sure that Python3 and pip are installed on your machine.

Installation

To get started first clone this repository to the wanted location

git clone https://github.com/faberno/icinga2-email-summary.git
cd icinga2-email-summary

Install the required packages

• icinga2apic: An Icinga2 client to handle the API requests
• Jinja2: A templating engine to automatically create the html for the email

pip install -r requirements.txt

Usage

Configuration

Rename config.py.sample to config.py and configure it to your needs

• send_mail (boolean): If false, no emails will be sent (recommended for testing)
• use_whitelist (boolean): If true, only addresses that have been specified in the whitelist.txt can receive emails (recommended for testing).
  whitelist.txt should contain one address per row

user1@example.com
user2@example.com

• icinga_host (string): URL of the Icinga2 host
• icinga_apiuser (string): Name of API User, which the client will use. Ideally, this user should have read rights only
• icinga_apipassword (string): Password of the API User
• subject (string): The subject of the sent emails
• from_addr (string): The email address the messages are sent from
• smtp_host (string): URL of the SMTP server ('localhost' if on the same server)
• smtp_port (integer): Port of the SMTP host (0 if host is 'localhost')
• smtp_username & smtp_password (string): Credentials of the SMTP user (not needed íf this script runs on the SMTP server)
• log_file (string): Path to the log file
• log_format (string): Formatting of the log messages (see here for details)
• log_level (logging.{level}): Logging level provided by the built-in logging library

As can be seen above, it makes sense to have Icinga, SMTP and this script running on the same machine.

Execution

After making sure main.py has execution permissions, it can be executed by

python3 path/to/main.py

To schedule an automatic execution, you could use crontab. The below example will execute the script Monday to Friday at 8 and 16 o'clock.

0 8,16 * * 1-5 python3 path/main.py

License

Copyright 2022 The Samply Community

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.