search

NETWAYS / icinga2-notification-telegram

Send Icinga 2 notifications via Telegram
https://netways.de/
GNU General Public License v3.0
16 stars 9 forks source link
icinga notifications plugin telegram

readme

Notification by Telegram

Send Icinga 2 notifications via Telegram.

Preparing

Create your Bot

You need a bot to begin:

Follow the official Telegram guide and do not forget to grab your bot API TOKEN (referred to here as BOT_TOKEN) afterwards

Get your chat_id(s)

You can notify a specific TG user account or throw a message to a TG group.

In order to do so you need to know the corresponding (hidden) ID also called chat_id (-q TELEGRAM_CHATID).

If you want to notify a group/channel:

  1. Add your bot to that group/channel
  2. Send with your favorite client a simple mention msg to your bot (e.g. hi @mybot)
  3. Catch updates for your bot: curl https://api.telegram.org/bot<BOT_TOKEN>/getUpdates

  4. Review the output, an example below:

    "message":{"message_id":91, "from":{"id":123456789, "is_bot":false,"first_name":"foo","username":"foobar","language_code":"de"}, "chat":{"id":-987654321, "title":"","type":"group","all_members_are_administrators":true},"date":1563547428,"group_chat_created":true}}]}`

    There are 2 important parts here:

    • a) "from":{"id":123456789 which is the unique user/chat_id of the user who sends a message to your bot (required to send to a notify to that person directly)
    • b) "chat":{"id":-987654321 which is the unique group/channel id of the group where the message has been sent

If you do not want to notify a group i.e. just a direct user notification:

  1. Do the same as above, just at step 1 make a direct message to your bot instead
  2. As you have done a direct message you will only get a "from" id which is all you need here

Examples

Testing a notification

Sending a test notification – replace the token, botname and chat id obviously.

sudo -u nagios ./alert-by-telegram.sh -4 127.0.0.1 \
-a service \
-d"$(date +%F-%T)" \
-e serviceshort \
-l myhostalias \
-o testing-telegram-notifiy \
-p $BOT_NAME> \
-q $GROUP_CHAT_ID \
-r $BOT_TOKEN \
-c mycomment \
-b mycommentauthor \
-i https://myicingaserver/icingaweb2 \
-n myhostdisplayname \
-s CRITICAL \
-t PROBLEM \
-u fullservicename

Icinga2 objects

Example host objects

Example host template ```ini template Host "Generic Host Template" { check_command = "hostalive" max_check_attempts = "3" check_interval = 1m retry_interval = 1m check_timeout = 30s enable_notifications = true enable_active_checks = true enable_passive_checks = true enable_event_handler = true enable_flapping = true enable_perfdata = true volatile = false vars.notification_type = "Telegram" } ```
Example host object ```ini object Host "icinga2-master" { import "Generic Host Template" address = "127.0.0.1" } ```

Example user templates

Generic user template ```ini template User "Generic User Template" { enable_notifications = true } ```
User "telegram_bot" ```ini object User "telegram_bot" { import "Generic User Template" display_name = "Bot via Telegram" email = "you@yourdomain.tld" states = [ Critical, Down, OK, Unknown, Up, Warning ] types = [ Custom, Problem, Recovery ] } ```

Example command definitions

Notification Command: Hosts by Telegram ```ini object NotificationCommand "Notify Host By Telegram" { import "plugin-notification-command" command = [ "/etc/icinga2/scripts/alert-by-telegram.sh" ] arguments += { "-4" = { required = true value = "$address$" } "-6" = "$address6$" "-a" = "host" "-b" = "$notification.author$" "-c" = "$notification.comment$" "-d" = { required = true value = "$icinga.long_date_time$" } "-i" = "$icingaweb2url$" "-l" = { required = true value = "$host.name$" } "-n" = "$host.display_name$" "-o" = { required = true value = "$host.output$" } "-p" = { required = true value = "$telegram_bot$" } "-q" = { required = true value = "$telegram_chatid$" } "-r" = { required = true value = "$telegram_bottoken$" } "-s" = { required = true value = "$host.state$" } "-t" = { required = true value = "$notification.type$" } "-v" = "$telegram_notification_logtosyslog$" } } ```
Notification Command: Services by Telegram ```ini object NotificationCommand "Notify Service By Telegram" { import "plugin-notification-command" command = [ "/etc/icinga2/scripts/alert-by-telegram.sh" ] arguments += { "-4" = { required = true value = "$address$" } "-6" = "$address6$" "-a" = "service" "-b" = "$notification.author$" "-c" = "$notification.comment$" "-d" = { required = true value = "$icinga.long_date_time$" } "-e" = { required = true value = "$service.name$" } "-i" = "$icingaweb2url$" "-l" = { required = true value = "$host.name$" } "-n" = "$host.display_name$" "-o" = { required = true value = "$service.output$" } "-p" = { required = true value = "$telegram_bot$" } "-q" = { required = true value = "$telegram_chatid$" } "-r" = { required = true value = "$telegram_bottoken$" } "-s" = { required = true value = "$service.state$" } "-t" = { required = true value = "$notification.type$" } "-u" = { required = true value = "$service.display_name$" } "-v" = "$telegram_notification_logtosyslog$" } } ```

Example notification objects

Notification Template: Telegram Generic ```ini template Notification "Template: Telegram (Generic)" { vars.telegram_bot = "" vars.telegram_bottoken = "" vars.telegram_chatid = "" vars.telegram_notification_logtosyslog = true } ```
Notification Template: Host Notifications ```ini template Notification "Template: Host Notifications via Telegram" { import "Template: Telegram (Generic)" command = "Notify Host By Telegram" interval = 1h } ```
Notification Template: Service Notifications ```ini template Notification "Template: Service Notifications via Telegram" { import "Template: Telegram (Generic)" command = "Notify Service By Telegram" interval = 4h } ```

Example notification apply rules

Apply rule for host notifications ```ini apply Notification "Host Alert via @telegram_bot" to Host { import "Template: Host Notifications via Telegram" interval = 1h assign where host.vars.notification_type == "Telegram" states = [ Down, Up ] types = [ Custom, Problem, Recovery ] users = [ "telegram_bot" ] } ```
Apply rule for service notifications ```ini apply Notification "Service Alerts via @telegram_bot" to Service { import "Template: Service Notifications via Telegram" interval = 12h assign where host.vars.notification_type == "Telegram" users = [ "telegram_bot" ] } ```

Example Director screenshot

Notifications by Telegram via Icinga Director ![Icinga Director Config](img/Telegram_Notification_in_Icinga_Director.jpg)

Related Director Baskets

License

Copyright (C) 2018 Marianne M. Spiller github@spiller.me

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.