Skip to content

Перенос хостов между серверами Glaber/Zabbix

Скрипт scripts/importer/import_hosts.py переносит хосты вместе с зависимыми группами хостов и шаблонами с одного сервера Glaber (или Zabbix) на другой через JSON-RPC API (api_jsonrpc.php). Для работы требуется только Python 3, установка дополнительных библиотек не нужна.

Назад

Этот раздел входит в главу Администрирование Glaber.

Принцип работы

Перенос выполняется по этапам, чтобы зависимости всегда создавались раньше объектов, которые от них зависят:

  1. Источник. Перечисляются все хосты источника вместе с группами хостов и шаблонами, от которых зависит каждый хост.
  2. Назначение. Перечисляются хосты, группы и шаблоны на целевом сервере.
  3. Дельта. Исключаются:
    • хосты, которые уже есть на назначении (совпадение по техническому или видимому имени);
    • шаблоны и группы, которые уже присутствуют на назначении;
    • хосты, перечисленные в файле no_import.txt;
    • хосты, созданные автоматически — сетевым обнаружением (discovery) или LLD-прототипами хоста (признак flags = 4). Они не переносятся никогда, так как будут заново созданы собственными правилами обнаружения на назначении;
    • при флаге --enabled-hosts-only — хосты, отключённые (не мониторятся) на источнике.

Кроме того, напрямую привязанные к хостам шаблоны, а также шаблоны, перечисленные в файле imports.txt (см. ниже), разворачиваются в полную цепочку зависимостей (замыкание шаблонов): в него попадают и шаблоны, привязанные к другим шаблонам как родительские (parentTemplates), и шаблоны, на триггеры которых ссылаются зависимости триггеров импортируемых шаблонов, — даже если между ними нет связи шаблон-в-шаблоне (см. ниже). 4. Зависимости. Недостающие группы экспортируются с источника и импортируются на назначение, затем то же самое делается для шаблонов — по одному в порядке, при котором и родительские шаблоны, и шаблоны-источники зависимостей триггеров создаются раньше зависимых, чтобы вложенные шаблоны и их триггеры разрешились корректно, а отклонённый шаблон был виден по имени. 5. Хосты. Оставшиеся хосты импортируются по одному, с выводом прогресса по каждому хосту. Ошибка одного хоста не прерывает перенос остальных.

По умолчанию импорт не перезаписывает существующие объекты: правило updateExisting отключено для всех типов, deleteMissing не включается ни для одного. Исключение — фаза шаблонов, когда источник новее назначения: в этом случае присутствующие шаблоны полностью заменяются новой версией (updateExisting включается для сущностей шаблона), но deleteMissing по-прежнему не используется, поэтому сущности, существующие только на назначении, не удаляются (см. «Автоматическая полная замена шаблонов»).

Триггеры и вложенные зависимости

Хост может зависеть от триггера, а триггер — от другого триггера или от шаблона. Скрипт учитывает это следующим образом:

  • Триггеры хоста переносятся автоматически: configuration.export всегда включает собственные триггеры хоста вместе с их зависимостями (selectDependencies, разрешёнными в выражения). Правило импорта triggers.createMissing воссоздаёт их на назначении.
  • Вложенные шаблоны. Триггер шаблона может зависеть от триггера другого шаблона, привязанного к этому шаблону (шаблон-на-шаблоне). Экспорт шаблона ссылается на родительские шаблоны только по имени, не включая их определение, поэтому скрипт рекурсивно обходит parentTemplates и собирает полное замыкание шаблонов. Все недостающие шаблоны замыкания импортируются до хостов, благодаря чему зависимости триггеров разрешаются.
  • Группы шаблонов. Начиная с версии 6.4 шаблоны принадлежат отдельным группам шаблонов (template_groups). Правила импорта включают template_groups.createMissing, поэтому недостающие группы шаблонов и дашборды шаблонов (templateDashboards) создаются автоматически. Для более старых версий используется правило templateScreens.
  • Зависимости триггера между разными несвязанными хостами в Zabbix/Glaber запрещены, поэтому разрешения замыкания шаблонов достаточно для корректного переноса всех зависимостей.

