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 commands 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 current value (value of a counter, value of limit or threshold parameter).

For commands expire, restart and set the new state of a limit is registered 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 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 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 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. Updated limits' and thresholds' 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 (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 database immediately even if a threshold is inactive as in the case of limits, but new threshold's settings will be checked on next threshold_time_slice time event.

ipactl accepts value as a decimal 64-bit integer, time or bytes. Formats 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 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 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.