IPA_CONV(8)                                                        IPA_CONV(8)



НАИМЕНОВАНИЕ
       ipa_conv -- IPA модуль учёта/базы данных для конвертирования статистики

ОПИСАНИЕ
       ipa_conv это IPA модуль учёта/базы данных, обладающий следующими  свой-
       ствами:

       -      Модуль разработан для конвертирования статистики;

       -      Статистика  конвертируется  в  соответствии  с пользовательскими
              планами, одновременно можно использовать несколько планов;

       -      Каждый план может содержать правила конвертирования для месяцев,
              дней, дней недели и временных интервалов;

       -      Статистика одного статического правила может быть конвертирована
              и отправлена другому статическому правилу.

       Имя системы учёта и имя базы данных -- conv.

ОБЗОР ИДЕИ
       ipa_conv состоит из одного модуля учёта и одного модуля базы данных, но
       эти  два  модуля реализованы в одном объектном файле.  Этот файл должен
       быть загружен два раза в конфигурационном файле ipa.conf(5), один раз с
       использованием параметра ac_mod и второй раз с использованием параметра
       db_mod.  В действительности только одна копия  объектного  файла  будет
       загружена  в  адресное  пространство  ipa(8)  и модуль проверяет это во
       время инициализации.

       Произвольное статическое правило может  использовать  этот  модуль  как
       базу данных (в этом случае это правило называется ``правило-источник'')
       и/или как систему учёта (в этом случае это  правило  называется  ``пра-
       вило-получатель'').  Каждое правило-источник является источником стати-
       стики для некоторого одного правила-получателя.  Каждое  правило-источ-
       ник  имеет план конвертации для конвертирования статистики для соответ-
       ствующего правила-получателя.  Одно правило-получатель  может  получать
       конвертированную статистику от нескольких правил-источников.

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

       План  конвертирования  состоит  из временных интервалов с информацией о
       том, как конвертировать статистику.  Эта информация содержит два числа,
       первое  число  X это количество исходной статистики, второе число Y это
       количество соответствующей конвертированной статистики: полные X единиц
       исходной  статистики  конвертируются  в  Y единиц (X > 0 и Y >= 0).  По
       умолчанию модуль масштабирует значения X и Y  до  наименьших  возможных
       значений, но это свойство можно отменить.

       Есть  несколько форматов временных интервалов (даны ниже).  Модуль базы
       данных всегда выбирает наиболее подходящий временной интервал.   Наибо-
       лее  подходящий  временной интервал выбирается когда модуль базы данных
       получает обновлённую статистику для правила-источника.   Если  значение
       статистики  было s1 во время t1 и значение статистики равно s2 во время
       t2 для некоторого правила-источника и не было  обновлений  базы  данных
       для  этого  правила между t1 и t2, то временной интервал выбирается для
       времени t2 и разность (s2 - s1) конвертируется и отправляется  правилу-
       получателю  (эта  разность  может быть отрицательной).  Слишком длинные
       временные интервалы между обновлениями базы данных могут быть  причиной
       неточного конвертирования статистики.

       Обычно правило-источник должно быть записано выше соответствующего пра-
       вила-получателя в файле конфигурации и лучше сообщить ipa(8)  не  изме-
       нять  их  внутреннего  порядка (используйте параметр keep_rules_order).
       Если правило-источник обрабатывается первым и соответствующее  правило-
       получатель обрабатывается вторым в тоже самое время, то правило-получа-
       тель получит конвертированную статистику немедленно.  Иначе оно получит
       конвертированную статистики во время следующего обновления базы данных.

       Этот модуль работает с увеличивающейся статистикой  и  с  уменьшающейся
       статистикой.   Так как модуль базы данных получает только неотрицатель-
       ную статистику, то этот модуль не может корректно  обработать  ситуацию
       когда  статистика  для  некоторого  правила становится отрицательной (в
       этом случае база данных модуля получает нулевую статистику от  ipa(8)).
       Если  эта  статистика станет снова положительной, то модуль будет рабо-
       тать как ожидается.

