|
Конфигурационный файл для ipastat. | |
НАИМЕНОВАНИЕ
ipastat - конфигурационный файл для ipastat(8)
ОПИСАНИЕ
Файл ipastat.conf это конфигурационный файл для ipastat(8). Этот файл
или любой-другой файл, указанный в опции -f в командной строке ipas-
tat(8), обрабатывается когда ipastat(8) начинает свою работу.
ФОРМАТ ФАЙЛА
Почти после каждого параграфа приведен пример. Так как IPA пакет не
содержит каких-либо модулей, то в примерах используются модуль
ipa_st_sdb, только лишь потому, что это был первый модуль статистики,
разработанный для IPA.
Общий синтаксис.
Любая логическая строка в конфигурационном файле может быть записана в
несколько текстовых строках для улучшения читаемости конфигурации. Нет
никакого правила в какой строке размещать зарезервированные слова,
аргументы или специальные символы. Если формат позволяет использовать
один пробельный символ (пробел или символ табуляции), то можно исполь-
зовать столько пробельных символов, сколько необходимо для улучшения
форматирования конфигурационного файла. Все элементы в конфигурационном
файле регистрозависимые. Конфигурационный файл состоит из секций, пара-
метров и комментариев.
Комментарии.
Существуют shell-подобные и C-подобные комментарии. Если вы используете
C-подобный комментарий в shell-подобном комментарии, то C-подобный ком-
ментарий игнорируется.
Пример:
# Shell-подобный комментарий.
/* C-подобный комментарий. */
/*
* Другой C-подобный комментарий.
*/
Секции и параметры.
Секция состоит из имени секции, опциональных аргументов и тела секции.
Тело секции должно быть заключено в фигурные скобки:
секция [[=] аргумент] {
/* Параметры и секции. */
}
Параметр состоит из имени и опциональных аргументов. Каждый параметр
должен заканчиваться символом `;' в конце списка своих аргументов:
параметр [[=] аргумент];
Символ `=' после имени параметра (секции) опционален. Некоторые пара-
метры похоже на переменные (и для таких параметров естественно исполь-
зовать символ `='), другие похожи на инструкции. В любом случае, в
можете выбрать синтаксис, который вам наиболее подходит.
Аргумент может содержать строки:
"строка"
Возможно использовать последовательности ``\t'', ``\n'', ``\\'' и
``\"'', чтобы представить символ табуляции, символ новой строки, обрат-
ный слэш и двойную кавычку внутри строки. Если необходимо разделить
строку на несколько линий (строк в файле), то используйте символ `\' в
конце текущей линии (не добавляйте лишних пробельных символов после
обратного слэша). Если строка записана в несколько линий без символов
`\', то каждый символ новой строки добавляется в строку.
Макропеременные.
Возможно определить макропеременные и использовать их почти где угодно
в конфигурационном файле:
${переменная} = "строка";
Имя любой макропеременной может состоять из букв, цифр и знака доллара.
Что является буквой определяется функцией isalpha(3), которая исполь-
зует локаль.
Значением любой макропеременной должна быть строка, когда макроперемен-
ная расширяется, то первый и последний символы двойной кавычки убира-
ются.
Макропеременные могут быть локальными или глобальными. Макропеременная
является глобальной, если она определена вне какой-либо секции, иначе
макропеременная является локальной для всех вложенных секций и для всех
внешних секции. Локальные макропеременные скрывают глобальные макропе-
ременные.
Есть несколько предопределённых макропеременных:
${$} - расширяется в символ `$';
${rule} - расширяется в имя текущей секции rule;
${limit} - расширяется в имя текущей секции limit;
${threshold} - расширяется в имя текущей секции 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 в качестве шаблонов:
posix_re_pattern = <boolean>;
Значение этого параметра по умолчанию ``no''. Этот параметр не должен
быть указан в какой-либо секции.
Включаемые файлы должны иметь того владельца, кто запустил ipa(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.
Использование модулей статистики.
Существуют специальные модули статистики, которые используются для
того, чтобы запрашивать статистику. ipastat(8) использует эти внешние
модули статистики с помощью специального ipa_st_mod API, описанного в
странице документации ipa_mod(3).
Параметр st_mod сообщает ipastat(8), что необходимо загрузить заданный
IPA модуль статистики:
st_mod "имя_файла";
Этот параметр не должен располагаться в какой-либо секции. Возможно
использовать несколько модулей баз данных одновременно.
Пример:
st_mod "ipa_st_sdb.so";
Этот параметр загружает один модуль статистики.
Конфигурирование модулей.
Документация для IPA модуля должна давать всю информацию как конфигури-
ровать модуль, но обычно конфигурация IPA модуля интегрируется в конфи-
гурационный файл ipastat.conf(5).
Каждый модуль имеет конфигурационный префикс, который используется для
того, чтобы отличать секции и параметра модуля. Если параметр записан в
форме:
префикс:параметр [[=] аргумент];
то ipastat(8) попытается найти загруженный модуль, с конфигурационным
префиксом ``префикс'', затем передаст этот параметр для разбора найден-
ному модулю.
Секции также могут иметь префиксы:
префикс:секция [[=] аргумент] {
/* Параметры и секции модуля. */
}
В этом случае параметры и секции внутри такой секции должны быть запи-
саны без префикса и они будут переданы соответствующему модулю для
обработки.
Документация для модуля должна описывать сам модуль, конфигурационный
префикс модуля, имя базы данных или имя системы учёта и все секции и
параметры модуля.
Пример:
global {
sdb:db_dir = "/var/ipa/sdb";
}
Здесь секция global содержит один параметр модуля.
Правила статистики.
ipastat(8) запрашивает статистику основываясь на правилах. Существуют
два типа правил: статические и динамические. Статическое правило описы-
вается в секции rule. Динамическое правило не имеет описания в конфигу-
рационном файле, ipastat(8) генерит любое динамическое правило на лету,
в соответствии с настройками в командной строке и в конфигурационном
файле.
Несколько правил (статических, динамических) могут разделять одни и те
же установки. Существует несколько путей это сделать. Первый путь это
использовании секции global. Второй путь это использование секций
rulepat (шаблоны правил). И третий путь это указание установок для
динамических правил в командной строке.
Если какое-то правило (статическое, динамическое) не содержит установок
для какой-то секции или параметра, то наследуются установки с подходя-
щей секции rulepat, далее наследуются установки из секции global, если
некоторые секции или параметра всё ещё не определены, то используются
установки по умолчанию. Запустите ipastat(8) с ключами -tt, чтобы уви-
деть реальные значения всех параметров.
Следующие параметры могут быть использованы в секциях global, rulepat и
rule: st_list.
Использование систем статистики.
Выше был определён параметр st_mod, который сообщает, что необходимо
загрузить модуль и позволяет этому модулю обрабатывать свою конфигура-
цию. Параметр st_list определяет список используемых систем стати-
стики:
st_list = <список>;
<Список> это набор имён, разделённых пробельными символами. Чтобы полу-
чить имена систем статистики, прочтите документацию для модулей, кото-
рые вы указали в параметрах st_list.
Если какое-то правило (лимит, порог) содержит параметр st_list, то
системы статистики, перечисленные в его значении, будут опрашиваться
для получения статистики для этого правила (лимита, порога). Этот пара-
метр позволяет создавать список систем статистики для каждого правила
(лимита, порога) по отдельности.
Первая система статистики, которая в состоянии выполнить запрос, будет
использоваться для выполнения запроса определённой статистики.
Заметьте, что порядок систем статистики важен.
Существует одна встроенная в ipastat(8) система статистики 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 <имя-лимита> {
/* Параметры и секции лимита. */
}
Вы должны давать такие имена лимитам, которые также являются коррект-
ными именами лимитов для используемой вами системы статистики.
Секция limit не требует каких-либо обязательных установок.
Лимиты имеют имена, поэтому возможно использовать несколько лимитов в
одном правиле и они будут различаться по именам.
Использование отдельных систем статистики для лимитов.
Существует параметр st_list, который определяет список систем стати-
стики используемых правилом. По умолчанию лимит использует тот же самый
список систем статистики, который определён для его правила (он насле-
дует этот список). Но возможно использовать параметр st_list в секции
limit:
rule <имя-правила> {
/* Параметры и секции правила. */
st_list <список1>;
limit <имя-лимита> {
/* Параметры и секции лимита. */
st_list <список2>;
}
}
<Список1> и <список2> могут содержать общие элементы, в любом случае
<список1> используется только для правила, а <список2> используется
только для лимита.
Зачем использовать раздельные системы статистики для правила и его
лимитов? Не все системы статистики работают с лимитами и даже если
какая-то система статистики работает с лимитами, она может поддерживать
не все функции (методы) для лимитов. См. детали реализации в странице
документации ipa_mod(3).
Прочтите в документации к системе статистики, которую вы используйте,
может ли она работать с лимитами и что конкретно модуль поддерживает,
когда работает с лимитами.
Пороги.
Порог описывается в секции threshold:
threshold <имя-порога> {
/* Параметры и секции порога. */
}
Вы должны давать такие имена порогам, которые также являются коррект-
ными именами порогов для используемой вами системы статистики.
Секция threshold не требует каких-либо обязательных установок.
Пороги имеют имена, поэтому возможно использовать несколько порогов в
одном правиле и они будут различаться по именам.
Использование отдельных систем статистики для порогов.
Подобно лимитам возможно использовать параметр st_list в секции thresh-
old и указывать различные списки систем статистики для правила и его
порога.
Динамические правила, лимиты и пороги.
По умолчанию если какое-то правило не найдено в конфигурационном файле,
то это правило считается как несуществующее. Но число правил может быть
велико и правила могут не существовать на момент создания конфигураци-
онного файла. В этом случае не возможно или не удобно держать все воз-
можные правила в конфигурационном файле.
Чтобы решить эту проблему существуют динамические правила. Возможно
создавать динамические правила не лету и эти динамические правила будут
наследовать установки из подходящей секции rulepat и секции global,
подобно статическим правилам. Чтобы включить поддержку динамических
правил установите параметр dynamic_rules в ``yes'':
dynamic_rules = <boolean>;
По умолчанию значение этого параметра равно ``no''.
Существую схожие параметры для лимитов и порогов: 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'':
check_next_rulepat = <boolean>;
Этот параметр может быть указан только в секции rulepat и его значение
по умолчанию равно ``no''.
Любой параметр и любая секция (включая секции limit и threshold), кото-
рая может быть использована в секции 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.
16 апреля 2005 г.
|
