IPASTAT.CONF(5)

НАИМЕНОВАНИЕ
ipastat -- конфигурационный файл для ipastat(8)

ОПИСАНИЕ
Файл ipastat.conf это конфигурационный файл для ipastat(8). Этот файл или любой-другой файл, указанный в опции -f в командной строке ipastat(8), обрабатывается когда ipastat(8) начинает свою работу.

ФОРМАТ ФАЙЛА

Почти после каждого параграфа приведен пример. Так как IPA пакет не содержит каких-либо модулей, то в примерах используются модуль ipa_st_sdb, только лишь потому, что это был первый модуль статистики, разработанный для IPA.

  Общий синтаксис
Любая логическая строка в конфигурационном файле может быть записана в несколько текстовых строках для улучшения читаемости конфигурации. Нет никакого правила в какой строке размещать зарезервированные слова, аргументы или специальные символы. Если формат позволяет использовать один пробельный символ (пробел или символ табуляции), то можно использовать столько пробельных символов, сколько необходимо для улучшения форматирования конфигурационного файла. Все элементы в конфигурационном файле регистрозависимые. Конфигурационный файл состоит из секций, параметров и комментариев.

  Комментарии
Существуют shell-подобные и C-подобные комментарии. Если вы используете C-подобный комментарий в shell-подобном комментарии, то C-подобный комментарий игнорируется.

Пример:

# Shell-подобный комментарий.
/* C-подобный комментарий. */
/*
 * Другой C-подобный комментарий.
 */

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

секция [[=] аргумент] {
    /* Параметры и секции. */
}

Параметр состоит из имени и опциональных аргументов. Каждый параметр должен заканчиваться символом `;' в конце списка своих аргументов:

параметр [[=] аргумент];

Символ `=' после имени параметра или секции опционален. Некоторые параметры похоже на переменные (и для таких параметров естественно использовать символ `='), другие похожи на инструкции. В любом случае, в можете выбрать синтаксис, который вам наиболее подходит.

Аргумент может содержать строки:

"строка"

Возможно использовать последовательности ``\t'', ``\n'', ``\\'' и ``\"'', чтобы представить символ табуляции, символ новой строки, обратный слэш и двойную кавычку внутри строки. Если необходимо разделить строку на несколько линий (строк в файле), то используйте символ `\' в конце текущей линии (не добавляйте лишних пробельных символов после обратного слэша). Если строка записана в несколько линий без символов `\', то каждый символ новой строки добавляется в строку.

  Макропеременные
Определение макропеременной имеет следующую форму:

${переменная} = "строка";

Имя любой макропеременной может состоять из букв, цифр, символов '_' и знаков доллара. Что является буквой определяется функцией isalpha(3), которая использует текущую локаль.

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

Макропеременные могут быть локальными или глобальными. Макропеременная является глобальной, если она определена вне какой-либо секции, иначе макропеременная является локальной для всех вложенных секций и для всех внешних секции. Локальные макропеременные скрывают глобальные макропеременные.

Есть несколько предопределённых макропеременных:

