BrokerBackupPlugin#

Описание плагина#

Плагин предназначен для формирования архивов с резервными копиями файлов брокера Artemis MQ.

Ручное подключение плагина#

Для подключения плагина к SMBX необходимо:

• сформировать конфигурационный файл backupPlugin.conf, в котором должны быть указаны настройки плагина;

• в broker_instance_dir/etc/broker.xml необходимо добавить настройки плагина в разделе broker-plugins;

• в classpath Artemis( e.g.:broker_instance_dir/lib) положить broker-backup-plugin-*.jar-файл.

Настройки плагина#

Все настройки являются необязательными.

Пример конфигурационного файла плагина backupPlugin.conf#

  backupPlugin: {
    BROKER_DIR_PATH: "path_to_broker_config_directory"
    INCLUSION_RULES: "*, subdir/*.xml"
    EXCLUSION_RULES: "*.diz, *.zip"
    BACKUP_DIR_PATH: "path_to_backup_directory"
    BACKUP_FILENAME_PATTERN: "pattern_of_backup_filename"
    DESCRIPTION_FILE_EXTENSION: json
    FILE_PERMISSIONS: "400"
    TIMER_PERIOD_SEC: 600
    BACKUP_STORAGE_LIMIT: 100
    THREAD_PRIORITY: 3
    IS_PURGE_ON: false
    IS_BACKUP_TRIGGER_ON_CRITICAL_FAILURE: false
    IS_BACKUP_TRIGGER_ON_REGISTERED: false
    IS_BACKUP_TRIGGER_ON_TIMER: true
    IS_BACKUP_TRIGGER_ON_RELOAD: false
  }

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

Пример настройки плагина в broker.xml#

<broker-plugins>

  <broker-plugin class-name="ru.sbt.ss.artemis.plugin.backup.BrokerBackupPlugin">
     <property key="CONFIG_PATH" value="path_to_backupPlugin_configuration" />  <!-- ОБЯЗАТЕЛЬНЫЙ путь до конфигурационного файла /-->
     <property key="RELOAD_CHECK_PERIOD_MS" value="period_in_ms" />             <!-- необязательная периодичность проверки планировщиком обнаружения изменений в файле конфигурации в миллисекундах /-->
  </broker-plugin>
</broker-plugins>

Подключение plugin через Jenkins Job artemis_custom#

Для подключения plugin с помощью Jenkins, необходимо в файле inventories/<новая директория>/group_vars/all/vars.yml внести настройки (пример приведен ниже), далее запустить Jenkins Job artemis_custom с параметрами:

• inventory — выбрать инвентори, для которого запускается plugin;

• playbook — artemis.yml;

• tags — plugin_backup.

Пример настройки plugin в vars.yml#

backup_plugin: # конфигурация плагина по созданию архивов
    BROKER_DIR_PATH: "path/to/artemis" # Путь к каталогу с конфигурацией брокера, файлы из которого требуется добавить в архив
    INCLUSION_RULES: "**" # Правила включения файлов исходного каталога в архив
    EXCLUSION_RULES: "" # Правила исключения файлов исходного каталога из архива
    BACKUP_DIR_PATH: "/backup" # Путь к каталогу для сохранения архива
    BACKUP_FILENAME_PATTERN: "backup.%d{yyyy-MM-dd.HH-mm-ss}.zip" # Шаблон имени файла архива
    TIMER_PERIOD_SEC: 86400 # Период времени срабатывания таймера в секундах
    RELOAD_CHECK_PERIOD_SEC: 600 # Период времени проверки факта перезагрузки конфигурации брокера в секундах
    DESCRIPTION_FILE_EXTENSION: json # Расширение файла с описанием архива
    BACKUP_STORAGE_LIMIT: 30 # Максимальное количество архивов на хранении
    THREAD_PRIORITY: 3 #Приоритет процесса создания архивной копии
    IS_PURGE_ON: "true" # Признак включения процедуры чистки архивов
    IS_BACKUP_TRIGGER_ON_CRITICAL_FAILURE: "false" # Признак включения триггера backup по событию брокера CRITICAL FAILURE
    IS_BACKUP_TRIGGER_ON_REGISTERED: "true" # Признак включения триггера создания архива по событию брокера REGISTERED
    IS_BACKUP_TRIGGER_ON_TIMER: "true" # Признак включения триггера создания архива по таймеру
    IS_BACKUP_TRIGGER_ON_RELOAD: "true" # Признак включения триггера создания архива по событию перезагрузки конфигурации брокера

