Настройка оповещений из Zabbix в Matrix - полное руководство для начинающих

Система мониторинга Zabbix умеет отправлять уведомления о проблемах на серверах по электронной почте, в Telegram, Slack и другие сервисы. Но что если вы используете защищённый мессенджер Matrix (например, на базе Synapse)? Интеграция Zabbix с Matrix позволяет получать алерты прямо в комнату, где вся команда может быстро на них реагировать. В этой статье мы подробно разберём, как настроить zabbix отправка оповещений в matrix с помощью небольшого Python-скрипта. Вам не потребуются дополнительные библиотеки только стандартный Python, уже установленный на сервере Zabbix.

Содержание:

Зачем отправлять оповещения Zabbix в Matrix?

Matrix это децентрализованный, безопасный и открытый протокол для обмена сообщениями. Он позволяет создавать комнаты, вести историю, поддерживает end-to-end шифрование.
Интеграция с Zabbix даёт следующие преимущества:

Мгновенная доставка уведомлений в удобный мессенджер.
Возможность группового обсуждения проблем прямо в комнате с алертами.
Отсутствие зависимости от внешних платных сервисов (если вы сами хостите Matrix).
Гибкое форматирование сообщений с поддержкой HTML.

Что потребуется для настройки

Перед началом убедитесь, что у вас есть:

Работающий сервер Zabbix (версия 5.0 или новее) с доступом к интернету или к вашему Matrix-серверу.
Сервер Matrix (например, Synapse) или доступ к существующему домашнему серверу. Подойдёт как публичный сервер (matrix.org), так и ваш собственный.
Аккаунт пользователя-бота в Matrix (не используйте личный аккаунт).
Комната в Matrix, куда будут приходить уведомления.
Базовые навыки работы с командной строкой Linux.

Вся интеграция строится вокруг скрипта на Python, который Zabbix будет вызывать при срабатывании триггера. Скрипт использует стандартную библиотеку Python (urllib, json) и не требует установки дополнительных пакетов.

Часть 1. Подготовка на стороне Matrix

Прежде чем трогать Zabbix, нужно создать бота и получить все необходимые идентификаторы.

1.1. Регистрация пользователя-бота

Зарегистрируйте нового пользователя на вашем Matrix-сервере. Лучше использовать имя, отражающее его роль, например @zabbix-bot:yourdomain.com. Сделать это можно через любой клиент Matrix (Element, FluffyChat, командная строка). Запомните пароль он понадобится для получения токена доступа.

1.2. Создание комнаты для уведомлений

Создайте комнату (публичную или приватную), в которую будут приходить алерты. Пригласите туда только что созданного бота.

1.3. Принятие приглашения ботом

Войдите в аккаунт бота через клиент и подтвердите участие в комнате. Если вы используете клиент Element, зайдите под ботом, откройте раздел «Приглашения» и примите приглашение.

1.4. Получение необходимых параметров

Вам понадобятся три значения:

Homeserver URL — адрес вашего Matrix-сервера. Например, https://matrix.yourdomain.com или https://matrix.org. Обязательно с протоколом HTTPS.
Room ID — внутренний идентификатор комнаты. В Element его можно найти в настройках комнаты: откройте комнату → нажмите на название комнаты вверху → «Настройки» → вкладка «Дополнительно» → скопируйте «Внутренний идентификатор комнаты». Выглядит он примерно так: !abcdefghijk:yourdomain.com.
Access Token бота. В Element: кликните на аватар бота → «Настройки» → «Справка и о нас» → внизу «Дополнительно» → «Токен доступа». Нажмите кнопку «Получить токен». Скопируйте длинную строку, начинающуюся с syt_....

Важно: токен доступа даёт полный доступ к аккаунту бота. Храните его в безопасности. Никому не показывайте.

Часть 2. Создание скрипта оповещения на сервере Zabbix

Zabbix вызывает внешние скрипты из директории, указанной в параметре AlertScriptsPath. По умолчанию в Ubuntu/Debian это /usr/lib/zabbix/alertscripts/.

2.1. Написание скрипта

Подключитесь к серверу Zabbix по SSH и создайте файл скрипта:

bash

