From 11db4a3e1d499a2e2da4cf312db1655eb0f055fc Mon Sep 17 00:00:00 2001
From: Maxim Mamontov <faust.madf@gmail.com>
Date: Sun, 4 Sep 2016 14:04:36 +0300
Subject: [PATCH] Added description for ScriptParams, DisableSessionLog and
 FilterParamsLog.

---
 doc/help/ch4.xml | 51 +++++++++++++++++++++++++-----------------------
 1 file changed, 27 insertions(+), 24 deletions(-)

diff --git a/doc/help/ch4.xml b/doc/help/ch4.xml
index 99a0ce70..00130ea0 100644
--- a/doc/help/ch4.xml
+++ b/doc/help/ch4.xml
@@ -24,23 +24,26 @@
     <itemizedlist mark="opencircle">
       <listitem><para>Rules – обязательный параметр, указывающий серверу, где находится файл с правилами для подсчета трафика клиентов. Стандартное значение: /etc/stargazer/rules.</para></listitem>
       <listitem><para>LogFile – обязательный параметр, указывающий серверу расположение файла, в который будут заноситься все сообщения системы. Стандартное значение: /var/log/stargazer.log.</para></listitem>
-      <listitem><para>PidFile — не обязательный параметр, указывающий серверу где находится файл хранящий PID (идентификатор процесса) дэмона. По умолчанию это /var/run/stargazer.pid. Используется скриптами запуска/останова.</para></listitem>
+      <listitem><para>PidFile — необязательный параметр, указывающий серверу где находится файл хранящий PID (идентификатор процесса) дэмона. По умолчанию это /var/run/stargazer.pid. Используется скриптами запуска/останова.</para></listitem>
       <listitem><para>ModulesPath – обязательный параметр, указывающий серверу путь, где находятся подключаемые модули (плагины). Стандартное значение: /usr/lib/stg.</para></listitem>
       <listitem><para>DetailStatWritePeriod – обязательный параметр, указывающий серверу через какое время должна записываться детальная статистика клиента. Стандартное значение: 1/6. Данный параметр может принимать следующие значения: 3 - раз в три часа, 2 - раз в два часа, 1 - раз в чаc, 1/2 - раз в пол часа, 1/4 - раз в 15 минут, 1/6 - раз в 10 минут.</para></listitem>
-      <listitem><para>StatWritePeriod – не обязательный параметр, указывающий серверу периодичность записи в БД информации о статистике пользователя в минутах. При большом количестве пользователей эту величину стоит увеличить, так как запись в БД может занимать длительное время. По умолчанию имеет значение 10.</para></listitem>
+      <listitem><para>StatWritePeriod – необязательный параметр, указывающий серверу периодичность записи в БД информации о статистике пользователя в минутах. При большом количестве пользователей эту величину стоит увеличить, так как запись в БД может занимать длительное время. По умолчанию имеет значение 10.</para></listitem>
       <listitem><para>DayFee – обязательный параметр, указывающий серверу, в какой день месяца снимать с клиентских счетов сумму абонплаты, в соответствии с тарифными планами клиентов. Может принимать значения от 0 до 31, стандартное значение: 1. Следует помнить, что в некоторых месяцах не более 28 дней. Значение 0 соответствует последнему дню месяца по календарю.</para></listitem>
       <listitem><para>DayResetTraff – обязательный параметр, указывающий серверу в какой день месяца сбрасывать помесячную статистику клиентов и осуществлять переход на новый тариф, если он был изменен у клиента. Может принимать значения от 0 до 31, стандартное значение: 1. Следует помнить, что в некоторых месяцах не более 28 дней. Значение 0 соответствует последнему дню месяца по календарю.</para></listitem>
       <listitem><para>SpreadFee – обязательный параметр, указывающий серверу производить ли «размазанное» снятие абонплаты. Может принимать значения yes и no. При указании значения yes сумма абонплаты указанная в тарифе пользователя будет сниматься не раз в месяц, а каждый день равными долями. Стандартное значение: no.</para></listitem>
       <listitem><para>FreeMbAllowInet – обязательный параметр, указывающий серверу выполнять ли для пользователя скрипт OnConnect, если у него на балансе отсутствуют средства, но остался предоплаченный трафик. Может принимать значения yes и no. Стандартное значение: no.</para></listitem>
       <listitem><para>WriteFreeMbTraffCost – обязательный параметр, определяющий как  будет писаться стоимость трафика в детальной статистике. Может принимать значения yes и no, стандартное значение: no. При указании значения yes в детальной статистике пользователя стоимость трафика будет писаться в любом случае, даже если он попадает в FreeMb. При указании значения no доя исчерпания FreeMb в детальной статистике будет указана нулевая стоимость трафика.</para></listitem>
       <listitem><para>DayFeeIsLastDay – обязательный параметр, указывающий серверу когда снимать абонплату. Может принимать значения yes и no, стандартное значение: yes. Это влияет на то, как будет снята абонплата (АП) при переходе на новый тариф. Если у пользователя был тариф A с АП=100 и он хочет перейти на тариф B с АП=200, то при переходе на новый тариф со счета пользователя снимется 100, если указано значение yes (абонплата снята до смены тарифа), и 200, если указано значение no (абонплата снята перед сменой тарифа).</para></listitem>