Особенности работы плагина#

Плагин формирует архивную копию в формате ZIP и файл с описанием архива в формате JSON.

Формат файла с архивом бэкапа - ZIP.

Формат файла описания - JSON.

Имена файлов архива и описания архивных копий создаются на основе шаблона из параметра настройки BACKUP_FILENAME_PATTERN.

В архив запаковывается содержимое каталога, путь к которому указан в параметре настройки BROKER_DIR_PATH.

По умолчанию используется «штатный» каталог с конфигурационными файлами брокера broker_instance_dir/etc/.

Архивируемые файлы и вложенные подкаталоги сохраняются в архиве с оригинальной датой и вместе со своими правами доступа (только в POSIX OS). Sticky bit, SUID, SGID - не сохраняются.

В случае недоступности какого-либо архивируемого файла/каталога в момент архивирования, создание копии прекращается и логируется ошибка, что предотвращает получение не консистентных архивных копий.

Пример файла описания архива#

{
  "description" : {
    "archive" : "/path/to/backup/archive/dir/backup.2022-06-17_12-19-38.zip",
    "datetime" : "2022-06-17T12:19:38.621243",
    "trigger" : "TIMER"
  },
  "parameters" : {
    "brokerDirPath" : "/path/to/broker/directory/etc",
    "inclusionRules" : [ "/path/to/broker/directory/etc/*", "/path/to/broker/directory/etc/*/*" ],
    "exclusionRules" : [ "/path/to/broker/directory/etc/*.diz", "/path/to/broker/directory/etc/*.zip", "/path/to/broker/directory/etc/*.json" ],
    "backupDirPath" : "/path/to/backup/archive/dir",
    "backupFileNamePattern" : "backup.%d{yyyy-MM-dd_HH-mm-ss}.zip",
    "descriptionFileExt" : "json",
    "timerPeriodSec" : 10,
    "backupStorageLimit" : 5,
    "isPurgeOn" : true
  }
}

Маски включения и исключения файлов#

В состав архива добавляются только те файлы, имена которых удовлетворяют любой маске из списка включений параметра INCLUSION_RULES.

Если имена файлов соответствуют какой-либо маске из списка исключений параметра EXCLUSION_RULES, файл НЕ включается в архив.

При этом приоритет отдается списку исключений (EXCLUSION_RULES).

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

В маске можно использовать подстановочные символы:

• * символ подстановки любой строки, не содержащей / (может маскировать только имена файлов, но не путей).

• ** символ подстановки любой строки, включая символ / (может маскировать имена файлов с путями).

По умолчанию в архив включаются все файлы исходного каталога, при этом вложенные каталоги игнорируются (*.*).

Список исключений по умолчанию *.zip, *.diz запрещает добавлять в архив файлы с расширениями zip и diz (архива и его описания соответственно).

Маски могут содержать также пути (относительно каталога BROKER_DIR_PATH). Это позволяет включать в архив файлы из вложенных каталогов.

