Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 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.

   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
       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:

	   "string"

       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 ex-
       ternal 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.

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

       These  parameters can be	used anywhere in the configuration file	except
       inside modules' sections, and contents of included files	 will  be  in-
       cluded  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
       sections.

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

       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
       character'').

	   /* 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.

       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
       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
       sections.

       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  un-
       signed	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-
       ber''.

   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 dy-
       namic rules.  A static rule is described	in the rule  section.	A  dy-
       namic  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  pa-
       rameters.

       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 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.

       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 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).

       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
       parameter.

   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
       limits 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
       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 in-
       herit  settings from the	matched	rulepat	section	and the	global section
       like any	static rule.  To turn on dynamic rules	support	 set  the  dy-
       namic_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 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-
       tions.

       Example:

	   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.

   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
       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.

       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://www.freebsd.org/cgi/man.cgi?query=ipastat.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help