-      <listitem><para>ExecutersNum – не обязательный параметр который определяющий сколько скриптом может выполняться одновременно (регулирует количество процессов stg-exec). По умолчанию имеет значение 1. Если выполнение ваших скриптов занимает много времени имеет смысл увеличить это значение. Каждый исполнитель скриптов блокируется на время, пока отработает скрипт. Если исполнителей несколько — они принимают скрипты на выполнение по принципу «кто успел».</para></listitem>
-      <listitem><para>StgMsgKey – не обязательный параметр отвечающий за идентификатор очереди сообщений для исполнителя скриптов. По умолчанию данный параметр имеет значение 5555. Рекомендуется не изменять значение параметра без нужды. Его изменение целесообразно лишь в том случае, если в системе требуется запустить более одной копии сервера биллинга.</para></listitem>
-      <listitem><para>ShowFeeInCash – не обязательный параметр, определяющий как будет показано состояние счета абонента в авторизаторе и сколько денег ему будет разрешено использовать в текущем месяце. Может принимать значения yes и no, по умолчанию имеет значение yes. При указании no в авторизаторе будет показано состояние счета  без учета следующего снятия абонплаты. Так же эти деньги нельзя будет использовать для оплаты трафика в текущем месяце. Пример: у абонента на счету 200 денег при абонплате в 50 денег — в этом случае ему будет показано 150 денег в авторизаторе и он сможет в текущем месяце израсходовать только 150 денег, но снятие абонплаты не уведет его в «минус».</para></listitem>
-      <listitem><para>FullFee – не обязательный параметр, указывающий серверу снимать полную абонплату, даже если учетная запись абонента была заморожена (или не существовала) часть учетного периода. Принимает значения yes и no, по умолчанию установлен в no.</para></listitem>
-      <listitem><para>MessagesTimeout — не обязательный параметр, устанавливающий время жизни не отправленных сообщений абонентам. Время указывается в сутках. При превышении этого времени сообщение будет удалено, в т. ч. из БД. Если указано значение 0 то не отправленные сообщения никогда не будут удаляться из базы (в частности, это приведет к постепенному росту размера базы, увеличению нагрузки на сервер при авторизации абонентов и к тому что долго отсутствовавший абонент при авторизации получит все пропущенные сообщения). По умолчанию имеет значение 0.</para></listitem>
-      <listitem><para>FeeChargeType — не обязательный параметр, регулирующий процесс снятия абонплаты. Может принимать значения 0, 1 и 2, по умолчанию имеет значение 0. При значении 0 абонплата снимается как обычно, при значении 1 абонплата снимается только если баланс пользователя положительный или равен нулю, при значении 2 абонплата снимается только если баланс пользователя больше или равен абонплате. Значение 2 следует использовать с осторожностью, т. к. при этом на безлимитных тарифах абоненты получат услугу бесплатно.</para></listitem>
-      <listitem><para>ReconnectOnTariffChange — не обязательный параметр, указывающий серверу выполнить переподключение пользователя при смене тарифа. Может принимать значения yes и no, по умолчанию имеет значение no. При указании значения yes подключенные пользователи будут отключены непосредственно перед сменой тарифа и подключены сразу после нее. Может быть полезно для управления шейпером.</para></listitem>
+      <listitem><para>ExecutersNum – необязательный параметр который определяющий сколько скриптом может выполняться одновременно (регулирует количество процессов stg-exec). По умолчанию имеет значение 1. Если выполнение ваших скриптов занимает много времени имеет смысл увеличить это значение. Каждый исполнитель скриптов блокируется на время, пока отработает скрипт. Если исполнителей несколько — они принимают скрипты на выполнение по принципу «кто успел».</para></listitem>
+      <listitem><para>StgMsgKey – необязательный параметр отвечающий за идентификатор очереди сообщений для исполнителя скриптов. По умолчанию данный параметр имеет значение 5555. Рекомендуется не изменять значение параметра без нужды. Его изменение целесообразно лишь в том случае, если в системе требуется запустить более одной копии сервера биллинга.</para></listitem>
+      <listitem><para>ShowFeeInCash – необязательный параметр, определяющий как будет показано состояние счета абонента в авторизаторе и сколько денег ему будет разрешено использовать в текущем месяце. Может принимать значения yes и no, по умолчанию имеет значение yes. При указании no в авторизаторе будет показано состояние счета  без учета следующего снятия абонплаты. Так же эти деньги нельзя будет использовать для оплаты трафика в текущем месяце. Пример: у абонента на счету 200 денег при абонплате в 50 денег — в этом случае ему будет показано 150 денег в авторизаторе и он сможет в текущем месяце израсходовать только 150 денег, но снятие абонплаты не уведет его в «минус».</para></listitem>
+      <listitem><para>FullFee – необязательный параметр, указывающий серверу снимать полную абонплату, даже если учетная запись абонента была заморожена (или не существовала) часть учетного периода. Принимает значения yes и no, по умолчанию установлен в no.</para></listitem>
+      <listitem><para>MessagesTimeout — необязательный параметр, устанавливающий время жизни не отправленных сообщений абонентам. Время указывается в сутках. При превышении этого времени сообщение будет удалено, в т. ч. из БД. Если указано значение 0 то не отправленные сообщения никогда не будут удаляться из базы (в частности, это приведет к постепенному росту размера базы, увеличению нагрузки на сервер при авторизации абонентов и к тому что долго отсутствовавший абонент при авторизации получит все пропущенные сообщения). По умолчанию имеет значение 0.</para></listitem>
+      <listitem><para>FeeChargeType — необязательный параметр, регулирующий процесс снятия абонплаты. Может принимать значения 0, 1 и 2, по умолчанию имеет значение 0. При значении 0 абонплата снимается как обычно, при значении 1 абонплата снимается только если баланс пользователя положительный или равен нулю, при значении 2 абонплата снимается только если баланс пользователя больше или равен абонплате. Значение 2 следует использовать с осторожностью, т. к. при этом на безлимитных тарифах абоненты получат услугу бесплатно.</para></listitem>
+      <listitem><para>ReconnectOnTariffChange — необязательный параметр, указывающий серверу выполнить переподключение пользователя при смене тарифа. Может принимать значения yes и no, по умолчанию имеет значение no. При указании значения yes подключенные пользователи будут отключены непосредственно перед сменой тарифа и подключены сразу после нее. Может быть полезно для управления шейпером.</para></listitem>
+      <listitem><para>ScriptParams — необязательный параметр, который определяет дополнительный набор данных передаваемых в скрипты OnConnect и OnDisconnect. По умолчанию этот параметр пуст. В нем можно указать названия полей записи пользователя, разделенных пробелами, значения которых будут переданы в скрипты после стандартного набора, включающего login, ip, cash, id и dirs. Допустимые имена полей: "cash", "upload", "download", "lastCashAdd", "passiveTime", "lastCashAddTime", "freeMb", "lastActivityTime", "password", "passive", "disabled", "disabledDetailStat", "alwaysOnline", "tariffName", "nextTariff", "address", "note", "group", "email", "phone", "realName", "credit", "creditExpire", "ips", "userdata0" ... "userdata9". Так, например, если указать ScriptParams = tariffName userdata0 то список параметров передаваемых в скрипты будет: login, ip, cash, id, dirs, tariffName, userdata0. Названия параметров регистронезависимые.</para></listitem>
+      <listitem><para>DisableSessionLog — необязательный параметр позволяющий отключать запить сессий пользователя в БД. Может принимать значения yes и no. По умолчанию установлен в no, то есть запись сессий включена.</para></listitem>
+      <listitem><para>FilterParamsLog — необязательный параметр который позволяет фильтровать запись в журнал изменений параметров. Может принимать значения "*" (разрешена запись жернала для всех параметров) или список названий полей записи пользователя, разделенный пробелами. Допустимые имена полей такие-же как и для ScriptParams. По умолчанию имеет значение "*", то есть разрешено журналирование всех параметров. Если указать FilterParamsLog = cash tariffName password то в журнал изменений будут попадать только изменения параметров cash, tariffName и password. Изменения других параметров, например note, group или address в журнал не попадут.</para></listitem>
       <listitem><para>Для именования направлений учета трафика в конфигурационном файле используется секция DirNames:</para>
       <programlisting linenumbering="unnumbered">
       &lt;DirNames&gt;