sudo nano /usr/lib/zabbix/alertscripts/matrix_notification.py

Вставьте следующий код. Скрипт принимает 4 аргумента: адрес сервера Matrix, Room ID, токен доступа и текст сообщения (все остальные аргументы объединяются в одно сообщение). Он формирует HTML-версию сообщения (замена переносов строк на <br>) и отправляет через Matrix Client-Server API.

python

#!/usr/bin/env python3
import sys
import json
import time
import uuid
import urllib.request
import urllib.parse
import ssl

# Проверяем, что передано достаточно аргументов
if len(sys.argv) < 4:
    print("Usage: matrix_notification.py <homeserver_url> <room_id> <access_token> <message...>")
    sys.exit(1)

HOMESERVER_URL = sys.argv[1].strip('/')
ROOM_ID = urllib.parse.quote(sys.argv[2], safe='')
ACCESS_TOKEN = sys.argv[3]

# Объединяем все остальные аргументы в одно сообщение (поддерживает многострочный текст)
MESSAGE_BODY = "\n".join(sys.argv[4:])

# Генерируем уникальный идентификатор транзакции, чтобы избежать дублей
txid = f"zabbix_{int(time.time()*1000)}_{uuid.uuid4().hex[:8]}"

url = f"{HOMESERVER_URL}/_matrix/client/r0/rooms/{ROOM_ID}/send/m.room.message?access_token={ACCESS_TOKEN}"

# HTML-форматирование: заменяем переводы строк на <br>
html_body = MESSAGE_BODY.replace('\n', '<br>')

data = {
    "msgtype": "m.text",
    "body": MESSAGE_BODY,
    "format": "org.matrix.custom.html",
    "formatted_body": html_body
}

req = urllib.request.Request(
    url,
    data=json.dumps(data).encode('utf-8'),
    headers={'Content-Type': 'application/json'},
    method='POST'
)

try:
    with urllib.request.urlopen(req, timeout=10) as response:
        res = json.loads(response.read().decode('utf-8'))
        print(f"Success: Event ID {res.get('event_id')}")
except Exception as e:
    print(f"Error sending message: {e}", file=sys.stderr)
    sys.exit(1)

Примечание: Для тестовых сред с самоподписанными сертификатами: если ваш Matrix-сервер использует собственный SSL-сертификат, не заверенный официальным центром, Python будет выдавать ошибку SSL. Для отладки можно временно отключить проверку сертификата, добавив в начало скрипта (после импортов) следующий код:

python

ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

а затем в вызове urlopen указать context=ctx. Не используйте это в production.

2.2. Настройка прав

Сделайте скрипт исполняемым и установите владельца zabbix:

bash

sudo chmod +x /usr/lib/zabbix/alertscripts/matrix_notification.py
sudo chown zabbix:zabbix /usr/lib/zabbix/alertscripts/matrix_notification.py

2.3. Ручное тестирование скрипта

Перед настройкой Zabbix проверьте, что скрипт работает. Замените значения на свои:

bash

sudo -u zabbix /usr/lib/zabbix/alertscripts/matrix_notification.py \
  "https://matrix.yourdomain.com" \
  "!room_id:yourdomain.com" \
  "syt_your_bot_token" \
  "Тестовое сообщение из командной строки"

Если в вашей комнате Matrix появилось сообщение скрипт работает корректно. Если нет, проверьте правильность URL, Room ID и токена, а также сетевые доступы с сервера Zabbix к вашему Matrix-серверу.

Часть 3. Интеграция с Zabbix (веб-интерфейс)

Теперь подключим скрипт к Zabbix как способ оповещения (Media Type) и настроим действия.

3.1. Создание способа оповещения (Media Type)

Зайдите в веб-интерфейс Zabbix под администратором. Перейдите в Администрирование → Способы оповещений. Нажмите кнопку Создать способ оповещения.

Заполните поля:

Имя: Matrix
Тип: Скрипт
Имя скрипта: matrix_notification.py (без полного пути, Zabbix сам ищет в AlertScriptsPath)
Скриптовые параметры добавляем три параметра, которые будут передаваться скрипту. Zabbix автоматически подставит значения из настроек пользователя и макросов.

