FreeBSD Manual Pages
IPASTAT.CONF(5) File Formats Manual IPASTAT.CONF(5) NAME ipastat.conf -- ipastat(8) configuration file DESCRIPTION The ipastat.conf file is a configuration file for ipastat(8). This file or any other one, specified in the -f option in the ipastat(8) command line is read when ipastat(8) starts working. FILE FORMAT There is an example almost after each paragraph. Since IPA distribution does not have any module, ipa_st_sdb module is used in examples just be- cause this was the first statistics module designed for IPA. General syntax 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, then as much as needed space characters, tab characters and newline 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. Comments 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. Example: # Shell-like comment. /* C-like comment. */ /* * Another C-like comment. */ Sections and parameters A section consists of its name, optional arguments and its body. A sec- tion's body should be placed in curly braces: section [[=] argument] { /* Parameters and sections. */ } A parameter consists of its name and optional arguments. Every parameter should have the `;' character at the end of its arguments list: parameter [[=] argument]; The `=' character after the section's or parameter's name is optional. Some parameters look like variables (it is naturally to use the `=' charac- ter for them), another ones look like instructions. In any case you can choose a syntax you like more. An argument can contain strings: "string" The ``\t'', ``\n'', ``\\'' and ``\"'' sequences should be used for repre- senting 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 char- acters after the back-slash character). If a string is written in several lines without `\' characters, then each newline character is added to a string. Macro variables The definition of a macro variable has the following form: ${variable} = "string"; A macro variable name consists of letters, digits, '_' symbols and dollar signs. What is a letter is checked with isalpha(3) function which uses current locale. 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. 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 sec- tions. Local macro variables can hide global ones. There are some predefined macro variables: ${$} - a `$' character; ${rule} - the current rule name; ${limit} - the current limit name; ${threshold} - the current threshold name. 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. Macro variable ${$} cannot be used for constructing macro variables names (see the example). Macro variable can be used almost anywhere in the configuration file. When macro variable is expanded, then its value is expanded recursively. 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. Example: ${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). 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. Including files Configuration information can be kept in several configuration files. Files are included with the help of the following parameters: include "/path/file"; include_files "/directory/pattern"; The include parameter includes one file. The include_files parameter in- cludes files, which match the given shell pattern from the specified direc- tory. These parameters can be used anywhere in the configuration file except in- side modules' sections, and contents of included files will be included im- mediately. Files can be included from included files. Each included file should have correctly specified parameters with arguments, comments and sections with arguments, but it can have not closed sections. POSIX regular expressions can be used as patterns in include_files parame- ters as well, to enable them set the posix_re_pattern parameter to ``yes'' before parameters which include files with POSIX regular expression pat- terns (the default value of this parameter is ``no''): posix_re_pattern = <boolean>; This parameter should not be placed in any section. Included files must be owned by the user who run ipastat(8) and must not be writable for group and other users. If files are included with the help of the include_files parameter, then a directory specified in this parameter also should have the same properties. Examples: posix_re_pattern = yes; include "/usr/local/etc/ipastat.local.conf"; include_files "/usr/local/etc/ipastat/LAN/."; First parameter includes one file, second parameter includes each file in the given directory (the ``.'' POSIX regular expression means ``any charac- ter''). /* posix_re_pattern = no; */ include_files "/usr/local/etc/ipastat/LAN/*"; Here a shell pattern is used. First string should be uncommented if previ- ously POSIX regular expressions were used. Using statistics modules IPA statistics modules are used for querying statistics. ipastat(8) and statistics modules work together via the ipa_st_mod API described in the ipa_mod(3) manual page. The st_mod parameter dynamically loads the given statistics module: st_mod "file_name"; This parameter should not be placed in any section. Several statistics modules can be used one time. The given file name should be a shared-object (shared library) file name if ipastat(8) uses dlopen(3) interface or it can be a .la file if the libtool's ltdl library interfaces is used. Example: st_mod "ipa_st_sdb.so"; This parameter loads one statistics module. Configuring modules A documentation for some IPA module should give all information how to con- figure it. Usually configuration of a IPA module is integrated to the con- figuration file ipastat.conf(5). Each module has a configuration prefix, which is used for distinguishing module's sections and parameters. If there is a parameter like this one: prefix:parameter [[=] argument]; then ipastat(8) will try to find a loaded module with configuration prefix ``prefix'', then ipastat(8) will give this parameter for parsing to the found module. Sections also can have prefixes: prefix:section [[=] argument] { /* Module's parameters and sections. */ } In this case parameters and sections inside such section should be written without a prefix and this section and all its internal sections and parame- ters will be passed to the appropriate module for parsing. Documentation for some module should describe a module itself, module's configuration prefix, statistics name and all module's parameters and sec- tions. Example: global { sdb:db_dir = "/var/db/ipa_sdb"; } Here the global section has one module's parameter. Units of statistics Arguments of some parameters and sections can be bytes, time and unsigned 64-bit integer numbers. Such data type is defined as IPA_CONF_TYPE_VALUE in ipa_mod(3). Sometimes it is desirable to use only one data type for such values, because ``10'', ``10m'' and ``10M'' are correct values and mean 10, 10 minutes and 10 Mbytes respectively. The value_units parameter can be used for specifying desired data type for arguments with IPA_CONF_TYPE_VALUE data type and for controlling their real values: value_units = <type>; This parameter should not be placed in any section and it is better to place it before other parameters and sections. It accepts the following values: ``any'' (the default value), ``time'', ``bytes'' and ``number''. Names of rules, limits and thresholds Any symbol in any name must be letter, digit or punctuation symbol from the ASCII character set. Any name cannot contain double quote, '/' and '\' symbols. You should give such names that are also valid rules names for statistics systems you use. Statistics rules ipastat(8) queries statistics based on rules. There are static and dynamic rules. A static rule is described in the rule section. A dynamic rule does not have description in the configuration file, but it is generated on-the-fly accordingly to the settings in the command line and in the con- figuration file. Several rules (static, dynamic) can share the same settings. There are several ways to do this. The first way is using the global section. The second way is using rulepat (rules patterns) sections. And the third way is specifying settings for dynamic rules in the command line. If some rule (static, dynamic) does not have settings for some section or parameter, then it inherits settings from matched rulepat section, then it inherits settings from the global section; if there are still some unspeci- fied sections or parameters, then default settings are used. Run ipas- tat(8) with -tt switches to see real values of all parameters. Following parameters can be used in global, rulepat and rule sections: st_list. Using statistics systems The st_list parameter specifies a list of used statistics systems: st_list = <list>; <List> is a set of names separated by a space character. To get names of statistics systems read manual pages for modules you specified in st_mod parameters. If some rule (limit, threshold) has the st_list parameter, then statistics systems listed in its argument will be queried for statistics for this rule (limit, threshold). This parameter allows to create per rule (limit, threshold) statistics systems list. The first statistics system can perform asked query will be used for query- ing particular type of statistics. Note that the order of statistics sys- tems is important. There is one built-in statistics system null: this statistics system does not return any statistics. If the st_list parameter is not specified, then the null statistics system is used. Example: st_mod "ipa_st_sdb.so"; global { st_list = sdb; } Here one statistics system is specified. Static rules Static rules are called ``static'' because they exist in the configuration file. The rule section describes settings for one static rule: rule <rule-name> { /* Rule's parameters and sections. */ } The rule 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 pa- rameters (own or inherited). Example: st_mod "ipa_st_sdb.so"; rule local.traf { st_list = sdb; sdb:db_dir = "/somewhere/${rule}"; } Here a rule uses one statistics system, it also has module's specific para- meter. Limits A limit is described in the limit section: limit <limit-name> { /* Limit's parameters and sections. */ } One rule can have several limits. If a rule has at least one limit, then it will no inherit any limits from the matched rulepat section. The limit section does not have any mandatory settings. Statistics systems and limits (thresholds) A limit inherits a list of statistics systems from its rule, but a limit can have own list of statistics systems: rule <rule-name> { /* Rule's parameters and sections. */ st_list = <list1>; limit <limit-name> { /* Limit's parameters and sections. */ st_list = <list2>; } } <List1> and <list2> can contain common elements, <list1> is used only for a rule and <list2> is used only for a limit in any case. Why to use separate statistics system lists for a rule and a 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. Read in the statistics module's documentation whether it can work with lim- its and what exactly a module supports when it works with limits. Everything said above corresponds to thresholds as well. Thresholds A threshold is described in the threshold section: threshold <threshold-name> { /* Threshold's parameters and sections. */ } One rule can have several thresholds. If a rule has at least one thresh- old, then it will no inherit any thresholds from the matched rulepat sec- tion. The threshold section does not have any mandatory settings. Dynamic rules, limits and thresholds 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 of the configuration file creation. In this case it is impossible or inconvenient to keep all possible rules in the configuration file. To solve this problem there are so called dynamic rules. It is possible to create dynamic rules on-the-fly and these dynamic rules will inherit set- tings from the matched rulepat section and the global section like any sta- tic rule. To turn on dynamic rules support set the dynamic_rules parameter to ``yes'' (the default value is ``no''): dynamic_rules = <boolean>; There are similar parameter for limits and thresholds: dynamic_limits and dynamic_thresholds respectively: dynamic_limits = <boolean>; dynamic_thresholds = <boolean>; These parameters should not be placed in any section. Dynamic limits and dynamic thresholds can be created for dynamic and static rules. Example: dynamic_limits = yes; In this example only creating of dynamic limits is allowed. Rules patterns Using rules patterns is an effective method for sharing common settings for rules. The global section allows to specify some common settings for any rules. Rules patterns allow to specify common settings for classes of sta- tic and dynamic rules. 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. A rule pattern is defined in the rulepat section: rulepat "<regexp>" { /* Parameters and sections. */ } Each rule pattern is named by POSIX 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 check_next_rulepat parameter to ``yes'' (the default value is ``no''): check_next_rulepat = <boolean>; This parameter can be used only in the rulepat section. Any parameter and any section, that is allowed to use in the rule section, can be used in the rulepat section. 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 they appear in the configuration file. Modules also can expect their parameters and sections in rulepat sections. Example: st_mod "ipa_st_sdb.so"; rulepat "^client" { st_list = sdb; } Here the rulepat section ``catches'' all rules with ``client'' substring at the beginning of their names. Debugging Sometime it is necessary to find out why something goes wrong. There are some parameters, which should be used for debugging: debug_st_null - report when null statistics system is used (alone, 1). Each debugging parameter accepts a debug level as an argument, maximum de- bug level for each debug parameter is specified as a number in parenthesis. If there is a word ``alone'' in parenthesis, then a parameter should not be placed in any section. By default debugging is off for everything. Example: debug_st_null = 1; Here ipastat(8) will report about usage of the null statistics system. FILES ipastat.conf (run ipastat(8) with the -h switch and check default configuration file pathname) SEE ALSO ipa(8), ipactl(8), ipastat(8), ipa.conf(5), ipa_mod(3) AUTHOR Andrey Simonenko <simon@comsys.ntu-kpi.kiev.ua> BUGS If you find any, please send email me. July 19, 2007 IPASTAT.CONF(5)
NAME | DESCRIPTION | FILE FORMAT | FILES | SEE ALSO | AUTHOR | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ipastat.conf&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>