IPACTL(8) IPACTL(8)
NAME
ipactl -- control utility for ipa(8)
SYNOPSIS
ipactl -h|v
ipactl [-n] [-s socket] [-w timeout]
[[-a autorule] -r rule [-l limit|-t threshold]] command [args]
DESCRIPTION
ipactl is the utility 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. It is necessary to enable an Unix domain socket for
receiving control messages and grand access to users who are allowed to
send control messages in ipa.conf(5) before using 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: domain socket.
-a autorule
Specify an autorule name.
-r rule
Specify a rule name.
-l limit
Specify a limit name.
-t threshold
Specify a threshold name.
-n Do not wait for an answer from ipa(8) (asynchronous regime).
-s socket
Connect to the given socket instead of connecting to the default
Unix
-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.
If -l or -t option is used, then the -r option also should be used.
Available commands are (required options are in parenthesis):
create (-a, -r)
Create a dynamic rule.
delete (-r)
Delete a dynamic rule.
dump (no opts)
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 seconds (see ipa.conf(5)).
expire (-r, -l)
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.
freeze (no opts)
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
seconds (see ipa.conf(5)).
memory (no opts)
Output information about used memory, about memory zones and
memory arrays (using statistics from ipa_memfunc functions).
restart (-r, -l)
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 [counter [+|-]value] (-r, -l)
Change the value of the limit parameter for the limit, it should
have the load_limit parameter set to ``yes''. Optionally
limit's counter also can be changed in the same command.
set threshold [+|-]value [counter [+|-]value] (-r, -t)
Change the value of the threshold parameter for the threshold,
it should have the load_threshold parameter set to ``yes''.
Optionally threshold's counter also can be changed in the same
command.
set counter [+|-]value (-r, -l, -t)
Change rule's, limit's or threshold's counter.
status (no opts, -a, -r, -l, -t)
Output different status information.
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 the new state of a limit is regis-
tered in the database immediately. If a limit is inactive, then a
limit (and its rule) is set to active and after updating of the 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 the
rule's counter. Read paragraph about statistics and negative statis-
tics 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
inactive, then their statistics is not updated, only the 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 statis-
tics 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. Updated limits' and thresholds' statistics will not be
checked immediately, checking for limits and thresholds will be sched-
uled 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 (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 the new state of a threshold is registered in the data-
base immediately even if a threshold is inactive as in the case of lim-
its, but new threshold's settings will be checked on next thresh-
old_time_slice time event.
ipactl accepts value as a decimal 64-bit integer, time or bytes. For-
mats for time and bytes are similar with the same formats in
ipa.conf(5).
EXAMPLES
Output information about memory usage:
ipactl memory
Output status information about limit:
ipactl -r rule -l limit status
Create dynamic rule:
ipactl -a autorule -r rule create
Add 10 Mbytes to the limit parameter:
ipactl -r rule -l limit set limit +10M
DIAGNOSTICS
ipactl exits with a return code 0 on success; 1 if it cannot parse com-
mand 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 execution
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.
January 27, 2007 IPACTL(8)