====== BQRunAt - функционал bq.sh для запуска внешних команд при старте/останове брокера БД ======

Версия: bq.sh ver. 4.6.2 \\
TT#: 0139423, 0291009

===== Назначение =====

Обеспечение возможности запуска настраиваемых shell-команд в привязке к событиям старта и останова брокера БД.
Предусмотрено до пяти команд в каждом из перечисленных временных отрезков:
  * непосредственно перед моментом запуска брокера БД (proserve)
  * после успешного запуска брокера БД
  * непосредственно перед командой останова брокера базы (proshut)
  * после останова базы

===== Синтаксис ===== 

Все управление функционалом реализуется путем установки переменных окружения (обычно в запускающем скрипте).
Предусмотрены следующие переменные:

=== Включение функционала BQRunAt ===
<code bash>

  BQRunAtEnabled=yes   # включение функционала BQRunAt

</code>

=== Управление запуском ===

<code bash>

  BQRunAtStart{05|04|03|02|01}='команда или скрипт'	  # ПЕРЕД стартом
  BQRunAtStart{1|2|3|4|5}='команда или скрипт'	          # ПОСЛЕ старта

  BQRunAtStop{5|4|3|2|1}='команда или скрипт'	          # ПЕРЕД остановом
  BQRunAtStop{01|02|03|04|05}='команда или скрипт'	  # ПОСЛЕ останова

</code>

=== Управление полномочиями ===

<code bash>

  BQRunAtUUser={<unix-user>|.}        # unix-user для выполнения всех команд BQRunAt
       bis - значение по умолчанию
       .   - текущий пользователь (под которым выполняется bq.sh в данный момент)

  BQRunAtStart<NN>UUser={<unix-user>|.}
     # unix-user для выполнения конкретной команды BQRunAtStart<NN>

  BQRunAtStop<NN>UUser={<unix-user>|.}
     # unix-user для выполнения конкретной команды BQRunAtStop<NN>

</code>

=== Управление сообщениями ===

<code bash>

 BQRunAtStart<NN>Verbosе={0|1|2|3}       # уровень сообщений при старте
 BQRunAtStop<NN>Verbosе={0|1|2|3}        # уровень сообщений при останове
    0 – сообщение отсутствует
    1 – выводится UUser и имя соответствующей переменной (BQRunAt...)
    2 - UUser, имя переменной и первое слово заданной команды
    3 – UUser, имя переменной и вся команда целиком (с аргументами)
    по умолчанию: 2

</code>

===== Использование =====

==== Управление запуском ====

Для включения функционала необходимо установить переменную окружения ''BQRunAtEnabled=yes''. Любое другое значение ''BQRunAtEnabled'', в т.ч. пустое или неопределенное, отключает функционал полностью.

Команды, которые необходимо привязать к событию старта брокера БД, задаются переменными вида ''BQRunAtStart''//NN//, где //NN// – числовое значение, определяющее порядок выполнения  заданной команды. Аналогично, переменные ''BQRunAtStop''//NN// задают команды, привязанные к событию останова брокера БД.
Если //NN// начинается на ''0'' (цифру ноль), то соответствующая команда выполняется при остановленном брокере БД.
Если же //NN// состоит из одной цифры от ''1'' до ''5'', то данная команда будет выполняться при запущенном брокере БД. Значение //NN// определяет приоритет команды: чем оно по модулю меньше, тем ближе к событию старта/останова будет выполняться команда. То есть, команды со значениями ''01'' и ''1'' будут ближе по времени к этим событиям, чем команды ''05'' и ''5''.

Таким образом, последовательность выполнения команд будет следующая:

=== При старте: ===

''BQRunAtStart05'' \\
''BQRunAtStart04'' \\
''BQRunAtStart03'' \\
''BQRunAtStart02'' \\
''BQRunAtStart01'' \\
//<старт брокера БД>// \\
//<старт всех включенных batch-процессов>// \\
//<старт всех заданных логин-брокеров (as,ws,ns)>// \\
//<старт служебных процессов (APW,BIW,AIW,WDOG)>// \\
''BQRunAtStart1'' \\
''BQRunAtStart2'' \\
''BQRunAtStart3'' \\
''BQRunAtStart4'' \\
''BQRunAtStart5'' \\

__Важно__: блок ''BQRunAtStart//[1-5]//'' выполняется только в случае успешного старта брокера БД.

=== При останове: ===

''BQRunAtStop5'' \\
''BQRunAtStop4'' \\
''BQRunAtStop3'' \\
''BQRunAtStop2'' \\
''BQRunAtStop1'' \\
//<останов брокера БД>// \\
''BQRunAtStop01'' \\
''BQRunAtStop02'' \\
''BQRunAtStop03'' \\
''BQRunAtStop04'' \\
''BQRunAtStop05'' \\