Например, маски из списка включения: *, subdir/*, позволяют добавить в архив все файлы основного каталога и подкаталога с именем subdir.

Следующий список позволяет добавить в архив все файлы из каталогов до второго уровня вложенности включительно: *, */*, */*/*.

Следующий список добавляет все файлы из всех каталогов любого уровня вложенности: **.

Шаблон имени архива#

Имя файла архива формируется в соответствии с шаблоном, который указан в параметре настройки BACKUP_FILENAME_PATTERN, в который может подставляться значение текущих (на момент формирования архива) даты и времени.

Требуемый формат даты и времени задается внутри шаблона выражением: %d{<формат-даты-и-времени>} в соответствии с ISO 8601.

Шаблон по умолчанию: broker.backup.%d{yyyy-MM-dd.HH-mm-ss}.zip.

Архивная копия сохраняется в каталоге, путь к которому указан в параметре настройки BACKUP_DIR_PATH.

По умолчанию используется «штатный» каталог с конфигурационными файлами брокера broker_instance_dir/etc/.

Процедура чистки архивов#

Если включена процедура чистки архивов (признак IS_PURGE_ON = true), плагином будет поддерживаться ограничение на предельное количество одновременно хранимых файлов архивов (определяется параметром BACKUP_STORAGE_LIMIT).

Первыми удаляются наиболее «старые» архивы (по времени создания файла). Вместе с архивами удаляются и файлы их описания.

События-триггеры резервного копирования#

Событием-триггером формирования архива может являться:

• момент регистрации плагина на сервере (REGISTERED):

  • включается параметром настройки IS_BACKUP_TRIGGER_ON_REGISTERED в значении true;

  • по умолчанию: true (включено);

• момент возникновения критической ошибки сервера (CRITICAL_FAILURE):

  • включается параметром настройки IS_BACKUP_TRIGGER_ON_CRITICAL_FAILURE в значении true;

  • по умолчанию: false (выключено);

• таймер (TIMER) с периодом, заданным в параметре настройки TIMER_PERIOD:

  • включается параметром настройки IS_BACKUP_TRIGGER_ON_TIMER в значении true;

  • по умолчанию: true (включено);

  • период таймера по умолчанию: 1 день (86400 сек);

• факт перезагрузки конфигурации плагина (RELOAD):

  • включается параметром настройки IS_BACKUP_TRIGGER_ON_RELOAD в значении true;

  • по умолчанию: true (включено).

Для принудительного создания архива можно использовать событие-триггер REGISTERED, переведя его в значение true.

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

Обработка ошибок загрузки/перезагрузки конфигурации плагина#

Механизм перезагрузки конфигурации реализует следующее поведение в случае возникновения ошибок при чтении или обработке конфигурации методом configProcessor:

• если ошибка происходит при начальной инициализации плагина, то выбрасывается исключение ActiveMQException, которое приводит к остановке брокера.

Пример фрагмента лога:

ERROR ru.sbt.ss.artemis.plugin.backup.BrokerBackupPlugin  - Error occurred on loading BROKER_BACKUP_PLUGIN configuration after initial initialisation
ERROR ru.sbt.ss.artemis.plugin.commons.utils.CommonUtils$  - An error occurred while executing a block of code:String: 1: No configuration setting found for key 'backupPlugin'
    com.typesafe.config.ConfigException$Missing: String: 1: No configuration setting found for key 'backupPlugin'
        at com.typesafe.config.impl.SimpleConfig.findKeyOrNull(SimpleConfig.java:157)
        at com.typesafe.config.impl.SimpleConfig.findOrNull(SimpleConfig.java:175)
        at com.typesafe.config.impl.SimpleConfig.find(SimpleConfig.java:189)
        ...
ERROR org.apache.activemq.artemis.core.server  - AMQ224000: Failure in initialisation
    org.apache.activemq.artemis.api.core.ActiveMQException: String: 1: No configuration setting found for key 'backupPlugin'
        at ru.sbt.ss.artemis.plugin.commons.utils.CommonUtils$.$anonfun$orThrowActiveMQException$1(CommonUtils.scala:26)
        at scala.util.Failure.fold(Try.scala:247)
        ...

• если ошибка происходит при перезагрузке плагина из-за обновления конфигурации, то плагин получает последнюю успешно загруженную конфигурацию через callback-метод onProcessConfig.

Пример фрагмента лога:

INFO  r.s.s.a.p.c.config.reload.PluginConfigurationReloadCallback  - Reloading BROKER_BACKUP_PLUGIN
ERROR ru.sbt.ss.artemis.plugin.backup.BrokerBackupPlugin  - Error occurred on loading BROKER_BACKUP_PLUGIN configuration after reload
    com.typesafe.config.ConfigException$Missing: String: 1: No configuration setting found for key 'backupPlugin'
        at com.typesafe.config.impl.SimpleConfig.findKeyOrNull(SimpleConfig.java:157)
        at com.typesafe.config.impl.SimpleConfig.findOrNull(SimpleConfig.java:175)
        at com.typesafe.config.impl.SimpleConfig.find(SimpleConfig.java:189)
        ...
WARN  ru.sbt.ss.artemis.plugin.backup.BrokerBackupPlugin  - Previous successful configuration will be used: BROKER_BACKUP_PLUGIN_CONFIG:{
    "BACKUP_DIR_PATH" : "/u01/backup-local",
    "BACKUP_STORAGE_LIMIT" : 10,
    "EXCLUSION_RULES" : "*.diz, *.zip",
    "FILE_PERMISSIONS" : "400",
    "IS_BACKUP_TRIGGER_ON_CRITICAL_FAILURE" : true,
    "IS_BACKUP_TRIGGER_ON_REGISTERED" : true,
    "IS_BACKUP_TRIGGER_ON_RELOAD" : true,
    "IS_BACKUP_TRIGGER_ON_TIMER" : false,
    "IS_PURGE_ON" : true,
    "TIMER_PERIOD_SEC" : 600
}

INFO  ru.sbt.ss.artemis.plugin.backup.BrokerBackupPlugin  - Configuration: BROKER_BACKUP_PLUGIN_CONFIG:{
    "BACKUP_DIR_PATH" : "/u01/backup-local",
    "BACKUP_STORAGE_LIMIT" : 10,
    "EXCLUSION_RULES" : "*.diz, *.zip",
    "FILE_PERMISSIONS" : "400",
    "IS_BACKUP_TRIGGER_ON_CRITICAL_FAILURE" : true,
    "IS_BACKUP_TRIGGER_ON_REGISTERED" : true,
    "IS_BACKUP_TRIGGER_ON_RELOAD" : true,
    "IS_BACKUP_TRIGGER_ON_TIMER" : false,
    "IS_PURGE_ON" : true,
    "TIMER_PERIOD_SEC" : 600
}
 processed successfully: BrokerBackupConfiguration({"backupParams":{"brokerDirPath":"","inclusionRules":["*"],"exclusionRules":["*.diz","*.zip"],"backupDirPath":"/u01/backup-local","backupFileNamePattern":"broker.backup.%d{yyyy-MM-dd.HH-mm-ss}.zip","descriptionFileExt":"diz","timerPeriodSec":600,"backupStorageLimit":10,"threadPriority":3,"isPurgeOn":true},"triggerFlags":{"isOnCriticalFailure":true,"isOnRegistered":true,"isOnTimer":false,"isOnReload":true},"permissions":{"filePermissions":"400","dirPermissions":"775"},"objectMapper":{}})

• если ошибки при обработке отсутствуют, то плагин получает новую загруженную из файла конфигурацию через callback-метод onProcessConfig.

Пример фрагмента лога:

INFO  r.s.s.a.p.c.config.reload.PluginConfigurationReloadCallback  - Reloading BROKER_BACKUP_PLUGIN
INFO  ru.sbt.ss.artemis.plugin.backup.BrokerBackupPlugin  - Configuration: BROKER_BACKUP_PLUGIN_CONFIG:{
    "BACKUP_DIR_PATH" : "/u01/backup-local",
    "BACKUP_STORAGE_LIMIT" : 10,
    "EXCLUSION_RULES" : "*.diz, *.zip",
    "FILE_PERMISSIONS" : "400",
    "IS_BACKUP_TRIGGER_ON_CRITICAL_FAILURE" : false,
    "IS_BACKUP_TRIGGER_ON_REGISTERED" : true,
    "IS_BACKUP_TRIGGER_ON_RELOAD" : true,
    "IS_BACKUP_TRIGGER_ON_TIMER" : true,
    "IS_PURGE_ON" : true,
    "TIMER_PERIOD_SEC" : 600
}
 processed successfully: BrokerBackupConfiguration({"backupParams":{"brokerDirPath":"","inclusionRules":["*"],"exclusionRules":["*.diz","*.zip"],"backupDirPath":"/u01/backup-local","backupFileNamePattern":"broker.backup.%d{yyyy-MM-dd.HH-mm-ss}.zip","descriptionFileExt":"diz","timerPeriodSec":600,"backupStorageLimit":10,"threadPriority":3,"isPurgeOn":true},"triggerFlags":{"isOnCriticalFailure":false,"isOnRegistered":true,"isOnTimer":true,"isOnReload":true},"permissions":{"filePermissions":"400","dirPermissions":"775"},"objectMapper":{}})