.\" Copyright (c) 2005 Andrey Simonenko .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)$Id: ipastat.conf.5,v 1.2.2.2 2007/07/20 09:53:40 simon Exp $ .\" .TH IPASTAT.CONF 5 "16 апреля 2005 г." .SH НАИМЕНОВАНИЕ ipastat -\- конфигурационный файл для ipastat(8) .SH ОПИСАНИЕ Файл \fBipastat.conf\fP это конфигурационный файл для ipastat(8). Этот файл или любой-другой файл, указанный в опции \fB-f\fP в командной строке ipastat(8), обрабатывается когда ipastat(8) начинает свою работу. .PP .SH ФОРМАТ ФАЙЛА .PP Почти после каждого параграфа приведен пример. Так как IPA пакет не содержит каких-либо модулей, то в примерах используются модуль ipa_st_sdb, только лишь потому, что это был первый модуль статистики, разработанный для IPA. .PP \fBОбщий синтаксис.\fP .PP Любая логическая строка в конфигурационном файле может быть записана в несколько текстовых строках для улучшения читаемости конфигурации. Нет никакого правила в какой строке размещать зарезервированные слова, аргументы или специальные символы. Если формат позволяет использовать один пробел (пробел или символ табуляции), то можно использовать столько пробелов, сколько необходимо для улучшения форматирования конфигурационного файла. Все элементы в конфигурационном файле регистрозависимые. Конфигурационный файл состоит из секций, параметров и комментариев. .PP \fBКомментарии.\fP .PP Существуют shell\-подобные и C\-подобные комментарии. Если вы используете C\-подобный комментарий в shell\-подобном комментарии, то C\-подобный комментарий игнорируется. .PP \fIПример:\fP .PP .nf # Shell-подобный комментарий. /* C-подобный комментарий. */ /* * Другой C-подобный комментарий. */ .fi .PP \fBСекции и параметры.\fP .PP Секция состоит из имени секции, опциональных аргументов и тела секции. Тело секции должно быть заключено в фигурные скобки: .PP .nf секция [[=] аргумент] { /* Параметры и секции. */ } .fi .PP Параметр состоит из имени и опциональных аргументов. Каждый параметр должен заканчиваться символом `;' в конце списка своих аргументов: .PP .nf параметр [[=] аргумент]; .fi .PP Символ `=' после имени параметра (секции) опционален. Некоторые параметры похоже на переменные (и для таких параметров естественно использовать символ `='), другие похожи на инструкции. В любом случае, в можете выбрать синтаксис, который вам наиболее подходит. .PP Аргумент может содержать строки: .PP .nf "строка" .fi .PP Возможно использовать последовательности ``\\t'', ``\\n'', ``\\\\'' и ``\\"'', чтобы представить символ табуляции, символ новой строки, обратный слэш и двойную кавычку внутри строки. Если необходимо разделить строку на несколько линий (строк в файле), то используйте символ `\\' в конце текущей линии (не добавляйте лишних пробелов после обратного слэша). Если строка записана в несколько линий без символов `\\', то каждый символ новой строки добавляется в строку. .PP \fBМакропеременные.\fP .PP Возможно определить макропеременные и использовать их почти где угодно в конфигурационном файле: .PP .nf ${переменная} = "строка"; .fi .PP Имя любой макропеременной может состоять из букв, цифр и знака доллара. Что является буквой определяется функцией isalpha(3), которая использует локаль. .PP Значением любой макропеременной должна быть строка, когда макропеременная расширяется, то первый и последний символы двойной кавычки убираются. .PP Макропеременные могут быть локальными или глобальными. Макропеременная является глобальной, если она определена вне какой-либо секции, иначе макропеременная является локальной для всех вложенных секций и для всех внешних секции. Локальные макропеременные скрывают глобальные макропеременные. .PP Есть несколько предопределённых макропеременных: .PP ${$}\ \ \ \ \ \-\ расширяется в символ `$'; .br ${rule}\ \ \-\ расширяется в имя текущей секции \fBrule\fP; .br ${limit}\ \-\ расширяется в имя текущей секции \fBlimit\fP; .br ${threshold}\ \-\ расширяется в имя текущей секции \fBthreshold\fP. .PP Любая макропеременная (включая предопределённые), за исключением ${$}, по необходимости может быть переопределена. Рекомендуется не переопределять или уничтожать макропеременные в модулях. .PP Макропеременная ${$} не может быть использована для конструирования имён макропеременных (см. пример). .PP Макропеременные расширяются в момент их использования, а не в момент их определения. Макропеременные также расширяются в строках. .PP \fIПример:\fP .PP .nf ${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} не определена как глобальная. .fi .PP \fBВключение файлов.\fP .PP Возможно хранить конфигурацию в нескольких файлах. Файлы могут быть включены при помощи следующих параметров: .PP .nf include "/путь/файл"; include_files "/директория/шаблон"; .fi .PP Параметр \fBinclude\fP включает один файл. Параметр \fBinclude_files\fP включает несколько файлов из указанной директории, имена которых совпадают с указанным шаблоном. .PP Эти параметры могут быть использованы где угодно, за исключением секций модулей. Возможно включать файлы из включённых файлов и т.д. Каждый включённый файл должен содержать корректно определённые параметры с аргументами, комментарии и секции с аргументами, но он может содержать незакрытые секции. .PP Возможно использовать регулярные выражения POSIX (расширенный формат) в качестве шаблонов в параметрах \fBinclude_files\fP, для этого установите параметр \fBposix_re_pattern\fP в ``yes'' перед параметрами, которые включают файлы с регулярными выражениями POSIX в качестве шаблонов: .PP .nf posix_re_pattern = ; .fi .PP Значение этого параметра по умолчанию ``no''. Этот параметр не должен быть указан в какой-либо секции. .PP Включаемые файлы должны иметь того владельца, кто запустил ipa(8) и не должны иметь прав на запись для группы и остальных пользователей. Если файлы включаются с помощью параметра \fBinclude_files\fP, то и директории указанные в этом параметре тоже должны иметь те же свойства. .PP \fIПример:\fP .PP .nf posix_re_pattern = yes; include "/usr/local/etc/ipastat.local.conf"; include_files "/usr/local/etc/ipastat/LAN/."; .fi .PP Первый параметр включает один файл, второй параметр включает каждый файл в данной директории, регулярное выражение POSIX ``.'' означает любой символ. .PP .nf /* posix_re_pattern = no; */ include_files "/usr/local/etc/ipastat/LAN/*"; .fi .PP Здесь используется шаблон shell. Первую строку необходимо раскомментировать, если перед этим использовались регулярные выражения POSIX. .PP \fBИспользование модулей статистики.\fP .PP Существуют специальные модули статистики, которые используются для того, чтобы запрашивать статистику. ipastat(8) использует эти внешние модули статистики с помощью специального \fIipa_st_mod\fP API, описанного в странице документации ipa_mod(3). .PP Параметр \fBst_mod\fP сообщает ipastat(8), что необходимо загрузить заданный IPA модуль статистики: .PP .nf st_mod "имя_файла"; .fi .PP Этот параметр не должен располагаться в какой-либо секции. Возможно использовать несколько модулей баз данных одновременно. .PP \fIПример:\fP .PP .nf st_mod "ipa_st_sdb.so"; .fi .PP Этот параметр загружает один модуль статистики. .PP \fBКонфигурирование модулей.\fP .PP Документация для IPA модуля должна давать всю информацию как конфигурировать модуль, но обычно конфигурация IPA модуля интегрируется в конфигурационный файл ipastat.conf(5). .PP Каждый модуль имеет конфигурационный префикс, который используется для того, чтобы отличать секции и параметра модуля. Если параметр записан в форме: .PP .nf префикс:параметр [[=] аргумент]; .fi .PP то ipastat(8) попытается найти загруженный модуль, с конфигурационным префиксом ``префикс'', затем передаст этот параметр для разбора найденному модулю. .PP Секции также могут иметь префиксы: .PP .nf префикс:секция [[=] аргумент] { /* Параметры и секции модуля. */ } .fi .PP В этом случае параметры и секции внутри такой секции должны быть записаны без префикса и они будут переданы соответствующему модулю для обработки. .PP Документация для модуля должна описывать сам модуль, конфигурационный префикс модуля, имя базы данных или имя системы учёта и все секции и параметры модуля. .PP \fIПример:\fP .PP .nf global { sdb:db_dir = "/var/ipa/sdb"; } .fi .PP Здесь секция \fBglobal\fP содержит один параметр модуля. .PP \fBПравила статистики.\fP .PP ipastat(8) запрашивает статистику основываясь на правилах. Существуют два типа правил: статические и динамические. Статическое правило описывается в секции \fBrule\fP. Динамическое правило не имеет описания в конфигурационном файле, ipastat(8) генерит любое динамическое правило на лету, в соответствии с настройками в командной строке и в конфигурационном файле. .PP Несколько правил (статических, динамических) могут разделять одни и те же установки. Существует несколько путей это сделать. Первый путь это использовании секции \fBglobal\fP. Второй путь это использование секций \fBrulepat\fP (шаблоны правил). И третий путь это указание установок для динамических правил в командной строке. .PP Если какое-то правило (статическое, динамическое) не содержит установок для какой-то секции или параметра, то наследуются установки с подходящей секции \fBrulepat\fP, далее наследуются установки из секции \fBglobal\fP, если некоторые секции или параметра всё ещё не определены, то используются установки по умолчанию. Запустите ipastat(8) с ключами \fB-tt\fP, чтобы увидеть реальные значения всех параметров. .PP Следующие параметры могут быть использованы в секциях \fBglobal\fP, \fBrulepat\fP и \fBrule\fP: \fBst_list\fP. .PP \fBИспользование систем статистики.\fP .PP Выше был определён параметр \fBst_mod\fP, который сообщает, что необходимо загрузить модуль и позволяет этому модулю обрабатывать свою конфигурацию. Параметр \fBst_list\fP определяет список используемых систем статистики: .PP st_list = <список>; .PP <Список> это набор имён, разделённых пробелами. Чтобы получить имена систем статистики, прочтите документацию для модулей, которые вы указали в параметрах \fBst_list\fP. .PP Если какое-то правило (лимит, порог) содержит параметр \fBst_list\fP, то системы статистики, перечисленные в его значении, будут опрашиваться для получения статистики для этого правила (лимита, порога). Этот параметр позволяет создавать список систем статистики для каждого правила (лимита, порога) по отдельности. .PP Первая система статистики, которая в состоянии выполнить запрос, будет использоваться для выполнения запроса определённой статистики. Заметьте, что порядок систем статистики важен. .PP Существует одна встроенная в ipastat(8) система статистики \fInull\fP: она не возвращает никакой статистики. Если параметр \fBst_list\fP не определён, то используется система статистики \fInull\fP. .PP \fIПример:\fP .PP .nf st_mod "ipa_st_sdb.so"; global { st_list = sdb; } .fi .PP Здесь определена одна система статистики. .PP \fBСтатические правила.\fP .PP Статические правила называются ``статическими'' потому, что они существуют в конфигурационном файле. .PP Секция \fBrule\fP описывает установки для одного статического правила: .PP .nf rule <имя-правила> { /* Параметры и секции правила. */ } .fi .PP Вы должны давать такие имена правилам, которые также являются корректными именами правилами для используемой вами системы статистики. .PP Секция \fBrule\fP не требует каких-либо обязательных установок. Если какое-то правило не содержит ни одной секции и параметра, то оно называется пустым правилом. Очевидно, что такие правила бессмысленны, поэтому любое правило имеет несколько параметров (собственные или наследованные). .PP \fIПример:\fP .PP .nf st_mod "ipa_st_sdb.so"; rule local.traf { st_list = sdb; sdb:db_dir = "/somewhere/${rule}"; } .fi .PP Здесь правило использует одну систему статистики, оно также имеет один параметр модуля. .PP \fBЛимиты.\fP .PP Лимит описывается в секции \fBlimit\fP: .PP .nf limit <имя-лимита> { /* Параметры и секции лимита. */ } .fi .PP Вы должны давать такие имена лимитам, которые также являются корректными именами лимитов для используемой вами системы статистики. .PP Секция \fBlimit\fP не требует каких-либо обязательных установок. .PP Лимиты имеют имена, поэтому возможно использовать несколько лимитов в одном правиле и они будут различаться по именам. .PP \fBИспользование отдельных систем статистики для лимитов.\fP .PP Существует параметр \fBst_list\fP, который определяет список систем статистики используемых правилом. По умолчанию лимит использует тот же самый список систем статистики, который определён для его правила (он наследует этот список). Но возможно использовать параметр \fBst_list\fP в секции \fBlimit\fP: .PP .nf rule <имя-правила> { /* Параметры и секции правила. */ st_list <список1>; limit <имя-лимита> { /* Параметры и секции лимита. */ st_list <список2>; } } .fi .PP <Список1> и <список2> могут содержать общие элементы, в любом случае <список1> используется только для правила, а <список2> используется только для лимита. .PP Зачем использовать раздельные системы статистики для правила и его лимитов? Не все системы статистики работают с лимитами и даже если какая-то система статистики работает с лимитами, она может поддерживать не все функции (методы) для лимитов. См. детали реализации в странице документации ipa_mod(3). .PP Прочтите в документации к системе статистики, которую вы используйте, может ли она работать с лимитами и что конкретно модуль поддерживает, когда работает с лимитами. .PP \fBПороги.\fP .PP Порог описывается в секции \fBthreshold\fP: .PP .nf threshold <имя-порога> { /* Параметры и секции порога. */ } .fi .PP Вы должны давать такие имена порогам, которые также являются корректными именами порогов для используемой вами системы статистики. .PP Секция \fBthreshold\fP не требует каких-либо обязательных установок. .PP Пороги имеют имена, поэтому возможно использовать несколько порогов в одном правиле и они будут различаться по именам. .PP \fBИспользование отдельных систем статистики для порогов.\fP .PP Подобно лимитам возможно использовать параметр \fBst_list\fP в секции \fBthreshold\fP и указывать различные списки систем статистики для правила и его порога. .PP \fBДинамические правила, лимиты и пороги.\fP .PP По умолчанию если какое-то правило не найдено в конфигурационном файле, то это правило считается как несуществующее. Но число правил может быть велико и правила могут не существовать на момент создания конфигурационного файла. В этом случае не возможно или не удобно держать все возможные правила в конфигурационном файле. .PP Чтобы решить эту проблему существуют динамические правила. Возможно создавать динамические правила не лету и эти динамические правила будут наследовать установки из подходящей секции \fBrulepat\fP и секции \fBglobal\fP, подобно статическим правилам. Чтобы включить поддержку динамических правил установите параметр \fBdynamic_rules\fP в ``yes'': .PP .nf dynamic_rules = ; .fi .PP По умолчанию значение этого параметра равно ``no''. .PP Существую схожие параметры для лимитов и порогов: \fBdynamic_limits\fP и \fBdynamic_thresholds\fP соответственно: .PP .nf dynamic_limits = ; dynamic_thresholds = ; .fi .PP Динамические лимиты и динамические пороги могут быть созданы для динамических и статических правил. .PP \fIПример:\fP .PP .nf dynamic_limits = yes; .fi .PP В этом примере разрешено создание только динамических лимитов. .PP \fBШаблоны правил.\fP .PP Использование шаблонов правил это эффективный метод для разделения общих установок для нескольких правил. Как было сказано раньше, секция \fBglobal\fP позволяет определить общие установки для любых правил. Шаблоны правил позволяют определить общие установки для классов статических и динамических правил. .PP Если какое-то статическое или динамическое правило не имеет какого-то параметра или секции, то оно наследовует этот параметр или секцию из подходящего шаблона правила. Шаблоны правил определяются в секциях \fBrulepat\fP: .PP .nf rulepat "" { /* Параметры и секции. */ } .fi .PP Каждый шаблон правила поименован регулярным выражением POSIX (расширенный формат). ipastat(8), разобрав конфигурационный файл, находит подходящий шаблон правила для каждого статического правила и добавляет неопределённые установки для статического правила из шаблона правила. Аналогично, создав динамическое правило, ipastat(8) находит подходящий шаблон правила и добавляет неопределённые установки для динамического правила из шаблона правила. По умолчанию, когда подходящий шаблон правила найден, поиск следующего шаблона правила прекращается. Чтобы продолжить поиск следующих шаблонов правил, установите значение параметра \fBcheck_next_rulepat\fP в ``yes'': .PP .nf check_next_rulepat = ; .fi .PP Этот параметр может быть указан только в секции \fBrulepat\fP и его значение по умолчанию равно ``no''. .PP Любой параметр и любая секция (включая секции \fBlimit\fP и \fBthreshold\fP), которая может быть использована в секции \fBrule\fP может быть использована в секции \fBrulepat\fP. .PP Шаблоны правил могут быть указаны в любом месте в конфигурационном файле, важен их порядок, так как их регулярные выражение проверяются в том же самом порядке, в котором расположены шаблоны правил в конфигурационном файле. .PP Модули также могут ожидать параметры и секции в секциях \fBrulepat\fP. .PP \fIПример\fP: .PP .nf st_mod "ipa_st_sdb.so"; rulepat "^client" { st_list sdb; } .fi .PP Вторая секция \fBrulepat\fP ``ловит'' все правила с подстрокой ``client'' в начале их имён. .PP \fBОтладка.\fP .PP Иногда необходимо определить почему что-то идёт не так как должно было быть. Существует несколько параметров, которые могут быть использованы для отладки ipastat(8): \fBdebug_st_null\fP\ \-\ сообщать об использовании системы статистики \fInull\fP (отдельно, 1). .PP Каждый параметр отладки принимает уровень отладки как аргумент, максимальный уровень отладки для каждого параметра определён как номер в скобках. Если в скобках есть слово ``отдельно'', то этот параметр должен располагаться отдельно. .PP По умолчанию отладка отключена. .PP \fIПример:\fP .PP .nf debug_st_null = 1; .fi .PP Если статистика не выводится, то указать ipastat(8) сообщать если используется встроенная система статистики \fInull\fP. .SH ФАЙЛЫ ipastat.conf .PP (запустите \fBipastat\fP с ключём \fB-h\fP, чтобы увидеть путевое имя конфигурационного файла, используемое по умолчанию) .SH ДРУГИЕ ИСТОЧНИКИ ipa(8), ipactl(8), ipastat(8), ipa.conf(5), ipa_mod(3) .SH АВТОР Andrey\ Simonenko\ .SH НЕДОРАБОТКИ Если вы обнаружите какие-либо ошибки, то, пожалуйста, сообщите мне по email.