@@ -109,10 +112,10 @@
     <sect2>
     <title>Описание параметров модуля для работы с СУБД Firebird:</title>
     <itemizedlist mark="opencircle">
-      <listitem><para>Server – не обязательный параметр, описывающий адрес сервера, на котором расположена СУБД. Может быть доменным именем или IP-адресом. Значение по умолчанию: localhost.</para></listitem>
-      <listitem><para>Database – не обязательный параметр, описывающий путь к БД на сервере или ее псевдоним (alias). Значение по умолчанию: /var/stg/stargazer.fdb.</para></listitem>
-      <listitem><para>User – не обязательный параметр, описывающий имя пользователя БД. Значение по умолчанию: stg.</para></listitem>
-      <listitem><para>Password – не обязательный параметр, описывающий пароль пользователя БД. Значение по умолчанию: 123456.</para></listitem>
+      <listitem><para>Server – необязательный параметр, описывающий адрес сервера, на котором расположена СУБД. Может быть доменным именем или IP-адресом. Значение по умолчанию: localhost.</para></listitem>
+      <listitem><para>Database – необязательный параметр, описывающий путь к БД на сервере или ее псевдоним (alias). Значение по умолчанию: /var/stg/stargazer.fdb.</para></listitem>
+      <listitem><para>User – необязательный параметр, описывающий имя пользователя БД. Значение по умолчанию: stg.</para></listitem>
+      <listitem><para>Password – необязательный параметр, описывающий пароль пользователя БД. Значение по умолчанию: 123456.</para></listitem>
       <listitem><para>IsolationLevel — Не обязательный параметр, описывающий уровень изоляции транзакций. Может принимать значения:</para>
         <itemizedlist mark="square">
           <listitem><para>Concurrency (используется по умолчанию);</para></listitem>
