.\" Copyright (c) 2000-2004 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: ipa.conf.5,v 1.9.2.3 2007/07/20 09:53:38 simon Exp $
.\"
.TH IPA.CONF 5 "April 16, 2005"
.SH NAME
ipa.conf -\- ipa(8) configuration file
.SH DESCRIPTION
The \fBipa.conf\fP file is a configuration file for ipa(8).
This file or any other one, specified in the \fB-f\fP option in the ipa(8)
command line, is read when ipa(8) starts working or receives a SIGHUP signal.
.SH FILE FORMAT
The \fBipa.conf\fP file can be quite simple and can be complex enough.
The main idea is to place as much as possible into configuration file(s)
instead of writing external programs to do accounting related tasks.
.PP
This manual page contains complete file format description and complete
documentation about all features of ipa(8).
.PP
Almost after each paragraph there is an example. Since IPA distribution
does not have any module, ipa_ipfw, ipa_ip6fw, ipa_atest and ipa_db_sdb
modules are used in examples, just because they were the first modules
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
${sublimit}\ \-\ expands to the name of current \fBsublimit\fP section;
.br
${threshold}\ \-\ expands to the name of current \fBthreshold\fP section;
.br
${autorule}\ \-\ expands to the name of current \fBautorule\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. Macro variables is a feature of the internal configuration
file parser, so ${rule} macro variable cannot be used in autorules
and in rules patterns (see information about substitutions in command
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 = <boolean>;
.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/ipa.local.conf";
	include_files "/usr/local/etc/ipa/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/ipa/LAN/*";
.fi
.PP
Here a shell pattern is used. First string should be uncommented if
previously POSIX regular expressions were used.
.PP
\fBUsing accounting modules.\fP
.PP
There are special accounting modules, which are used for gathering
statistics. ipa(8) uses such external accounting modules with the help from
the special \fIipa_ac_mod\fP API, described in the ipa_mod(3) manual page.
.PP
The \fBac_mod\fP parameter tells ipa(8) to load the given IPA accounting
module:
.PP
.nf
	ac_mod "file_name";
.fi
.PP
This parameter should not be placed in any section. It is possible to
use several accounting modules at once.
.PP
\fIExample:\fP
.PP
.nf
	ac_mod "ipa_ipfw.so";
	ac_mod "ipa_ip6fw.so";
.fi
.PP
These parameters load two accounting modules.
.PP
\fBUsing database modules.\fP
.PP
There are special database modules, which are used for storing
statistics to databases. ipa(8) uses such external database modules with
the help from the special \fIipa_db_mod\fP API, described in the ipa_mod(3)
manual page.
.PP
The \fBdb_mod\fP parameter tells ipa(8) to load the given IPA database
module:
.PP
.nf
	db_mod "file_name";
.fi
.PP
This parameter should not be placed in any section. It is possible to
use several database modules at once.
.PP
\fIExample:\fP
.PP
.nf
	db_mod "ipa_db_sdb.so";
.fi
.PP
This parameter loads one database 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 ipa.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 ipa(8) will try to find a loaded module with configuration prefix
``prefix'', then ipa(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, database or accounting system name and
all module's parameters and sections.
.PP
\fIExample:\fP
.PP
.nf
	sdb: {
	    allow_symlinks = yes;
	}

	ipfw:debug_ipfw = 1;
.fi
.PP
Given section's name can confuse one, but everything is correct.
A module can have empty section's and parameter's name.
.PP
\fBAccounting rules.\fP
.PP
ipa(8) performs accounting 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, but any dynamic rule is generated on-the-fly from some autorule
described in the \fBautorule\fP section.
.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 common settings for dynamic rules in
\fBautorule\fP sections.
.PP
If some rule (static, dynamic) does not have settings for some
section or parameter (dynamic rules also inherit settings from their
autorule), 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 ipa(8) with \fB-tt\fP switches to see real values of
all parameters.
.PP
Following parameters can be used in \fBglobal\fP, \fBrulepat\fP, \fBrule\fP
and \fBautorule\fP sections: \fBac_list\fP, \fBdb_list\fP, \fBappend_time\fP,
\fBupdate_time\fP, \fBworktime\fP, \fBctl_rule_acl\fP, \fBdebug_exec\fP,
\fBdebug_limit\fP, \fBdebug_limit_init\fP, \fBdebug_threshold\fP,
\fBdebug_threshold_init\fP.
.PP
\fBUsing accounting systems.\fP
.PP
Above the \fBac_mod\fP parameter was introduced, which tells to load
a module and allows it to parse its configuration. The \fBac_list\fP
parameter specifies a list of used accounting systems:
.PP
	ac_list = <list>;
.PP
<List> is a set of names separated by space characters. To get
names of accounting systems read documentations for modules you specified
in \fBac_mod\fP parameters.
.PP
If some rule has the \fBac_list\fP parameter, then accounting systems
listed in its value will be asked for statistics for this rule.
This parameter allows to create per rule accounting systems list.
.PP
There is one built-in accounting system \fInull\fP in ipa(8): this
accounting system always returns 0 as statistics. If the \fBac_list\fP
parameter is not specified, then the \fInull\fP accounting system is used.
.PP
\fIExample:\fP
.PP
.nf
	ac_mod "ipa_ipfw.so";
	ac_mod "ipa_ip6fw.so";

	global {
	    ac_list = ipfw ip6fw;
	}
.fi
.PP
Here two accounting systems are specified.
.PP
\fBUsing databases.\fP
.PP
Above the \fBdb_mod\fP parameter was introduced, which tells to load
a module and allows it to parse its configuration. The \fBdb_list\fP
parameter specifies a list of used databases:
.PP
	db_list = <list>;
.PP
<List> is a set of names separated by space characters. To get
names of databases read documentations for modules you specified in
\fBdb_mod\fP parameters.
.PP
If some rule (limit, threshold) has the \fBdb_list\fP parameter, then
databases listed in its value will be used for storing statistics
for this rule (limit, threshold). This parameter allows to create per
rule (limit, threshold) databases list.
.PP
There is one built-in database \fInull\fP in ipa(8): data sent to this
database is not kept anywhere. If the \fBdb_list\fP parameter is not
specified, then the \fInull\fP database is used.
.PP
\fIExample:\fP
.PP
.nf
	db_mod "ipa_db_sdb.so";

	global {
	    db_list = sdb;
	}
.fi
.PP
Here one database is specified.
.PP
\fBAccounting per period of a week.\fP
.PP
By default ipa(8) performs accounting for all days in a week, but
it is possible to perform accounting only for some time intervals in
a week. The \fBworktime\fP parameter specifies time intervals when
ipa(8) should perform accounting:
.PP
.nf
	worktime = <X> h1:m1-h2:m2 [h1:m1-h2:m2];
	worktime = <X> *;
.fi
.PP
<X> means a day of a week. Valid values for <X> are: `\fBS\fP' Sunday,
`\fBM\fP' Monday, `\fBT\fP' Tuesday, `\fBW\fP' Wednesday, `\fBH\fP' Thursday,
`\fBF\fP' Friday, `\fBA\fP' Saturday. There can be only one record for
each day.
Time intervals cannot be overlapped or be placed not in the order.
.PP
00:00-24:00 interval or the `\fB*\fP' character means a whole day.
.PP
When \fBworktime\fP allows to perform accounting, the section
where it is placed is called ``active'', else it is called ``inactive''.
.PP
What exactly this parameter defines for autorules, rules, limits and
thresholds read in appropriate paragraphs.
.PP
Note that time intervals given in the \fBworktime\fP parameter do not
guarantee that exactly the same time intervals will appear in the database,
because the running copy of ipa(8) can have low priority or the system
can be to busy.
.PP
The end of one time interval can be the start of the next time interval,
this feature is only useful for rules (see below).
.PP
\fIExample:\fP
.PP
Perform accounting only at Monday, Tuesday and Wednesday:
.PP
.nf
	worktime = M * T * W *;
.fi
.PP
Perform accounting at Thursday from 8:00 till 14:30 and from 18:20 till 21:00,
at Sunday from midnight till 10:35 (the value is written in several
lines, just for indenting):
.PP
.nf
	worktime = H 08:00-14:30 18:20-21:00
	           S 00:00-10:35;
.fi
.PP
\fBDatabase time intervals.\fP
.PP
The \fBupdate_time\fP parameter determines time interval when
ipa(8) should update statistics for some rule:
.PP
.nf
	update_time = <time>;
.fi
.PP
If this parameter is omitted, then default value is 1 minute.
.PP
The \fBappend_time\fP parameter determines time interval when
ipa(8) should append a new record to the database for some rule:
.PP
.nf
	append_time = <time>;
.fi
.PP
This parameter has not default value. A new statistics record for each
rule is added to the database at the end of each day in any case.
.PP
Usually a value of the \fBappend_time\fP parameter is greater than
a value of the \fBupdate_time\fP parameter.
.PP
ipa(8) tries to combine several time events into one to reduce resource
usage, this feature has another interesting moment, for example
if \fBupdate_time\fP is 5 minutes, then ipa(8) always schedules
time events for this parameter at 00:00, 00:05, 00:10 and so on.
.PP
There are some programs such as date(1) or ntpdate(8), which can change
UTC and local time, also the time zone can change itself. Such events
can cause an ``some time related problems occurred'' non fatal errors in
ipa(8). Parameters \fBupdate_time\fP and \fBappend_time\fP can cause
more such errors. For example, if you call ntpdate(8) very often and the
value of the \fBupdate_time\fP parameter is nearly equal to the time
interval of ntpdate(8) invocations, then you can receive a lot of warning
messages from ipa(8).
.PP
It is possible to set how time events are sensitive to time changes
in the \fBsensitive_time\fP parameter:
.PP
.nf
	sensitive_time = <time>;
.fi
.PP
By default the value of this parameter is equal to 30 seconds.
This parameter should not be placed in any section.
.PP
The \fBwakeup_time\fP parameter specifies maximum number of seconds
ipa(8) can sleep. This parameter tells ipa(8) when to wakeup and check if
everything is correct with time, time zone, etc.:
.PP
.nf
	wakeup_time = <time>;
.fi
.PP
By default the value of this parameter is equal to 10 minutes.
This parameter should not be placed in any section.
.PP
\fIExample:\fP
.PP
.nf
	global {
	    update_time = 30s;
	    append_time = 1h 30m;
	}
.fi
.PP
The `\fBs\fP' character means seconds, `\fBm\fP' minutes, `\fBh\fP'
hours (spaces are optional). If <time> is specified as
a complex value, then hours should be placed before minutes and seconds,
minutes should be placed before seconds.
.PP
\fBDescriptions of rules, limits and thresholds.\fP
.PP
\fBrule\fP, \fBlimit\fP and \fBthreshold\fP sections can have
the \fBinfo\fP parameter, which is passed to the database and is
used for describing a section:
.PP
.nf
	info = "string";
.fi
.PP
The value of this parameter should not contain `\\n' and `\\t' characters.
Usually this value should help to recall what this rule, limit or
threshold is used for. For example, this value is output by the ipastat(8)
program.
.PP
Dynamic rules get their descriptions from an accounting module, which
generates them, so you cannot specify descriptions for dynamic rules
in the configuration file.
.PP
\fIExample:\fP
.PP
.nf
	rule 10.1.2.3-in {
	    info = "My traffic from ISP";
	    /* ... */
	}
.fi
.PP
Sometimes rule's name is not very informative, so describing a rule
is a good idea.
.PP
\fBStatic rules.\fP
.PP
Static rules are called ``static'', because they exist in the configuration
file and any accounting module cannot delete them (dynamic rules can be
deleted).
.PP
The \fBrule\fP section describes settings for one static rule:
.PP
.nf
	rule <rule-name> {
	    /* Rule's parameters and sections. */
	}
.fi
.PP
You should give such names for rules, which are also valid rules names for
databases 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
If a rule has the \fBworktime\fP parameter, then a new accounting record
is appended to the database when a new time interval begins. If a rule is
inactive then all its limits and thresholds are inactive as well.
.PP
\fIExample:\fP
.PP
.nf
	ac_mod "ipa_ipfw.so";
	ac_mod "ipa_ip6fw.so";
	db_mod "ipa_db_sdb.so";

	rule local.traf {
	    ac_list = ipfw ip6fw;
	    db_list = sdb;
	    info = "Traffic to my LAN";
	    sdb:db_group = staff;
	    ipfw:rules = 100 200 300;
	    ip6fw:rules = 1.10;
	}
.fi
.PP
Here a rule uses two accounting systems and one database. It also
has a description and several modules' specific parameters.
.PP
\fBRunning commands.\fP
.PP
There are several sections which allow to specify a list of commands
which should be run if some event occurred.
.PP
The \fBexec\fP parameter is used for running commands:
.PP
.nf
	exec [<user>] "/path/command";
.fi
.PP
The \fBexec\fP parameter without <user> runs a command with privileges of
the user who run ipa(8), that is no actions in changing user or groups are
performed for running command.
.PP
The \fBexec\fP parameter with <user> runs a command with privileges of
the given user. A user can be given only by its name. ipa(8), at the moment
of running a command, will get UID and GIDs of the user. This parameter can
be used if ipa(8) is run by the super-user only.
.PP
It is possible to use macro variable (including predefined ones) in
commands strings (actually in any string). If you need to use name of the
rule in some command string in \fBrulepat\fP or \fBautorule\fP section
then you should use substitutions. Two substitutions are defined:
.IP %rule%
The name of the rule.
.IP %%
The `%' character.
.PP
These substitutions do not work in command strings placed in \fBrule\fP
sections, use macro variable ${rule} there instead.
.PP
By default commands should be given with absolute pathname, but it is
possible to specify commands with relative pathnames, just set
the \fBonly_abs_paths\fP parameter to ``no'', by default the value
of this parameter is ``yes'':
.PP
.nf
	only_abs_paths = <boolean>;
.fi
.PP
All commands are run with the help from the shell, so any shell-specific
command line constructions can be used:
.PP
.nf
	<shell_path> <shell_arg1> /path/command
.fi
.PP
Note that standard input (stdin), standard output (stdout) and standard
error (stderr) are handled in the same way as in ipa(8).
.PP
<Shell_path> is determined when IPA is built, usually it is /bin/sh
(see output of the ``ipa\ \-v'' command for the real path), but it is
possible to exactly specify the shell in the configuration file with
the help of the \fBshell_path\fP parameter:
.PP
.nf
	shell_path = "/path/shell";
.fi
.PP
<Shell_arg1> by default is equal to ``-c'', but it can be redefined
in the \fBshell_arg1\fP parameter:
.PP
.nf
	shell_arg1 = "<arg1>";
.fi
.PP
If there are not enough resources and ipa(8) is not able, for example,
to fork(2) a child to run commands list, then ipa(8) will exit with an
error code. But if some error occurred in a child which runs a command,
then ipa(8) will ignore this error, and a child simply will log a warning
message.
.PP
Parameters \fBonly_abs_paths\fP, \fBshell_path\fP and \fBshell_arg1\fP
should not be placed in any section.
.PP
\fIExample:\fP
.PP
.nf
	startup {
	    exec "/bin/echo \\"ipa started\\" | mail me";
	    exec nobody "/usr/local/bin/something";
	}

	only_abs_path = no;

	shutdown {
	    exec "echo \\"ipa stopped\\" | mail me";
	}

	rulepat "^client" {
	    startup {
	        exec "command %rule%";
	    }
	}

	rule 1 {
	    shutdown {
	        exec "echo rule off >> /tmp/${rule}.log";
	    }
	}
.fi
.PP
In the first section the ``mail'' command is given without an absolute
pathname. This is correct because only the first command is checked for
an absolute pathname, ipa(8) does not interpret shell-specific command
line constructions.
.PP
In the \fBrulepat\fP section substitution %rule% is used and in the
\fBrule\fP section macro variable ${rule} is used for inserting the name
of the rule to the command string.
.PP
\fBRunning commands at startup and shutdown.\fP
.PP
In \fBstartup\fP (\fBshutdown\fP) section you can specify which commands
should be run when ipa(8) starts (finishes) working. These sections can be
placed alone (global commands) and in \fBautorule\fP, \fBrulepat\fP,
\fBrule\fP, \fBlimit\fP, \fBsublimit\fP and \fBthreshold\fP sections.
.PP
If these sections are placed alone (see below usage of these sections
in other sections), then they can contain only \fBexec\fP and \fBsync_exec\fP
parameters.
.PP
The algorithm of running commands in \fBstartup\fP (\fBshutdown\fP)
sections is the following:
.IP 1.
run global commands;
.IP 2.
run commands from \fBrule\fP sections;
.IP 2a.
in each \fBrule\fP section run commands for limits and thresholds;
.IP 2b.
in each \fBlimit\fP section run commands for its sublimits.
.PP
When ipa(8) rereads the configuration file (when it receives a SIGHUP
signal), then commands in \fBstartup\fP sections are ignored, but new
commands for \fBshutdown\fP sections will be used. If you need to run
some commands from \fBstartup\fP sections after reconfiguration, then
it is possible to run them by ipa(8) with the \fB-x\fP option.
.PP
\fIExample:\fP
.PP
.nf
	startup {
	    exec "command1";
	}

	rule 1 {
	    startup {
	        exec "command2";
	    }
	    limit 1 {
	        /* ... */
	        startup {
	            exec "command3";
	        }
	    }
	}

	rule 2 {
	    startup {
	        exec "command4";
	    }
	}
.fi
.PP
Here commands are run in the following order on startup: command1,
command2, command3 and command4.
.PP
\fBRunning commands synchronously and asynchronously.\fP
.PP
There are two regimes of running commands: synchronous and asynchronous.
In synchronous regime ipa(8) is waiting for the exit of running commands.
In asynchronous regime ipa(8) having run commands, is not waiting for
the exit of running commands and continues its work.
.PP
By default commands in all \fBstartup\fP and \fBshutdown\fP sections
are run synchronously, in all other sections commands are run
asynchronously.
.PP
The \fBsync_exec\fP parameter allows to specify synchronous or asynchronous
regime for any section:
.PP
.nf
	sync_exec = <boolean>;
.fi
.PP
This parameter can be used in any section, which accepts \fBexec\fP parameters.
.PP
\fIExample:\fP
.PP
.nf
	startup {
	    sync_exec = no;
	    exec "/path/something";
	}
.fi
.PP
In this example default synchronous regime of the \fBstartup\fP section
is changed to asynchronous.
.PP
\fBAbout statistics.\fP
.PP
ipa(8) interprets statistics as 64-bit unsigned integers, statistics
can be whatever (for example time, bytes or numbers). If some rule uses
several accounting systems, then ipa(8) summarizes statistics got from
each accounting module. Usually an accounting module returns positive
statistics, but it can return negative statistics.
.PP
ipa(8) internally for rules stores statistics in two 64-bit unsigned integer
counters: one counter for positive statistics and another one for negative
statistics. In any time one of these counters is equal to zero. If the
negative statistics counter is overflowed, then ipa(8) reports about
occurred problem and exits, since such overflow means wrong configuration.
If the positive statistics counter is overflowed, then ipa(8) asks
the database to append a new record for a rule to store statistics which
does not fit the size of its internal counter.
.PP
Any limit or threshold has the same two counters, but if limit's or
threshold's positive or negative counter is overflowed, then ipa(8)
reports about occurred problem and exits, since such overflow means
wrong configuration. Also each threshold has several counters for
each time slice (negative or positive sign is kept in a bitmap).
.PP
Statistics is given to the database as 64-bit unsigned integers
with the value of the current local time.
.PP
Usually positive statistics is greater than negative statistics,
but this is not required. Only positive statistics is stored in the
database and while ipa(8) is running, negative statistics is kept
in its memory, but when ipa(8) exits and some rule, limit or threshold
has negative statistics, then this negative statistics is lost (a log
message will be sent). In other words, ipa(8) is able to subtract
statistics from the current value of its positive statistics counter
and there is not any way to subtract statistics from old statistics
in the database.
.PP
\fBLimits: introduction.\fP
.PP
A limit should be considered with the context of some rule. Sometimes
limits in IPA are called triggers. If there is a need to do some actions
when statistics for some rule reaches some value during some time period,
then the \fBlimit\fP section should be used. This section can have several
sections and must have at least one parameter named \fBlimit\fP:
.PP
.nf
	limit <limit-name> {
	    limit = <limit-value>;
	    /* Limit's parameters and sections. */
	}
.fi
.PP
You should give such names for limits, which are also valid limits names for
databases you use.
.PP
Any limit has 64-bit unsigned counter for positive statistics which is
changed by ipa(8) and which is compared with the value of the \fBlimit\fP
parameter. If the counter's value becomes equal to or greater than the value
of the \fBlimit\fP parameter then a limit is treated as reached and ipa(8)
will not changed the limit's counter any more. A limit's counter is updated
synchronously with a rule's counter.
.PP
Limits have names, hence it is possible to use several limits in one
rule and they are distinguished by names.
.PP
ipa(8) knows nothing about units of statistics, so it is possible
to use different formats of <limit\-value>: bytes, time and unsigned
64-bit integer (see examples below). <Limit\-value> always is converted
to unsigned 64-bit integer.
.PP
A limit can pass several states: a limit is not reached, a limit is
reached (plus optionally running commands), a reached limit is expired
(plus optionally running commands) and pseudo state when a not reached limit
should be restarted. The \fBlimit\fP section can have some parameters and
some sections, which determine a limit's states (described below).
.PP
If a limit is not reached, then its statistics is checked each time
when its rule is updated (this time interval is not bigger than the
value of the \fBupdate_time\fP parameter).
.PP
\fIExample:\fP
.PP
.nf
	rule my-account {
	    /* Rule's parameters and sections. */
	    limit 1 {
	        limit = 1M 500K;
	        info = "Bytes limit";
	    }
	    limit 2 {
	        limit = 2h 30m;
	        info = "Time limit";
	    }
	    limit 3 {
	        limit = 1234567890;
	        info = "Numerical limit";
	    }
	}
.fi
.PP
There are three independent limits in one rule in this example.
.PP
When the value of the \fBlimit\fP parameter is given as bytes, then the
`\fBT\fP' character means TBytes, `\fBG\fP' Gbytes, `\fBM\fP' Mbytes,
`\fBK\fP' Kbytes, `\fBB\fP' bytes (spaces are optional). If a value
is specified as a complex value, then Tbytes should be placed before Gbytes
and Mbytes and so on.
.PP
\fBActive and inactive limits.\fP
.PP
If a limit does not have own \fBworktime\fP parameter, then it is active
when its rule is active, that is, if the rule's \fBworktime\fP parameter
allows accounting, then a limit works as usually, if accounting is not
allowed for its rule, then ipa(8) ignores a limit and will start to work
with it when the rule's \fBworktime\fP parameter allows to perform
accounting again.
.PP
Any limit can have own \fBworktime\fP parameter. In this case if a rule
is active, then ipa(8) checks the limit's \fBworktime\fP parameter.
.PP
When a limit is inactive, then times specified by the \fBrestart\fP
and \fBexpire\fP parameters are not checked.
.PP
So, it is possible to have active rule and inactive limit. But it is
impossible to have inactive rule and active limit. All time intervals
in the limit's \fBworktime\fP parameter must be subsets of time intervals
in the rule's \fBworktime\fP.
.PP
\fIExample:\fP
.PP
.nf
	rule my-account {
	    /* ... */
	    worktime = A * S *;
	    limit 1 {
	        limit = 10M;
	        worktime = A 08:00-21:00 S 08:00-21:00;
	    }
	}
.fi
.PP
Here the rule is active only at Saturday and Sunday and the limit
is active only from 08:00 till 21:00 at the same days. Since 08:00-21:00
time interval is a subset of 00:00-24:00 time interval, then everything
is correct in these two parameters.
.PP
\fBRestarting a not reached limit.\fP
.PP
The time when a new limit was created (or reached limit was restarted again)
is known as ``start time''. ipa(8) changes a limit's counter only while
a limit is not reached. It is possible to specify time when a not reached
limit should be restarted with zeroed (flushed) counter.
.PP
The \fBrestart\fP section allows to specify time when to restart a not
reached limit:
.PP
.nf
	limit <limit-name> {
	    /* Limit's parameters and sections. */
	    restart {
	        restart = <restart-time>;
	        /* Commands. */
	    }
	}
.fi
.PP
The \fBrestart\fP section must have at least the \fBrestart\fP parameter.
There are three methods for specifying this time. Let's see them in
following examples.
.PP
It is possible to specify optional commands which will be run, when not
reached limit is restarted.
.PP
ipa(8) also informs accounting systems used by limit's rule when
a not reached limit is restarted, so if you do not specify commands
in the \fBrestart\fP section, then some actions still can be performed by
accounting systems.
.PP
If a limit does not have the \fBrestart\fP section, then this limit
(if it is not reached) cannot be automatically restarted, but it can be
restarted by the ipactl(8) utility.
.PP
\fIExample 1:\fP
.PP
.nf
	rule my.traf {
	    ac_list = ipfw;
	    ipfw:rules = 100 200;
	    limit 1 {
	        limit = 1G;
	        restart {
	            restart = 20h 30m;
	        }
	    }
	}
.fi
.PP
Here the value of the \fBrestart\fP parameter is added to limit's
start time and calculated value is time when a limit should be restarted.
Here we can consider restart time as simply number of seconds from
limit's start time.
.PP
The `\fBs\fP' character means seconds, `\fBm\fP' minutes, `\fBh\fP' hours,
`\fBD\fP' days and `\fBW\fP' weeks.
.PP
\fIExample 2:\fP
.PP
.nf
	rule my.traf {
	    ac_list = ipfw;
	    ipfw:rules = 100 200;
	    limit 1 {
	        limit = 1G;
	        restart {
	            restart = +W;
	        }
	    }
	}
.fi
.PP
Here the limit will be restarted at the end of a week after limit's
start time. A character after the `\fB+\fP' sign means: `\fBm\fP' a
minute, `\fBh\fP' a hour, `\fBD\fP' a day, `\fBW\fP' a week, `\fBM\fP'
a month.
.PP
\fIExample 3:\fP
.PP
.nf
	rule my.traf {
	    ac_list = ipfw;
	    ipfw:rules = 100 200;
	    limit 1 {
	        limit = 1G;
	        restart {
	            restart = +M 2D;
	        }
	    }
	}
.fi
.PP
In this example the limit will be restarted on the third day of
the next month after limit's start time: the restart time for ``+M''
(start of the next month) is calculated and then ``2D'' (two days) are
added to the calculated value.
.PP
Note that ``2D\ +M'' is not the same: here ``2D'' is added to limit's
start time and then the restart time for ``+M'' is calculated (and we
always will get first day of some next month here).
.PP
\fBActions when a limit is reached.\fP
.PP
When a limit is reached, ipa(8) runs commands listed in the \fBreach\fP
section:
.PP
.nf
	limit <limit-name> {
	    /* Limit's parameters and sections. */
	    reach {
	        /* Commands. */
	    }
	}
.fi
.PP
The \fBreach\fP section can be absent or empty and no commands will be
run when a limit is reached.
.PP
ipa(8) also informs accounting systems used by limit's rule when a limit
becomes reached, so if you do not specify commands in the \fBreach\fP
section, then some actions still can be performed by accounting systems.
.PP
\fIExample:\fP
.PP
.nf
	rule my.traf {
	    ac_list = ipfw;
	    ipfw:rules = 100;
	    limit 1 {
	        limit = 1G;
	        restart {
	            restart = +W;
	        }
	        reach {
	            exec "/somewhere/stop_traffic";
	        }
	    }
	}
.fi
.PP
Here there is 1 Gbyte limit, which is restarted at the end of the week if
it is not reached, but if it becomes reached, then the given command is run.
.PP
\fBRestarting a reached limit.\fP
.PP
It is possible to restart a reached limit. To do this you should use the
\fBexpire\fP section:
.PP
.nf
	limit <limit-name> {
	    /* Limit's parameters and sections. */
	    expire {
	        expire = <restart-time>;
	        /* Commands. */
	    }
	}
.fi
.PP
The \fBexpire\fP section must have at least the \fBexpire\fP parameter.
.PP
It is possible to specify optional commands which will be run, when reached
limit is restarted.
.PP
ipa(8) also informs accounting systems used by limit's rule when a reached
limit is restarted, so if you do not specify commands in the \fBexpire\fP
section, then some actions still can be performed by accounting systems.
.PP
If a limit does not have the \fBexpire\fP section, then this limit
(if it is reached) cannot be automatically restarted, but it can
be restarted by the ipactl(8) utility.
.PP
The value of the \fBexpire\fP parameter can be 0s, this means that
reached limit will be restarted immediately.
.PP
\fIExample:\fP
.PP
.nf
	rule my.traf {
	    ac_list = ipfw;
	    ipfw:rules = 100;
	    limit 1 {
	        limit = 1G;
	        restart {
	            restart = +W;
	        }
	        reach {
	            exec "/somewhere/stop_traffic";
	        }
	        expire {
	            expire = +W;
	            exec "/somewhere/start_traffic";
	        }
	    }
	}
.fi
.PP
Here there is 1 Gbyte per week limit. If the limit is reached, then at
the begin of the week it will be restarted. If this limit is not reached,
then it is also restarted at the begin of the week.
.PP
\fBStartup and shutdown sections for a rule.\fP
.PP
Two sections were described above for running commands at startup and
shutdown. A rule can have these sections as well, but \fBstartup\fP and
\fBshutdown\fP section placed in the \fBrule\fP section can have extra
subsections:
.PP
\fBif_any_reached\fP\ \ \ \ \ \-\ if any of rule's limits is reached;
.br
\fBif_any_not_reached\fP\ \-\ if any of rule's limits is not reached;
.br
\fBif_all_reached\fP\ \ \ \ \ \-\ if all rule's limits are reached;
.br
\fBif_all_not_reached\fP\ \-\ if all of rule's limits are not reached.
.PP
These subsections determine commands, which should be run if limits
fit a subsection condition.
.PP
Any rule can have empty \fBstartup\fP or \fBshutdown\fP section, in this
case this section is not inherited from the matched \fBrulepat\fP section.
.PP
\fIExample:\fP
.PP
.nf
	rule my.traf {
	    ac_list = ipfw;
	    ipfw:rules = 100;
	    startup {
	        exec "/somewhere/count_traffic";
	        if_any_reached {
	            /* ... */
	            exec "/bin/echo \\"Some limit in rule ${rule} was \\
	reached\\" | mail admin";
	        }
	    }
	    limit 1 {
	        limit = 1G;
	        restart {
	            restart = +M;
	        }
	        info = "1G per month";
	        /* ... */
	    }
	    limit 2 {
	        limit = 500M;
	        restart {
	            restart = +W;
	        }
	        info = "500M per week";
	        /* ... */
	    }
	}
.fi
.PP
Here there are two limits: 1 Gbyte per month and 500 Mbytes per week, the
\fBif_any_reached\fP section will be used if any of these two limits
is reached at the moment of the start of ipa(8).
Also rule's \fBstartup\fP section has one command that is always run at
startup.
Here we use one back-slash character for splitting a command string.
.PP
\fBStartup and shutdown sections for a limit.\fP
.PP
A \fBlimit\fP section also can have own \fBstartup\fP and \fBshutdown\fP
sections with following extra subsections:
.PP
\fBif_reached\fP\ \ \ \ \ \-\ if a limit is reached;
.br
\fBif_not_reached\fP\ \-\ if a limit is not reached.
.PP
These subsections determine commands, which should be run if a limit
fits a subsection condition.
.PP
ipa(8) also informs accounting systems used by limit's rule at startup
and shutdown if a limit is reached or is not reached, so if you do not
specify startup and/or shutdown commands for a limit, then some actions
still can be performed by accounting systems.
.PP
\fBUsing separate databases for limits.\fP
.PP
There is the \fBdb_list\fP parameter, which determines a list of databases
used by a rule. By default a limit uses the same list of databases as its
rule (it inherits this list). But it is possible to use the \fBdb_list\fP
parameter in the \fBlimit\fP section:
.PP
.nf
	rule <rule-name> {
	    /* Rule's parameters and sections. */
	    db_list <list1>;
	    limit <limit-name> {
	        /* Limit's parameters and sections. */
	        db_list <list2>;
	    }
	}
.fi
.PP
<List1> and <list2> can contain common elements, in any case <list1>
is used only for a rule and <list2> is used only for a limit.
.PP
Why to use separate database lists for a rule and its limit? Not all
databases work with limits and even if some database works with
limits, it can support not all functions (methods) for limits. See
implementation details in the ipa_mod(3) manual page.
.PP
Suppose some limit uses several databases. From which database
will ipa(8) get current limit state? The first database, which is able
to return a limit's state, will be asked for the current limit's state,
even if some other database has another limit's state, it will not
be asked for it and its limit's state will be lost, then ipa(8)
will update the current limit's state in each database.
.PP
Note that the order of databases for a limit is important.
.PP
Read in the database module's documentation you use information,
if it can work with limits and what exactly a module supports when
it works with limits.
.PP
\fBUsing the value of the limit parameter from the database.\fP
.PP
Sometimes it is necessary to keep the value of the \fBlimit\fP parameter
in the database and change this value in the database, so there should
be a way to tell ipa(8) to use the value of the \fBlimit\fP parameter
from the database. The \fBload_limit\fP parameter was implemented for
this purpose:
.PP
.nf
	limit <limit-name> {
	    /* Limit's parameters and sections. */
	    load_limit = <boolean>;
	}
.fi
.PP
If you want to load the value of the \fBlimit\fP parameters from the
database, then set the value of the \fBload_limit\fP parameter to ``yes''.
If the database does not have current state of a limit (for example if a
limit is new), then the value of the \fBlimit\fP parameter from the
configuration file will be used, that's why the \fBlimit\fP parameter
always must be specified.
.PP
By default the value of the \fBload_limit\fP parameter is ``no''.
.PP
One of possible cases why one wants to set this parameter to ``yes'' is
the usage of the ipactl(8) utility for changing the value of the
\fBlimit\fP parameter on-the-fly.
.PP
This parameter can be specified in the \fBglobal\fP section, if some
\fBlimit\fP section does not have this parameter, then its value will
be set from the \fBglobal\fP section.
.PP
\fBLimits initialization.\fP
.PP
When ipa(8) starts, rereads the configuration file or does reinitialization
when some time related problems occurred, it performs following steps for
an arbitrary limit:
.IP 1.
The current limit's state is read from the database, if the database does
not have the limit's state, then a new limit's state is registered with
the value of the \fBlimit\fP parameter from the configuration file and
with zero counter, and initialization of the limit is complete, else ipa(8)
does second step (2a or 2b).
.IP 2a.
If the limit is not reached with the current state from the database,
then if the value of the \fBload_limit\fP parameter is ``no'', then ipa(8)
updates the value of the \fBlimit\fP parameter from the configuration
file; if the value of the \fBload_limit\fP parameter is ``yes'', then
ipa(8) ignores the value of the \fBlimit\fP parameter from the configuration
file and gets this value from the database. In any case the limit is marked
as not reached, even if with new settings it becomes reached. Then ipa(8)
updates date when the limit should be restarted accordingly to the value of
the \fBrestart\fP parameter from the configuration file, ignoring this date
from the database.
.IP 2b.
If the limit is reached, then ipa(8) marks this limit as reached and
does not update the value of the \fBlimit\fP parameter in the database
(that is it does not honor the value of the \fBload_limit\fP parameter
at this moment and this can be seen in the output for the ipactl(8)'s
command \fIstatus\fP for this limit). Then ipa(8) updates date when the
limit will expire accordingly to the value of the \fBexpire\fP parameter
from the configuration file, ignoring this date from the database.
.PP
\fBLimits: about limit's events again.\fP
.PP
To help understand how exactly an arbitrary limit works, let's
write the time diagram of its states:
.PP
.nf
                 +--------------+--> Restart (Tstart)
                 |              |
                 Trestart_exec  Treach_exec    Texpire_exec
--|------>------||------>------||------>------||------------->
  Tstart      Trestart         Treach       Texpire       time
.fi
.PP
\fBSublimits.\fP
.PP
A sublimit is a part of some limit. The main purpose of a sublimit is
to register an event when some part of the \fBlimit\fP parameter's
value is reached. Since a sublimit is a part of some \fBlimit\fP
section, then the value of a sublimit must be given in the same
units as the value of the \fBlimit\fP parameter. To simplify specifying
of sublimits it is possible to give the value of any sublimit in
per cent, that is some per cent of the \fBlimit\fP parameter's value:
.PP
.nf
	limit <limit-name> {
	    limit = <limit-value>;
	    /* Limit's parameters and sections. */
	    sublimit <sublimit-value> {
	        /* Sublimit's sections. */
	    }
	}
.fi
.PP
Sublimits can contain only \fBreach\fP, \fBstartup\fP and \fBshutdown\fP
sections. All these sections has the same format and mean the same as
for limits. ipa(8) does not inform accounting systems about sublimits'
events, just because sublimits are invisible for modules.
.PP
A limit can have several not duplicated (different <sublimit-values>)
sublimits.
.PP
Since sublimits states are not kept in the database, then it is always
better to use sublimits than adding extra limits to some rule if possible.
.PP
\fIExample:\fP
.PP
.nf
	rule my.traf {
	    /* ... */
	    limit l1 {
	        limit = 1G;
	        load_limit = yes;
	        restart {
	            restart = +M;
	        }
	        info = "${rule}, ${limit} per month";
	        /* ... */
	        sublimit 50% {
	            reach {
	                exec "/bin/echo \\"half of ${rule}'s limit \\
	${limit} reached\\" | mail me";
	            }
	        }
	    }
	}
.fi
.PP
Here there is the sublimit which will send an email when half of the l1
limit is reached. Even if the value of the \fBlimit\fP parameter will
be changed by the ipactl(8) utility, sublimit's value will be adjusted,
because it is given in per cent.
.PP
\fBThresholds: introduction.\fP
.PP
Thresholds allow to monitor rule's statistics for some time period before
current time and do some actions when statistics for this time period is
less than, equal to or greater than the given value. This time period
also can be called ``sliding time window''. A threshold is described by
the \fBthreshold\fP section with following format:
.PP
.nf
	threshold <threshold-name> {
	    threshold = <threshold-value>;
	    threshold_time_width = <time>;
	    threshold_time_slice = <time>;
	    /* Other threshold's parameters and sections. */
	}
.fi
.PP
You should give such names for thresholds, which are also valid thresholds
names for databases you use.
.PP
Any threshold has 64-bit unsigned counter which is changed by ipa(8)
and which is compared with the value of the \fBthreshold\fP parameter.
If the counter's value becomes less than, equal to or greater than the
value of the \fBthreshold\fP parameter, then commands from the optional
\fBbelow_threshold\fP, \fBequal_threshold\fP or \fBabove_threshold\fP
section are run. A threshold's counter is changed synchronously with
a rule's counter each \fBthreshold_time_slice\fP time interval.
.PP
ipa(8) knows nothing about units of statistics, so it is possible
to use different formats of <threshold\-value>: bytes, time and unsigned
64-bit integer. <Threshold\-value> always is converted to unsigned
64-bit integer.
.PP
It is possible to specify a deviation of <threshold-value> with
the help of the \fBthreshold_deviation\fP parameter. The value of
the \fBthreshold_deviation\fP parameter must be given in the same
units as the value of the \fBthreshold\fP parameter. To simplify
specifying of a threshold deviation it is possible to give its value
in per cent, that is some per cent of the \fBthreshold\fP parameter's
value.
.PP
The value of the \fBthreshold_time_width\fP parameter determines the
width of sliding time window. The value of the \fBthreshold_time_slice\fP
parameter determines time intervals of sliding time window movement.
The \fBthreshold_time_width\fP parameter's value must be greater than
the \fBthreshold_time_slice\fP parameter's value, and must be divisible
on this value. In other words, a threshold's counter represents a
snapshot of rule's statistics for last \fBthreshold_time_width\fP
seconds. Unlike limits thresholds do not have ``start time'', because
their statistics is sliding in time in discrete time intervals
equal to \fBthreshold_time_slice\fP seconds. These two parameters
can be specified in the \fBglobal\fP section and they will be used
if some \fBthreshold\fP section does not have them.
.PP
Thresholds have names, hence it is possible to use several thresholds
in one rule and they are distinguished by names.
.PP
Accounting systems used by threshold's rule are notified about
threshold's events, so accounting systems also can do some actions
when the value of a threshold's counter is less, equal or greater
than the \fBthreshold\fP parameter's value.
.PP
It is possible to limit number of times commands are run and accounting
systems are informed from \fBbelow_threshold\fP (X), \fBequal_threshold\fP
(Y) and \fBabove_threshold\fP (Z) sections in the \fBthreshold_balance\fP
parameter:
.PP
.nf
	threshold_balance = X:Y:Z;
.fi
.PP
This parameter can be specified in the \fBglobal\fP section and
if some \fBthreshold\fP section does not have it, then its value
will be inherited from the \fBglobal\fP section.
.PP
There are three internal counters x, y and z, which count how many
times commands were run and accounting systems were informed from
\fBbelow_threshold\fP, \fBequal_threshold\fP and \fBabove_threshold\fP
sections consecutively. These counters initially are equal to X, Y and
Z respectively. When threshold's counter is below than the value of
the \fBthreshold\fP parameter and x is not equal to zero, then it is
decremented, y is set to Y and z is set to Z, then commands from
the \fBbelow_threshold\fP section are run and accounting systems
are informed about threshold's event. The same for y and z counters.
.PP
To unlimit value of X, Y or Z, specify it as `\fB\-\fP'. In implementation
infinitive value really is equal to UINT_MAX. By default the value of
this parameter is \-:\-:\-.
.PP
\fIExample:\fP
.PP
.nf
	rule lan {
	    ac_list = ipfw;
	    ipfw:rules = 100 200 -300;
	    update_time = 1m;
	    limit l1 {
	        limit = 1G;
	        info = "Control each 1G of bandwidth usage";
	        reach {
	            exec "/bin/echo \\"1G of ${rule} reached\\" | mail me";
	        }
	        expire {
	            expire = 0s;
	        }
	    }
	    threshold t1 {
	        threshold = 500M;
	        threshold_balance = 1:-:1;
	        threshold_deviation = 50M;
	        threshold_time_width = 24h;
	        threshold_time_slice = 15m;
	        info = "500M plus-minus 50M threshold per 24h";
	        below_threshold {
	            exec "/somewhere/increase_bandwidth ${rule}";
	        }
	        above_threshold {
	            exec "/somewhere/decrease_bandwidth ${rule}";
	        }
	    }
	}
.fi
.PP
Here the rule has one threshold and one limit.
.PP
The threshold allows to dynamically control bandwidth in 500 Mbytes
plus-minus 50 Mbytes (we increase speed by some increase_bandwidth program
and decrease speed by some decrease_bandwidth program) per 24 hours
(this is one day, but not a week day, here 24 hours mean time interval).
Time slice is 15 minutes, note that the threshold will not be checked
every minute here (the value of the \fBupdate_time\fP parameter for
this rule).
.PP
Statistics for the rule and the limit will be updated every minute. The
limit allows to send an email when next 1 Gbyte of bandwidth has been used.
.PP
\fBActive and inactive thresholds.\fP
.PP
Thresholds like limits can be active and inactive and can have own
\fBworktime\fP parameter. So, for more information read appropriate
paragraph for limits.
.PP
What is the value of the threshold's counter when a threshold was inactive
and becomes active due to the \fBworktime\fP parameter's value? One
solution is to allow a threshold's time window to slide during time
interval of inactivity, another solution is to ``move'' a threshold's
time window over time interval of inactivity. In the first solution
statistics for the threshold's counter during time interval of inactivity
is 0 and the value of the threshold's counter is decreased. In the second
solution statistics during time interval of inactivity is ignored (it is
skipped) and the value of the threshold's counter is not changed.
.PP
What is the value of the threshold's counter when ipa(8) starts working
and there is a state of a threshold in the database? There are also two
solutions for this situation as for previous question.
.PP
It is possible to select solutions for above described situations with
the help of the \fBthreshold_type\fP parameter, its value is equal to
ORed bits (given as hexadecimal values):
.IP 0x1
jump over time interval, when ipa(8) did not run (was stopped);
.IP 0x2
jump over time interval, when a threshold was inactive.
.PP
By default the \fBthreshold_type\fP parameter's value is equal to 0.
Possible values of this parameter are: 0, 1, 2 and 3 (0x1|0x2).
Normal values for this parameter are 0 or 3, values with only one bit
set should be used with care, since when a threshold is initialized, it
is treated as active (read the paragraph about thresholds initialization).
.PP
This parameter can be specified in the \fBglobal\fP section and
if some \fBthreshold\fP section does not have it, then its value
will be inherited from the \fBglobal\fP section.
.PP
\fIExample:\fP
.PP
.nf
	rule client {
	    ac_list = ipfw;
	    ipfw:rules = 100 200 300;
	    update_time = 1m;
	    threshold t {
	        threshold = 100M;
	        threshold_deviation = 10%;
	        threshold_time_width = 5h;
	        threshold_time_slice = 15m;
	        threshold_type = 3;
	        worktime = M 08:00-21:00 T 08:00-21:00 W 08:00-21:00
	                   H 08:00-21:00 F 08:00-21:00;
	        info = "100M plus-minus 10% threshold per 5h (type 3)";
	        below_threshold {
	            exec "/somewhere/increase_bandwidth ${rule}";
	        }
	        above_threshold {
	            exec "/somewhere/decrease_bandwidth ${rule}";
	        }
	    }
	}
.fi
.PP
Suppose that the given rule is for one client which has access to Internet
each work day from 08:00 to 21:00. We allow him 100 Mbytes plus-minus 10%
per 5 hours speed (we increase speed by some increase_bandwidth program
and decrease speed by some decrease_bandwidth program).
.PP
Suppose that current counter's value of the threshold is 90 Mbytes at 21:00.
When 08:00 of the next day comes, by default current counter's value of the
threshold becomes 0 Mbyte, because there is at least one time interval in
5 hours between 21:00 and 08:00 of the next day. Here we use threshold
type 3 and time window will ``jump'' from 21:00 to 08:00 and current
counter's value of the threshold will be unchanged, that is 90 Mbytes at
08:00 of the next day. We also can stop ipa(8) at 21:00 and run it again
at 08:00 and a threshold's time window will also ``jump'' from 21:00 to
08:00.
.PP
If there are several clients with the same settings, then at 08:00 non of
them will be able to intensively start to use own part of common bandwidth.
.PP
\fBUsing the value of the threshold parameter from the database.\fP
.PP
A threshold likes a limit can have \fBload_threshold\fP parameter,
which means the same and is used for the same purpose. So, read
appropriate paragraph for limits for more information.
.PP
\fBStartup and shutdown sections for a threshold.\fP
.PP
An arbitrary threshold can have own \fBstartup\fP and \fBshutdown\fP
sections, which can contain only lists of commands.
.PP
\fBUsing separate databases for thresholds.\fP
.PP
Like limits, it is possible to use the \fBdb_list\fP parameter in the
\fBthreshold\fP section and have different lists of databases for a rule
and its threshold.
.PP
\fBThresholds initialization.\fP
.PP
Unlike limits, initialization of thresholds is very simple, since
thresholds cannot be reached or not reached: ipa(8) gets current state
of a threshold from the first database, which is able to return a
threshold's state, if this database does not have a threshold's state,
then a new state is registered with the value of the \fBthreshold\fP
parameter from the configuration file, else ipa(8) honors values of
\fBload_threshold\fP and \fBthreshold_type\fP parameters and updates
threshold's state. Note that when a threshold is initialized it is
assumed as active, even if its \fBworktime\fP parameter marks this
threshold as inactive. Since threshold's statistics slices are not saved
in the database, valid statistics slices are initialized approximately,
according to the current local time, threshold's timestamps and its
counter value.
.PP
\fBThresholds: about thresholds again.\fP
.PP
To help understand how exactly an arbitrary threshold works, let's
write the time diagram:
.PP
.nf
     <-------------- time_width ------------->

(t1) |---c1--|---c2--|---c3--|---c4--|---c5--| --> sliding

(t2)         |---c2--|---c3--|---c4--|---c5--|---c6--| --> sliding

     <-slice->
-----|-------|-------|-------|-------|-------|-------|-------|-->
     t1      t2                                                time
.fi
.PP
On this diagram we see threshold's statistics at time \fIt1\fP and at
\fIt2\fP. All statistics is represented as a sum of \fIci\fP, each \fIci\fP
of statistics is equal to statistics of a rule during one time slice
\fIt2\ \-\ t1\fP. A threshold slides in time discretely and its statistics
is a snapshot of rule's statistics for last \fItime_width\fP seconds.
.PP
\fBDynamic rules and autorules.\fP
.PP
Dynamic rules are generated from autorules by specially designed
accounting modules on-the-fly. Internally in ipa(8) static and dynamic
rules are almost indistinguishable and any parameter (except the
\fBac_gather_*\fP parameters) and section (including \fBlimit\fP and
\fBthreshold\fP sections) in static rules can be used in dynamic rules.
.PP
An autorule is described by the \fBautorule\fP section:
.PP
.nf
	autorule <autorule-name> {
	    /* Parameters and sections. */
	}
.fi
.PP
<Autorule-name> it is not stored in the database, but an accounting module
can use this name for generating names of dynamic rules, so use the same
restrictions as for <rule-name> for the database you use.
.PP
A dynamic rule is looks like a static rule. There are only two
restrictions for autorules (hence for dynamic rules): an autorule
can have only one accounting system in the \fBac_list\fP parameter's
value and an autorule cannot have \fBac_gather_*\fP parameters.
.PP
The configuration file can have several autorules at once. Any autorule
usually have at least the \fBac_list\fP parameter with one element in its
value. (It is possible to implement support for several accounting systems
for one autorule, but it is senseless.) This one element in the \fBac_list\fP
parameter's value determines accounting system, which can create and delete
dynamic rules. Every time when this accounting system is asked for new
statistics (the \fIac_get_stat\fP function in ipa_mod(3)), it has a
chance to create and/or delete (previously created) dynamic rules. The
value of the \fBupdate_time\fP parameter determines the time interval of
\fIac_get_stat\fP function invocations (this function can be called
more often).
.PP
If you want to use some database for dynamic rules, then this
database should support dynamic rules.
.PP
If an autorule has the \fBworktime\fP parameter, then this parameter
is used by an autorule. Dynamic rules generated from this autorule
inherit autorule's \fBworktime_rule\fP parameter as their \fBworktime\fP
parameter. If an autorule does not have the \fBworktime\fP parameter,
then it inherits this parameter from the \fBglobal\fP section.
.PP
Since an autorule and its dynamic rules can use different \fBworktime\fP
parameters, it is possible to have inactive autorule and active
dynamic rules and vice versa.
.PP
A dynamic rule inherits parameters and sections from its autorule, if
some parameters and sections are still undefined, then they are
inherited from the matched \fBrulepat\fP section, then from the
\fBglobal\fP section and then default settings are used.
.PP
If an autorule has \fBstartup\fP and \fBshutdown\fP sections, then these
sections are for dynamic rules, not for an autorule itself. If you wish
to use the name of some dynamic rule in some command line, then
you cannot use the ${rule} macro variable, because it is expanded
by the internal configuration file parser, instead use command line
substitutions (see above).
.PP
Any autorule can have empty \fBstartup\fP or \fBshutdown\fP section,
in this case this section is not inherited from matched \fBrulepat\fP
section for its dynamic rules.
.PP
If you need different limits or thresholds for dynamic rules created
from the same autorule, then specify these limits and thresholds in
different \fBrulepat\fP sections.
.PP
\fIExample:\fP
.PP
.nf
	ac_mod "ipa_atest.so";
	db_mod "ipa_db_sdb.so";

	global {
	    db_list = sdb;
	    append_time = 1h;
	}

	autorule a {
	    ac_list = atest;
	    update_time = 1m;
	    limit 1 {
	        limit = 100M;
	        restart {
	            restart = +W;
	        }
	        reach {
	            exec "/somewhere/stop_traffic.sh %rule%";
	            exec "/bin/echo \\"%rule%'s limit ${limit} reached\\" |
	                mail admin";
	        }
	        expire {
	            expire = +M;
	            exec "/somewhere/start_traffic.sh %rule%";
	        }
	    }
	}
.fi
.PP
Here each dynamic rule generated from the autorule will inherit
autorule's \fBupdate_time\fP parameter and like static rules each
dynamic rule will inherit \fBdb_list\fP and \fBappend_time\fP
parameters from the \fBglobal\fP section. Each dynamic rule will have
one limit, since we cannot use the ${rule} macro variable in dynamic
rules (actually in autorules), then %rule% substitution is used. Using
the ${limit} macro variable in a limit in an autorule is correct, since
limit's name is know for the configuration file parser.
.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, dynamic rules
can inherit common settings from their autorules. 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 can inherit this parameter or section from the matched rule
pattern. Rules patterns are defined in the \fBrulepat\fP sections:
.PP
.nf
	rulepat "<regexp>" {
	    /* Parameters and sections. */
	}
.fi
.PP
Each rule pattern is named by POSIX extended regular expression. Having
parsed the configuration file, ipa(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, ipa(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 = <boolean>;
.fi
.PP
This parameter can be used only in the \fBrulepat\fP section, and its
default value is ``no''.
.PP
Any parameter (except \fBac_gather_*\fP parameters) 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
	ac_mod "ipa_ipfw.so";
	db_mod "ipa_db_sdb.so";

	global {
	    ac_list = ipfw;
	    db_list = sdb;
	    update_time = 1m;
	    load_limit = yes;
	    sdb:db_group = staff;
	}

	rulepat "0${$}" {
	    check_next_rulepat = yes;
	    update_time = 30s;
	    threshold 1 {
	        threshold = 1G;
	        threshold_deviation = 10%;
	        threshold_time_width = 10h;
	        threshold_time_slice = 5m;
	        below_threshold {
	            exec "/somewhere/increase-bandwidth.sh %rule%";
	        }
	        above_threshold {
	            exec "/somewhere/decrease-bandwidth.sh %rule%";
	        }
	    }
	}

	rulepat "^client" {
	    worktime = M 08:00-20:00 T 08:00-20:00 W 08:00-20:00
	               H 08:00-20:00 F 08:00-20:00 A 08:00-17:00;
	}
.fi
.PP
Here first \fBrulepat\fP section ``catches'' all rules with zero at the
end of their names (macro variable ${$} is expanded to single character `$',
and `$' at the end of POSIX regular expression means the end of the string).
Since the value of its \fBcheck_next_rulepat\fP is ``yes'' then next
rule pattern is checked. Second \fBrulepat\fP section ``catches'' all
rules with ``client'' substring at the beginning of their names.
.PP
\fBGathering statistics from several rules.\fP
.PP
Usually each rule gets statistics from accounting modules, but sometimes
it is necessary to summarize statistics from several rules and it is
impossible or too expensive give this task to accounting modules.
.PP
The \fBac_gather_add\fP and \fBac_gather_sub\fP parameter allow to
get statistics for one rule from several rules and add or subtract
this statistics:
.PP
.nf
	rule <rule-name> {
	    /* Rule's parameters and sections. */
	    ac_gather_add = "<regexp>";
	    ac_gahter_sub = "<regexp>";
	}
.fi
.PP
Here <regexp> is a POSIX extended regular expression, if some rule's name
matches this regular expression, then its statistics is gathered by a rule
in which the \fBac_gather_*\fP parameters are specified. Note that this
parameter also works with dynamic rules. It is also possible to make complex
dependencies in this parameter (see an example).
.PP
This parameter should be placed in the \fBrule\fP section, that is it
can be used only with static rules, but can gather statistics from
static and dynamic rules.
.PP
The \fBac_list\fP is a synchronous parameter in respect to the \fBrule\fP
section: when some rule is updated, statistics is fetched from each
accounting system a rule uses. \fBac_gather_*\fP are asynchronous
parameters in respect to the \fBrule\fP section: current rule gets
statistics from a rule matched \fBac_gather_*\fP parameters' regular
expressions when this matched rule is updated.
.PP
A rule which has \fBac_gather_*\fP parameters can also have the
\fBac_list\fP parameter.
.PP
\fIExample:\fP
.PP
.nf
	ac_mod "ipa_ipfw.so";

	global {
	    ac_list = ipfw;
	}

	rule client1 {
	    ipfw:rules = 100 102 104;
	    info = "Statistics for first client";
	}

	rule client2 {
	    ipfw:rules = 200 202 204;
	    info = "Statistics for second client";
	    /* ac_gather_add = "^clients${$}"; <-- WRONG! */
	}

	rule clients {
	    ac_gather_add = "^client[[:digit:]]+${$}";
	    info = "Statistics for all clients";
	}

	rule server {
	    ipfw:rules = 1000 1002;
	    info = "Statistics for server";
	}

	rule all_stat {
	    ac_gather_add = "^(server|clients)${$}";
	    info = "Statistics for all in my LAN";
	}

	rule all_except_client2_stat {
	    ac_gather_add = "^all_stat${$}";
	    ac_gather_sub = "^client2${$}";
	    info = "Statistics for all in my LAN except client2";
	}
.fi
.PP
Here we have six static rules: client1, client2, clients, server,
all_stat and all_except_client2_stat. The rule clients gets statistics
from client1 and client2 rules. The rule all_stat gets statistics from
clients and server rules.
And the rule all_except_client2_stat gets statistics from rules
clients and server not including statistics from rule client2.
.PP
The client2 rule has incorrectly used the \fBac_gather_add\fP parameter
in a comment, if this parameter exists in this rule, then we will
get a cycle in rules dependencies: client2->clients->client2... ipa(8)
does not check cycles in rules dependencies.
.PP
\fBUsing ipactl(8) program.\fP
.PP
The ipactl(8) program allows to send control commands to ipa(8) via an
Unix domain socket. Before using this program you should allow to use it
by setting the value of the \fBctl_enable\fP parameter to ``yes'',
by default the value of this parameter value is ``no'':
.PP
.nf
	ctl_enable = <boolean>;
.fi
.PP
If the value of this parameter is ``yes'', then ipa(8) creates an Unix
domain socket and listens for commands on it. The created Unix domain
socket is owned by the user who run ipa(8), access permissions for
the socket are defined by the value of the \fBctl_socket_perm\fP
parameter.
.PP
There is the default path to this Unix domain socket (see the output of
the ``ipactl\ \-h'' command), but you can define the Unix domain socket
pathname in the \fBctl_socket_path\fP parameter:
.PP
.nf
	ctl_socket_path = "/path/to/socket";
.fi
.PP
By default ipa(8) waits for data from the socket during 10 seconds,
you can change this timeout in the \fBctl_timeout\fP parameter:
.PP
.nf
	ctl_timeout = <time>;
.fi
.PP
You can define access permissions to the socket in the
\fBctl_socket_perm\fP parameter:
.PP
.nf
	ctl_socket_perm = <permissions>;
.fi
.PP
<Permissions> is a sequence of characters `\fBu\fP', `\fBg\fP' and `\fBo\fP'.
These characters determine who (user, group or others) is allowed
to write to the socket. You can allow other users to write to the
socket only if ipa(8) understands following parameters. If this parameter
is not given, then its default value is ``u''.
.PP
ipa(8) run under FreeBSD is able to check ipactl(8)'s messages credentials
(check this in the output of the ``ipa\ \-v'' command), so on this system
you also have to define \fBctl_acl_class\fP, \fBctl_dump_acl\fP,
\fBctl_freeze_acl\fP, \fBctl_stat_acl\fP and \fBctl_rule_acl\fP parameters.
.PP
The \fBctl_acl_class\fP parameter defines class of ACL (access control list):
the name of ACL followed by ACL definition. This parameter should not be
placed in any section:
.PP
.nf
	ctl_acl_class <class> [<ACL>];
.fi
.PP
ACL consists of elements separated by space characters, each its
element has following format:
.PP
.nf
	[!]<user>|%<group>
.fi
.PP
The `\fB!\fP' character means that access is denied.
The `\fB%\fP' character means that the following name is a group name.
<User> and <group> must be given as symbolic names (UID and GID do
not work here).
Elements in ACL are checked from the left to the right.
Here ``access denied'' means that the user is not allowed to use some
control command.
When a control message arrives, ipa(8) translates user name or groups
name of each ACL to UID or GID and compares it with a message's sender
credentials.
.PP
The \fBctl_dump_acl\fP parameter applies ACL for ipactl(8)'s command
\fIdump\fP:
.PP
.nf
	ctl_dump_acl <class>;
.fi
.PP
The \fBctl_freeze_acl\fP parameter applies ACL for ipactl(8)'s command
\fIfreeze\fP:
.PP
.nf
	ctl_freeze_acl <class>;
.fi
.PP
The \fBctl_stat_acl\fP parameter applies ACL for ipactl(8)'s
commands \fIstatus\fP and \fImemory\fP:
.PP
.nf
	ctl_stat_acl <class>;
.fi
.PP
The \fBctl_rule_acl\fP parameter applies ACL to a rule for
ipactl(8)'s \fIexpire\fP, \fIrestart\fP, \fIset\fP and \fIstatus\fP
commands:
.PP
.nf
	ctl_rule_acl <class>;
.fi
.PP
If ACL is not defined and it is not inherited, then it is considered
as empty ACL, and means that access is denied for anybody.
.PP
Let's show how to use all these parameters in examples.
.PP
\fIExample 1:\fP
.PP
.nf
	ctl_enable = yes;
	ctl_socket_perm = ug;
.fi
.PP
In this example ipa(8) does not know how to get ipactl(8)'s control messages
credentials. We allow user and group to write commands to the socket
(this is controlled by access permissions of the socket). It is impossible
to allow other users to write to the socket for security reasons.
.PP
\fIExample 2:\fP
.PP
.nf
	ctl_enable = yes;
	ctl_socket_path = "/var/tmp/ipactl.sock";
	ctl_timeout = 10s;
.fi
.PP
Here we change Unix domain socket path and timeout. The \fBctl_socket_perm\fP
parameter is not used, so its default value ``u'' will be used.
.PP
\fIExample 3:\fP
.PP
.nf
	ctl_enable = yes;
	ctl_socket_perm = ugo;
	ctl_acl_class empty;
	ctl_acl_class root   root;
	ctl_acl_class admins root !john %wheel;

	ctl_dump_acl root;

	global {
	    ctl_rule_acl admins;
	    /* ... */
	}

	rulepat "^vip" {
	    ctl_rule_acl root;
	    /* ... */
	}

	rulepat "^staff" {
	    ctl_rule_acl admins;
	    /* ... */
	}

	rule lan-all {
	    ctl_rule_acl empty;
	    /* ... */
	}
.fi
.PP
In this example ipa(8) knows how to get ipactl(8)'s control messages
credentials, so we have to use \fBctl_acl_class\fP, \fBctl_dump_acl\fP
and \fBctl_rule_acl\fP parameters, also we are able to allow to write
to the socket others users in the \fBctl_socket_perm\fP parameter.
Three ACL classes are defined: empty, root, admins.
.PP
\fBFreezing work of ipa(8).\fP
.PP
It is sometime necessary to be sure that ipa(8) does nothing during
some period of time. There are two parameters which allow to
freeze work of ipa(8).
.PP
First parameter \fBsleep_after_dump\fP allows to specify period of time
during which ipa(8) should sleep and ignore any signals after execution
of the \fIdump\fP command from ipactl(8).
.PP
Second parameter \fBfreeze_time\fP allows to specify period of time
during which ipa(8) should sleep and ignore any signals after receiving
the \fIfreeze\fP command from ipactl(8).
.PP
.nf
	freeze_time = <time>;
	sleep_after_dump = <time>;
.fi
.PP
Values of these parameter should not be relatively big, because there
is a chance that some time event can be checked too late.
.PP
The \fBsleep_after_dump\fP and \fBfreeze_time\fP parameters do not have
default values.
.PP
These parameters should not be placed in any section.
.PP
\fIExample:\fP
.PP
.nf
	freeze_time = 30s;
	sleep_after_dump = 5s;
.fi
.PP
Here we say ipa(8) to sleep 5 seconds after the \fIdump\fP command,
and sleep 30 seconds after the \fIfreeze\fP command. This is a very common
case: we send the \fIdump\fP command, for example, if we want to fetch
current statistics later, and we send the \fIfreeze\fP command to freeze
work of ipa(8) and change something in the system. Here we assume that
30 seconds will be enough to make all necessary changes in the system.
.PP
\fBOrder of active rules.\fP
.PP
ipa(8) checks rules starting from the head of the active rules queue.
If all rules are independent, then you should not worry about their
order, but if, for example rule r1 should be checked before rule r2,
then read following several paragraphs.
.PP
If there is not any \fBac_gather_*\fP parameters and there is not any
\fBworktime\fP parameters, then the order of active rules is the same
as the order of rules in the configuration file.
.PP
If there is at least one \fBac_gather_*\fP parameter, then the order
of rules is changed to follow dependencies specified in \fBac_gather_*\fP
parameters, but if some rules do not match regular expressions
given in \fBac_gather_*\fP parameters, then their relative order is
the same as their relative order in the configuration file.
.PP
If there is not any \fBac_gather_*\fP parameters and there are rules
with \fBworktime\fP parameters, then the order of these rules can be
changed.
.PP
Dynamic rules always are added to the head of the active rules
queue, because dynamic rules cannot have \fBac_gather_*\fP
parameters, but some static rule can get statistics from dynamic
rules.
.PP
If you wish to keep the order of active rules the same as the order
of rules in the configuration file, then set the \fBkeep_rules_order\fP
parameter to ``yes'', by default the value of this parameter is ``no'':
.PP
.nf
	keep_rules_order = <boolean>;
.fi
.PP
Be careful with the order of rules in the configuration file if you have
at least one \fBac_gather_*\fP parameter and the \fBkeep_rules_order\fP
parameter is set to ``yes'': place rules which give statistics below
rules, which get statistics.
.PP
Limits and thresholds in one rule are checked in the same order,
as they are written in the configuration and this order is not changed.
.PP
Note that some modules are sensitive to the order of active rules.
.PP
This parameter should not be placed in any section.
.PP
\fIExample:\fP
.PP
.nf
	keep_rules_order = yes;
.fi
.PP
Now ipa(8) will not change the order of active rules.
.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 ipa(8):

\fBdebug_ac_null\fP\ \ \ \ \-\ report about usage of \fInull\fP
accounting system (alone, 1);
.br
\fBdebug_db_null\fP\ \ \ \ \-\ report about usage of \fInull\fP
database (alone, 1);
.br
\fBdebug_time\fP\ \ \ \ \ \ \ \-\ debug various time related events (alone, 2);
.br
\fBdebug_worktime\fP\ \ \ \-\ debug \fBworktime\fP parameters (alone, 1);
.br
\fBdebug_exec\fP\ \ \ \ \ \ \ \-\ debug \fBexec\fP parameters (rule, 1);
.br
\fBdebug_autorule\fP\ \ \ \-\ debug autorules (alone, 1);
.br
\fBdebug_limit\fP\ \ \ \ \ \ \-\ debug limit related events (rule, 1);
.br
\fBdebug_limit_init\fP\ \-\ give more information about limits
initialization (rule, 1);
.br
\fBdebug_threshold\fP\ \ \-\ debug threshold related events (rule, 1);
.br
\fBdebug_threshold_init\fP\ \-\ give more information about thresholds
initialization (rule, 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, if there is a word ``rule'' in parenthesis, then
a parameter can be placed in \fBglobal\fP, \fBrule\fP, \fBrulepat\fP
and \fBautorule\fP sections.
.PP
By default debugging is off for everything.
.PP
\fIExample:\fP
.PP
.nf
	debug_worktime = 1;

	global {
	    debug_limit_init = 1;
	}
.fi
.PP
In this example detail information will be sent to the log file about
\fBworktime\fP's time intervals and about limits initialization for all
rules.
.SH FILES
ipa.conf
.PP
(run ipa(8) with the \fB-h\fP switch and check default configuration file
pathname)
.SH SEE ALSO
ipa(8), ipactl(8), ipastat(8), ipastat.conf(5), ipa_mod(3)
.SH AUTHOR
Andrey\ Simonenko\ <simon@comsys.ntu-kpi.kiev.ua>
.SH BUGS
If you find any, please send email me.