.\" 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.1 2007/07/20 09:53:39 simon Exp $ .\" .TH IPASTAT.CONF 5 "April 16, 2005" .SH NAME ipastat.conf -\- ipastat(8) configuration file .SH DESCRIPTION The \fBipastat.conf\fP file is a configuration file for ipastat(8). This file or any other one, specified in the \fB-f\fP option in the ipastat(8) command line, is read when ipastat(8) starts working. .PP .SH FILE FORMAT .PP Almost after each paragraph there is an example. Since IPA distribution does not have any module, ipa_st_sdb module is used in examples, just because this was the first statistics module designed for IPA. .PP \fBGeneral syntax.\fP .PP Any logical line in the configuration file can be written in several text lines for indenting purpose. There is not any rule in which line to place reserved words, arguments and special symbols. If some format allows one space character (a space character and a tab character), then as much as needed space characters can be written there for indenting. All elements in a configuration file are case sensitive. A configuration file consists of sections, parameters and comments. .PP \fBComments.\fP .PP There are shell\-like and C\-like comments. If you use a C\-like comment in a shell\-like comment, then a C\-like comment is ignored. .PP \fIExample:\fP .PP .nf # Shell-like comment. /* C-like comment. */ /* * Another C-like comment. */ .fi .PP \fBSections and parameters.\fP .PP A section consists of its name, optional arguments and its body. A section's body should be placed in curly braces: .PP .nf section [[=] argument] { /* Parameters and sections. */ } .fi .PP A parameter consists of its name and optional arguments. Every parameter should have the `;' character at the end of its arguments list: .PP .nf parameter [[=] argument]; .fi .PP The `=' character after the section's or parameter's name is optional. Some parameters look like variables (it is naturally to use the `=' character for such parameters), another ones look like instructions. In any case, you can choose a syntax you like more. .PP An argument can contain strings: .PP .nf "string" .fi .PP It is possible to use ``\\t'', ``\\n'', ``\\\\'' and ``\\"'' sequences to represent tab, newline, back-slash and double quote characters inside a string. If it is needed to split a string to several lines, then use one `\\' character at the end of the current line (do not put extra space characters after the back-slash character). If a string is written in several lines without `\\' characters, then each newline character is added to a string. .PP \fBMacro variables.\fP .PP It is possible to define macro variables and then use them almost anywhere in the configuration file: .PP .nf ${variable} = "string"; .fi .PP A name of any macro variable can consist of characters, digits and dollar signs. What is a character is checked with isalpha(3) function, which uses locale. .PP A value of any macro variable should be a string, when a macro variable is expanded then first and last double quotes of its value are removed. .PP Macro variables can be local or global. A macro variable is global if it is defined outside any section, else a macro variable is local. A local macro variables are local for all nested sections and for all external sections. Local macro variables can hide global ones. .PP There are some predefined macro variables: .PP ${$}\ \ \ \ \ \-\ expands to a `$' character; .br ${rule}\ \ \-\ expands to the name of current \fBrule\fP section; .br ${limit}\ \-\ expands to the name of current \fBlimit\fP section; .br ${threshold}\ \-\ expands to the name of current \fBthreshold\fP section. .PP Any macro variable (including predefined ones) except ${$} can be redefined if needed. It is not recommended to redefine or delete predefined macro variables in modules. .PP Macro variable ${$} cannot be used for constructing macro variables names (see an example). .PP Macro variables are expanded at the moment of their usage and not at the moment of their definition. Macro variables are expanded also in strings. .PP \fIExample:\fP .PP .nf ${a} = "${b}"; # Definition of ${a}. ${b} = "1"; # Definition of ${b}. param = ${a}; # Expands to 1. ${b} = "2"; # Redefine ${b}. param = ${a}; # Expands to 2. param = "${$}{b}"; # Expands to "${b}" (sequence of characters # inside string). section { ${a} = "1"; # Definition of local ${a}, which hides # global ${a}. ${c} = "4"; # Definition of local ${c}. param = ${a}; # Expands to 1. subsection { ${a} = "2";# Redefine local ${a}. ${b} = "3";# Redefine global ${b}. } param = ${a}; # Expands to 2. param = ${b}; # Expands to 3. } # param = ${c}; <-- Error: ${c} is not defined as global. .fi .PP \fBIncluding files.\fP .PP It is possible to keep configuration information in several configuration files. Files are included with the help of following parameters: .PP .nf include "/path/file"; include_files "/directory/pattern"; .fi .PP The \fBinclude\fP parameter includes one file. The \fBinclude_files\fP parameter includes some files from the specified directory, names of which match the given shell pattern. .PP These parameters can be used anywhere in the configuration file, except inside modules' sections, and included files will be included at once. It is possible to include files from included files, and so on. Each included file should have correctly specified parameters with arguments, comments and sections with arguments, but it can have not closed sections. .PP It is possible to use POSIX extended regular expressions as patterns in \fBinclude_files\fP parameters, for this set the \fBposix_re_pattern\fP parameter to ``yes'' before parameters, which include files with POSIX regular expression patterns, by default the value of this parameter is ``no'': .PP .nf posix_re_pattern = ; .fi .PP This parameter should not be placed in any section. .PP Included files must be owned by the user, who run ipa(8) and must not be writable for group and other users. If files are included with the help of the \fBinclude_files\fP parameter, then a directory in this parameter also should have the same properties. .PP \fIExamples:\fP .PP .nf posix_re_pattern = yes; include "/usr/local/etc/ipastat.local.conf"; include_files "/usr/local/etc/ipastat/LAN/."; .fi .PP First parameter includes one file, second parameter includes each file in the given directory, the ``.'' POSIX regular expression means any character. .PP .nf /* posix_re_pattern = no; */ include_files "/usr/local/etc/ipastat/LAN/*"; .fi .PP Here a shell pattern is used. First string should be uncommented if previously POSIX regular expressions were used. .PP \fBUsing statistics modules.\fP .PP There are special statistics modules, which are used for querying statistics. ipastat(8) uses such external statistics modules with the help from the special \fIipa_st_mod\fP API, described in the ipa_mod(3) manual page. .PP The \fBst_mod\fP parameter tells ipastat(8) to load the given IPA statistics module: .PP .nf st_mod "file_name"; .fi .PP This parameter should not be placed in any section. It is possible to use several statistics modules at once. .PP \fIExample:\fP .PP .nf st_mod "ipa_st_sdb.so"; .fi .PP This parameter loads one statistics module. .PP \fBConfiguring modules.\fP .PP Documentations for some IPA module should give all information how to configure it, but usually configuration of some IPA module is integrated to the configuration file ipastat.conf(5). .PP Each module has a configuration prefix, which is used for distinguishing module's sections and parameters. If there is a parameter like this one: .PP .nf prefix:parameter [[=] argument]; .fi .PP then ipastat(8) will try to find a loaded module, which has configuration prefix ``prefix'', then ipastat(8) will give this parameter for parsing to the found module. .PP Sections also can have prefixes: .PP .nf prefix:section [[=] argument] { /* Module's parameters and sections. */ } .fi .PP In this case parameters and sections inside such section should be written without a prefix and this section and all its internal sections and parameters will be passed to the appropriate module for parsing. .PP Documentation for some module should describe a module itself, module's configuration prefix, statistics name and all module's parameters and sections. .PP \fIExample:\fP .PP .nf global { sdb:db_dir = "/var/db/ipa_sdb"; } .fi .PP Here the \fBglobal\fP section has one module's parameter. .PP \fBStatistics rules.\fP .PP ipastat(8) queries statistics based on rules. There are two types of rules: static and dynamic. A static rule is described in the \fBrule\fP section. A dynamic rule does not have description in the configuration file, any dynamic rule is generated on-the-fly by ipastat(8), according to the settings in the command line and in the configuration file. .PP Several rules (static, dynamic) can share the same settings. There are several ways to do this. First way is to use the \fBglobal\fP section. Second way is to use \fBrulepat\fP (rules patterns) sections. And the third way is specifying settings for dynamic rules in the command line. .PP If some rule (static, dynamic) does not have settings for some section or parameter, then it inherits settings from matched \fBrulepat\fP section, then it inherits settings from the \fBglobal\fP section, if there are still some unspecified sections or parameters, then default settings are used. Run ipastat(8) with \fB-tt\fP switches to see real values of all parameters. .PP Following parameters can be used in \fBglobal\fP, \fBrulepat\fP and \fBrule\fP sections: \fBst_list\fP. .PP \fBUsing statistics systems.\fP .PP Above the \fBst_mod\fP parameter was introduced, which tells to load a module and allows it to parse its configuration. The \fBst_list\fP parameter specifies a list of used statistics systems: .PP st_list = ; .PP is a set of names separated by space characters. To get names of statistics systems read manual pages for modules you specified in \fBst_mod\fP parameters. .PP If some rule (limit, threshold) has the \fBst_list\fP parameter, then statistics systems listed in its value will be used for querying statistics for this rule (limit, threshold). This parameter allows to create per rule (limit, threshold) statistics systems list. .PP First statistics system which will be able to perform asked query will be used for querying particular type of statistics. Note that the order of statistics systems is important. .PP There is one built-in statistics system \fInull\fP in ipastat(8): it does not return any statistics. If the \fBst_list\fP parameter is not specified, then the \fInull\fP statistics system is used. .PP \fIExample:\fP .PP .nf st_mod "ipa_st_sdb.so"; global { st_list = sdb; } .fi .PP Here one statistics system is specified. .PP \fBStatic rules.\fP .PP Static rules are called ``static'' just because they exist in the configuration file. .PP The \fBrule\fP section describes settings for one static rule: .PP .nf rule { /* Rule's parameters and sections. */ } .fi .PP You should give such names for rules, which are also valid rules names for statistics systems you use. .PP The \fBrule\fP section does not have any mandatory settings. If some rule does not have any sections and parameters, then it is called an empty rule. It is obvious, that empty rules are senseless, so any rule usually has some parameters (own or inherited). .PP \fIExample:\fP .PP .nf st_mod "ipa_st_sdb.so"; rule local.traf { st_list = sdb; sdb:db_dir = "/somewhere/${rule}"; } .fi .PP Here a rule uses one statistics system, it also has module's specific parameter. .PP \fBLimits.\fP .PP A limit is described in the \fBlimit\fP section: .PP .nf limit { /* Limit's parameters and sections. */ } .fi .PP You should give such names for limits, which are also valid limits names for statistics system you use. .PP The \fBlimit\fP section does not have any mandatory settings. .PP Limits have names, hence it is possible to use several limits in one rule and they are distinguished by names. .PP \fBUsing separate statistics systems for limits.\fP .PP There is the \fBst_list\fP parameter, which determines a list of statistics systems used by a rule. By default a limit uses the same list of statistics systems, which is specified for its rule (it inherits this list). But it is possible to use the \fBst_list\fP parameter in the \fBlimit\fP section: .PP .nf rule { /* Rule's parameters and sections. */ st_list ; limit { /* Limit's parameters and sections. */ st_list ; } } .fi .PP and can contain common elements, in any case is used only for a rule and is used only for a limit. .PP Why to use separate statistics systems lists for a rule and its limit? Not all statistics systems work with limits and even if some statistics system works with limits, it can support not all functions (methods) for limits. See implementation details in the ipa_mod(3) manual page. .PP Read in the documentation for a statistics system module you use for information if it can work with limits and what exactly a module supports when works with limits. .PP \fBThresholds.\fP .PP A threshold is described in the \fBthreshold\fP section: .PP .nf threshold { /* Threshold's parameters and sections. */ } .fi .PP You should give such names for thresholds, which are also valid thresholds names for statistics system you use. .PP The \fBthreshold\fP section does not have any mandatory settings. .PP Thresholds have names, hence it is possible to use several thresholds in one rule and they are distinguished by names. .PP \fBUsing separate statistics systems for thresholds.\fP .PP Like limits, it is possible to use the \fBst_list\fP parameter in the \fBthreshold\fP section and have different lists of statistics systems for a rule and its threshold. .PP \fBDynamic rules, limits and thresholds.\fP .PP By default if some rule is not found in the configuration file, then this rule is considered as nonexistent. But number of rules can be very big and rules cannot exist at the moment when the configuration file was created. In this case it is impossible or inconvenient to keep all possible rules in the configuration file. .PP To solve this problem there is one optional feature called dynamic rules. It is possible to create dynamic rules on-the-fly and these dynamic rules will inherit settings from the matched \fBrulepat\fP section and the \fBglobal\fP section like any static rule. To turn on this feature, set the value of the \fBdynamic_rules\fP parameter to ``yes'': .PP .nf dynamic_rules = ; .fi .PP By default the value of this parameter is ``no''. .PP There are similar parameter for limits and thresholds: \fBdynamic_limits\fP and \fBdynamic_thresholds\fP respectively: .PP .nf dynamic_limits = ; dynamic_thresholds = ; .fi .PP Dynamic limits and dynamic thresholds can be created for dynamic and static rules. .PP \fIExample:\fP .PP .nf dynamic_limits = yes; .fi .PP In this example only creating of dynamic limits is allowed. .PP \fBRules patterns.\fP .PP Using rules patterns is an effective method for sharing common settings for rules. As it was said above, the \fBglobal\fP section allows to specify some common settings for any rules. Rules patterns allow to specify common settings for classes of static and dynamic rules. .PP If some static or dynamic rule does not have some parameter or section, then it inherits this parameter or section from the matched rule pattern. Rules patterns are defined in the \fBrulepat\fP sections: .PP .nf rulepat "" { /* Parameters and sections. */ } .fi .PP Each rule pattern is named by POSIX extended regular expression. Having parsed the configuration file, ipastat(8) finds a matched rule pattern for each static rule and applies unspecified settings from a rule pattern to a static rule. Similarly, having created a dynamic rule, ipastat(8) finds a matched rule pattern and applies unspecified settings from a rule pattern to a dynamic rule. By default when a matched rule pattern is found the search terminates. To continue search for other rule patters, set the value of the \fBcheck_next_rulepat\fP parameter to ``yes'': .PP .nf check_next_rulepat = ; .fi .PP This parameter can be used only in the \fBrulepat\fP section, and its default value is ``no''. .PP Any parameter and any section (including \fBlimit\fP and \fBthreshold\fP sections), which is allowed to use in the \fBrule\fP section, can be used in the \fBrulepat\fP section. .PP Rules patterns can be placed anywhere in the configuration file, but their order is important, because theirs regular expressions are checked in the same order as rules patters are placed in the configuration file. .PP Modules also can expect their parameters and sections in \fBrulepat\fP sections. .PP \fIExample\fP: .PP .nf st_mod "ipa_st_sdb.so"; rulepat "^client" { st_list sdb; } .fi .PP Here the \fBrulepat\fP section ``catches'' all rules with ``client'' substring at the beginning of their names. .PP \fBDebugging.\fP .PP Sometime it is necessary to find out why something goes wrong. There are some parameters, which should be used for debugging ipastat(8): \fBdebug_st_null\fP\ \-\ report about usage of \fInull\fP statistics system (alone, 1). .PP Each debugging parameter accepts a debug level as an argument, maximum debug level for each debug parameter is specified as a number in parenthesis. If there is a word ``alone'' in parenthesis, then a parameter should be placed alone. .PP By default debugging is off for everything. .PP \fIExample:\fP .PP .nf debug_st_null = 1; .fi .PP If no statistics is outputted, then ask ipastat(8) to report if built-in \fInull\fP statistics system is used. .SH FILES ipastat.conf .PP (run ipastat(8) with the \fB-h\fP switch and check default configuration file pathname) .SH SEE ALSO ipa(8), ipactl(8), ipastat(8), ipa.conf(5), ipa_mod(3) .SH AUTHOR Andrey\ Simonenko\ .SH BUGS If you find any, please send email me.