Metadata-Version: 2.1
Name: icinga2telegram
Version: 0.2.2
Summary: Send your Icinga2 alerts to Telegram
Home-page: https://github.com/ekeih/icinga2telegram
Author: Max Rosin
Author-email: git@hackrid.de
License: LICENSE
Platform: UNKNOWN
Description-Content-Type: text/markdown
Requires-Dist: Click
Requires-Dist: emoji
Requires-Dist: Jinja2
Requires-Dist: python-telegram-bot

# icinga2telegram

icinga2telegram is a small Python script to send your [Icinga2](https://icinga.com) alerts to
Telegram. It also adds emojis to your alerts to highlight the type and importance of the alert.
(You can disable it with `--no-emojis`.)

![Screenshot of icinga2telegram](screenshot.png)

## Why Python instead of a simple Bash script?
Several other people implemented Icinga2-Telegram notifications by writing a simple Bash
script. Most of the time this works but there are a few things I do not like about the
Bash solutions:

1. They use two scripts with almost the same content.
2. Bash can screw up really bad when your alert output contains special characters.
3. The Bash solutions are based on environment variables. This does not work natively with
Icinga2 director as it only supports arguments in command definitions.

Obviously the Python implementation has a bigger footprint than the Bash solution. It
requires a Python interpreter and installs several Python packages as dependencies. This
could be a problem for an embedded system with very limited resources but most Icinga2
instances run on powerful machines and the icinga2telegram footprint does not matter there.
In return you get a single maintainable and robust script that you can use for host and
service notifications.

## Installation and Setup

### Install icinga2telegram
It is recommended (but not required) to install icinga2telegram in a Python virtualenv.
```
pip install icinga2telegram
````

Run `icinga2telegram --help` to see all available options.

### Create a Telegram Bot
You need to create a Telegram bot by talking to the Botfather of Telegram. Please follow
the [official instructions](https://core.telegram.org/bots#creating-a-new-bot) and
copy your bot token. You will need it for the Icinga2 configuration.

### Get your CHAT-ID
Now you need to talk to your new bot because a bot can not start a new chat. Just open a
chat with your bot and send a message. Afterwards you have to fetch the CHAT-ID of
the conversation between you and your bot. Replace TOKEN with your actual token.

```
curl -s 'https://api.telegram.org/botTOKEN/getUpdates'
```

If you have `jq` installed it is even simpler with:
```
curl -s 'https://api.telegram.org/botTOKEN/getUpdates' | jq '.result[].message.chat'
{
  "id": CHAT-ID,
  "first_name": "Max",
  "username": "exampleuser",
  "type": "private"
}
```

Copy your CHAT-ID. You will need it for the Icinga2 configuration.
If you want to add more users everyone has to send a message to your bot and you need to
extract the CHAT-IDs as shown above.
(You can also invite your bot to groups but then you have to write a message like `@yourbot foo`
to the group to send the message (with your CHAT-ID) to your bot.)


## Icinga2 Example Configuration

This is just one way to use icinga2telegram for your notifications. Of course you can use another
way to glue your users, CHAT-IDs and the actual notifications together.

### User Definition with your CHAT-ID as a Variable
```
object User "max" {
    display_name = "Max"
    enable_notifications = true
    vars.telegram_chat_id = "CHAT-ID"
}
```

### Notification Definition for Hosts
```
apply Notification "Max (Host)" to Host {
    command = "icinga2telegram Host"
    assign where host.address
    users = [ "max" ]
}
```

### Notification Definition for Services
```
apply Notification "Max (Service)" to Service {
    command = "icinga2telegram Service"
    assign where host.address
    users = [ "max" ]
}

```

### Command Definition for Hosts
```
object NotificationCommand "icinga2telegram Host" {
    import "plugin-notification-command"
    command = [ "/opt/icinga2telegram/bin/icinga2telegram" ]
    timeout = 1m
    arguments += {
        "--address" = "$address$"
        "--chat" = "$user.vars.telegram_chat_id$"
        "--hostdisplayname" = "$host.display_name$"
        "--hostname" = "$host.name$"
        "--hostoutput" = "$host.output$"
        "--hoststate" = "$host.state$"
        "--icingaweb2url" = "https://monitoring.example.com/icingaweb2"
        "--notification-author" = "$notification.author$"
        "--notification-comment" = "$notification.comment$"
        "--notification-type" = "$notification.type$"
        "--time" = "$icinga.timet$"
        "--token" = "TOKEN"
    }
}
```

### Command Definition for Services
```
object NotificationCommand "icinga2telegram Service" {
    import "plugin-notification-command"
    command = [ "/opt/icinga2telegram/bin/icinga2telegram" ]
    timeout = 1m
    arguments += {
        "--address" = "$address$"
        "--chat" = "$user.vars.telegram_chat_id$"
        "--hostdisplayname" = "$host.display_name$"
        "--hostname" = "$host.name$"
        "--hostoutput" = "$host.output$"
        "--hoststate" = "$host.state$"
        "--icingaweb2url" = "https://monitoring.example.com/icingaweb2"
        "--notification-author" = "$notification.author$"
        "--notification-comment" = "$notification.comment$"
        "--notification-type" = "$notification.type$"
        "--servicedisplayname" = "$service.display_name$"
        "--servicename" = "$service.name$"
        "--serviceoutput" = "$service.output$"
        "--servicestate" = "$service.state$"
        "--time" = "$icinga.timet$"
        "--token" = "TOKEN"
    }
}
```

## License
```
Send your Icinga2 alerts to Telegram
Copyright (C) 2018  Max Rosin

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 <https://www.gnu.org/licenses/>.
```


