Page History

{toc}

Система событий --- механизм {ais_name}, посредством которого управляющие воздействия ядра системы передаются на сетевые службы и оборудование. С помощью событий выполняется множество задач, в том числе следующие:
* приостановление и возобновление доступа абонентов к услугам;
* установка параметров оказания услуг абонентам на оборудовании;
* рассылка абонентам уведомлений и напоминаний о платежах.
* управление портами оборудования.

h2. Общая схема

Управление объектами (ОУ) и субъектами (СУ) учета построено на основе _событий_ (events), возникающих при переходе ОУ/СУ из одного состояния в другое. Здесь _состояние_ понимается в широком смысле: изменение атрибутов (в том числе дополнительных параметров, задаваемых пользователем), адресов, связей и привязок ОУ или СУ.

{graphviz}
// Управление ОУ (общая схема)
digraph G {
  size="5,5"
  graph [style=filled]
  node [style=filled, shape=box, color=black, fillcolor=white]

  "ОУ" [shape=ellipse]
  "ОУ"->{"Состояние 1"; "Состояние 2"} [dir=none]

  subgraph cluster_0 {
    color=white
    "Состояние 1"->"Событие"->"Состояние 2" [constraint=false]
    "Событие" [shape=parallelogram, fillcolor=red, width=2, height=0.25, fixedsize=true]
  }

  "Событие"->"Действия"
  "Действия"->"Агент" [label="Команды"] 
  "Агент" [shape=ellipse]
}
{graphviz}

Событие вызывает набор связанных с ним _действий_ (actions), которое преобразует эти действия в набор _команд_. В свою очередь, команды с помощью протокола удалённого управления передаются на выполнение _агенту_ {{hamd}} --- специальному внешнему приложению, непосредственно взаимодействующему с сетевыми службами или оборудованием.

h2. Настройки событий

Соответствие друг другу событий, действий и команд задаётся в {ais_name} в настройках событий (_Справочники -> События_). На рисунке показаны основные взаимосвязи между настройками события.
{graphviz}
digraph G {
  size="5,5"
  graph [style=filled]
  node [style=filled, shape=box, color=black, fillcolor=white]

  "Управление СУ/ОУ"->{"События"; "Действия"; "Очередь команд";}
  
  "События"->"Возможные события" [dir=none]
  "Возможные события" [shape=record, style=rounded, label="{Привязка | Адрес | Состояние | Состояние\ родителя | Поступление\ платежа | Рекомендуемый\ платеж | Выставление\ счета | Подключение\ услуги | Отключение услуги}"];

  "Действия"->"Возможные действия" [dir=none]
  "Возможные действия" [shape="record", style=rounded, label="{SNMP-команда | Команда\ RSH/SSH/Telnet | Shell-скрипт}"];
} 
{graphviz}

h3. События

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

События добавляются в _очередь_, которая затем обрабатывается заданиями по агентам. Такой подход позволяет работать с произвольными событиями, которые могут возникать в любом модуле системы, а вызовы процедуры добавления нового события в очередь являются асинхронными, то есть не блокируют выполнение пакета. Кроме того, можно применять события не только для управления устройствами, но и в любых других целях, например, для рассылки Email-сообщений, SMS-уведомлений, факсов и т. д.

В настройках событий указываются:
* Тип события.
* Тип (позиция номенклатуры) управляемого ОУ.
* Тип привязки управляемого ОУ к управляющей службе.
* Набор прямых действий.
* Набор обратных действий.
* Менеджер (агент) который будет выполнять связанные с данным событием действия.
* Настройки, зависящие от конкретного типа события.

h3. Действия и команды

Действие для {ais_name} представляет собой набор шаблонов команд в текстовом виде. Для использования в шаблонах предусмотрены специальные _подстановки_, которые при обработке команды агентом заменяются на конкретные значения атрибутов, идентификаторов и других параметров ОУ и СУ (например, подстановка {{$TERM_PHYS_ADDR}} может быть заменена на значение {{00-1A-B1-DF-24-A4}}). При этом в {ais_name} существует как жёстко запрограммированный набор подстановок, так и набор, задаваемый пользователем с помощью _параметризованных подстановок_. Например, дополнительные параметры ОУ могут представляться подстановкой ({{$TERM_OBJ_ADD_PARAM\[add_param_id\]}}, где {{add_param_id}} --- идентификатор дополнительного параметра).

Действия при настройке события добавляются двумя группами --- _прямой_ и _обратной_. Для каждого действия может быть задано действие, ему противоположное. Это позволяет системе управления при необходимости с помощью обратного действия корректно отменять изменения, сделанные на оборудовании прямым действием.

Команда имеет свой _тип взаимодействия_ (SNMP, RSH, SSH, локальный и т.д.), определяющий протокол, по которому эта команда будет передаваться на управляемое устройство.

{info}Следует отметить, что деление команд на типы взаимодействия с точки зрения ядра {ais_name} достаточно условно. Тип взаимодействия имеет значение лишь для интерпретации команды агентом, поэтому на стороне ядра только хранится соответствующая настройка, которая передается агенту при выполнении команды.{info}

