Skip to content

TeraIT-at/icinga-telegram-bot

Repository files navigation

icinga-telegram-bot

Send notifications and acknoledgments via Telegram to Icinga2 via API.

Installation

Setting up icinga-telegram-bot

  • on Ubuntu install python3 and venv
sudo apt install python3-venv python3
  • create a virtual environment (e.g. in /opt)
cd /opt
git clone https://github.com/joni1993/icinga-telegram-bot.git
cd icinga-telegram-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
  • copy example configuration cp icinga-telegram-bot.config.example icinga-telegram-bot.config

  • edit the configuration according to your needs

  • test icinga-telegram-bot works by issuing venv/bin/python3 -m icingatelegrambot.app --config_file=icinga-telegram-bot.config

Install Systemd service

  • sudo cp contrib/icinga-telegram-bot.service /etc/systemd/system
  • sudo systemctl daemon-reload
  • sudo systemctl start icinga-telegram-bot
  • sudo systemctl enable icinga-telegram-bot

Icinga2 API

  • Create an API user in icinga with at least the following permissions
vim /etc/icinga2/conf.d/api-users.conf

object ApiUser "icinga-bot" {
  password = "icinga"

  permissions = [ "objects/query/Host", "objects/query/Service", "status/query", "actions/*" ]
}

For further details check the Icinga2 API documentation

Telegram Bot API

Check the official instructions for creating a Telegram bot

Install the Notifications scripts

  • Copy the scripts from contrib folder to your Icinga2 installation
sudo cp contrib/*.sh /etc/icinga2/scripts/

Run the bot

venv/bin/python3 -m icingatelegrambot.app --config_file=icinga-telegram-bot.config -h
usage: app.py [-h] [--config_file CONFIG_FILE]

This is an Icinga2 Telegram bot. It can be used to interact with Icinga2 from
your Telegram client. It uses the Icinga2 API. Version: 0.1.0 (2020-02-26)

optional arguments:
  -h, --help            show this help message and exit
  --config_file CONFIG_FILE
                        points to the config file to read config data from
                        which is not installed under the default path
                        './icinga-telegram-bot.config'")

Configuration

The bot features some options in its configuration:

  • allowed_chat_ids = [1234567890] # Specifies which Telegram chat ids are allowed to issue commands
  • commands_only_administrators = true # Specifies if only Telegram Group Administrators can issue commands

Use the bot

These functions are currently implemented:

  • /send_notification (Host|Service);(Hostname);(Servicename);Your text

    • (Host|Service) specifies if you want to send a notification to a host or a service (e.g. Host)
    • (Hostname) specifies the hostname (e.g. my-hostname)
    • (Servicename) specifies the servicename (e.g. my-servicename) - only specify when first argument is Service
  • /schedule_downtime (Host|Service);(Hostname);(Servicename);(Comment);(Start time);(End time);(Fixed);(Duration);(All services);(Trigger name);(Child options)

    • (Host|Service)* specifies if you want to send a notification to a host or a service (e.g. Host)
    • (Hostname)* specifies the hostname (e.g. my-hostname)
    • (Servicename) specifies the servicename (e.g. my-servicename) - only specify when first argument is Service
    • (Comment)*: comment that for the downtime (usually why this downtime will happen)
    • (Start time)*: start time (e.g. 01.01.1970 03:00 or now or In 2 hours)
    • (End time)*: see (Start time)
    • (Fixed): if this schedule is fixed or flexible downtime (true or false, y,n); defaults to false
    • (Duration)**: duration of downtime in seconds (required if fixed is false)
    • (All services): if this is set to true it sets a downtime for all services on the matched host (true or false, y,n); defaults to false
    • (Trigger name): sets a trigger for a triggered downtime (see Icinga docs)
    • (Child options): if and how to schedule child downtimes (no, triggeredChildren,nonTriggeredhildren) (see Icinga docs)
  • Notifications

Example Notification

  • Quick Acknowledge

Example Quick Acknowledge

  • Acknowledge with own Text

Example Acknowledge Step 1

Example Acknowledge Step 2

Example Acknowledge Step 3

  • Remove Acknowledgement

Example Remove Acknowledgement

Todo

  • Implement User ACL (registration, permissions, ...)
  • Commands for querying Hosts / Services
  • Icinga Status Check (check Icinga 2application status regularly and notify about errors)