@@ -132,11 +135,11 @@
     <sect2>
     <title>Описание параметров модуля для работы с СУБД PostgreSQL:</title>
     <itemizedlist mark="opencircle">
-      <listitem><para>Server – не обязательный параметр, описывающий адрес сервера, на котором расположена СУБД. Может быть доменным именем или IP-адресом. Значение по умолчанию: localhost.</para></listitem>
-      <listitem><para>Database – не обязательный параметр, описывающий имя БД. Значение по умолчанию: stargazer.</para></listitem>
-      <listitem><para>User – не обязательный параметр, описывающий имя пользователя БД. Значение по умолчанию: stg.</para></listitem>
-      <listitem><para>Password – не обязательный параметр, описывающий пароль пользователя БД. Значение по умолчанию: 123456.</para></listitem>
-      <listitem><para>Retries — не обязательный параметр, описывающий количество попыток переподключения к СУБД в случае потери связи. Попытки производятся с интервалом в 1 секунду. Значение по умолчанию: 3.</para></listitem>
+      <listitem><para>Server – необязательный параметр, описывающий адрес сервера, на котором расположена СУБД. Может быть доменным именем или IP-адресом. Значение по умолчанию: localhost.</para></listitem>
+      <listitem><para>Database – необязательный параметр, описывающий имя БД. Значение по умолчанию: stargazer.</para></listitem>
+      <listitem><para>User – необязательный параметр, описывающий имя пользователя БД. Значение по умолчанию: stg.</para></listitem>
+      <listitem><para>Password – необязательный параметр, описывающий пароль пользователя БД. Значение по умолчанию: 123456.</para></listitem>
+      <listitem><para>Retries — необязательный параметр, описывающий количество попыток переподключения к СУБД в случае потери связи. Попытки производятся с интервалом в 1 секунду. Значение по умолчанию: 3.</para></listitem>
     </itemizedlist>
     </sect2>
     <sect2>