Количество переносимых элементов данных (items) и триггеров выводится в плане переноса (этап 3) и по каждому хосту (этап 5). Флаг --verify дополнительно перечитывает каждый хост с назначения после импорта и сверяет число элементов и триггеров с источником.

Подготовка

Подготовьте учётные данные для обоих серверов. Доступны два способа аутентификации:

  • логин и пароль пользователя с правами на чтение источника и запись на назначении;
  • API-токен (рекомендуется) — создаётся в разделе Administration → API tokens.

Пароли и токены можно передать через переменные окружения, чтобы они не попадали в историю команд: SOURCE_PASSWORD, SOURCE_TOKEN, DEST_PASSWORD, DEST_TOKEN, а также SOURCE_USER, DEST_USER.

Запуск

Сначала выполните «холостой» прогон — он покажет, что будет перенесено, но не внесёт изменений:

python3 scripts/importer/import_hosts.py \
  --source-url https://source-glaber/api_jsonrpc.php \
  --source-token "$SOURCE_TOKEN" \
  --dest-url https://dest-glaber/api_jsonrpc.php \
  --dest-token "$DEST_TOKEN" \
  --dry-run

Если результат устраивает, запустите реальный перенос (без --dry-run):

python3 scripts/importer/import_hosts.py \
  --source-url https://source-glaber/api_jsonrpc.php \
  --source-user Admin --source-password "$SOURCE_PASSWORD" \
  --dest-url https://dest-glaber/api_jsonrpc.php \
  --dest-user Admin --dest-password "$DEST_PASSWORD"

Для серверов с самоподписанными сертификатами добавьте флаг --insecure.

Основные параметры

Параметр Назначение
--source-url / --dest-url URL api_jsonrpc.php источника и назначения (обязательные)
--source-user / --dest-user пользователь для входа
--source-password / --dest-password пароль (или переменные SOURCE_PASSWORD / DEST_PASSWORD)
--source-token / --dest-token API-токен вместо логина и пароля
--no-import-file путь к файлу исключений (по умолчанию — no_import.txt рядом со скриптом)
--imports-file путь к файлу imports.txt со списком дополнительных имён шаблонов для импорта (по умолчанию — файл рядом со скриптом); каждое имя ищется на источнике и импортируется, если его ещё нет на назначении
--host-filter переносить только хосты, имя которых совпадает с glob-шаблоном
--enabled-hosts-only пропускать хосты, отключённые (не мониторятся) на источнике
--insecure не проверять TLS-сертификаты
--timeout таймаут HTTP-запросов в секундах (по умолчанию 60)
--export-version принудительно задать zabbix_export.version перед импортом (например 6.0); по умолчанию версия понижается до версии назначения только если источник новее
--strip-unknown адаптировать экспорт под старшую версию назначения: удалить атрибуты, неизвестные схеме назначения (устраняет ошибки unexpected tag), и добавить обязательные теги, которые новый источник не экспортирует (например formulaid у условий фильтра); сейчас схема включена для назначения 6.4. Пересчёт координат виджетов дашбордов с более широкой сетки новой версии (7.0+ — 72 колонки, 6.4 — 24) под сетку назначения выполняется автоматически и не требует этого флага
--verify после импорта каждого хоста перечитать его с назначения и сверить число элементов и триггеров с источником
--dry-run показать план переноса без внесения изменений

Файл исключений no_import.txt

Рядом со скриптом находится файл scripts/importer/no_import.txt. В нём перечисляются имена хостов, которые нужно исключить из переноса. Правила:

  • одно имя хоста на строку;
  • имя сопоставляется и с техническим именем хоста (host), и с видимым (name), без учёта регистра;
  • пустые строки и строки, начинающиеся с #, игнорируются.

Пример:

# Эти хосты не переносим
template-host-do-not-touch
Test server