Вариант 1 (простой, но менее безопасный): прямо указываем URL и токен в параметрах. Не подходит для production, потому что секрет виден в интерфейсе.

https://matrix.yourdomain.com
{ALERT.SENDTO}
syt_your_bot_token
{ALERT.SUBJECT}
{ALERT.MESSAGE}

Вариант 2 (рекомендованный): используем глобальные макросы для хранения секретов.

Сначала создайте глобальные макросы. Перейдите в Администрирование → Общие → Макросы. Добавьте два макроса:

Макрос	Значение
`{$MATRIX_HOMESERVER}`	`https://matrix.yourdomain.com`
`{$MATRIX_BOT_TOKEN}`	`syt_your_bot_token`

Затем в параметрах скрипта укажите:

{$MATRIX_HOMESERVER}
{ALERT.SENDTO}
{$MATRIX_BOT_TOKEN}
{ALERT.SUBJECT}
{ALERT.MESSAGE}

Теперь при редактировании Media Type вы не увидите реальный токен он будет скрыт. Макросы видны только пользователям с правом доступа к ним.

Нажмите Добавить.

3.2. Назначение медиатипа пользователю

Перейдите в Администрирование → Пользователи. Выберите пользователя, который будет получать уведомления (например, Admin). Откройте вкладку Оповещения (Media). Нажмите Добавить.

Заполните:

Тип: Matrix
Отправлять на: вставьте Room ID комнаты (например, !abcdefg:yourdomain.com). Именно это значение попадёт в макрос {ALERT.SENDTO}.
Остальные поля (время отправки, период) оставьте по умолчанию.

Нажмите Добавить.

3.3. Создание действия (Action)

Действия определяют, на какие события Zabbix будет отправлять уведомления и кому.

Перейдите в Настройка → Действия → Действия триггеров. Нажмите Создать действие (или отредактируйте существующее). Вкладка Действие:

Имя: Отправка в Matrix
Условия: задайте, какие события должны срабатывать (например, важность «Высокая» или «Средняя»). Можно оставить пустым для всех.

Вкладка Операции здесь настраивается, что именно делать при проблеме.

Нажмите Добавить в блоке «Операции». Заполните:

Тип операции: Отправить сообщение
Пользователи: выберите того пользователя, которому вы добавили медиатип Matrix.
Тип медиа: Matrix (можно оставить «Все», если нет других способов).

Ниже задайте Тема и Сообщение. Здесь можно использовать макросы Zabbix и HTML-теги (они будут преобразованы в форматированный текст Matrix). Пример для проблемы:

Тема:

Проблема: {EVENT.NAME}

Сообщение:

html

<b>Проблема: {EVENT.NAME}</b><br>
<font color="red">Важность: {EVENT.SEVERITY}</font><br>
Узел: {HOST.NAME}<br>
Время: {EVENT.TIME}<br>
<code>{ITEM.LASTVALUE}</code>

Для операции восстановления (когда проблема решена) нажмите Добавить в блоке «Операции восстановления». Заполните аналогично, но с другим текстом:

html

<b> Проблема устранена: {EVENT.RECOVERY.NAME}</b><br>
Узел: {HOST.NAME}<br>
Время восстановления: {EVENT.RECOVERY.TIME}

Сохраните действие.

Часть 4. Проверка работоспособности

Чтобы убедиться, что zabbix отправка оповещений в matrix работает, создайте тестовый триггер или просто отключите какой-нибудь агент. Через несколько секунд в комнате Matrix должно появиться сообщение о проблеме. Затем восстановите состояние (включите агент) — должно прийти сообщение о восстановлении.

Если сообщения не приходят:

Проверьте логи Zabbix (вкладка Отчётность → Действия там будет статус каждой операции).
Проверьте системный журнал сервера Zabbix: tail -f /var/log/zabbix/zabbix_server.log ищите ошибки, связанные с matrix_notification.py.
Запустите скрипт вручную от пользователя zabbix (как в разделе 2.3) и убедитесь, что он отрабатывает без ошибок.

Часть 5. Рекомендации по безопасности

