.\" Copyright (c) 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: ipactl.8,v 1.1.4.3 2007/07/20 09:53:38 simon Exp $ .\" .TH IPACTL 8 "April 16, 2005" .SH NAME ipactl -\- control utility for ipa(8) .SH SYNOPSIS .nf \fBipactl\fP\ \fB-h\fP|\fBv\fP \fBipactl\fP\ [\fB-n\fP] [\fB-s\fP\ ]\ [\fB-w\fP\ ] \ \ \ \ \ \ \ [\fB-r\fP\ [\fB-l\fP |\fB-t\fP ]]\ [] .fi .SH DESCRIPTION \fBipactl\fP 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 \fBipactl\fP. Before using \fBipactl\fP 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 \fBipactl\fP. Read details about access control in the ipa.conf(5) manual page. .PP \fBipactl\fP utility also can be used as a source of statistics for a rule, even if this rule does not use any accounting system. .PP Available options are: .IP \fB-s\fP\ Connect to , instead of connecting to default Unix domain socket. .IP \fB-r\fP\ The name of the rule. .IP \fB-l\fP\ The name of the limit. .IP \fB-t\fP\ The name of the threshold. .IP \fB-n\fP Do not wait for an answer from ipa(8), asynchronous regime. .IP \fB-w\fP\ 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. .IP \fB-h\fP Print the help message about available options and exit. .IP \fB-v\fP Show the version number, configuration settings and exit. .PP Available commands are: .IP \fIdump\fP Force dumping statistics to database, after receiving the answer from ipa(8), it is possible that ipa(8) will be freezed for \fBsleep_after_dump\fP time (see ipa.conf(5)). .IP \fIfreeze\fP Freeze work of ipa(8), after receiving the answer from ipa(8), you can be sure, that ipa(8) will be freezed for \fBfreeze_time\fP (see ipa.conf(5)). .IP \fImemory\fP Output information about used memory and about memory zones and memory arrays (using statistics from \fIipa_memfunc\fP functions). .IP \fIstatus\fP Output different status information, this command can be used with \fB-r\fP, \fB-l\fP and \fB-t\fP options. .IP \fIexpire\fP Expire the limit, if it was already reached, even if it does not have the \fBexpire\fP section; but if it has the \fBexpire\fP section and there are commands in this section, then these commands will be run. .IP \fIrestart\fP Restart the limit, if it is currently not reached, event if it does not have the \fBrestart\fP section; but if it has the \fBrestart\fP section and there are commands in this section, then these commands will be run. .IP \fIset\fP\ \fIlimit\fP\ [+|-] Change the value of the \fBlimit\fP parameter for the limit, it should have the value of its \fBload_limit\fP parameter equal to ``yes''. .IP \fIset\fP\ \fIthreshold\fP\ [+|-] Change the value of the \fBthreshold\fP parameter for the threshold, it should have the value of its \fBload_threshold\fP parameter equal to ``yes''. .IP \fIset\fP\ \fIcounter\fP\ [+|-] Change rule's, limit's or threshold's counter. .PP Any control command which requires or also requires . .PP In all commands `+' means increasing and `-' means decreasing of current value (value of a counter, value of \fBlimit\fP or \fBthreshold\fP parameter). .PP For commands \fIexpire\fP, \fIrestart\fP and \fIset\fP a new state of a limit is registered in the database immediately and a limit's state is updated immediately 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. .PP The \fIset\fP 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 inactive, 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. .PP The \fIset\fP 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. .PP If a limit is reached and after command \fIset\fP it becomes not reached, and if it has the \fBexpire\fP section, then no commands from this section are run. .PP If a limit is not reached and after command \fIset\fP it becomes reached, and if it has the \fBreach\fP section, then all commands from this section are run. .PP If some sublimit is not reached and after command \fIset\fP it becomes reached, and if it has the \fBreach\fP section, then all commands from this section are run. .PP The \fIset\fP command for a limit has one side effect: if a limit does not have the \fBload_limit\fP with the value ``yes'', and it is reached, and the value of the \fBlimit\fP parameter in the database is not equal to the value of the \fBlimit\fP parameter in the configuration file, then if you change a limit's counter, then a counter and the value of the \fBlimit\fP parameter (real value) are updated together in the database. .PP For command \fIset\fP a new state of a threshold is registered in the database immediately, even if a threshold is inactive or its rule is inactive as in the case of limits. New threshold's settings will be checked on next \fBthreshold_time_slice\fP time event. .PP \fBipactl\fP accepts as decimal 64-bit integer, time or bytes. Formats for time and bytes used in are similar with the same formats in ipa.conf(5), but spaces in formats are not allowed. .SH DIAGNOSTICS \fBipactl\fP 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 execution of a control command in ipa(8) failed. If it is run with the \fB-n\fP switch, then it is impossible to find out from a return code whether ipa(8) successfully executed the given control command or not. .SH FILES ipactl.sock .PP (run \fBipactl\fP with the \fB-h\fP switch and check default path) .SH SEE ALSO ipa(8), ipastat(8), ipa.conf(5), ipastat.conf(5), ipa_mod(3) .SH AUTHOR Andrey\ Simonenko\ .SH BUGS If you find any, please send email me.