@@ -169,8 +172,8 @@
     <itemizedlist mark="opencircle">
       <listitem><para>Port — обязательный параметр, определяющий порт, на который будут приходить запросы от FreeRADIUS. Может принимать значение от 1 до 65535, стандартное значение: 6666.</para></listitem>
       <listitem><para>Password — обязательный параметр, задающий пароль для шифрования данных, передаваемых на FreeRADIUS. Должен совпадать с паролем в настройке плагина FreeRADIUS (rlm_stg.so). Стандартное значение: 123456.</para></listitem>
-      <listitem><para>AuthServices — не обязательный параметр, задающий список сервисов которым будет позволена только авторизация с использованием БД Stargazer. При успешной авторизации абонент не переходит в состояние Online и для него не производится подсчет трафика. Названия сервисов в списке должны разделяться пробелами, по умолчанию этот параметр пуст.</para></listitem>
-      <listitem><para>AcctServices — не обязательный параметр, задающий список сервисов, по которым будет производится аккаунтинг. При успешной авторизации в этих сервисах абонент переходит в состояние Online и для него производится подсчет трафика. Необходимо заметить, что в этом случае трафик захватывается как обычно, без использования возможностей протокола RADIUS (через пакет аккаунтинга InterimUpdate), т.к. это не позволяет классифицировать полученный трафик по направлениям. Названия сервисов в списке должны разделяться пробелами, по умолчанию этот параметр пуст.</para></listitem>
+      <listitem><para>AuthServices — необязательный параметр, задающий список сервисов которым будет позволена только авторизация с использованием БД Stargazer. При успешной авторизации абонент не переходит в состояние Online и для него не производится подсчет трафика. Названия сервисов в списке должны разделяться пробелами, по умолчанию этот параметр пуст.</para></listitem>
+      <listitem><para>AcctServices — необязательный параметр, задающий список сервисов, по которым будет производится аккаунтинг. При успешной авторизации в этих сервисах абонент переходит в состояние Online и для него производится подсчет трафика. Необходимо заметить, что в этом случае трафик захватывается как обычно, без использования возможностей протокола RADIUS (через пакет аккаунтинга InterimUpdate), т.к. это не позволяет классифицировать полученный трафик по направлениям. Названия сервисов в списке должны разделяться пробелами, по умолчанию этот параметр пуст.</para></listitem>
     </itemizedlist>
     <para>Обмен данными между плагином и FreeRADIUS происходит по протоколу UDP.</para>
     </sect2>
@@ -178,7 +181,7 @@
     <title>Описание параметров модуля XML-RPC (conf_rpc) для поддержки протокола управления XML-RPC:</title>
     <itemizedlist mark="opencircle">
       <listitem><para>Port — обязательный параметр, определяющий порт на который будут приходить запросы XML-RPC. Может принимать значения от 1 до 65535, стандартное значение: 8080.</para></listitem>
