TelegramModule plugin for openITCOCKPIT 4

Features

• Receive notifications in Telegram as usual based on openITCOCKPIT contacts
• Multiple Telegram connections for different openITCOCKPIT contacts possible
• Notifications sent by the module can be received by any chat with a real telegram user or by channels
• Acknowledge issues with a button in the bot message (optional with enabled two-way integration)

Read Usage for more information

Installation

Proceed with this installation tutorial if you have a "default" (non-docker) openITCOCKPIT installation.

Latest version from GitHub

• Clone the module contents into /opt/openitc/frontend/plugins/TelegramModule
• Run composer install in /opt/openitc/frontend/plugins/TelegramModule
• Run openitcockpit-update --cc

Commands step by step:

git clone https://github.com/binsky08/openITCOCKPIT-Telegram-Module /opt/openitc/frontend/plugins/TelegramModule

apt-get install composer
composer -d /opt/openitc/frontend/plugins/TelegramModule install

openitcockpit-update --cc

Note for existing installations: the customization of /opt/openitc/frontend/src/Lib/PluginManager.php is no longer needed!

Installation for openitcockpit-ce Docker setup

Proceed with this installation tutorial if you have an openitcockpit-ce Docker setup.

• Clone the module contents into a custom host directory like /opt/TelegramModule
  • git clone https://github.com/binsky08/openITCOCKPIT-Telegram-Module /opt/TelegramModule
• If you have an already existing setup, run docker compose down to stop it.
• Edit your compose.yml and add these two lines to the volume mounts of the service openitcockpit

  - /opt/TelegramModule/:/opt/openitc/frontend/plugins/TelegramModule
  - /opt/TelegramModule/:/opt/openitc/src/frontend/plugins/TelegramModule:ro
  

• Run docker run --rm -it -v /opt/TelegramModule:/app composer install --ignore-platform-reqs --no-scripts to install the module dependencies using a temporary composer docker container
  • or just run composer install in /opt/TelegramModule if you have composer installed at your host system
• Start the openITCOCKPIT docker setup with docker compose up -d

Configuration

Basic configuration

• Open BotFather in telegram
• Run /newbot
  • define e.g. openITCOCKPIT as name
  • define e.g. oitcTGBot as username

Your new bot is now located at t.me/oitcTGBot

• Copy the HTTP API token which was generated by the BotFather.

Keep your token secure and store it safely, it can be used by anyone to control your bot!

• Open the openITCOCKPIT Telegram configuration, enter the copied bot token and save the configuration.

• Add the 'host-notify-by-telegram' and 'service-notify-by-telegram' commands to your notification contact.

• To apply the changed notification contact (with the Telegram notification commands), run an export in openITCOCKPIT.

Extended configuration (recommended)

To enable real-time interactions from the bot with openITCOCKIT, setup the two-way webhook integration.

• Open the openITCOCKPIT Telegram configuration and check the optional field "Enable two-way webhook integration".

• Make sure the configured "External webhook domain" is correct and openITCOCKPIT is reachable from the Internet using this domain.

• Create a new openITCOCKPIT API Key for your user and insert it into the "Webhook api key" field.

• Save the changes and try it out.

openITCOCKPIT automatically set up the webhook for the bot with the given token. This connection can be removed by saving with an unchecked "Enable two-way webhook integration" field.

Usage

Notifications sent by the openITCOCKPIT Telegram Module can be received by any chat with a real telegram user or by channels.

A Telegram chat gets only the notifications for a defined openITCOCKPIT contact. (identified by custom authentication codes)

To start the interaction, search the bot username in the Telegram global search field and start a chat with your bot.

After starting the chat you need to authorize yourself with an authentication code for a openITCOCKPIT Contact, that can be manually generated in the openITCOCKPIT Telegram configuration for Contacts containing a Telegram notification command. (type /auth xxx in the chat with your key as xxx)

If the authorization was successful, use the bot control command /start to enable openITCOCKPIT notifications. Otherwise you will not receive any notifications.

With enabled two-way integration, issues can be acknowledged by simply clicking the button for an action provided by the bot message.

If your openITCOCKPIT is reachable from the Internet and you configured the two-way webhook integration, interactions with the bot are processed within seconds.

If your openITCOCKPIT is not reachable from the Internet, the built-in basic one-way integration calls up interactions cached by Telegram and processes them every minute. (Therefore, interactions with the bot can take up to a minute to process!)

Run /help in bot chat to get more information about how to control the bot.

Update

• Extract the current release archive over the existing TelegramModule folder or pull from the main branch
• Install dependencies
• Run an openitcockpit-update
• Apply new user roles if required
• Refresh monitoring configuration in the openITCOCKPIT web frontend

Commands

git -C /opt/openitc/frontend/plugins/TelegramModule pull
composer -d /opt/openitc/frontend/plugins/TelegramModule install
openitcockpit-update --cc

Commands for openitcockpit-ce Docker setup

Run these commands on the Docker host system of your openitcockpit-ce setup.

git -C /opt/TelegramModule pull
docker run --rm -it -v /opt/TelegramModule:/app composer install --ignore-platform-reqs --no-scripts
docker compose exec openitcockpit openitcockpit-update --cc

Troubleshooting

• If you aren't using the two-way integration or switching from two-way to one-way, it could happen that the cronjob is not going to be executed by openITCOCKPIT.
  • That problem should be solved after running it once manually: oitc cronjobs -f -t TelegramProcessUpdates
  • Note that the cron job is not needed if you use a two-way setup of this plugin