Чтобы использовать другой файл, укажите его через --no-import-file /путь/к/файлу.

Файл imports.txt — импорт шаблонов по имени

Рядом со скриптом находится файл scripts/importer/imports.txt. Он позволяет явно перечислить шаблоны, которые нужно перенести, даже если ни один из переносимых хостов к ним не привязан. Правила:

  • одно имя шаблона на строку;
  • имя сопоставляется и с видимым именем шаблона (name), и с техническим (host), без учёта регистра;
  • допускаются glob-шаблоны (* и ?), например Template Net *;
  • пустые строки и строки, начинающиеся с #, игнорируются.

Каждое имя ищется на источнике; найденный шаблон вместе со связанными с ним родительскими шаблонами и шаблонами-целями зависимостей триггеров попадает в замыкание и импортируется только если его ещё нет на назначении (проверка по имени/техническому имени, как и для шаблонов переносимых хостов). Имена, не нашедшие соответствия на источнике, выводятся отдельной строкой и пропускаются.

Пример:

# Эти шаблоны нужно перенести, даже если ни один хост к ним не привязан
Template App OS Linux
Template DB PostgreSQL
Template Net *

Так как шаблоны из imports.txt импортируются независимо от хостов, прогон выполнит фазу импорта шаблонов, даже если новых хостов для переноса нет. Чтобы использовать другой файл, укажите его через --imports-file /путь/к/файлу.

Пример вывода

Ниже показан типичный прогон. Обратите внимание на строку о замыкании шаблонов и на количество переносимых элементов и триггеров:

phase 1: enumerating source hosts, groups and templates ...
  42 host(s), 7 host group(s)
phase 2: enumerating destination hosts, groups and templates ...
  destination already has 10 host name(s), 3 group(s), 24 template name(s)
phase 3: computing the delta ...
  import: 12 host(s); skip existing: 28; skip excluded: 2; skip disabled: 0; skip discovered: 5
  template closure: 31 template(s) (18 directly linked); missing groups: 4; missing templates: 9
  entities to transfer: 2410 item(s), 1834 trigger(s) across 12 host(s)
phase 4: creating missing groups and templates ...
  importing 4 host group(s): Linux servers, Databases, ...
  importing 9 template(s) incl. nested parents: Template OS Linux, Template ICMP Ping, ...
phase 5: importing hosts one by one ...
  [1/12] db-01 (410 item(s), 312 trigger(s)) -> imported, 410 item(s)/312 trigger(s) verified
  [2/12] web-01 (233 item(s), 188 trigger(s)) -> imported, 233 item(s)/188 trigger(s) verified
  ...
done: 12 host(s) imported, 0 failed

Перенос со старшей версии на младшую

configuration.export всегда формирует файл в формате своей версии (zabbix_export.version, например 6.4 для Glaber 6.4). Если назначение — сервер более старой версии, его валидатор импорта отвергает такой файл с ошибкой:

Invalid tag "/zabbix_export/version": unsupported version number

Скрипт обрабатывает этот случай автоматически: перед каждым импортом он понижает значение zabbix_export.version до собственной версии назначения (major.minor). При подключении выводится соответствующее уведомление:

connecting to destination https://dest-glaber/api_jsonrpc.php ...
  destination API 6.0.20
  NOTE: source (6.4.10) is newer than destination (6.0.20); export version will be rewritten to 6.0 before import

Поведение:

  • версия понижается только при необходимости — если назначение той же версии или новее, данные передаются без изменений (повышение версии не выполняется);
  • тело экспорта не изменяется — переписывается только тег версии;
  • если автоопределения недостаточно, задайте версию вручную флагом --export-version, например --export-version 6.0. Он применяется всегда, даже если назначение новее источника.

Ограничение

Само по себе понижение переписывает только номер версии. Если в данных встречаются сущности или поля, которых старая схема не знает (например monitored_by и proxy_group у хостов, template_groups и дашборды шаблонов появились в 6.4/7.0), валидатор назначения отвергает их отдельной ошибкой:

