Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IPACTL(8)		    System Manager's Manual		     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''.  Op-
	      tionally	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 in-
       active, 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)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | DIAGNOSTICS | FILES | SEE ALSO | AUTHOR | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ipactl&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help