Храните токен в глобальных макросах, а не в параметрах Media Type. Это скрывает секрет от посторонних глаз. Макросы, содержащие конфиденциальные данные, не должны быть доступны всем пользователям.
Ограничьте права на скрипт. Установите chmod 750 или 700 на matrix_notification.py, чтобы только пользователь zabbix и члены группы могли его читать.
Используйте отдельного бота с минимальными правами. Не передавайте личный токен администратора.
Применяйте HTTPS для соединения с Matrix-сервером. Никогда не используйте HTTP в production.
Включите проверку SSL-сертификата не отключайте её в production, как показано в предупреждении выше.

Часть 6. Расширенные возможности (по желанию)

6.1. Конфигурационный файл вместо аргументов

Если вы не хотите передавать токен даже через глобальные макросы, можно вынести настройки в файл. Создайте /etc/zabbix/matrix.conf с содержимым:

json

{
  "homeserver": "https://matrix.yourdomain.com",
  "token": "syt_your_bot_token",
  "default_room": "!default_room_id:yourdomain.com"
}

Установите права 640 и владельца zabbix:zabbix. Затем измените скрипт, чтобы он читал конфиг из файла. В параметрах Media Type останется передавать только сообщение и, опционально, Room ID.

6.2. Отправка файлов (графиков)

Matrix API позволяет загружать файлы. Можно расширить скрипт, чтобы он прикреплял скриншоты графиков из Zabbix (например, если Zabbix сгенерировал PNG). Это требует дополнительного кода для загрузки через /upload и отправки m.image события.

6.3. Экранирование HTML-тегов в сообщениях

Если макросы Zabbix могут содержать символы < и >, они могут испортить HTML-форматирование. В скрипте можно добавить экранирование: заменить < на < и > на >, но только для тех частей сообщения, которые не являются частью разметки, которую вы создаёте сами. Проще всего формировать сообщение в действии Zabbix, используя только безопасные теги (например, <b>, <i>, <font color>). Спецсимволы внутри макросов лучше экранировать стандартной функцией html.escape в скрипте.

Заключение

Мы полностью разобрали процесс интеграции Zabbix с Matrix: от создания бота и комнаты до написания скрипта и настройки действий в Zabbix. Zabbix отправка оповещений в matrix теперь работает в вашей инфраструктуре. Вы получаете быстрые, красиво оформленные уведомления о проблемах и восстановлении, которые можно обсуждать прямо в комнате с коллегами.

Этот подход использует только стандартные возможности Zabbix и Python, не требует установки дополнительных пакетов и легко переносится на любой сервер. Следуйте рекомендациям по безопасности, и ваш канал оповещений будет надёжным и защищённым.

Расширенная настройка sudo, делегирование прав без компрометации безопасности

Как обновить виндовс 7 до 10 бесплатно

Создание и обслуживание локального RPM/DEB-репозитория для изолированных сетей

Windows Update: как обновить винду — полное руководство для начинающих

Настройка оповещений из Zabbix в Matrix — полное руководство для начинающих

Зачем отправлять оповещения Zabbix в Matrix?

Что потребуется для настройки

Часть 1. Подготовка на стороне Matrix

1.1. Регистрация пользователя-бота

1.2. Создание комнаты для уведомлений

1.3. Принятие приглашения ботом

1.4. Получение необходимых параметров

Часть 2. Создание скрипта оповещения на сервере Zabbix

2.1. Написание скрипта

2.2. Настройка прав

2.3. Ручное тестирование скрипта

Часть 3. Интеграция с Zabbix (веб-интерфейс)

3.1. Создание способа оповещения (Media Type)

3.2. Назначение медиатипа пользователю

3.3. Создание действия (Action)

Часть 4. Проверка работоспособности

Часть 5. Рекомендации по безопасности

Часть 6. Расширенные возможности (по желанию)

6.1. Конфигурационный файл вместо аргументов

6.2. Отправка файлов (графиков)

6.3. Экранирование HTML-тегов в сообщениях

Заключение

Возможно будет интересно:

Расширенная настройка sudo, делегирование прав без компрометации безопасности

Как обновить виндовс 7 до 10 бесплатно

Создание и обслуживание локального RPM/DEB-репозитория для изолированных сетей

Windows Update: как обновить винду — полное руководство для начинающих

Share

Copy short link