h3. Менеджер активного оборудования hamd (агент управления)

Менеджер {{hamd}} (Hydra Active Management Daemon) --- это специализированное приложение, являющееся внешним по отношению к ядру АСР и предназначенное для приёма от него команд и их дальнейшего выполнения. Данный агент, как и другие агенты {ais_name} разработан на языке Python и поставляется в исходных кодах.

Менеджер принимает сообщения от ядра АСР по протоколу [XML-RPC | http://www.xmlrpc.com] аналогично агенту {{hcd}}. В сообщении передаётся как сам пакет команд, так и дополнительные параметры, необходимые для его выполнения (данные для аутентификации на оборудовании и т.д.). Связь ядра с менеджером инициируется _заданием_ по этому менеджеру.

Подстановки передаются отдельно от шаблона, что позволяет проводить их дополнительную обработку на стороне агента.

После того, как пакет команд выполнен, агент передаёт в систему отчёт о выполнении, в котором содержится результат выполнения каждой команды. Всего возможны четыре варианта: успех, предупреждение, ошибка и неизвестно. Пользователь сам задает то, какой результат вернуть в систему в каждом конкретном случае. Кроме того, вместе с результатом можно передавать и сообщение с расшифровкой проблемы. Подробная и качественная обработка ошибок позволяет легче обнаруживать и устранять проблемы, возникающие при работе системы, что в конечном счёте приводит к экономии рабочего времени и средств.

Для стандартных типов взаимодействия обработка ответов выполняется автоматически. Так, для типа взаимодействия _Локально_ (выполнение shell-скрипта на локальном сервере) ошибкой считается ненулевой код возврата, а в качестве расшифровки ошибки {{hamd}} передает в {ais_name} все, что скрипт выдал за время своей работы на стандартный вывод ошибок (stderr).

В приложении имеется [пример скрипта|^acl.sh] по управлению доступом абонентов программным файрволом с помощью утилиты {{iptables}}.

h3. Задания

Задания приводят механизм управления СУ/ОУ в действие. Основная сущность, с которой работают задания --- _очередь событий_.

Суть очереди событий ясна из названия. Событие вместе с набором связанных с ним действий добавляется  в хвост очереди, а выполнение действий менеджером идёт с её начала. При этом действия группируются в разрезе каждого устройства, на котором они выполняются. Это позволяет использовать _взаимозависимости команд_ --- в зависимости от результата выполнения очередной команды может прерываться выполнение следующих команд на этом же устройстве.

На каждый менеджер создается одно задание {ais_name} в момент перевода менеджера в активное состояние. После создания задание автоматически запускается с определенной периодичностью.

h3. Взаимодействие при управлении ОУ

Взаимодействие сущностей {ais_name} при срабатывании события по ОУ показано на примере управления доступом оконечного оборудования абонента к услугам оператора.

{graphviz}
digraph G {
  size="7,7"
  graph [style=filled]
  node [style=filled, shape=box, color=black, fillcolor=white]
  rank=source

  "Абонент" [shape=ellipse, fillcolor=lightpink]

  subgraph cluster_1 {
    color=lightblue
    rank=max
    "Оконечное оборудование" [shape=ellipse]
    "Оконечное оборудование"->{"Состав"; "Атрибуты оборудования"}
    "Состав" [shape=record, label="{Порт\ 1 | Порт\ 2 | ... | Порт\ N}"]
  }

  subgraph cluster_2 {
    color=darkseagreen2
    rank=min
    "Файрвол" [shape=ellipse]
    "Коммутатор" [shape=ellipse]
  }

  subgraph cluster_3 {
    color=mistyrose
    rank=min
    "Событие"->"Действия"->"Команды"
  }

  "Абонент"->"Оконечное оборудование"
  "Оконечное оборудование"->{"Коммутатор"; "Файрвол"}
  "Очередь событий" [shape=record, label="{Событие\ 1 | Событие\ 2 | ... | Событие\ N}"]
  "Событие"->"Очередь событий"
  "Очередь событий"->"Менеджер"[label="Задание"]
  "Менеджер"->{"Файрвол"; "Коммутатор"} [label="Команды"]
}
{graphviz}

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

h3. Примеры типовых событий

При работе оператора связи возникают типовые задачи по управлению оборудованием и службами. Все нижеперечисленные задачи решаются с помощью событий:
# Задание и изменение привязки MAC-порт (IP-MAC-порт).
# Задание и изменение скорости доступа на шейпере (iptables, ipfw, Cisco...).
# Включение и отключение доступа абонента к услугам связи (управлением файрволом, разрыв PPP-сессий и т.д.).
# Включение и отключение абонентского порта при блокировке абонента.
# Перепривязка оконечного оборудования абонента к другому устройству (переезд).
# Уведомление абонента о поступлении платежа на его лицевой счет.
# Уведомление абонента о рекомендуемом платеже за несколько дней до предполагаемого отключения.
# Уведомление абонента о выставленном ему счете на оплату услуг.

h3. Прямые и обратные действия

Обратные действия необходимы не всегда. Часто бывает достаточно задать только прямое действие. Например, если услуги абоненту оказываются по технологии PPPoE, то для события на отключение услуги необходимо задать действие, которое разрывает текущую PPP-сессию с помощью SNMP-команды или CoA-запроса по протоколу RADIUS. Ясно, что в этом случае задавать обратное действие бессмысленно, потому что однажды разорванная сессия уже не может быть восстановлена со стороны сервера.

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

Например, в случае, если на шейпере абонент идентифицируется по статическому IP-адресу его оборудования, и по какой-то причине у абонента изменился IP-адрес, необходимо задать обратное действие на событие _При подключении услуги Интернет-трафик вх._ В этом случае система, обнаружив, что значение подстановки {{$TERM_IP_ADDRESS}} изменилось, автоматически выполнит отменяющее событие (удалит правило шейпера для старого IP-адреса), а затем снова выполнит прямое действие с новым значением IP-адреса.

h3. Настройка событий в {ais_name}

Предположим, что необходимо настроить события на включение и отключение услуги _Доступ в Интернет_, которые будут разрешать или ограничивать доступ абонента в Интернет на программном файрволе {{iptables}}.

1. В настройках событий (_Справочники->События_) на вкладке _Типы объектов_ найдите позицию номенклатуры, по которой будет происходить событие. В данном случае такой позицией будет _Программный файрвол_.

!events1.png!

2. В настройках действий для программного файрвола (вкладка _Действия_) создайте новое действие _Разрешить доступ в интернет_ и настройте его как показано на рисунке ниже. Настройка _Тип взаимодействия_ задает протокол, по которому будут выполняться команды, входящие в данное действие. Список доступных подстановок можно получить, нажав на специальную кнопку в правой части поля ввода команды.

!events2.png!

Включенная галочка _Игнорировать ошибки_ в настройках действия означает, что если любая входящая в него команда завершится ошибкой, то дальнейшее выполнение других действий по этому же событию будет продолжено; в противном случае выполнение будет прервано. Аналогичная галочка _Игнорировать ошибки_ в настройках конкретной команды означает то же самое, но в пределах одного действия.

Подстановка {{$TERM_IP_ADDR}} в теле команды при ее выполнении менеджером будет заменена на IP-адрес оконечного оборудования абонента, по которому произошло событие.

Аналогичным образом создается действие _Запретить доступ в интернет_, оно отличается от разрешающего действия только содержимым команды.

3. Вернитесь на вкладку _События_ и создайте новое событие как показано на рисунке ниже.

!events3.png!

_Тип привязки объекта_ позволяет выбрать тип привязки, с помощью которой абонентское оборудование связано с файрволом. Это полезно в случае, когда на одном и том же абонентском оборудовании задано несколько типов событий, которые обрабатывается разными сетевыми службами. Например, доступ и пропускная способность канала могут регулироваться на одной и той же сетевой службе --- файрволе. Указание разных типов привязки позволяет обрабатывать эти события отдельно, несмотря на то, что они происходят на одной сетевой службе.

4. Привяжите действия _Разрешить доступ в интернет_ и _Запретить доступ в интернет_ к созданному в п. 3 событию. Результат показан на иллюстрации к п. 1. Подробнее о прямых и обратных действиях рассказано ниже.

Настройка событий завершена, осталось настроить только абонентское оборудование.

5. На форме редактирования тестового абонента откройте его оборудование и перейдите на вкладку _Привязки_. Привяжите это оборудование к сетевой службе, для которой задано событие (на рисунке ниже это служба IPTABLES1, имеющая тип _Программный файрвол_). В поле _Тип привязки_ нужно указать именно тот тип, который задан в настройках события, в противном случае событие не сработает.

!events4.png!

6. Выставьте абоненту инвойс по его оборудованию, если он не был ранее выставлен, и попробуйте изменить состояние услуги доступа на вкладке _Услуги_ формы редактирования абонента. В нижней части экрана должно появиться сообщение _По <оборудование абонента> произошло событие "При подключении услуги Доступ в интернет" для IPTABLES1_. Если такое сообщение не появляется, нужно проверить настройки события и настройки привязки.

h3. Запрос текущего состояния событий

Иногда возникает ситуация, когда оборудование, ограничивающее доступ абонента к услугам, перезагружается или выходит из строя, при этом появляется необходимость восстановить текущее состояние выполненных ранее событий.   Это делается с помощью командной строки утилитой {{hamdctl.py}}.

Для получения текущего состояния запускать так:
{code}/opt/hydra/hamd/binlib/hamdctl.py -u http://login:password@host:port request object-id:<object-id>{code}
Здесь {{object-id}} --- это идентификатор сетевой службы {ais_name}, по которой запрашивается текущее состояние событий. Если продолжить описанный выше пример, то такой службой будет программный файрвол IPTABLES1. Идентификатор этого файрвола можно получить на форме его редактирования.