IPACTL(8) IPACTL(8)
NAME
ipactl -- control utility for ipa(8)
SYNOPSIS
ipactl -h|v
ipactl [-n] [-s <socket>] [-w <timeout>]
[-r <rule> [-l <limit>|-t <threshold>]] <command> [<args>]
DESCRIPTION
ipactl utility is used for controlling ipa(8) on-the-fly. The control
is done by sending messages to a well known Unix domain socket for
ipa(8) and ipactl. Before using ipactl it is necessary to enable an
Unix domain socket for receiving control messages in ipa.conf(5) and
grand access to users, who will be allowed to use ipactl. Read details
about access control in the ipa.conf(5) manual page.
ipactl utility also can be used as a source of statistics for a rule,
even if this rule does not use any accounting system.
Available options are:
-s <socket>
Connect to <socket>, instead of connecting to default Unix
domain socket.
-r <rule>
The name of the rule.
-l <limit>
The name of the limit.
-t <threshold>
The name of the threshold.
-n Do not wait for an answer from ipa(8), asynchronous regime.
-w <timeout>
Specify number of seconds to wait for an answer from ipa(8),
zero means infinite timeout (this is default). Actually this
timeout is used for two or three separate system calls.
-h Print the help message about available options and exit.
-v Show the version number, configuration settings and exit.
Available commands are:
dump Force dumping statistics to database, after receiving the answer
from ipa(8), it is possible that ipa(8) will be freezed for
sleep_after_dump time (see ipa.conf(5)).
freeze Freeze work of ipa(8), after receiving the answer from ipa(8),
you can be sure, that ipa(8) will be freezed for freeze_time
(see ipa.conf(5)).
memory Output information about used memory and about memory zones and
memory arrays (using statistics from ipa_memfunc functions).
status Output different status information, this command can be used
with -r, -l and -t options.
expire Expire the limit, if it was already reached, even if it does not
have the expire section; but if it has the expire section and
there are commands in this section, then these commands will be
run.
restart
Restart the limit, if it is currently not reached, event if it
does not have the restart section; but if it has the restart
section and there are commands in this section, then these com-
mands will be run.
set limit [+|-]<value>
Change the value of the limit parameter for the limit, it should
have the value of its load_limit parameter equal to ``yes''.
set threshold [+|-]<value>
Change the value of the threshold parameter for the threshold,
it should have the value of its load_threshold parameter equal
to ``yes''.
set counter [+|-]<value>
Change rule's, limit's or threshold's counter.
Any control command which requires <limit> or <threshold> also requires
<rule>.
In all commands `+' means increasing and `-' means decreasing of cur-
rent value (value of a counter, value of limit or threshold parameter).
For commands expire, restart and set a new state of a limit is regis-
tered in the database immediately and a limit's state is updated imme-
diately even if a limit is inactive or its rule is inactive, in this
case a limit (and its rule) is set to active and after updating of
limit's state, a limit (and its rule) is set to inactive again.
The set command for a rule allows only to increase or decrease a rule's
counter. Read paragraph about statistics and negative statistics in the
ipa.conf(5) manual page, to understand what's going on, when you
decrease statistics. If some of rule's limits or thresholds are inac-
tive, then their statistics is not updated, only a rule's counter and
active rule's limits and thresholds are updated. If a rule is inactive,
then it is set to active and after updating of rule's statistics, a
rule is set to inactive again, but any limit or threshold is not set to
active.
The set command for a rule can change statistics for rule's limits and
thresholds. This statistics will not be checked immediately, checking
for limits and thresholds will be scheduled and will happen as quickly
as possible.
If a limit is reached and after command set it becomes not reached, and
if it has the expire section, then no commands from this section are
run.
If a limit is not reached and after command set it becomes reached, and
if it has the reach section, then all commands from this section are
run.
If some sublimit is not reached and after command set it becomes
reached, and if it has the reach section, then all commands from this
section are run.
The set command for a limit has one side effect: if a limit does not
have the load_limit with the value ``yes'', and it is reached, and the
value of the limit parameter in the database is not equal to the value
of the limit parameter in the configuration file, then if you change a
limit's counter, then a counter and the value of the limit parameter
(real value) are updated together in the database.
For command set a new state of a threshold is registered in the data-
base immediately, even if a threshold is inactive or its rule is inac-
tive as in the case of limits. New threshold's settings will be checked
on next threshold_time_slice time event.
ipactl accepts <value> as decimal 64-bit integer, time or bytes. For-
mats for time and bytes used in <value> are similar with the same for-
mats in ipa.conf(5), but spaces in formats are not allowed.
DIAGNOSTICS
ipactl exits with a return code of 0 on success; 1 if it cannot parse
command line, cannot send a command or receive an answer from ipa(8); 2
if it receives the answer from ipa(8) and this answer says that execu-
tion of a control command in ipa(8) failed. If it is run with the -n
switch, then it is impossible to find out from a return code whether
ipa(8) successfully executed the given control command or not.
FILES
ipactl.sock
(run ipactl with the -h switch and check default path)
SEE ALSO
ipa(8), ipastat(8), ipa.conf(5), ipastat.conf(5), ipa_mod(3)
AUTHOR
Andrey Simonenko <simon@comsys.ntu-kpi.kiev.ua>
BUGS
If you find any, please send email me.
April 16, 2005 IPACTL(8)