Invalid tag "/zabbix_export/hosts/host/monitored_by": unexpected tag "monitored_by"

Неизвестные теги не игнорируются — импорт прерывается. Обратная ситуация тоже возможна: обязательный для старой схемы тег новая версия может не экспортировать (например formulaid у условий фильтра LLD в 7.0+), и тогда валидатор назначения сообщает the tag ... is missing. Третья разновидность — валидированный тег, но значение вне допустимого для старой версии диапазона: так, координаты виджетов дашбордов из 7.0+ (сетка 72 колонки) не проходят на 6.4 (сетка 24 колонки) с ошибкой Invalid parameter "/.../widgets/N/x": value must be one of 0-23. Чтобы автоматически привести экспорт к схеме назначения (срезать неизвестные теги и добавить обязательные), используйте флаг --strip-unknown. Пересчёт сетки дашбордов выполняется автоматически всегда, когда источник новее назначения, и не требует этого флага.

Адаптация экспорта под старшую версию (--strip-unknown)

Валидатор импорта строг в обе стороны: тег, которого нет в схеме версии назначения, вызывает ошибку unexpected tag, а обязательный тег, который новая версия не экспортирует, — ошибку the tag ... is missing. Кроме того, значения некоторых полей новой версии не проходят проверку диапазона на старой (например координаты виджетов дашбордов). Перед импортом скрипт рекурсивно обходит экспортированный JSON и

  1. удаляет атрибуты, отсутствующие в схеме назначения — по флагу --strip-unknown;
  2. добавляет обязательные теги, которые новый источник не экспортирует, — тоже по флагу --strip-unknown;
  3. пересчитывает координаты виджетов дашбордов с более широкой сетки новой версии на сетку назначения — автоматически, независимо от флага (это правка чисто на понижение версии: она нужна всегда, когда источник новее).

Схема получена непосредственно из валидатора назначения (ui/include/classes/import/validators/C64XmlValidator.php) и встроена прямо в import_hosts.py — скрипт остаётся одним самодостаточным файлом, отдельные модули не нужны.

Поведение:

  • схема привязана к версии назначения (или к версии из --export-version, если он задан). Сейчас включена схема для 6.4 — текущей версии Glaber;
  • удаление выполняется консервативно: теги срезаются только там, где набор допустимых потомков известен точно. Поддеревья с условной/динамической схемой (например параметры шагов предобработки) считаются «непрозрачными» и не трогаются, поэтому корректные данные никогда не удаляются по ошибке;
  • индексируемые массивы (hosts, items, tags, interfaces и т. п.) обрабатываются поэлементно;
  • добавление обязательных тегов: начиная с 7.0 условия фильтра LLD экспортируются без formulaid (кроме фильтров с пользовательской формулой), тогда как схема 6.4 требует его у каждого условия. Скрипт проставляет отсутствующие formulaid позиционно (A, B, C, …) — в фильтрах правил обнаружения и в фильтрах переопределений (overrides), ровно так же, как это сделал бы экспорт 6.4;
  • пересчёт сетки дашбордов: начиная с 7.0 ширина сетки виджетов (DASHBOARD_MAX_COLUMNS) выросла с 24 до 72 колонок, поэтому координата x (и width) виджета из нового источника не проходит проверку диапазона на 6.4 — Invalid parameter "/.../widgets/N/x": value must be one of 0-23. Скрипт масштабирует x и width каждого виджета обратно на сетку назначения (деление на 3 для 72 → 24, с округлением вниз, width не меньше 1, x + width не выходит за границы). y/height не трогаются: строк в 6.4 больше (128 против 64), поэтому значения нового источника всегда помещаются. Виджет, который после сжатия наложился бы на уже размещённый на той же странице, отбрасывается (валидатор назначения отвергает пересечения); счётчики пересчитанных и отброшенных виджетов выводятся в итоговом отчёте. Пересчёт выполняется автоматически (не требует --strip-unknown) и только при понижении версии — когда сетка источника шире сетки назначения;
  • если флаг задан, но для версии назначения схемы нет, скрипт не продолжает работу молча: выводится ошибка и перенос прерывается с кодом возврата 2 (чтобы вы не получили ту же ошибку уже от сервера назначения).

