IPA(8) IPA(8)
NAME
ipa -- utility for accounting
SYNOPSIS
ipa -h|v
ipa [-c dir] [-u user] [-g group] [-p pid_file] -k signal
ipa [-c dir] [-u user] [-g group] [-f conf_file] -t [-t]
ipa [-d] [-c dir] [-u user] [-g group] [-f conf_file] [-p pid_file]
[-o log_file] [-i log_ident]
ipa -x [-c dir] [-u user] [-g group] [-f conf_file]
[-r rule [-l limit [-s sublimit]|-t threshold]]
section [subsection]
DESCRIPTION
IPA is the ``Pluggable Accounting System''. The IPA distribution con-
sists of three utilities for general purpose accounting: ipa, ipactl
and ipastat. 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 and describes all its
features.
ipa periodically takes statistics from IPA accounting modules and
passes this statistics to IPA database modules according to settings in
the ipa.conf(5) configuration file. It is possible to use several
accounting systems and databases at once.
Available options are:
-c dir Set the directory ipa should chroot(2) into immediately, the
directory should be given with absolute path. The working
directory 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 conf_file
Use the given configuration file instead of using the default
configuration file, the configuration file name should be given
with absolute pathname.
-i log_ident
Use the given log-ident (the default log-ident is ``ipa'').
-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 whether PID-
file is locked, no signal is sent). The PID of the running copy
is taken as the PID of the process which has the exclusive lock
on a PID-file. No signal will be sent if a PID-file is not
exclusively locked.
-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.
-t Parse the configuration file, output its content and exit. This
option allows to check whether ipa and IPA modules understand
your configuration file(s). Two -tt switches enable so called
``mimic real configuration regime''. ipa will set all default
values and will apply settings from rulepat sections to rule
sections in this regime.
-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.
-x Run commands from the given section (subsection) and exit. It
is impossible to run commands from any section from autorule or
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 the exclusive lock on its PID-file to pre-
vent multiple 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 the shutdowning of the ipa running copy. It is
the only one correct way to shutdown it. If the -d switch is given 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
one given in the command line when ipa was run). If ipa 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 ipa.
Do not send a SIGKILL signal to the running copy of ipa, use this sig-
nal only if 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 argument.
Note that ipa caught the above mentioned signals only if it does not
currently execute some function from used IPA modules or does not runs
commands in a synchronous regime. Handling of other signals is unde-
fined.
If ipa starts in the background, then it redirects the standard input
(stdin) to /dev/null (see output of the ``ipa -v'' command for the real
path), output to the standard output (stdout) and the standard error
output (stderr) is redirected to internal pipe(2)s and asynchronously
is logged with *STDOUT and *STDERR prefixes respectively. Write ends
of each pipes are set in the 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.
If ipa starts in the foreground, 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 it runs 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 non-zero return
code 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)