.\" Copyright (c) 2000-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: ipa.8,v 1.8.4.3 2007/07/20 09:53:38 simon Exp $ .\" .TH IPA 8 "April 16, 2005" .SH NAME ipa -\- utility for accounting .SH SYNOPSIS .nf \fBipa\fP\ \fB-h\fP|\fBv\fP \fBipa\fP\ [\fB-c\fP\ ]\ [\fB-u\fP\ ]\ [\fB-g\fP\ ] \ \ \ \ [\fB-p\fP\ ]\ \fB-k\fP\ \fBipa\fP\ [\fB-c\fP\ ]\ [\fB-u\fP\ ]\ [\fB-g\fP\ ]\ [\fB-f\fP\ ] \ \ \ \ \fB-t\fP [\fB-t\fP] \fBipa\fP\ [\fB-d\fP]\ [\fB-c\fP\ ]\ [\fB-u\fP\ ]\ [\fB-g\fP\ ]\ [\fB-f\fP\ ] \ \ \ \ [\fB-o\fP\ ]\ [\fB-i\fP\ ]\ [\fB-p\fP\ ] \fBipa\fP\ \fB-x\fP\ [\fB-c\fP\ ]\ [\fB-u\fP\ ]\ [\fB-g\fP\ ]\ [\fB-f\fP\ ] \ \ \ \ [\fB-r\fP\ \ [\fB-l\fP\ [\fB-s\fP ]|\fB-t\fP ]] \ \ \ \ section\ [subsection] .fi .SH DESCRIPTION IPA is a ``Pluggable Accounting System''. The IPA distribution consists of three utilities for general purpose accounting: \fBipa\fP, \fBipactl\fP and \fBipastat\fP. Each of these utilities is described on its own manual page. .PP \fBipa\fP is an utility for accounting. The ipa.conf(5) manual page gives the complete description how to configure \fBipa\fP, it also describes all its features. .PP \fBipa\fP, accordingly to settings in the ipa.conf(5) configuration file, periodically takes statistic from IPA accounting modules and passes this statistic to IPA database modules. It is possible to use several accounting systems and databases at once. .PP Available options are: .IP \fB-c\fP\ Set the directory \fBipa\fP should chroot(2) into immediately, the directory should be given with absolute path. The working directory is not changed. .IP \fB-d\fP Do not run in the background. If log-file is used, then all log messages are sent to standard error output (stderr) as well. If syslog is used, then log messages are copied to stderr only on some systems. This option is useful for debugging. .IP \fB-f\fP\ Use the given instead of using default configuration file, the configuration file name should be given with absolute pathname. .IP \fB-k\fP\ Send a signal to the running copy of \fBipa\fP. Valid arguments are: \fIshutdown\fP (send a SIGTERM signal), \fIreconfigure\fP (send a SIGHUP signal), \fIkill\fP (send a SIGKILL signal), \fItest\fP (test if PID-file is locked, no signal is sent). PID of the running copy is taken as PID of the process which has exclusive lock on a PID-file. No signal will be sent, if a PID-file is not exclusively locked. .IP \fB-i\fP\ Use the given log-ident, instead of using default log-ident ``ipa''. .IP \fB-o\fP\ Write log messages to the given log-file instead of using syslog. This file can be safely removed while \fBipa\fP is running, it will be recreated. This feature helps to make logs rotating. .IP \fB-p\fP\ Use the given instead of using default PID-file. This option allows to start some copies of \fBipa\fP at once. .IP \fB-u\fP\ Change the UID of the running copy of \fBipa\fP to the given user. The given value may be either a user name or the UID. If the \fB-g\fP option is not given, then the GID will be the primary group of the given user, all supplementary user's groups are set as well. .IP \fB-g\fP\ Change the GID of the running copy of \fBipa\fP to the given group. The given value may be either a group name or the GID. This option also changes all supplementary user's groups. .IP \fB-t\fP Parse the configuration file, output its content and exit. This option allows to check if \fBipa\fP and IPA modules understand your configuration file(s). Output configuration usually should not be used as a configuration file (see a comment in the output). Two \fB-tt\fP switches enable so called ``mimic real configuration regime'', in this regime \fBipa\fP will set all default values and will apply settings from \fBrulepat\fP sections to \fBrule\fP sections. .IP \fB-x\fP\ ... Run commands from the given section (subsection) and exit. It is impossible to run commands from any section from \fBautorule\fP or \fBrulepat\fP sections. In this option rules inherit settings from \fBrulepat\fP sections. See the ipa.conf(5) manual page for information about sections and subsections names, rules, limits, sublimits and thresholds. .IP \fB-h\fP Print the help message about available options and exit. .IP \fB-v\fP Show the version number, some settings, what is supported from ipa.conf(5) and exit. .PP When \fBipa\fP starts, it acquires exclusive lock on PID-file to prevent multiple copies of itself from running and stores its PID in this file. This saved PID is not used by \fBipa\fP in any way. .PP A SIGTERM signal causes to shutdown the running copy of \fBipa\fP. This is only one correct way to shutdown it. If the \fB-d\fP switch is specified in the command line, then a SIGINT signal is handled as a SIGTERM signal (a SIGINT signal usually is sent to a foreground process when one types Control-C sequence). .PP A SIGHUP signal tells \fBipa\fP to reread its configuration file (default or specified one in the command line when \fBipa\fP was run). If \fBipa\fP cannot parse the configuration file, then it exits. Read the ipa.conf(5) manual page for more information why it is better in some cases to reread a configuration, instead of stopping and running \fBipa\fP. .PP Do not send a SIGKILL signal to the running copy of \fBipa\fP, use this signal if only \fBipa\fP does not work properly and does not catch a SIGTERM signal (or a SIGINT signal if it is run in the foreground regime). This note is here, just because the \fB-k\fP option accepts the \fIkill\fP argument. .PP Note that above mentioned signals are caught by \fBipa\fP only if it does not currently execute some function from used IPA modules or runs commands in synchronous regime. Handling of other signals is undefined. .PP When \fBipa\fP starts in the background, then it redirects standard input (stdin) to /dev/null (see output of the ``ipa\ \-v'' command for the real path), output to standard output (stdout) and standard error output (stderr) is redirected to internal pipe(2)s and asynchronously is logged with prefixes *STDOUT and *STDERR. Write ends of each pipes are set in non-blockable regime. Since a pipe(2) has a limited size of its buffer, then some information sent to stdout or stderr can be lost. Anyway this is better, than simply discard output to stdout and stderr. When \fBipa\fP starts in the debugging regime, then stdin and stderr works as usual (stderr is used for outputting log messages). \fBipa\fP does not sent any message to stdout and stderr (when run in the background), but library functions or run commands can send messages to stdout and stderr. .SH DIAGNOSTICS \fBipa\fP exits with a return code 0 on success, and with a return code 1 if any error occurred. By default \fBipa\fP is run in the background and you should not rely upon its return code (it is just a return code of a original process), it is better to look at its log-file. If you need to control a return code, then run \fBipa\fP in foreground (use the \fB-d\fP switch). .SH FILES ipa.pid .br ipa.conf .PP (run \fBipa\fP with the \fB-h\fP switch and check default paths) .SH SEE ALSO ipactl(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.