IPA(8) IPA(8)
NAME
ipa -- utility for accounting
SYNOPSIS
ipa -h|v
ipa [-c <directory>] [-u <user>] [-g <group>]
[-p <pid-file>] -k <signal>
ipa [-c <directory>] [-u <user>] [-g <group>] [-f <config-file>]
-t [-t]
ipa [-d] [-c <directory>] [-u <user>] [-g <group>] [-f <config-file>]
[-o <log-file>] [-i <log-ident>] [-p <pid-file>]
ipa -x [-c <directory>] [-u <user>] [-g <group>] [-f <config-file>]
[-r <rule> [-l <limit> [-s <sublimit>]|-t <threshold>]]
section [subsection]
DESCRIPTION
IPA is a ``Pluggable Accounting System''. The IPA distribution consists
of three utilities for general purpose accounting: ipa, ipactl and ipa-
stat. Each of these utilities is described on its own manual page.
ipa is an utility for accounting. The ipa.conf(5) manual page gives the
complete description how to configure ipa, it also describes all its
features.
ipa, 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.
Available options are:
-c <directory>
Set the directory ipa should chroot(2) into immediately, the
directory should be given with absolute path. The working direc-
tory is not changed.
-d 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.
-f <config-file>
Use the given <config-file> instead of using default configura-
tion file, the configuration file name should be given with
absolute pathname.
-k <signal>
Send a signal to the running copy of ipa. Valid arguments are:
shutdown (send a SIGTERM signal), reconfigure (send a SIGHUP
signal), kill (send a SIGKILL signal), test (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.
-i <log-ident>
Use the given log-ident, instead of using default log-ident
``ipa''.
-o <log-file>
Write log messages to the given log-file instead of using sys-
log. This file can be safely removed while ipa is running, it
will be recreated. This feature helps to make logs rotating.
-p <pid-file>
Use the given <pid-file> instead of using default PID-file. This
option allows to start some copies of ipa at once.
-u <user>
Change the UID of the running copy of ipa to the given user.
The given value may be either a user name or the UID. If the -g
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.
-g <group>
Change the GID of the running copy of ipa 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.
-t Parse the configuration file, output its content and exit. This
option allows to check if ipa 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 -tt switches enable so called ``mimic real configuration
regime'', in this regime ipa will set all default values and
will apply settings from rulepat sections to rule sections.
-x ... Run commands from the given section (subsection) and exit. It is
impossible to run commands from any section from autorule or
rulepat sections. In this option rules inherit settings from
rulepat sections. See the ipa.conf(5) manual page for informa-
tion about sections and subsections names, rules, limits, sub-
limits and thresholds.
-h Print the help message about available options and exit.
-v Show the version number, some settings, what is supported from
ipa.conf(5) and exit.
When ipa starts, it acquires exclusive lock on PID-file to prevent mul-
tiple copies of itself from running and stores its PID in this file.
This saved PID is not used by ipa in any way.
A SIGTERM signal causes to shutdown the running copy of ipa. This is
only one correct way to shutdown it. If the -d 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).
A SIGHUP signal tells ipa to reread its configuration file (default or
specified one in the command line when ipa was run). If ipa cannot
parse the configuration file, then it exits. Read the ipa.conf(5) man-
ual page for more information why it is better in some cases to reread
a configuration, instead of stopping and running ipa.
Do not send a SIGKILL signal to the running copy of ipa, use this sig-
nal if only ipa 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 -k option accepts the kill argu-
ment.
Note that above mentioned signals are caught by ipa 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.
When ipa 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 ipa starts in the debugging regime, then stdin and stderr works as
usual (stderr is used for outputting log messages). ipa 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.
DIAGNOSTICS
ipa exits with a return code 0 on success, and with a return code 1 if
any error occurred. By default ipa 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 ipa in foreground (use the -d
switch).
FILES
ipa.pid
ipa.conf
(run ipa with the -h switch and check default paths)
SEE ALSO
ipactl(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.
April 16, 2005 IPA(8)