IPASTAT.CONF(5)                                                IPASTAT.CONF(5)

       ipastat.conf -- ipastat(8) configuration file

       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.

       There  is  an example almost after each paragraph.  Since IPA distribu-
       tion does not have any module, ipa_st_sdb module is  used  in  examples
       just because 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 indent-
       ing.  All elements in a configuration file are case sensitive.  A  con-
       figuration file consists of sections, parameters and 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.


           # 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
       section's body should be placed in curly braces:

           section [[=] argument] {
               /* Parameters and sections. */

       A parameter consists of its name and optional arguments.  Every parame-
       ter 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 `='
       character for them), another ones look like instructions.  In any  case
       you can choose a syntax you like more.

       An argument can contain strings:


       The ``\t'', ``\n'', ``\\'' and ``\"'' sequences should be used for rep-
       resenting 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 writ-
       ten in several lines without `\' characters, then each newline  charac-
       ter 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 dol-
       lar 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 sections.  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 rede-
       fined  if  needed.   It is not recommended to redefine or delete prede-
       fined 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  recur-
       sively.   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.


           ${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
       includes  files, which match the given shell pattern from the specified

       These parameters can be used anywhere in the configuration file  except
       inside  modules'  sections,  and  contents  of  included  files will be
       included immediately.  Files can be included from included files.  Each
       included  file  should  have  correctly specified parameters with argu-
       ments, comments and sections with arguments, but it can have not closed

       POSIX  regular  expressions  can  be  used as patterns in include_files
       parameters as well, to enable them set the  posix_re_pattern  parameter
       to  ``yes''  before  parameters  which include files with POSIX regular
       expression patterns (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.


           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

           /* posix_re_pattern = no; */
           include_files "/usr/local/etc/ipastat/LAN/*";

       Here  a  shell  pattern is used.  First string should be uncommented if
       previously 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.


           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
       configure it.  Usually configuration of a IPA module is  integrated  to
       the configuration file ipastat.conf(5).

       Each  module has a configuration prefix, which is used for distinguish-
       ing 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 parameters 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


           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 follow-
       ing values: ``any'' (the default value), ``time'', ``bytes'' and ``num-

   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  statis-
       tics 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 configuration 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 unspecified sections or  parameters,  then  default  settings  are
       used.   Run  ipastat(8)  with  -tt  switches  to see real values of all

       Following parameters can be used in global, rulepat and rule  sections:

   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 statis-
       tics 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
       querying particular type of statistics.  Note that the order of statis-
       tics systems 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 speci-
       fied, then the null statistics system is used.


           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 configura-
       tion 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 usu-
       ally has some parameters (own or inherited).


           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

       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
       limits and what exactly a module supports when it works with limits.

       Everything said above corresponds to thresholds as well.

       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
       threshold, then it will no inherit  any  thresholds  from  the  matched
       rulepat section.

       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 possi-
       ble to create dynamic rules on-the-fly and  these  dynamic  rules  will
       inherit  settings  from the matched rulepat section and the global sec-
       tion like any static 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.


           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 static 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 pat-
       tern.  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 sec-
       tion, 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  sec-


           st_mod "ipa_st_sdb.so";

           rulepat "^client" {
               st_list = sdb;

       Here  the  rulepat  section  ``catches'' all rules with ``client'' sub-
       string at the beginning of their names.

       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
       debug level for each debug parameter is specified as a number in paren-
       thesis.  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.


           debug_st_null = 1;

       Here  ipastat(8) will report about usage of the null statistics system.


       (run ipastat(8) with the -h switch and check default configuration file

       ipa(8), ipactl(8), ipastat(8), ipa.conf(5), ipa_mod(3)

       Andrey Simonenko <simon@comsys.ntu-kpi.kiev.ua>

       If you find any, please send email me.

                                 July 19, 2007                 IPASTAT.CONF(5)