-      <listitem><para>CookieTimeout — не обязательный параметр, задающий время существования авторизационного Cookie в случае отсутствия активности в секундах. Значение по умолчанию: 1800 (30 минут).</para></listitem>
+      <listitem><para>CookieTimeout — необязательный параметр, задающий время существования авторизационного Cookie в случае отсутствия активности в секундах. Значение по умолчанию: 1800 (30 минут).</para></listitem>
     </itemizedlist>
     </sect2>
     <sect2>
@@ -203,8 +206,8 @@
     <sect2>
     <title>Описание параметров модуля cap_nf для захвата трафика:</title>
     <itemizedlist mark="opencircle">
-      <listitem><para>TCPPort — не обязательный параметр, указывающий порт который будет использоваться для приема данных при работе с NetFlow-proxy. Стандартное значение: 9996. Если параметр не указан — прием по протоколу TCP производиться не будет.</para></listitem>
-      <listitem><para>UDPPort — не обязательный параметр, указывающий порт для приема NetFlow-дагарамм. Стандартное значение: 9996. Если параметр не указан — прием датаграмм по протоколу UDP производиться не будет.</para></listitem>
+      <listitem><para>TCPPort — необязательный параметр, указывающий порт который будет использоваться для приема данных при работе с NetFlow-proxy. Стандартное значение: 9996. Если параметр не указан — прием по протоколу TCP производиться не будет.</para></listitem>
+      <listitem><para>UDPPort — необязательный параметр, указывающий порт для приема NetFlow-дагарамм. Стандартное значение: 9996. Если параметр не указан — прием датаграмм по протоколу UDP производиться не будет.</para></listitem>
     </itemizedlist>
     <para>В явном виде захват трафика не происходит. Данные о нем поступают от NetFlow-сенсора посредством протокола NetFlow. Это позволяет физически разделить перехват трафика и его учет. NetFlow-сенсор перехватывает трафик, и собирает данные о сессиях (в контексте UDP это передача данных между двумя портами в одном направлении). Информация о сессии включает в себя IP-адреса источника и назначения потока пакетов, номера портов источника и назначения, суммарную длину пакетов и различные дополнительные данные. NetFlow-трафик существенно меньше трафика, который он описывает, так как передается мета-информация а не сами данные. С учетом этого факта и того что биллинговый сервер теперь может не заниматься маршрутизацией пакетов и NAT'ом это существенно снижает нагрузку на него. Этот плагин рекомендуется использоваться в крупных сетях с развитой топологией, включающей несколько NAS'ов. Возможно использование совместно с аппаратными маршрутизаторами Cisco (они единственные имеют лицензию на аппаратную реализацию NetFlow). В качестве NetFlow-сенсоров можно использовать такие утилиты как fprobe, softflowd или ipcad. Так же можно использовать модуль ядра ipt_netflow (Linux) или ng_netflow (FreeBSD).</para>
     </sect2>
@@ -212,7 +215,7 @@
     <itemizedlist mark="opencircle">
       <listitem><para>Server — обязательный параметр, указывающий IP-адрес сервера на котором находится snmpd. Стандартное значение: 127.0.0.1.</para></listitem>
       <listitem><para>Port — обязательный параметр, указывающий порт на сервере через который будет происходить взаимодействие с snmpd. Стандартное значение: 199.</para></listitem>
-      <listitem><para>Password — не обязательный параметр, задающий пароль для авторизации плагина в snmpd. По умолчанию пароль не используется.</para></listitem>
+      <listitem><para>Password — необязательный параметр, задающий пароль для авторизации плагина в snmpd. По умолчанию пароль не используется.</para></listitem>
     </itemizedlist>
     <title>Описание параметров модуля smux для мониторинга состояния Stargazer:</title>
     <para>Модуль позволяет производить мониторинг биллинга средствами протокола SNMP. Он не реализует полноценный SNMP-сервер а лишь взаимодействует с существующим дэмоном snmpd, регистрируясь в нем для обслуживания определенного дерева параметров. В комплекте с биллингом идет MIB, описывающий доступные параметры для мониторинга. Параметры разделены на 6 секций, находящихся в узле stg24:</para>
-- 
2.44.2