Пример уведомления при подключении и итогового отчёта:

connecting to destination https://dest-glaber/api_jsonrpc.php ...
  destination API 6.4.11
  adapting export for destination 6.4 on import (strip unknown tags, add missing required tags, rescale wider dashboard grids)
...
stripped 37 unsupported tag(s) before import (e.g. discover, granularity, monitored_by, proxy_group, ...)
added 12 missing filter formulaid(s) for destination 6.4
rescaled 9 dashboard widget(s) to the destination's 24-column grid; dropped 1 overlapping widget(s)

Таким образом, типичный перенос с Zabbix 7.x/8.x на Glaber 6.4 выполняется комбинацией флагов --strip-unknown (и, при необходимости, --export-version):

python3 scripts/importer/import_hosts.py \
  --source-url https://new-zabbix/api_jsonrpc.php --source-token "$SOURCE_TOKEN" \
  --dest-url https://dest-glaber/api_jsonrpc.php --dest-token "$DEST_TOKEN" \
  --strip-unknown

Зависимости триггеров и обновление шаблонов

Ошибка «Trigger ... depends on trigger ..., which does not exist»

При импорте шаблона валидатор назначения разрешает зависимости триггеров, отыскивая целевой триггер среди (а) триггеров, созданных этим же импортом, и (б) триггеров, уже существующих на сервере назначения, — но только при точном совпадении имени, выражения и recovery-выражения (CImportReferencer::findTriggeridByName / selectTriggers). Если целевого триггера нет ни там, ни там, импорт шаблона прерывается этой ошибкой.

Типичные причины:

  • устаревший шаблон-родитель уже есть на назначении. По умолчанию скрипт пропускает шаблоны, которые уже присутствуют (по имени/техническому имени), и не переносит их заново. Если на назначении лежит старая копия родительского шаблона без триггера, на который ссылается зависимость, целевой триггер не будет найден. Это самая частая причина — «старый шаблон» (устраняется полной заменой шаблона новой версией, см. ниже);
  • зависимость на триггер шаблона, которого нет в экспорте. Зависимость триггера может указывать на триггер шаблона, не связанного с импортируемым как родитель (parentTemplates), — например на «соседний» шаблон, привязанный к тому же хосту. API запрещает зависимость от триггеров родительского шаблона, поэтому цель почти всегда именно соседняя. Скрипт автоматически находит такие цели и добавляет шаблоны-источники в замыкание (см. ниже), поэтому эта причина устранена; остаётся лишь риск «висячей» зависимости, оставшейся после удаления связи, когда целевого триггера больше нет нигде;
  • расхождение имени/выражения. Целевой триггер на назначении существует, но его техническое имя хоста/шаблона или выражение отличаются от экспортированных, поэтому точное сопоставление не срабатывает.

Расширение замыкания по зависимостям триггеров

Замыкание шаблонов строится не только по связям parentTemplates, но и по зависимостям триггеров: для каждого шаблона в замыкании скрипт запрашивает его триггеры (trigger.get с selectDependencies), находит шаблоны-владельцы целевых триггеров (selectHosts, отбирая только шаблоны — status = 3) и добавляет их в замыкание, рекурсивно раскрывая уже их parentTemplates и их собственные зависимости триггеров. Так шаблон, на триггер которого есть зависимость, но который не связан с импортируемым как родитель, всё равно попадает в экспорт и создаётся на назначении раньше зависимого шаблона (порядок учитывает оба типа рёбер). Дополнительная страховка — повторные проходы импорта (см. «Импорт шаблонов по одному»).

Автоматическая полная замена шаблонов