ФОРМАТ КОНФИГУРАЦИОННОГО ФАЙЛА
       Одна часть конфигурации  модуля  интегрирована  в  ipa.conf(5),  другие
       части конфигурации хранятся в файлах с планами конвертирования.  Конфи-
       гурационный префикс модуля -- ``conv''.

       Параметр conv:scale определяет должен ли модуль масштабировать значения
       во всех загружаемых планах конвертирования:

           conv:scale = <boolean>;

       Этот  параметр  должен быть расположен отдельно и должен использоваться
       перед параметрами conv:load.  По  умолчанию  значение  этого  параметра
       равно ``yes'' и модуль масштабирует все значения во всех планах.

       Параметр  conv:load  загружает  файл  с планом конвертирования и задаёт
       локальное имя для загруженного плана:

           conv:load = <plan-name> "/path/file";

       Этот параметр должен быть расположен отдельно и  должен  использоваться
       перед  параметрами  conv:plan.  Заданный файл загружается и обрабатыва-
       ется когда модуль обрабатывает этот параметр.

       Параметр conv:dest определяет  правило-получатель,  параметр  conv:plan
       определяет план конвертирования для этого правила:

           conv:dest = <rule-name>;
           conv:plan = <plan-name>;

       Эти  два параметра могут быть расположены в секции rule.  Модуль прове-
       ряет наличие указанного правила-получателя в конце обработки конфигура-
       ционного  файла.  Если правило-получатель неактивно, то оно не получает
       конвертированную статистику.

       Параметр conv:quiet позволяет подавлять некоторые сообщения модуля:

           conv:quiet = <value>;

       Этот параметр должен быть расположен отдельно.  По  умолчанию  значение
       этого параметра равно 3.  Если в его значении не установлен бит 0x1, то
       модуль посылает предупреждающее сообщение когда ipa(8) деинициализирует
       некоторое правило-получатель и это правило всё ещё имеет некоторую кон-
       вертированную статистику.  Если в его значении не установлен  бит  0x2,
       то модуль посылает предупреждающее сообщение когда ipa(8) деинициализи-
       рует некоторое правило-источник и это правило всё ещё  имеет  некоторую
       не сконвертированную статистику.

       Параметр conv:debug помогает отладить модуль:

           conv:debug = <level>;

       Этот  параметр  должен  быть расположен отдельно.  Разрешены только два
       значения для уровня отладки: 0 и 1.  По умолчанию значение этого  пара-
       метра равно 0, это означает, что отладка отключена.

ФОРМАТ ПЛАНА КОНВЕРТИРОВАНИЯ
       Файл  с  планом конвертирования состоит из строк.  Каждая строка должна
       состоять не более чем из  255  символов.   Каждая  строка  может  иметь
       shell-подобный  комментарий,  который начинается с символа '#'.  Пустые
       строки или строки только с комментариями игнорируются.

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

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

       o      year.mon.day/h1:m1-h2:m2 определяет временной интервал для года,
              месяца и дня.

       o      year.mon.day определяет год, месяц и день.

       o      mon.day/h1:m1-h2:m2 определяет временной интервал для  месяца  и
              дня.

       o      mon.day определяет месяц и день.

       o      mon определяет месяц.

       o      X/h1:m1-h2:m2 определяет временной интервал для дня недели.  Для
              X допустимы следующие значения: `S' воскресенье,  `M'  понедель-
              ник,  `T' вторник, `W' среда, `H' четверг, `F' пятница, `A' суб-
              бота.

       o      X определяет день недели.

       o      h1:m1-h2:m2 определяет временной интервал.

       o      `*' определяет установки по умолчанию и должна присутствовать  в
              любом плане.

       Месяц  может быть задан первыми тремя буквами названия месяца в англий-
       ском языке.

       День начинается в 00:00 и заканчивается в 24:00.

       Пример:

       Есть правило r1,  которое  получает  статистику  от  некоторой  системы
       учёта.  Необходимо получать только 50% этой статистики ночью с 00:00 до
       07:00, в остальное время статистика не должна изменяться.

       Создадим файл с планом конвертации /etc/ipa/plan/night:

           # Интервал      Исходная        Конвертированная
           *               1               1                 # 100%
           00:00-07:00     2               1                 #  50% (ночь)

       Создадим ipa.conf, правило r2 будет получать ковертированную статистику
       правила r1:

           /* ... */

           ac_mod "ipa_conv.so";
           db_mod "ipa_conv.so";

           conv:load = night "/etc/ipa/plan/night";

           rule r1 {
               /* ... */
               db_list = conv;
               conv:dest = r2;
               conv:plan = night;
           }

           rule r2 {
               /* ... */
               ac_list = conv;
           }

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

АВТОР
       Andrey Simonenko <simon@comsys.ntu-kpi.kiev.ua>

НЕДОРАБОТКИ
       Если  вы  обнаружите какие-либо ошибки, то, пожалуйста, сообщите мне по
       email.



                                22 июля 2009 г.                    IPA_CONV(8)