${$}         - символ `$';
${rule}      - имя текущего правила;
${limit}     - имя текущего лимита;
${threshold} - имя текущего порога.

Любая макропеременная (включая предопределённые), за исключением ${$}, по необходимости может быть переопределена. Не рекомендуется переопределять или уничтожать предопределённые макропеременные в модулях.

Макропеременная ${$} не может быть использована для конструирования имён макропеременных (см. пример).

Макропеременные могут использоваться почте где-угодно в конфигурационном файле. Когда макропеременная расширяется, её значение расширяется рекурсивно. Макропеременные расширяются в момент их использования, а не в момент их определения. Макропеременные также расширяются в строках.

Пример:

${a} = "${b}";      # Определение ${a}.
${b} = "1";         # Определение ${b}.
param = ${a};       # Расширяется в 1.
${b} = "2";         # Переопределение ${b}.
param = ${a};       # Расширяется в 2.
param = "${$}{b}";  # Расширяется в ${b} (последовательность
                    # символов внутри строки).
section {
    ${a} = "1";     # Определение локальной ${a}, которая
                    # скрывает глобальную ${a}.
    ${c} = "4";     # Определение локальной ${c}.
    param = ${a};   # Расширяется в 1.
    subsection {
        ${a} = "2"; # Переопределение локальной ${a}.
        ${b} = "3"; # Переопределение глобальной ${b}.
    }
    param = ${a};   # Расширяется в 2.
    param = ${b};   # Расширяется в 3.
}
# param = ${c};     <-- Ошибка: ${c} не определена как глобальная.

  Включение файлов
Возможно хранить конфигурацию в нескольких файлах. Файлы могут быть включены при помощи следующих параметров:

include "/путь/файл";
include_files "/директория/шаблон";

Параметр include включает один файл. Параметр include_files включает несколько файлов из указанной директории, имена которых совпадают с указанным шаблоном.

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

Возможно использовать регулярные выражения POSIX в качестве шаблонов в параметрах include_files, для этого установите параметр posix_re_pattern в ``yes'' перед параметрами, которые включают файлы с регулярными выражениями POSIX в качестве шаблонов (значение по умолчанию равно ``no''):

posix_re_pattern = <boolean>;

Этот параметр должен быть расположен отдельно.

Включаемые файлы должны иметь того владельца, кто запустил ipastat(8) и не должны иметь прав на запись для группы и остальных пользователей. Если файлы включаются с помощью параметра include_files, то и директории указанные в этом параметре тоже должны иметь те же свойства.

Пример:

posix_re_pattern = yes;
include "/usr/local/etc/ipastat.local.conf";
include_files "/usr/local/etc/ipastat/LAN/.";

Первый параметр включает один файл, второй параметр включает каждый файл в данной директории (регулярное выражение POSIX ``.'' означает любой символ).

/* posix_re_pattern = no; */
include_files "/usr/local/etc/ipastat/LAN/*";

Здесь используется шаблон shell. Первую строку необходимо раскомментировать, если перед этим использовались регулярные выражения POSIX.

  Использование модулей статистики
IPA модули статистики используются для получения статистики. ipastat(8) и модули статистики работают вместе с помощью ipa_st_mod API, описанного в странице документации ipa_mod(3).

Параметр st_mod динамически загружает указанный модуль статистики:

st_mod "имя_файла";

Этот параметр должен быть расположен отдельно. Возможно использовать несколько модулей статистики одновременно.

Данное имя файла должно быть именем shared-object (shared library) файла если ipastat(8) использует интерфейс dlopen(3) или это может быть .la файл если используется интерфейс библиотеки libtool ltdl.

Пример:

st_mod "ipa_st_sdb.so";

Этот параметр загружает один модуль статистики.

  Конфигурирование модулей
Документация для IPA модуля должна давать всю информацию как конфигурировать модуль. Обычно конфигурация IPA модуля интегрируется в конфигурационный файл ipastat.conf(5).

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

префикс:параметр [[=] аргумент];

то ipastat(8) попытается найти загруженный модуль, с конфигурационным префиксом ``префикс'', затем передаст этот параметр для разбора найденному модулю.

Секции также могут иметь префиксы:

префикс:секция [[=] аргумент] {
    /* Параметры и секции модуля. */
}

В этом случае параметры и секции внутри такой секции должны быть записаны без префикса и они будут переданы соответствующему модулю для обработки.

Документация для модуля должна описывать сам модуль, конфигурационный префикс модуля, имя системы статистики и все секции и параметры модуля.

Пример:

global {
    sdb:db_dir = "/var/db/ipa_sdb";
}

Здесь секция global содержит один параметр модуля.

  Единицы статистики
Некоторые параметры и секции могут принимать аргументы в байтах, времени и 64-битных беззнаковых целых числах. В ipa_mod(3) такой тип данных определён как IPA_CONF_TYPE_VALUE. Иногда желательно использовать только один тип данных для таких значений, так как ``10'', ``10m'' и ``10M'' являются корректными типами данных и означают 10, 10 минут и 10 Мбайт соответственно.

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

value_units = <type>;

Этот параметр должен быть расположен отдельно. Доступны следующие значения: ``any'' (по умолчанию), ``time'', ``bytes'' и ``number''.

  Имена правил, лимитов и порогов
Любой символ в любом имени должен быть буквой, цифрой или символом пунктуации из таблицы ASCII символов.

Имя не может содержать символ двойной кавычки, символы '/' и '\'.

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

  Правила статистики
ipastat(8) запрашивает статистику основываясь на правилах. Существуют статические и динамические правила. Статическое правило описывается в секции rule. Динамическое правило не имеет описания в конфигурационном файле, ipastat(8) генерирует любое динамическое правило на лету, в соответствии с настройками в командной строке и в конфигурационном файле.

Несколько правил (статических, динамических) могут разделять одни и те же установки. Существует несколько путей это сделать. Первый путь это использовании секции global. Второй путь это использование секций rulepat (шаблоны правил). И третий путь это указание установок для динамических правил в командной строке.

Если какое-то правило (статическое, динамическое) не содержит установок для какой-то секции или параметра, то наследуются установки из подходящей секции rulepat, далее наследуются установки из секции global, если некоторые секции или параметра всё ещё не определены, то используются установки по умолчанию. Запустите ipastat(8) с ключами -tt, чтобы увидеть реальные значения всех параметров.

Следующие параметры могут быть использованы в секциях global, rulepat и rule: st_list.

  Использование систем статистики
Параметр st_list определяет список используемых систем статистики:

st_list = <список>;

<Список> это набор имён, разделённых пробельными символами. Чтобы получить имена систем статистики, прочтите документацию для модулей, которые вы указали в параметрах st_mod.

Если какое-то правило (лимит, порог) содержит параметр st_list, то системы статистики, перечисленные в его значении, будут опрашиваться для получения статистики для этого правила (лимита, порога). Этот параметр позволяет создавать список систем статистики для каждого правила (лимита, порога) по отдельности.

Первая система статистики, которая в состоянии выполнить запрос, будет использоваться для выполнения запроса определённой статистики. Заметьте, что порядок систем статистики важен.

Существует одна встроенная система статистики null: эта система статистики не возвращает никакой статистики. Если параметр st_list не определён, то используется система статистики null.

Пример:

st_mod "ipa_st_sdb.so";
global {
    st_list = sdb;
}

Здесь определена одна система статистики.

  Статические правила
Статические правила называются ``статическими'' потому, что они существуют в конфигурационном файле.

Секция rule описывает установки для одного статического правила:

rule <имя-правила> {
    /* Параметры и секции правила. */
}

Секция rule не требует каких-либо обязательных установок. Если какое-то правило не содержит ни одной секции и параметра, то оно называется пустым правилом. Очевидно, что такие правила бессмысленны, поэтому любое правило имеет несколько параметров (собственные или наследованные).

Пример:

st_mod "ipa_st_sdb.so";
rule local.traf {
    st_list = sdb;
    sdb:db_dir = "/somewhere/${rule}";
}

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

  Лимиты
Лимит описывается в секции limit:

limit <имя-лимита> {
    /* Параметры и секции лимита. */
}

Одно правило может иметь несколько лимитов. Если правило содержит хотя бы один лимит, то это правило не наследует лимиты из подходящей секции rulepat.

Секция limit не требует каких-либо обязательных установок.

  Системы статистики и лимиты (пороги)
По умолчанию лимит наследует список систем статистики своего правила, но лимит может использовать собственный список систем статистики:

rule <имя-правила> {
    /* Параметры и секции правила. */
    st_list = <список1>;
    limit <имя-лимита> {
        /* Параметры и секции лимита. */
        st_list = <список2>;
    }
}

<Список1> и <список2> могут содержать общие элементы, в любом случае <список1> используется только для правила, а <список2> используется только для лимита.

Зачем использовать раздельные системы статистики для правила и его лимитов? Не все системы статистики работают с лимитами и даже если какая-то система статистики работает с лимитами, она может поддерживать не все функции (методы) для лимитов. См. детали реализации в странице документации ipa_mod(3).

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

Всё сказанное выше также справедливо для порогов.

  Пороги
Порог описывается в секции threshold:

threshold <имя-порога> {
    /* Параметры и секции порога. */
}

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

Секция threshold не требует каких-либо обязательных установок.

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

Чтобы решить эту проблему существуют динамические правила. Возможно создавать динамические правила не лету и эти динамические правила будут наследовать установки из подходящей секции rulepat и секции global, подобно статическим правилам. Чтобы включить поддержку динамических правил установите параметр dynamic_rules в ``yes'' (значение по умолчанию равно ``no''):

dynamic_rules = <boolean>;

Существую схожие параметры для лимитов и порогов: dynamic_limits и dynamic_thresholds соответственно:

dynamic_limits = <boolean>;
dynamic_thresholds = <boolean>;

Эти параметры должны быть расположены отдельно.

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

Пример:

dynamic_limits = yes;

В этом примере разрешено создание только динамических лимитов.

  Шаблоны правил
Использование шаблонов правил это эффективный метод для разделения общих установок для нескольких правил. Секция global позволяет определить общие установки для любых правил. Шаблоны правил позволяют определить общие установки для классов статических и динамических правил.

Если какое-то статическое или динамическое правило не имеет какого-то параметра или секции, то оно наследует этот параметр или секцию из подходящего шаблона правила. Шаблон правила определяется в секции rulepat:

rulepat "<regexp>" {
    /* Параметры и секции. */
}

Каждый шаблон правила поименован регулярным выражением POSIX. ipastat(8), разобрав конфигурационный файл, находит подходящий шаблон правила для каждого статического правила и добавляет неопределённые установки для статического правила из шаблона правила. Аналогично, создав динамическое правило, ipastat(8) находит подходящий шаблон правила и добавляет неопределённые установки для динамического правила из шаблона правила.

По умолчанию, когда подходящий шаблон правила найден, поиск завершается. Чтобы продолжить поиск следующих шаблонов правил, установите значение параметра check_next_rulepat в ``yes'' (значение по умолчанию равно ``no''):

check_next_rulepat = <boolean>;

Этот параметр может быть расположен только в секции rulepat.

Любой параметр и любая секция, которая может быть использована в секции rule может быть использована в секции rulepat.

Шаблоны правил могут быть расположены в любом месте в конфигурационном файле, важен их порядок, так как их регулярные выражение проверяются в том же самом порядке, в котором расположены шаблоны правил в конфигурационном файле.

Модули также могут ожидать параметры и секции в секциях rulepat.

Пример:

st_mod "ipa_st_sdb.so";
rulepat "^client" {
    st_list = sdb;
}

Вторая секция rulepat ``ловит'' все правила с подстрокой ``client'' в начале их имён.

  Отладка
Иногда необходимо определить почему что-то идёт не так как должно было быть. Существует несколько параметров, которые могут быть использованы для отладки ipastat(8): debug_st_null - сообщать об использовании системы статистики null (отдельно, 1).

Каждый параметр отладки принимает уровень отладки как аргумент, максимальный уровень отладки для каждого параметра определён как номер в скобках. Если в скобках есть слово ``отдельно'', то этот параметр не должен располагаться в какой-либо секции.

По умолчанию отладка отключена.

Пример:

debug_st_null = 1;

Если статистика не выводится, то указать ipastat(8) сообщать если используется встроенная система статистики null.

ФАЙЛЫ
ipastat.conf

(запустите ipastat с ключём -h, чтобы увидеть путевое имя конфигурационного файла, используемое по умолчанию)

ДРУГИЕ ИСТОЧНИКИ
ipa(8), ipactl(8), ipastat(8), ipa.conf(5), ipa_mod(3)

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

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