Чтобы устранить первую причину, когда источник новее назначения (например Zabbix 8.0 → Glaber 6.4), скрипт автоматически импортирует всё замыкание шаблонов, а не только отсутствующие. Уже присутствующие шаблоны при этом полностью заменяются новой версией: правила импорта включают updateExisting для сущностей шаблона (сам шаблон, элементы, триггеры, графики, правила обнаружения, веб-сценарии, карты значений, дашборды), поэтому определения из источника перезаписывают старую копию на назначении, а недостающие сущности создаются.

Группы (host_groups, template_groups) остаются в режиме «только создание» — общая группа никогда не переименовывается. Правило deleteMissing не включается, поэтому сущности, которые существуют только на назначении (например добавленные вручную), сохраняются и не удаляются.

Поведение включается без отдельного флага — по факту того, что версия источника новее (выше) версии назначения, и отражается в логе:

  NOTE: source (8.0.x) is newer than destination (6.4.11); export version will be
  rewritten to 6.4 before import, and templates already on the destination will be
  REPLACED by the newer source (updateExisting overwrites their entities; entities
  that exist only on the destination are kept, nothing is deleted)
...
  template closure: 42 template(s) (7 seeded); missing groups: 0;
  missing templates: 12; replacing 30 present template(s) with the newer source (updateExisting)
...
  importing 42 template(s) one by one (parents first, replacing existing (newer source)), ...

Если источник не новее назначения, как и раньше импортируются только отсутствующие шаблоны (в режиме «только создание», без перезаписи).

Note

Полная замена перезаписывает существующие сущности шаблона определениями из источника (например изменившуюся важность триггера или определение элемента) и создаёт недостающие, но не удаляет сущности, которые существуют только на назначении (deleteMissing отключено). То есть содержимое шаблона приводится к источнику для всех определённых в нём сущностей, однако добавленные на назначении вручную объекты сохраняются.

Импорт шаблонов по одному

Шаблоны импортируются по одному отдельным вызовом в порядке «сначала родители» (родительские шаблоны создаются до дочерних, поэтому внутрисемейные зависимости разрешаются штатно) и продолжая после ошибок, логируя каждый отклонённый шаблон по имени. Это позволяет точно увидеть, какой именно шаблон вызывает ошибку:

  importing 42 template(s) one by one (parents first, creating missing), continuing past failures: ...
  [1/42] template Template App OS -> imported
  [2/42] template Template DB MySQL -> FAILED: Trigger "..." depends on trigger "...", which does not exist.
  ...
  2 template(s) failed to import:
    - Template DB MySQL: Trigger "..." depends on trigger "...", which does not exist.

Порядок «сначала родители» учитывает только связи шаблон-в-шаблоне (parentTemplates). Однако триггер шаблона может зависеть от триггера соседнего шаблона, привязанного к тому же хосту (зависимости от триггеров родительского шаблона API запрещает, а соседний — разрешён), и между такими шаблонами нет связи parentTemplates, поэтому порядок их импорта не гарантирован. Чтобы это покрыть, отклонённые шаблоны импортируются повторными проходами, пока очередной проход не добавит ни одного нового шаблона: как только шаблон-источник зависимости появляется на назначении, зависимый шаблон импортируется со следующей попытки.

  [2/42] template Template DB MySQL -> FAILED: Trigger "..." depends on trigger "...", which does not exist.
  ...
  1 template(s) still failing after pass 1 (likely unresolved cross-template trigger dependencies); retrying ...
  [1/1] template Template DB MySQL (pass 2) -> imported

Если повторный проход не даёт прогресса (или исчерпано число проходов), оставшиеся ошибки считаются настоящими и выводятся по именам — бесконечного цикла не возникает.

Код возврата становится 1, если хотя бы один шаблон не удалось импортировать.

Код возврата

  • 0 — перенос завершён успешно (или в режиме --dry-run);
  • 1 — один или несколько хостов либо шаблонов не удалось импортировать, в том числе при несовпадении числа элементов или триггеров с флагом --verify;
  • 2 — ошибка подключения или API, либо --strip-unknown задан, но для версии назначения нет встроенной схемы (перенос прерывается до импорта);
  • 130 — выполнение прервано пользователем.