IPASTAT.CONF(5) IPASTAT.CONF(5)
НАИМЕНОВАНИЕ
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} - имя текущего правила;
${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_pat-
tern в ``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 модули статистики используются для получения статистики. ipas-
tat(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. ipas-
tat(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.
19 июля 2007 г. IPASTAT.CONF(5)