├── .gitignore ├── images ├── user_add_chat_id.png ├── activate_affected.png ├── activate_on_selected_sites.png ├── notification_configuration.png ├── notification_custom_macro.png ├── create_custom_user_attribute.png ├── custom_user_attributes_menu.png ├── logo-checkmk-telegram-notify.png ├── notification_rule_use_topic.png ├── telegram_notification_example.png ├── custom_user_attributes_creation.png ├── notification_configuration_test.png ├── notification_configuration_change.png ├── notification_rule_modify_privacy.png ├── global_notification_rules_create_clone.png ├── create_new_notification_rule_for_telegram.png ├── global_notification_rules_create_clone_v2.png └── create_new_notification_rule_for_telegram_v2.png ├── docs └── issues │ └── 12 │ ├── VAPkehWiIjj5.png │ ├── p52fZV5dIPU4.png │ └── comparison_output.png ├── LEGACY_CONFIGURATION.md ├── LICENSE ├── HELP.md ├── check_mk_telegram-notify.sh └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | config.xml 2 | .idea -------------------------------------------------------------------------------- /images/user_add_chat_id.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/user_add_chat_id.png -------------------------------------------------------------------------------- /images/activate_affected.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/activate_affected.png -------------------------------------------------------------------------------- /docs/issues/12/VAPkehWiIjj5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/docs/issues/12/VAPkehWiIjj5.png -------------------------------------------------------------------------------- /docs/issues/12/p52fZV5dIPU4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/docs/issues/12/p52fZV5dIPU4.png -------------------------------------------------------------------------------- /docs/issues/12/comparison_output.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/docs/issues/12/comparison_output.png -------------------------------------------------------------------------------- /images/activate_on_selected_sites.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/activate_on_selected_sites.png -------------------------------------------------------------------------------- /images/notification_configuration.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/notification_configuration.png -------------------------------------------------------------------------------- /images/notification_custom_macro.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/notification_custom_macro.png -------------------------------------------------------------------------------- /images/create_custom_user_attribute.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/create_custom_user_attribute.png -------------------------------------------------------------------------------- /images/custom_user_attributes_menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/custom_user_attributes_menu.png -------------------------------------------------------------------------------- /images/logo-checkmk-telegram-notify.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/logo-checkmk-telegram-notify.png -------------------------------------------------------------------------------- /images/notification_rule_use_topic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/notification_rule_use_topic.png -------------------------------------------------------------------------------- /images/telegram_notification_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/telegram_notification_example.png -------------------------------------------------------------------------------- /images/custom_user_attributes_creation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/custom_user_attributes_creation.png -------------------------------------------------------------------------------- /images/notification_configuration_test.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/notification_configuration_test.png -------------------------------------------------------------------------------- /images/notification_configuration_change.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/notification_configuration_change.png -------------------------------------------------------------------------------- /images/notification_rule_modify_privacy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/notification_rule_modify_privacy.png -------------------------------------------------------------------------------- /images/global_notification_rules_create_clone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/global_notification_rules_create_clone.png -------------------------------------------------------------------------------- /images/create_new_notification_rule_for_telegram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/create_new_notification_rule_for_telegram.png -------------------------------------------------------------------------------- /images/global_notification_rules_create_clone_v2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/global_notification_rules_create_clone_v2.png -------------------------------------------------------------------------------- /images/create_new_notification_rule_for_telegram_v2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/filipnet/checkmk-telegram-notify/HEAD/images/create_new_notification_rule_for_telegram_v2.png -------------------------------------------------------------------------------- /LEGACY_CONFIGURATION.md: -------------------------------------------------------------------------------- 1 | ### Configuration Checkmk version 1.6.0 2 | 3 | Now you can create your own alarm rules in Check_MK. 4 | 5 | ```WATO → Notifications → New Rule → Notification Method → Push Notification (using Telegram)``` 6 | 7 | 8 | 9 | - [CONFIGRURATION CHECK_MK VERSION 1.6.0](#configruration-check_mk-version-160) 10 | - [ACTIVATE CHANGES](#activate-changes) 11 | 12 | t you have to press "1 Change" and "Activate affected" 13 | 14 | Activate changes and commit 15 | 16 | To ensure that the parameters are also transferred in the event of an alert, it is strongly recommended that the Check_MK instance is restarted. 17 | ``` 18 | su - mysite 19 | omd stop 20 | omd start 21 | ``` -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 3-Clause License 2 | 3 | Copyright (c) 2020, Benedikt Filip 4 | All rights reserved. 5 | 6 | Redistribution and use in source and binary forms, with or without 7 | modification, are permitted provided that the following conditions are met: 8 | 9 | 1. Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer. 11 | 12 | 2. Redistributions in binary form must reproduce the above copyright notice, 13 | this list of conditions and the following disclaimer in the documentation 14 | and/or other materials provided with the distribution. 15 | 16 | 3. Neither the name of the copyright holder nor the names of its 17 | contributors may be used to endorse or promote products derived from 18 | this software without specific prior written permission. 19 | 20 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 23 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 24 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 26 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 27 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 | -------------------------------------------------------------------------------- /HELP.md: -------------------------------------------------------------------------------- 1 | # Help & Troubleshooting Guide 2 | 3 | Having trouble getting Checkmk Telegram notifications to work? This guide will help you identify and resolve common issues. 4 | 5 | ## Quick Checklist 6 | 7 | Before diving into advanced troubleshooting, ensure you have checked the following: 8 | 9 | - **curl** is installed on your system. 10 | - Run `curl --version` to verify. 11 | - **Bot token** and **chat ID** are correct. 12 | - Avoid extra spaces, line breaks, or incorrect quotes in your configuration. 13 | - The **bot is added to the chat or group** and has permission to post. 14 | - Test posting with `curl` to confirm the issue is not with the Checkmk script. 15 | - Your Checkmk host or Docker container has **internet access**. 16 | - Test with `curl` to the Telegram API. 17 | - Watch for errors like `no route to host` (firewall/proxy issues). 18 | - The **notification script is executable**. 19 | - Run: `chmod +x check_mk_telegram-notify.sh` 20 | - You have followed the steps in the [README instructions](./README.md#check_mk-configuration). 21 | 22 | ## Validate Notification (Dry-run) 23 | 24 | To verify your Telegram bot can send messages independently of Checkmk, use this direct API call: 25 | 26 | ```bash 27 | curl -s \ 28 | -X POST "https://api.telegram.org/bot/sendMessage" \ 29 | -d "chat_id=" \ 30 | -d "text=Test notification" 31 | ``` 32 | 33 | - Replace `` and `` with your actual values. 34 | 35 | This test confirms: 36 | 37 | - Bot token and chat ID are valid 38 | - Bot has permission to post 39 | - Host/container has internet access 40 | - A JSON response with `"ok":true` means the message was sent 41 | 42 | ## Logfile analysis 43 | 44 | Check the Checkmk notification log for error messages. Replace `{sitename}` with your actual site name: 45 | 46 | ```bash 47 | tail -f /omd/sites/{sitename}/var/log/notify.log 48 | ``` 49 | 50 | ## References and documentations 51 | 52 | For more troubleshooting and examples, see: 53 | 54 | - [Checkmk Documentation: Notifications – Chapter 11.3](https://docs.checkmk.com/latest/en/notifications.html) 55 | - [Checkmk GitHub Repository](https://github.com/Checkmk/checkmk) 56 | - [Checkmk Forum](https://forum.checkmk.com/) 57 | - [Telegram Bot API Documentation](https://core.telegram.org/bots/api) 58 | -------------------------------------------------------------------------------- /check_mk_telegram-notify.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Push Notification (using Telegram) 3 | # 4 | # Script Name : check_mk_telegram-notify.sh 5 | # Description : Send Check_MK notifications by Telegram 6 | # Author : https://github.com/filipnet/checkmk-telegram-notify 7 | # License : BSD 3-Clause "New" or "Revised" License 8 | # ====================================================================================== 9 | # Telegram API Token 10 | # Find telegram bot named "@botfather", type /mybots, select your bot and select "API Token" to see your current token 11 | if [ -z ${NOTIFY_PARAMETER_1} ]; then 12 | echo "No Telegram token ID provided. Exiting" >&2 13 | exit 2 14 | else 15 | TOKEN="${NOTIFY_PARAMETER_1}" 16 | fi 17 | 18 | # Telegram Chat-ID or Group-ID (and optional Thread-ID) 19 | # Open "https://api.telegram.org/bot/getUpdates" inside your Browser and send a HELLO to your bot, refresh side 20 | if [ -z ${NOTIFY_PARAMETER_2} ]; then 21 | if [ -z ${NOTIFY_CONTACT_TELEGRAMCHAT} ]; then 22 | echo "No Telegram Chat-ID or Group-ID provided. Exiting" >&2 23 | exit 2 24 | else 25 | CHAT_ID="${NOTIFY_CONTACT_TELEGRAMCHAT}" 26 | fi 27 | else 28 | CHAT_ID="${NOTIFY_PARAMETER_2%:*}" 29 | THREAD_ID="${NOTIFY_PARAMETER_2#*:}" 30 | if [ "${CHAT_ID}" = "${THREAD_ID}" ]; then 31 | THREAD_ID="" 32 | fi 33 | fi 34 | 35 | # Privacy settings to anonymize/masking IP addresses 36 | if [[ ${NOTIFY_PARAMETER_3} == "privacy" ]]; then 37 | # IPv4 IP addresses 38 | if [ ${NOTIFY_HOST_ADDRESS_4} ]; then 39 | slice="${NOTIFY_HOST_ADDRESS_4}" 40 | count=1 41 | while [ "$count" -le 4 ] 42 | do 43 | declare sec"$count"="${slice%%.*}" 44 | slice="${slice#*.}" 45 | count=$((count+1)) 46 | done 47 | # Adjust the output to your privacy needs here (Details in the readme.md) 48 | NOTIFY_HOST_ADDRESS_4="${sec1}.${sec2}.2.${sec4}" 49 | fi 50 | 51 | # IPv6 IP addresses 52 | if [ ${NOTIFY_HOST_ADDRESS_6} ]; then 53 | slice="${NOTIFY_HOST_ADDRESS_6}" 54 | count=1 55 | while [ "$count" -le 8 ] 56 | do 57 | declare sec"$count"="${slice%%:*}" 58 | slice="${slice#*:}" 59 | count=$((count+1)) 60 | done 61 | # Adjust the output to your privacy needs here (Details in the readme.md) 62 | NOTIFY_HOST_ADDRESS_6="${sec1}:${sec2}:${sec3}:${sec4}:ffff:ffff:ffff:${sec8}" 63 | fi 64 | else 65 | if [ ! -z ${NOTIFY_PARAMETER_3} ]; then 66 | echo "Invalid privacy parameter, check your Check_MK settings." >&2 67 | fi 68 | fi 69 | 70 | # Set an appropriate emoji for the current state 71 | # Feel free to change the emoji to your own taste. This is done by customizing the UTF8 code. Examples here: https://apps.timwhitlock.info/emoji/tables/unicode 72 | if [[ ${NOTIFY_WHAT} == "SERVICE" ]]; then 73 | STATE="${NOTIFY_SERVICESHORTSTATE}" 74 | else 75 | STATE="${NOTIFY_HOSTSHORTSTATE}" 76 | fi 77 | case "${STATE}" in 78 | OK|UP) 79 | EMOJI=$'\xE2\x9C\x85' # white heavy check mark 80 | ;; 81 | WARN) 82 | EMOJI=$'\xE2\x9A\xA0' # warning sign 83 | ;; 84 | CRIT|DOWN) 85 | EMOJI=$'\xF0\x9F\x86\x98' # squared sos 86 | ;; 87 | UNKN) 88 | EMOJI=$'\xF0\x9F\x94\x84' # anticlockwise downwards and upwards open circle arrows 89 | ;; 90 | esac 91 | 92 | # The emoji should be displayed with emoji presentation 93 | EMOJI+=$'\xEF\xB8\x8F' 94 | # Create a MESSAGE variable to send to your Telegram bot 95 | MESSAGE="${NOTIFY_HOSTNAME} (${NOTIFY_HOSTALIAS})%0A" 96 | MESSAGE+="${EMOJI} ${NOTIFY_WHAT} ${NOTIFY_NOTIFICATIONTYPE}%0A%0A" 97 | if [[ ${NOTIFY_WHAT} == "SERVICE" ]]; then 98 | MESSAGE+="${NOTIFY_SERVICEDESC}%0A" 99 | MESSAGE+="State changed from ${NOTIFY_PREVIOUSSERVICEHARDSHORTSTATE} to ${NOTIFY_SERVICESHORTSTATE}%0A" 100 | MESSAGE+="${NOTIFY_SERVICEOUTPUT}%0A" 101 | else 102 | MESSAGE+="State changed from ${NOTIFY_PREVIOUSHOSTHARDSHORTSTATE} to ${NOTIFY_HOSTSHORTSTATE}%0A" 103 | MESSAGE+="${NOTIFY_HOSTOUTPUT}%0A" 104 | fi 105 | MESSAGE+="%0AIPv4: ${NOTIFY_HOST_ADDRESS_4} %0AIPv6: ${NOTIFY_HOST_ADDRESS_6}%0A" 106 | MESSAGE+="${NOTIFY_SHORTDATETIME} | ${OMD_SITE}" 107 | 108 | # Send message to Telegram bot 109 | response=$(curl -S -s -q --connect-timeout 5 -X POST "https://api.telegram.org/bot${TOKEN}/sendMessage" -d chat_id="${CHAT_ID}" -d message_thread_id="${THREAD_ID}" -d text="${MESSAGE}") 110 | if [ $? -ne 0 ]; then 111 | echo "Not able to send Telegram message" >&2 112 | echo $response >&2 113 | exit 2 114 | else 115 | echo "Telegram message sent sucessfully" >&2 116 | exit 0 117 | fi 118 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![Telegram Plugin](https://img.shields.io/badge/Telegram-Plugin-blue) 2 | ![Checkmk Compatible](https://img.shields.io/badge/Check__MK-Compatible-brightgreen) 3 | 4 | # Checkmk Telegram Notify 5 | 6 | Checkmk Telegram Notify Logo 7 | 8 | 9 | 10 | - [Checkmk Telegram Notify](#checkmk-telegram-notify) 11 | - [Compatibility](#compatibility) 12 | - [Example](#example) 13 | - [Requirements](#requirements) 14 | - [Installation](#installation) 15 | - [Update existing installation](#update-existing-installation) 16 | - [Checkmk configuration](#checkmk-configuration) 17 | - [Acivate changes](#acivate-changes) 18 | - [Test notifications](#test-notifications) 19 | - [Optional features](#optional-features) 20 | - [Use of Telegram topics / threads](#use-of-telegram-topics--threads) 21 | - [Privacy anonymization / masquerading](#privacy-anonymization--masquerading) 22 | - [Custom User Attributes](#custom-user-attributes) 23 | - [Custom Macro](#custom-macro) 24 | - [Telegram Chat-ID instead of Group-ID](#telegram-chat-id-instead-of-group-id) 25 | - [Help & Troubleshooting Guide](#help--troubleshooting-guide) 26 | - [Contributions](#contributions) 27 | - [License](#license) 28 | 29 | 30 | 31 | ## Compatibility 32 | 33 | Understanding compatibility ensures that the plugin works seamlessly with your specific Checkmk version and environment. 34 | 35 | - Checkmk RAW version 1.6.0p18 36 | - Checkmk RAW version 2.4.0p4 for RedHat/CentOS/AlmaLinux/RockyLinux 8 and 9 37 | - Should also work with other versions of Checkmk 38 | 39 | ## Example 40 | 41 | Notifications are usually sent via a Telegram group. Here is an example of how a Telegram notification is structured. 42 | 43 | Telegram notification example 44 | 45 | ## Requirements 46 | 47 | To enable Checkmk to send notifications via Telegram, you need: 48 | 49 | - a Telegram bot 50 | - a username for the bot 51 | - an API token 52 | - a Telegram Chat- or Group-ID 53 | 54 | For detailed instructions on creating a Telegram bot, refer to the [official Telegram Bot documentation](https://core.telegram.org/bots#6-botfather). 55 | 56 | ## Installation 57 | 58 | Switch to the Checkmk site user to ensure proper permissions for the following commands 59 | 60 | ``` 61 | su - mysite 62 | ``` 63 | 64 | Navigate to the notification directory where custom notification scripts are stored 65 | 66 | ``` 67 | cd ~/local/share/Checkmk/notifications/ 68 | ``` 69 | 70 | Download the Telegram notify script from the Git repository (a new subfolder will be created to store the notification script and its related files, which are essential for the setup process) 71 | 72 | ``` 73 | `git clone https://github.com/filipnet/checkmk-telegram-notify.git` 74 | ``` 75 | 76 | Give the script execution permissions to ensure the script is executable and can be run by the system 77 | 78 | ``` 79 | chmod +x checkmk-telegram-notify/check_mk_telegram-notify.sh 80 | ls -l checkmk-telegram-notify/check_mk_telegram-notify.sh 81 | ``` 82 | 83 | Create a symbolic link to enable the plugin and integrate the notification script into the Checkmk system. This ensures the script is recognized and executed for Telegram notifications. Verify the symlink using `ls -l` to confirm it points to the correct script. 84 | 85 | ``` 86 | ln -s checkmk-telegram-notify/check_mk_telegram-notify.sh check_mk_telegram-notify.sh 87 | ``` 88 | 89 | ## Update existing installation 90 | 91 | To update an existing installation of the Checkmk Telegram notification script, follow these steps to ensure you have the latest features and fixes. 92 | 93 | ``` 94 | su - mysite 95 | cd ~/local/share/check_mk/notifications/checkmk-telegram-notify 96 | git pull 97 | ``` 98 | 99 | ## Checkmk configuration 100 | 101 | Now you can create your own alarm rules in Checkmk, which are configurations that define how and when notifications are sent based on specific conditions or events in your monitoring setup. 102 | 103 | To navigate to this path in the Checkmk interface, go to the main menu, select "Setup," then "Events," and finally "Notifications." 104 | 105 | `Setup → Events → Notifications` 106 | 107 | First create a clone of your existing mail notification rule 108 | 109 | Create clone 110 | 111 | - Change the description (e.g. Notify all contacts of a host/service via Telegram) 112 | - The notification method is "Push Notification (by Telegram)" 113 | - Select option "Call with the following parameters:" 114 | - As the first parameter we set the Telegram token ID (without bot-prefix), e.g., `123456789:ABCDEF1234567890abcdef1234567890` 115 | - The second parameter is the Telegram Chat-ID or Telegram Group-ID e.g., `-1001234567890` 116 | 117 | Adjust settings 118 | 119 | Referring to #6 and #15 at this point the note that initially only one field is displayed, further fields are only displayed after the first field has been filled. 120 | 121 | For configuration in Checkmk Legacy versions (1.x), please refer to [LEGACY_CONFIGURATION.md](LEGACY_CONFIGURATION.md). 122 | 123 | ### Acivate changes 124 | 125 | To activate it you have to press "Active on selected sites" 126 | 127 | Active on selected sites 128 | 129 | Restarting the Checkmk instance ensures that all configuration changes, including notification rules and script parameters, are fully applied and operational. This step helps avoid potential issues where changes might not take effect until the system is restarted. 130 | 131 | ``` 132 | su - mysite 133 | omd stop 134 | omd start 135 | ``` 136 | 137 | ### Test notifications 138 | 139 | You can verify if your notification rules are applied correctly by performing a notification check. Navigate to `Setup > Events > Notifications > Configuration` and use the `Test Notifications` button. This allows you to simulate and confirm the behavior of your notification rules. 140 | 141 | Test Notifications 142 | 143 | ## Optional features 144 | 145 | ### Use of Telegram topics / threads 146 | 147 | Telegram topics (also referred to as threads) are a feature available in Telegram groups that allow you to organize discussions into separate threads. This is particularly useful for managing notifications in large groups, as it helps keep conversations focused and organized. 148 | 149 | To send notifications to a specific topic within a Telegram group, append the `Thread-ID` to the `Group-ID`, separated by a colon. For example: `Group-ID:Thread-ID`. 150 | 151 | Use of topic 152 | 153 | To find the `Thread-ID`, use the `getUpdates` method of the Telegram Bot API: 154 | 155 | ``` 156 | https://api.telegram.org/bot/getUpdates 157 | ``` 158 | 159 | In the JSON response, look for the `message_thread_id` field. This field contains the ID of the thread. Example output: 160 | 161 | ``` 162 | ... "date":1743786667, "message_thread_id":281234, "forum_topic_created": ... 163 | ``` 164 | 165 | By combining the `Group-ID` and `Thread-ID`, you can ensure that notifications are sent directly to the desired topic within the group. 166 | 167 | ### Privacy anonymization / masquerading 168 | 169 | The current version of this script allows you to optionally enable IP anonymization. This gives you the option to comply with your own privacy policy or the recommendations of data protection authorities in certain countries if they prohibit the transmission of the full IP address. This masks IPv4 and IPv6 IP addresses before they are transmitted in a message to the Telegram service. 170 | 171 | The activation of the privacy settings is realized directly in the Notification Rules in Checkmk by NOTIFY_PARAMETER_3, here the value "privacy" has to be entered: 172 | 173 | Enable privacy settings 174 | 175 | There are certainly different requirements for privacy and masquerading of IP addresses. In the script, the IPv4 IP address is split into the 4 octets, the IPv6 address into the 8 columns. This allows to control **very individually** which parts of the addresses are sent via Telegram and which are not. Both, placeholders and manipulations are basically possible here. 176 | 177 | The adjustment is done exclusively in the following two lines of the script (Details in the readme.md). 178 | 179 | ``` 180 | NOTIFY_HOST_ADDRESS_4="${sec1}.${sec2}.2.${sec4}" 181 | NOTIFY_HOST_ADDRESS_6="${sec1}:${sec2}:${sec3}:${sec4}:ffff:ffff:ffff:${sec8}" 182 | ``` 183 | 184 | Explanation for the example configuration above: 185 | 186 | - 192.168.**143**.104 --> 192.168.**2**.104 187 | - 2001:db8:85a3:8d3:**1319**:**8a2e**:**370**:7348 --> 2001:db8:85a3:8d3:**ffff**:**ffff**:**ffff**:7348 188 | 189 | ### Custom User Attributes 190 | 191 | You can add a custom user attribute and use it in your script. This feature is particularly useful for tailoring notifications to individual users or groups, allowing you to specify unique identifiers like Telegram Chat-IDs directly in user profiles. It ensures that notifications are sent to the correct recipients without requiring manual adjustments in the script. 192 | 193 | - Go to: `Setup > Users > Custom User Attributes` 194 | 195 | Custom user attribute menu link 196 | 197 | - Create a custom attribute named `TELEGRAMCHAT` by click to `Add attribute` 198 | - Do NOT change the name, as it is required for compatibility with the notification script and Checkmk's configuration. 199 | - You can change the title and help text 200 | - Make sure you activate the option `Make this variable available in notifications` 201 | 202 | Custom user attribute creation 203 | 204 | - Edit your user and enter your Group/Chat-ID 205 | 206 | Custom macro for notification 207 | 208 | ### Custom Macro 209 | 210 | - Go to: `Setup > Events > Notifications>` 211 | 212 | Notification configuraton menu 213 | 214 | - Edit your notifcation. Add a custom macro. 215 | 216 | This pattern ensures that only valid Telegram Chat-IDs are used in the notification setup by accepting numbers with or without an optional minus sign and requiring a minimum of 5 digits.: 217 | Regex : `^-?\d{5,}$` 218 | 219 | - Breakdown: 220 | 221 | ``` 222 | ^: Start of the string. 223 | -?: An optional minus sign. 224 | \d{5,}: Five or more consecutive digits. 225 | $: End of the string. 226 | ``` 227 | 228 | - The macro ensures that only users with a valid Chat-ID receive notifications. 229 | - It validates the format of the Chat-ID, requiring a numeric value with at least 5 digits (the expected format for Telegram Chat-IDs). 230 | - Users without a valid Chat-ID will not receive notifications. 231 | - This behavior effectively acts as a whitelist, including only users with properly configured Chat-IDs matching the regex pattern. 232 | 233 | ### Telegram Chat-ID instead of Group-ID 234 | 235 | A different approach is to use the 'Pager address' field in Checkmk's user properties. This method simplifies configuration by directly linking user properties to the notification script, avoiding the need for additional custom attributes. The 'Pager address' gets exported as $NOTIFY_CONTACTPAGER variable to the script and as such all that's needed is: 236 | 237 | ``` 238 | if [ -z ${NOTIFY_CONTACTPAGER} ]; then 239 | echo "No pager address provided to be used as Chat-ID. Exiting" >&2 240 | exit 2 241 | else 242 | CHAT_ID="${NOTIFY_CONTACTPAGER}" 243 | fi 244 | ``` 245 | 246 | Custom macro for notification 247 | 248 | ## Help & Troubleshooting Guide 249 | 250 | You can find further information and assistance in the [HELP.md](HELP.md) 251 | 252 | ## Contributions 253 | 254 | - Thank you for the excellent code optimization contributions and additional information [ThomasKaiser](https://github.com/ThomasKaiser). 255 | - Best regards to [Jonathan Barratt](https://github.com/reduxionist) in Bangkok and many thanks for adding emojies to the module. 256 | - Many thanks to [progamernoob](https://github.com/progamernoob) for the contributions and enhancements to custom user attributes and macros. 257 | - Big thanks to [Sebastian Hayer-Lutz](https://github.com/Elompenta) for the idea with the symlinks and thereby supporting several plugins, as well as the timeout optimization. 258 | - Great Work [Christian Hesse](https://github.com/eworm-de) for implementing the solution to send notifications to specific topics within a Telegram group. 259 | 260 | ## License 261 | 262 | checkmk-telegram-notify and all individual scripts are under the BSD 3-Clause license unless explicitly noted otherwise. See the [LICENSE](LICENSE) file for more details 263 | --------------------------------------------------------------------------------