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 consists 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 syslog. 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 information about sections and subsections names, rules, limits, sublimits 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 prevent 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 signal 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 undefined.

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.