.\" 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: ipastat.8,v 1.9.2.1 2007/07/20 09:53:38 simon Exp $ .\" .TH IPASTAT 8 "April 16, 2005" .SH NAME ipastat -\- statistics viewer .SH SYNOPSIS .nf \fBipastat\fP\ \fB-h\fP|\fBv\fP \fBipastat\fP\ [\fB-c\fP\ ]\ [\fB-u\fP\ ]\ [\fB-g\fP\ ]\ [\fB-f\fP\ ] \ \ \ \ \ \ \ \ \fB-t\fP [\fB-t\fP] \fBipastat\fP\ [\fB-c\fP\ ]\ [\fB-u\fP\ ]\ [\fB-g\fP\ ]\ [\fB-f\fP\ ] \ \ \ \ \ \ \ \ \fB-q\fP\ .fi .SH DESCRIPTION \fBipastat\fP utility is used for querying IPA statistics modules and outputting results to the standard output (stdout). The ipastat.conf(5) manual page gives the complete description how to configure \fBipastat\fP, it also describes all its features. .PP \fBipastat\fP, accordingly to settings in the ipastat.conf(5) configuration file and settings in the command line, queries IPA statistics modules and outputs results to the standard output. This utility allows to output rules, limits and thresholds list, output statistics for rules, limits and thresholds. It is possible to use several statistics systems at once and query statistics for several rules, limits and thresholds at once. .PP \fBipastat\fP does not accept any signals and signals handling is undefined. .PP Available options are: .IP \fB-c\fP\ Set the directory \fBipastat\fP should chroot(2) into immediately, the directory should be given with absolute path. The working directory is not changed. .IP \fB-f\fP\ Use given instead of using default configuration file, the configuration file name should be given with absolute pathname. .IP \fB-u\fP\ Change the UID of the running copy of \fBipastat\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 \fBipastat\fP to the given group. The value given may be either a group name or a 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 \fBipastat\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 \fBipastat\fP will set all default values and will apply settings from \fBrulepat\fP sections to \fBrule\fP sections. .IP \fB-q\fP\ Query statistics from IPA statistics modules (described in the separate query options list). .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 ipastat.conf(5) and exit. .PP Query options are: .IP \fB-a\fP\ rules Output rules list. .IP \fB-a\fP\ limits Output limits list for given rules in the \fB-r\fP options. .IP \fB-a\fP\ thresholds Output thresholds list for given rules in the \fB-r\fP options. .IP \fB-x\fP\ Filter output of names (the \fB-a\fP option) with the given POSIX extended regular expression. .IP \fB-s\fP\ \ \ ... Specify \fBst_list\fP for next rules, limits or thresholds. New \fB-s\fP option starts new list of statistics systems. This list changes list of statistics systems given in the configuration file for rule, limit or threshold. It is possible to specify built-in \fInull\fP statistics system. If the list in this option is empty, then previous list is forgotten and the list from the appropriate section from the configuration file is used. .IP \fB-i\fP|\fBI\fP\ Specify time interval, to specify non continuous time interval use several options. The \fB-I\fP option means ``exact interval'' and has effect only for statistics for rules. Description of formats and what are time intervals see below. .IP \fB-r\fP\ Specify rule name, it is possible to use several rules at once. .IP \fB-l\fP\ Specify limit name, it is possible to use several limits at once. .IP \fB-t\fP\ Specify threshold name, it is possible to use several thresholds at once. .PP In all \fB-a\fP options it is allowed to use short arguments. .PP If the \fB-a\fP option is not given, then statistics for rules, limits or thresholds is outputted. It is not allowed to mix \fB-l\fP and \fB-t\fP options, also it is not allowed to mix single \fB-r\fP options and \fB-r\fP options with \fB-l\fP or \fB-t\fP options. In other words: it is possible to query statistics only for rules, only for limits or only for thresholds. .PP If a rule given in the \fB-r\fP option, does not exist in the configuration file, then \fBipastat\fP will create a rule with the given name on-the-fly if this is allowed in ipastat.conf(5) and this rule will inherit settings from \fBrulepat\fP and \fBglobal\fP sections. The same effect is for limits and thresholds (even for rules which exist in the configuration file). .PP \fBTime intervals.\fP .PP The general and complete form of a time interval is the following: .PP .nf Y1.M1.D1/h1:m1:s1-Y2.M2.D2/h2:m2:s2 .fi .PP where Y1, Y2 -\- years, M1, M2 -\- months, D1, D2 -\- days, h1, h2 -\- hours, m1, m2 -\- minutes and s1, s2 -\- seconds. Months can be given as three characters abbreviations of English language months' names. .PP Any time interval consists of left and right parts. Each part is not required to be completely specified. If the left part of a time interval is not complete, then first second of first minute of first hour (and so on) is taken. If the right part of a time interval is not complete, then the end of last second of last minute of last hour (and so on) is taken. .PP The right part of a time interval can be omitted. In this case the right part is equal to the left part. .PP For a rule a time interval means, that rule's database records timestamps should be in the range of dates given in a time interval. If a time interval is given in the \fB-i\fP option, then only one of rule's database records timestamps should be in the range of dates. If a time interval is given in the \fB-I\fP option, then both of rule's database records timestamps should be in the range of dates. If a time interval is not given, then by default time interval for the current month is used. .PP For a limit a time interval means, that limit's start time should be in the range of dates given in a time interval. If time interval is not given, then the current state of a limit is outputted. .PP For a threshold a time interval does not have any effect. .SH EXAMPLES Output rules list: .PP .nf ipastat -q -a rul .fi .PP Output rules list, which starts with "10" substring: .PP .nf ipastat -q -x ^10 -a rul .fi .PP Output limits list for my and lan rules: .PP .nf ipastat -q -a lim -r my -r lan .fi .PP Output thresholds list for given rules: rule1 and rule2 using statistics system sdb, rule3 should use statistics system from the configuration file: .PP .nf ipastat -q -a thr -s sdb -r rule1 -r rule2 -s "" rule3 .fi .PP Output statistics for rules rule1 and rule2 for current month: .PP .nf ipastat -q -r rule1 -r rule2 .fi .PP Output statistics for the rule rule1 for January and March for current year: .PP .nf ipastat -q -i jan -i mar -r rule1 .fi .PP Output statistics for the rule rule1 from 10:00 till 12:00 for current day: .PP .nf ipastat -q -i /10-/12 -r rule1 .fi .PP Output statistics for rules rule1, rule2 and rule3 for 2005 year: .PP .nf ipastat -q -i 2005 -r rule1 -r rule2 -r rule3 .fi .PP Output current states of limits lim1 for rule1 and limx for rule2: .PP .nf ipastat -q -r rule1 -l lim1 -r rule2 -l limx .fi .PP Output statistics for the same limits, but all states of all limits should have start time in January of 2004 year: .PP ipastat -q -i 2004.jan -r rule1 -l lim1 -r rule2 -l limx .PP Output statistics for thresholds thr1 for rule1, thrx and thry for rule2, threshold thrx should use statistics system sdb, other thresholds should use statistics systems from the configuration file: .PP .nf ipastat -q -r rule1 -t thr1 -r rule2 -s sdb -t thrx -s "" -t thry .fi .SH DIAGNOSTICS \fBipastat\fP exits with a return code 0 on success, and with a return code 1 if any error occurred. .SH FILES ipastat.conf .PP (run \fBipastat\fP with the \fB-h\fP switch and check default path) .SH SEE ALSO ipa(8), ipactl(8), ipa.conf(5), ipastat.conf(5), ipa_mod(3) .SH AUTHOR Andrey\ Simonenko\ .SH BUGS If you find any, please send email me.