__Важно__: Все команды ''BQRunAtStop''//NN// выполняются вне зависимости от успешности выполнения команды останова брокера БД. 

Никаких пауз или ожиданий при выполнении команд BQRunAt не производится.
Команды выполняются в среде, установленной скриптом bq.sh, то есть все основные переменные определены и доступны. Также следует учитывать, что в переменную ''PATH'' к этому моменту будут добавлены каталоги ''$DLC/bin'' и ''$BQ/bin'', что позволяет во многих случаях не указывать полный путь при настройке команд BQRunAt.

При использовании подстановок shell-переменных в настойке команд BQRunAt следует учитывать, что не экранированные переменные подставляются в момент определения BQRunAt, а экранированные – в момент выполнения. Например, запись:
<code bash>

  BQRunAtStart3=”$PROEXE $BQDB -pf $BQPF –p my-procedure.p”

</code>

не приведет к желаемому результату, т.к. переменная ''PROEXE'' определяется в самом bq.sh и на момент задания ''BQRunAtStart3'' еще не доступна. Подстановка же переменных ''BQDB'' и ''BQPF'' будет успешной, если определение ''BQRunAtStart3'' идет в запускающем скрипте __после__ определения этих переменных.
Для описанного применения следует использовать такую запись:
<code bash>

  BQRunAtStart3=”\$PROEXE \$BQDB -pf \$BQPF –p my-procedure.p”
</code>

Или такую:
<code bash>

  BQRunAtStart3=’$PROEXE $BQDB -pf $BQPF –p my-procedure.p’

</code>

Во втором и третьем случае все переменные указанной команды подставляются только в момент запуска ''BQRunAtStart3''.

==== Управление полномочиями ====

Функционалом предусмотрена возможность выполнения команд BQRunAt 
под полномочиями заданного пользователя unix с помощью системной 
команды ''su'' или аналога (определяется в bq.sh). По умолчанию все команды 
BQRunAt будут запускаться из-под unix-пользователя **bis**.

В случае необходимости изменить пользователя можно установкой переменной:
<code bash>

  BQRunAtUUser={<unix-user>|.}        # unix-user для выполнения всех команд BQRunAt
  
</code>
Специальное значение ''BQRunAtUUser=.'' (точка) отключает использование ''su''. В этом случае
все команды BQRunAt будут запускаться с полномочиями текущего пользователя 
(под которым выполняется bq.sh в данный момент). Будьте осторожны при использовании данного режима: 
возможны конфликты с правами доступа и потенциальные уязвимости.

Установкой перечисленных ниже переменных можно задать unix-пользователя для каждой
конкретной команды ''BQRunAtStart''//NN// или ''BQRunAtStop''//NN//:
<code bash>

  BQRunAtStart<NN>UUser={<unix-user>|.}
  BQRunAtStop<NN>UUser={<unix-user>|.}

</code>
Под заданным пользователем будет выполнятся только указанная команда. Для остальных 
по прежнему будет использоваться значение по умолчанию из переменной ''BQRunAtUUser''.
Здесь также специальное значение "''.''" (точка) приводит к выполнению команд
 под текущим пользователем.

==== Управление сообщениями ====

Перед запуском каждой из заданных команд BQRunAt скрипт bq.sh выводит 
в stdout (на терминал) информационное сообщение.
Установкой описанных ниже переменных можно управлять степенью подробности
этих сообщений. Уровень подробности задается отдельно для каждой из команд BQRunAt.
<code bash>

 BQRunAtStart<NN>Verbosе={0|1|2|3}       # уровень сообщений при старте
 BQRunAtStop<NN>Verbosе={0|1|2|3}        # уровень сообщений при останове

</code>
Предусмотрены следующие значения:

  *  ''0'' – сообщение отсутствует
  *  ''1'' – выводится UUser и имя соответствующей переменной (''BQRunAt''...)
  *  ''2'' – UUser, имя переменной и первое слово заданной команды
  *  ''3'' – UUser, имя переменной и вся команда целиком (с аргументами)

По умолчанию принимается значение: ''2''

===== История версий =====

v.4.6.2  //в процессе реализации// \\
[+] Добавлено управление полномочиями (переменные BQRunAtUUser, BQRunAtStart//NN//UUser, BQRunAtStop//NN//UUser)


v.4.6.1  30.08.2011 cksum: 1480063694 \\
[*] Функция BQRunAtStop: изменен порядок вызова, теперь: 5,4,3,2,1

v.4.6.0  15.12.2010 cksum: 1976088185  \\
[+] Добавлен функционал: BQRunAtStart, BQRunAtStop




{{tag>scripts doc}}