.\" Copyright (c) 2003-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_mod.3,v 1.2.2.4 2007/07/20 09:53:38 simon Exp $ .\" .TH IPA_MOD 3 "April 16, 2005" .SH NAME ipa_mod -\- IPA modules APIs .SH SYNOPSIS \fB#include \fP .SH DESCRIPTION This manual page describes API of all types of IPA modules. Let's call any IPA module simply ``a module''. Information given in this manual page is mainly for developers, but it can be interesting for anybody who wish to understand how IPA utilities work with IPA modules. .PP This manual page has descriptions of the following APIs: .PP ipa_memfunc API version 1 (IPA_MEMFUNC_API_VERSION); .br ipa_ac_mod API version 1 (IPA_AC_MOD_API_VERSION); .br ipa_db_mod API version 1 (IPA_DB_MOD_API_VERSION); .br ipa_st_mod API version 1 (IPA_ST_MOD_API_VERSION). .PP The type \fIu_int\fP used here is actually \fIunsigned\ int\fP, it is not defined in \fB\fP. .PP \fBModule's symbols naming.\fP .PP Any module is stored in a file with the name like \fIfoobar\-x.y.z.so\fP. After loading a module using the dlopen(3) or similar function, any of IPA utilities removes a suffix and a version number from the module's file name and tries to find \fIfoobar_ac_mod\fP, \fIfoobar_db_mod\fP or \fIfoobar_st_mod\fP symbol in a module if a module is accounting, database or statistics module. If a module has a searched symbol, then a module is considered as an IPA module. .PP Then found (void\ *) pointer to a symbol is converted to one of three \fI(struct\ ipa_XX_mod\ *)\fP pointers. Structures \fIipa_XX_mod\fP determine APIs between IPA utilities and modules. .PP Such method of naming symbols in modules allows to have several modules of different types in one file. You can create links to a module's file with different names to follow above given naming scheme. .PP \fBSingle-threaded and multi-threaded modules.\fP .PP Any module can be single-threaded or multi-threaded. If a module is not expected to be blocked in some of its functions, then it can be built as single-threaded. If a module is expected to be blocked in some of its functions or if a module need to continuously monitor some event, then it must be built as multi-threaded. Alternatively a module can fork(2) another process and use some form of IPC to communicate with it from some of its functions, and used IPC functions also must be nonblockable. .PP If a module is single-threaded, then it can use signals for own purpose (for example SIGALRM to implement timeout), except signals used by an IPA utility, which loaded this module. If a module is multi-threaded, then it is not allowed to use signals. .PP It is very important to return from a module's function as quickly as possible, since IPA utilities expect, that module's functions will not block. If a module spends too much time in its functions, then timestamps of statistics and reaction on some planned events will be not very accurate in IPA utilities. .PP Even if a module is not designed as multi-threaded, other modules can be multi-threaded. All loaded modules must be all single threaded or must be all multi-threaded. So any single-threaded module should be able to be built as multi-threaded. A module always should set correct flag in its API structure to say if it is single or multi-threaded. .PP IPA utilities are single-threaded by design, but if at least one multi-threaded module is used, then they must be built as multi-threaded. In multi-threaded regime functions from \fIipa_memfunc\fP, which is exported by IPA utilities to modules, become thread-safe. .PP Modules are allowed to create threads only after configuration phase. .PP \fBExported memory allocation functions for a module.\fP .PP Modules APIs require some type of organization of data in modules. \fIipa_memfunc\fP functions are exported to a module and tries to help a module with memory manipulation. A module is free to decide if it will use these functions or if it will not. In some functions modules are required to use functions from \fIipa_memfunc\fP. .PP There are four types of functions from \fIipa_memfunc\fP: initialization and deinitialization functions, functions for general purpose memory allocation, functions for working with mzones and functions for working with marrays. .PP Functions \fImem_*\fP for general purpose memory allocation are wrappers for standard library memory allocation functions (malloc(3), calloc(3), realloc(3), free(3), strdup(3) and for vasprintf(3) function, found on some systems). All these functions do additional checks. Any memory allocated with some of \fImem_*\fP functions should be freed with \fImem_free\fP function. These functions accept extra one argument, called \fImem_type\fP (memory type), which is used for collecting statistics about memory usage. This \fImem_type\fP should be created by the \fImem_type_new\fP function. .PP Marrays (memory arrays) are used for creating arrays of items. Mzones (memory zones) are used for creating items of the same size. All \fImarray_*\fP and \fImzone_*\fP functions internally use \fImem_*\fP memory allocation functions. .PP Functions from \fIipa_memfunc\fP detect wrong pointers and incorrect arguments in \fImem_*\fP, \fImarray_*\fP and \fImzone_*\fP functions. If some critical error is found in any of these functions, then this function terminates execution of a program and a core dump is generated. .PP If IPA utilities were built with defined WITH_MEMFUNC_DEBUG macro variable, then allocated and freed memory objects are filled with some garbage bytes, so if some part of code uses already freed memory, then it is likely, that it will get an error. Also \fImem_realloc\fP in this case is equivalent to malloc(3) new area, memcpy(3) old data to new area, free(3) old area. .PP Any IPA utility during exit stage and during reconfiguration checks size of allocated and not freed memory, if this size is not equal to zero, then a debug message is sent to the log. If some mzone of marray was not deinitialized, then its name appears in a debug message. .PP The \fIipa_memfunc\fP has following format: .PP .nf typedef struct ipa_mem_type_struct ipa_mem_type; typedef struct ipa_marray_struct ipa_marray; typedef struct ipa_mzone_struct ipa_mzone; typedef struct { u_int api_ver; int (*memfunc_init)(void); void (*memfunc_deinit)(int foreign); ipa_mem_type *m_parser; ipa_mem_type *(*mem_type_new)(const char *name, const char *desc, u_int flags); void *(*mem_malloc)(size_t size, ipa_mem_type *mem_type); void *(*mem_calloc)(size_t number, size_t size, ipa_mem_type *mem_type); void *(*mem_realloc)(void *ptr, size_t size, ipa_mem_type *mem_type); char *(*mem_strdup)(const char *str, ipa_mem_type *mem_type); int (*mem_vasprintf)(ipa_mem_type *mem_type, char **bufp, const char *format, va_list ap); void (*mem_free)(void *ptr, ipa_mem_type *mem_type); ipa_marray *(*marray_init)(const char *name, const char *desc, u_int flags, void **arr, size_t isize, u_int nitems, u_int nalloc); void (*marray_deinit)(ipa_marray *marray); int (*marray_alloc)(ipa_marray *marray, u_int *idxp, int fixed); void (*marray_free)(ipa_marray *marray, u_int idx); void (*marray_minimize)(ipa_marray *marray); int (*marray_check_index)(ipa_marray *marray, u_int idx); u_int (*marray_nused)(ipa_marray *marray); ipa_mzone *(*mzone_init)(const char *name, const char *desc, u_int flags, size_t isize, u_int nitems, u_int nalloc); void (*mzone_deinit)(ipa_mzone *mzone); void *(*mzone_alloc)(ipa_mzone *mzone); void (*mzone_free)(ipa_mzone *mzone, void *ptr); u_int (*mzone_nused)(ipa_mzone *mzone); } ipa_memfunc; .fi .IP \fIapi_ver\fP Version of the \fIipa_memfunc\fP API, a module should check values of supported API versions with IPA_MEMFUNC_API_VERSION during compilation. .IP \fImemfunc_init\fP A child of a module can call this function to initialize all other \fIipa_memfunc\fP functions. .IP \fImemfunc_deinit\fP A child of a module can call this function to free all memory allocated in mzones and marrays, and deinitialize all other \fIipa_memfunc\fP own structures. If \fIforeign\fP flag is non-zero then all messages about memory leaks will be suppressed and statistics about memory usage will be flushed. Note that this and previous functions can be called only in a child of some module. .IP \fIm_parser\fP This is a pointer to mem_type used by a parser to allocate memory during configuration file parsing. .IP \fImem_type_new\fP Create new mem_type, \fIname\fP is a short name for new mem_type, \fIdesc\fP is its description (usually several words) and \fIflags\fP are ORed flags for new mem_type. Currently only one flag IPA_MEMFUNC_FLAG_PTHREAD defined, which should be set if memory of this mem_type will be allocated or freed from several threads asynchronously. This function returns a pointer to new mem_type or NULL if an error occurred. .IP \fImem_malloc\fP Analogous to malloc(3). .IP \fImem_calloc\fP Analogous to calloc(3). .IP \fImem_realloc\fP Analogous to realloc(3). .IP \fImem_strdup\fP Analogous to strdup(3). .IP \fImem_vasprintf\fP Analogous to vasprintf(3) found on some systems. This function sets \fI*bufp\fP to be a pointer to a buffer sufficiently large to hold the formatted string. If sufficient space cannot be allocated, this function will return -1 and set \fI*bufp\fP to be a NULL pointer. \fIformat\fP and \fIap\fP are the same arguments as for vprintf(3). .IP \fImem_free\fP Analogous to free(3). .IP \fImarray_init\fP Create marray, \fIname\fP is a name of marray, it should exist until marray is deinitialized. It is better to give a name for marray in a form :. \fIdesc\fP is its description (usually several words). \fIflags\fP determines ORed flags for new marray, currently only one flag IPA_MEMFUNC_FLAG_PTHREAD is defined, this flag must be set if items from this marray can be allocated and freed by several threads asynchronously. \fIarr\fP is a pointer where to store the pointer to the actual array of items. \fIisize\fP is a size of one item in marray. \fInitems\fP means number of items to allocate initially. \fInalloc\fP means number of items to allocate if there is not any unused items in marray. If you are not sure about these values, then set them to 1. This function returns a pointer to just created marray or NULL if an error occurred. Note that the pointer saved in memory pointed by \fIarr\fP can be changed by next \fImarray_alloc\fP and \fImarray_free\fP functions calls. .IP \fImarray_deinit\fP Release memory used by \fImarray\fP. If a module does not call this function, then an IPA utility will report about leak of memory and deinitialize module's marray, but this deinitialization does not mean that memory leak is avoided, because deinitialization of marray is not deep-free for its items. If \fImarray\fP is NULL, then this function does nothing. .IP \fImarray_alloc\fP Allocate a new item in \fImarray\fP. If \fIfixed\fP is non-zero, then \fI*idxp\fP should be a desired index number of a new item in \fImarray\fP, else this function will allocate an item with the lowest possible unused index number and save this index number in \fI*idxp\fP. This function returns 0 if a new item was allocated and -1 if an error occurred. Usually a module calls this function with non-zero value of the \fIfixed\fP argument. .IP \fImarray_free\fP Return previously allocated item with index \fIidx\fP to \fImarray\fP. .IP \fImarray_minimize\fP Try to minimize memory used by \fImarray\fP. Such minimization is possible because \fImarray_alloc\fP and \fImarray_free\fP try to keep extra memory for future items allocations. .IP \fImarray_check_index\fP This function checks if an item with the \fIidx\fP index was allocated previously in \fImarray\fP and if it was not allocated, then 0 is returned, else non-zero value is returned. .IP \fImarray_nused\fP Return number of allocated items from \fImarray\fP. .IP \fImzone_init\fP Create mzone, \fIname\fP is a name of mzone, it should exist until mzone is deinitialized. It is better to give a name for mzone in a form :. \fIdesc\fP is its description (usually several words). \fIflags\fP means the same as in \fImarray_init\fP function, mzone also accepts IPA_MEMFUNC_FLAG_OPTIMIZE, this flag should be set if it will be many items in a mzone. \fIisize\fP is a size of one item in mzone. \fInitems\fP means number of items to allocate initially. \fInalloc\fP means number of items to allocate if there is not any unused item in mzone. If you are not sure about these values, then set them to 1. This function returns a pointer to just created mzone or NULL if an error occurred. .IP \fImzone_deinit\fP Release memory used by \fImzone\fP. If a module does not call this function, then an IPA utility will report about leak of memory and deinitialize module's mzone, but this deinitialization does not mean that memory leak is avoided, because deinitialization of mzone is not deep-free for its items. If \fImzone\fP is NULL, then this function does nothing. .IP \fImzone_alloc\fP Allocate a new item from \fImzone\fP. This function returns a pointer to a new item or NULL if an error occurred. .IP \fImzone_free\fP Return previously allocated item pointed by \fIptr\fP to \fImzone\fP. .IP \fImzone_nused\fP Return number of allocated items from \fImzone\fP. .PP \fBExported support functions for a module.\fP .PP Sometime a module needs to add some macro variable to some section of the configuration file, or needs to output own parameters, when an IPA utility outputs parsed configuration file, or needs to send a log message. Since a module does not know how to do this, an IPA utility, which uses this module, exports \fIipa_suppfunc\fP functions to a module: .PP .nf typedef struct { void (*print_string)(const char *string); void (*print_bytes)(const uint64_t *value); void (*print_time)(const uint64_t *value); void (*print_value)(const uint64_t *value, u_int value_type); void (*print_boolean)(int value); void (*print_space)(void); void (*set_indent)(int indent); void (*print_param_name)(const char *prefix, const char *param); void (*print_param_args)(const char *format, va_list ap); void (*print_param_end)(void); void (*print_sect_name)(const char *prefix, const char *sect); void (*print_sect_args)(const char *format, va_list ap); void (*print_sect_begin)(void); void (*print_sect_end)(void); void (*open_log)(void); void (*close_log)(void); void (*logmsg)(const char *mod_name, int priority, int code, const char *format, va_list ap); void (*logconferr)(const char *mod_name, int code, const char *format, va_list ap); int (*local_sym_add)(char *sym, char *val, int copy_flag); int (*local_sym_del)(cost char *sym); int (*global_sym_add)(char *sym, char *val, int copy_flag); int (*global_sym_del)(cost char *sym); } ipa_suppfunc; .fi .IP \fIprint_string\fP This function prints a string with quotes. .IP \fIprint_bytes\fP This function prints bytes value. .IP \fIprint_time\fP This function prints time value. .IP \fIprint_value\fP This function prints bytes, time or 64-bit unsigned number if \fIvalue_type\fP is IPA_CONF_TYPE_BYTES, IPA_CONF_TYPE_TIME or IPA_CONF_TYPE_UINT64 respectively. .IP \fIprint_boolean\fP This function prints boolean value. .IP \fIprint_space\fP This function prints one space character if it was not printed yet. .IP \fIset_indent\fP A module should call this function before outputting any parameter or sections inside own section to set correct \fIindent\fP, which is given as positive indent level. .IP \fIprint_param_name\fP This function outputs a parameter's name \fIparam\fP with configuration prefix \fIprefix\fP. If a parameter does not have a configuration prefix, then \fIprefix\fP should be NULL. .IP \fIprint_param_args\fP This vprintf(3)-like function outputs parameter's arguments. It can be invoked several times for the same parameter. .IP \fIprint_param_end\fP This function should be called after outputting all parameter's arguments. .IP \fIprint_sect_name\fP This function outputs a section's name \fIsect\fP with configuration prefix \fIprefix\fP. If a section does not have a configuration prefix, then \fIprefix\fP should be NULL. .IP \fIprint_sect_args\fP This vprintf(3)-like function outputs section's arguments. It can be invoked several times for the same section. .IP \fIprint_sect_begin\fP This function should be called after outputting all section's arguments. .IP \fIprint_sect_end\fP This function should be called at the end of a module's section. .IP \fIopen_log\fP .IP \fIclose_log\fP If a module needs to fork another process, then that process can use \fIlogmsg\fP function (described below), but if it needs to close some descriptors and then use log system again, then it should call \fIclose_log\fP and then \fIopen_log\fP function. Creation of the file descriptor for sending log messages is delayed until the first message is sent. .IP \fIlogmsg\fP A module should use this function for sending log messages from any part of its code, but not from configuration file parsing functions. \fImod_name\fP is a module's name. \fIpriority\fP is a priority of the message: IPA_LOG_INFO, IPA_LOG_WARNING or IPA_LOG_ERR. \fIcode\fP is the errno(2) value or 0 if there is not any error condition. \fIformat\fP and \fIap\fP are vprintf(3)-like arguments. .IP \fIlogconferr\fP A module should use this function for sending messages about errors during configuration file parsing. Arguments means the same as for \fIlogmsg\fP function. .IP \fIlocal_sym_add\fP Create a local macro variable with name \fIsym\fP and value \fIval\fP, if \fIcopy_flag\fP is non-zero, then memory will be allocated and \fIsym\fP and \fIval\fP will be copied to it, else original pointers will be used. This function returns 0 if a macro variable was created and -1 if something was wrong with memory allocation. .IP \fIlocal_sym_del\fP Delete a local macro variable with name \fIsym\fP. If there is no local variable with the given name, then -1 is returned, else 0 is returned. A module has a choice not to call this function for each variable previously created by the \fIlocal_sym_add\fP function, because an IPA utility automatically handles this. .IP \fIglobal_sym_add\fP Like \fIlocal_sym_add\fP, but for global macro variables. .IP \fIglobal_sym_del\fP Like \fIlocal_sym_del\fP, but for global macro variables. .PP \fBConfiguration section description.\fP .PP The \fIipa_conf_sect\fP structure is defined as: .PP .nf typedef struct { const char *sect_name; u_int sect_id; int arg_nargs; const char *arg_pattern; regex_t *arg_regexp; u_int arg_type; const u_int *sect_where; int (*arg_parse)(void *arg); } ipa_conf_sect; .fi .IP \fIsect_name\fP This is a name of the section. .IP \fIsect_id\fP This is a section ID, which is local for a module. This value should be greater than IPA_CONF_SECT_CUSTOM_OFFSET. .IP \fIarg_nargs\fP This is a number of arguments a section should have. Set this field to zero if a section does not expect any arguments. If a section can have variable number of arguments, then set this field to negative number, which absolute value is equal to minimal number of arguments a section should have. .IP \fIarg_pattern\fP A section's argument should match given POSIX extended regular expression. If there is not such expression, then this field should be set to NULL. .IP \fIarg_regexp\fP This is a pointer to the variable with regex_t type. If \fIarg_pattern\fP is not NULL, then this field also should not be NULL. It is possible share some regular expression between sections and parameters and do not waste memory for extra variables. In this case only one section or parameter must have valid pointer in \fIarg_pattern\fP, all others sections and parameters must set \fIarg_pattern\fP to NULL. .IP \fIarg_type\fP This is a type of the argument. There are following types: IPA_CONF_TYPE_INT32\ \ \ \ -\ int32_t; .br IPA_CONF_TYPE_UINT32\ \ \ -\ uint32_t; .br IPA_CONF_TYPE_INT64\ \ \ \ -\ int64_t; .br IPA_CONF_TYPE_UINT64\ \ \ -\ uint64_t; .br IPA_CONF_TYPE_STRING\ \ \ -\ a string; .br IPA_CONF_TYPE_BYTES\ \ \ \ -\ bytes; .br IPA_CONF_TYPE_TIME\ \ \ \ \ -\ time; .br IPA_CONF_TYPE_VALUE\ \ \ \ -\ value; .br IPA_CONF_TYPE_PER_CENT\ -\ per cent; .br IPA_CONF_TYPE_BOOLEAN\ \ -\ boolean; .br IPA_CONF_TYPE_MISC\ \ \ \ \ -\ without any format. Usually a module uses a regular expression (field \fIarg_regexp\fP) with IPA_CONF_TYPE_MISC argument type and does not use a regular expression with other argument types. IPA_CONF_TYPE_VALUE means time, bytes or uint64_t value. See below details. .IP \fIsect_where\fP This field determines where this section should be placed, it is a pointer to an array of u_int values, each value is an ID of a section, last element in this array should be equal to zero. Predefined sections IDs are follows: IPA_CONF_SECT_ROOT\ \ \ -\ no section; .br IPA_CONF_SECT_GLOBAL\ -\ the \fBglobal\fP section; .br IPA_CONF_SECT_RULE\ \ \ -\ the \fBrule\fP section; .br IPA_CONF_SECT_LIMIT\ \ -\ the \fBlimit\fP section; .br IPA_CONF_SECT_THRESHOLD\ -\ the \fBthreshold\fP section; .br IPA_CONF_SECT_AUTORULE\ -\ the \fBautorule\fP section; .br IPA_CONF_SECT_RULEPAT\ \ -\ the \fBrulepat\fP section. .IP \fIarg_parse\fP This function is called for parsing section arguments. A module can set this field to NULL if it has not any parsing function for arguments. \fIarg\fP is a pointer to some data, which depends on \fIarg_type\fP, and \fIarg_parse\fP function should perform following casts: IPA_CONF_TYPE_INT32\ \ \ -\ *(int32_t\ *)arg; .br IPA_CONF_TYPE_UINT32\ \ -\ *(uint32_t\ *)arg; .br IPA_CONF_TYPE_INT64\ \ \ -\ *(int64_t\ *)arg; .br IPA_CONF_TYPE_UINT64\ \ -\ *(uint64_t\ *)arg; .br IPA_CONF_TYPE_STRING\ \ -\ *(char\ **)arg; .br IPA_CONF_TYPE_BYTES\ \ \ -\ *(uint64_t\ *)arg; .br IPA_CONF_TYPE_TIME\ \ \ \ -\ *(uint64_t\ *)arg; .br IPA_CONF_TYPE_VALUE\ \ \ -\ *(uint64_t\ *)arg, *((uint64_t\ *)arg\ +\ 1) .br IPA_CONF_TYPE_BOOLEAN\ -\ *(int\ *)arg; .br IPA_CONF_TYPE_MISC\ \ \ \ -\ *(char\ **)arg. If \fIarg_type\fP is IPA_CONF_TYPE_STRING, then \fIarg\fP is a pointer to the allocated memory with the parsed string (whithout quote) by \fImem_malloc\fP function with \fIm_parser\fP mem_type, and a module should free this memory if it does not need it by \fImem_free\fP function. In other cases \fIarg_parse\fP function should copy any needed data and do not use data by pointers, also it is allowed to modify data \fIarg\fP points to. If \fIarg_type\fP is IPA_CONF_TYPE_MISC, then there are not white-space characters at the beginning and at the tail of \fIarg\fP, also there is only one `\ ' character between any two arguments in \fIarg\fP. If \fIarg_type\fP is IPA_CONF_TYPE_VALUE, then \fIarg\fP is a pointer to an array, first item of this array has type of value IPA_CONF_TYPE_BYTES, IPA_CONF_TYPE_TIME or IPA_CONF_TYPE_UINT64, second item has a value itself. .PP \fBConfiguration parameter description.\fP .PP The \fIipa_conf_param\fP structure is defined as: .PP .nf typedef struct { const char *param_name; int arg_nargs; const char *arg_pattern; regex_t *arg_regexp; u_int arg_type; const u_int *param_where; int (*arg_parse)(void *arg); } ipa_conf_param; .fi .IP \fIparam_name\fP This is a name of the parameter. .IP \fIarg_nargs\fP Explained above. .IP \fIarg_pattern\fP Explained above. .IP \fIarg_regexp\fP Explained above. .IP \fIarg_type\fP Explained above. .IP \fIparam_where\fP Explained above for \fIsect_where\fP. .IP \fIarg_parse\fP Explained above. .PP \fBStructure for representing dates.\fP .PP The \fIipa_tm\fP structure is defined as: .PP .nf typedef struct tm ipa_tm; .fi .PP Only following fields in the \fIipa_tm\fP structure can be used: \fItm_year\fP, \fItm_mon\fP, \fItm_mday\fP, \fItm_hour\fP, \fItm_min\fP, \fItm_sec\fP. These fields determine some local date. \fItm_year\fP is equal to the real value of the year and \fItm_mon\fP is equal to the real value of the month. .PP \fBLimit's state.\fP .PP The state of any limit is kept in the \fIipa_limit_state\fP structure: .PP .nf struct ipa_limit_state { uint64_t lim; uint64_t cnt; u_int event_date_set; ipa_tm event_date[IPA_LIMIT_EVENT_NUM]; }; .fi .IP \fIlim\fP This is a value of the \fBlimit\fP parameter. .IP \fIcnt\fP This is a value of the limit's counter. .IP \fIevent_date_set\fP This is a bits filed, which determines valid entries in \fIevent_date\fP array, each IPA_LIMIT_EVENT_xxx element in \fIevent_date\fP array has corresponding IPA_LIMIT_EVENT_xxx_SET bit in \fIevent_date_set\fP. .IP \fIevent_date\fP This is an array of limit's events dates. There are following entries in this array: IPA_LIMIT_EVENT_START\ -\ date when the limit started; IPA_LIMIT_EVENT_RESTART\ -\ date when the limit will restart or restarted; IPA_LIMIT_EVENT_RESTART_EXEC\ -\ date when commands for the restarted limit were run; IPA_LIMIT_EVENT_REACH\ -\ date when the limit reached; IPA_LIMIT_EVENT_REACH_EXEC\ -\ date when commands for the reached limit were run; IPA_LIMIT_EVENT_EXPIRE\ -\ date when the reached limit will expire and will restart or expired and restarted; IPA_LIMIT_EVENT_EXPIRE_EXEC\ -\ date when commands for the expired limit were run; IPA_LIMIT_EVENT_UPDATED\ -\ date when the limit was updated last time. .PP \fBThreshold's state.\fP .PP The state of any threshold is kept in the \fIipa_threshold_state\fP structure: .PP .nf struct ipa_threshold_state { uint64_t thr; uint64_t cnt; ipa_tm tm_from; ipa_tm tm_updated; }; .fi .IP \fIthr\fP This is a value of the \fBthreshold\fP parameter. .IP \fIcnt\fP This is a value of the threshold's counter. .IP \fItm_from\fP .IP \fItm_updated\fP Two timestamps for the threshold. .PP \fBAccounting module API.\fP .PP Accounting module API is exported by a module to an IPA utility in the \fIipa_ac_mod\fP structure: .PP .nf struct ipa_ac_mod { u_int api_ver; u_int mod_flags; const char *ac_name; const ipa_suppfunc *suppfunc; const ipa_memfunc *memfunc; const char *conf_prefix; ipa_conf_sect *conf_sect_tbl; ipa_conf_param *conf_param_tbl; int (*conf_init)(void); int (*conf_deinit)(void); int (*conf_event)(u_int event, u_int no, const void *arg); int (*conf_mimic_real)(void); int (*conf_inherit)(u_int rulepatno, u_int ruleno, const char *rule_name); void (*conf_show)(u_int sect_id, u_int no); int (*ac_pre_init)(void) int (*ac_init_autorule)(u_int autoruleno, const char *autorule_name); int (*ac_init_dynrule)(u_int autoruleno, u_int ruleno, const char *rule_name); int (*ac_init_statrule)(u_int ruleno, const char *rule_name); int (*ac_init)(void); int (*ac_deinit_rule)(u_int ruleno); int (*ac_deinit_autorule)(u_int autoruleno); int (*ac_deinit)(void); int (*ac_get_stat)(void); int (*ac_get_rule_stat)(u_int stat_generation, int newstat, u_int ruleno, int *addition, uint64_t *chunk); int (*ac_set_autorule_active)(u_int autoruleno, int active); int (*ac_set_rule_active)(u_int ruleno, int active); int (*ac_set_limit_active)(u_int ruleno, u_int limitno, int active); int (*ac_set_threshold_active)(u_int ruleno, u_int thresholdno, int active); int (*ac_limit_event)(u_int ruleno, u_int limitno, u_int event); int (*ac_threshold_event)(u_int ruleno, u_int thresholdno, u_int event); int (*ac_create_rule)(const char *mod_name, u_int autoruleno, u_int *ruleno, const char *rule_name, const char *rule_info); void (*ac_delete_rule)(const char *mod_name, u_int ruleno); }; .fi .IP \fIapi_ver\fP This is the version of the accounting module API, a module should check values of supported API versions with IPA_AC_MOD_API_VERSION during compilation. After loading a module, this version number is checked with version of used API version. .IP \fImod_flags\fP Flags, which describe module working regimes. Only one flag IPA_MOD_FLAG_PTHREAD_SAFE is defined, and it must be set if a module is thread-safe. .IP \fIac_name\fP This is a name of the module's accounting system. .IP \fIsuppfunc\fP This is a pointer to \fIipa_suppfunc\fP structure, which is exported to a module. .IP \fImemfunc\fP This is a pointer to \fIipa_memfunc\fP structure, which is exported to a module. .IP \fIconf_prefix\fP This is a configuration prefix for module's sections and parameters. .IP \fIconf_sect_tbl\fP This is a pointer to the array of the \fIipa_conf_sect\fP structures, which describe module's sections. Last item in this table should have \fIsect_name\fP equal to NULL. .IP \fIconf_param_tbl\fP This is a pointer to the array of the \fIipa_param_sect\fP structures, which describe module's parameters. Last item in this table should have \fIparam_name\fP equal to NULL. .IP \fIconf_init\fP After loading a module, this function is called. .IP \fIconf_deinit\fP After parsing a configuration file, this function is called. .IP \fIconf_event\fP This function is called each time when some configuration event occurs. \fIconf_event\fP describes a configuration event. Configuration events allows a module to know for which section its parameter or section belongs. There are following configuration events: IPA_CONF_EVENT_GLOBAL_BEGIN\ -\ the begin of the \fBglobal\fP section; IPA_CONF_EVENT_GLOBAL_END\ -\ the end of the \fBglobal\fP section; IPA_CONF_EVENT_RULE_BEGIN\ -\ the begin of the \fBrule\fP section, \fIarg\fP points to a string with the rule's name and should be casted to (const\ char\ *), \fIno\fP is an ordinal number of this section, starting from 0; IPA_CONF_EVENT_RULE_END\ -\ the end of the \fBrule\fP section; IPA_CONF_EVENT_LIMIT_BEGIN\ -\ the begin of the \fBlimit\fP section, \fIarg\fP points to a string with the limit's name and should be casted to (const\ char\ *), \fIno\fP is an ordinal number of this section in the current section, starting from 0; IPA_CONF_EVENT_LIMIT_END\ -\ the end of the \fBlimit\fP section; IPA_CONF_EVENT_THRESHOLD_BEGIN\ -\ the begin of the \fBthreshold\fP section, \fIarg\fP points to a string with the threshold's name and should be casted to (const\ char\ *), \fIno\fP is an ordinal number of this section in the current section, starting from 0; IPA_CONF_EVENT_THRESHOLD_END\ -\ the end of the \fBthreshold\fP section; IPA_CONF_EVENT_AUTORULE_BEGIN\ -\ the begin of the \fBautorule\fP section, \fIarg\fP points to a string with the autorule's name and should be casted to (const\ char\ *), \fIno\fP is an ordinal number of this section, starting from 0; IPA_CONF_EVENT_AUTORULE_END\ -\ the end of the \fBautorule\fP section; IPA_CONF_EVENT_RULEPAT_BEGIN\ -\ the begin of the \fBrulepat\fP section, \fIarg\fP points to a POSIX regular expression and should be casted to (const\ char\ *), \fIno\fP is an ordinal number of this section, starting from 0; IPA_CONF_EVENT_RULEPAT_END\ -\ the end of the \fBrulepat\fP section; IPA_CONF_EVENT_CUSTOM_SECT_BEGIN\ -\ the begin of some module's section, \fIno\fP is the ID of a module's section; IPA_CONF_EVENT_CUSTOM_SECT_END\ -\ the end of some module's section. For each IPA_CONF_EVENT_xxx_END \fIno\fP means the same as for corresponding IPA_CONF_EVENT_xxx_BEGIN. .IP \fIconf_mimic_real\fP If this function is called, then a module should mimic real configuration. .IP \fIconf_inherit\fP In this function a module should inherit all settings from the \fBrulepat\fP section number \fIrulepatno\fP for the rule number \fIruleno\fP with name \fIrule_name\fP. This function is called before \fIac_pre_init\fP, then a module should use \fIlogconferr\fP function for reporting about occurred errors, else \fIlogmsg\fP function should be used. .IP \fIconf_show\fP This function is called when IPA utility outputs the parsed configuration file. \fIsect_id\fP is the ID of a section. \fIno\fP is an ordinal number of a section with the given section ID. If a module has some configuration for this section, then it should output this configuration. A module should not directly output any configuration, instead it should use one of the functions from the \fIsuppfunc\fP structure. .IP \fIac_pre_init\fP This function is called after parsing a configuration file. A module should make general preinitialization of its accounting system. This function is always called before other \fIac_init*\fP functions. .IP \fIac_init_autorule\fP This function is called if some autorule uses a module. \fIautoruleno\fP is a number of the autorule, \fIautorule_name\fP is its name. .IP \fIac_init_dynrule\fP This function is called if some dynamic rule uses a module. \fIautoruleno\fP is a number of the autorule from which this dynamic rule was generated, \fIruleno\fP is a number of the dynamic rule, \fIrule_name\fP is its name. Data, \fIrule_name\fP points to, will exist until \fIac_deinit_rule\fP is called for this rule. This function is called when a module calls \fIac_create_rule\fP from \fIac_get_stat\fP. .IP \fIac_init_statrule\fP The same as \fIac_init_dynrule\fP but for static rules and is called after configuration phase. .IP \fIac_init\fP This function is called after all other \fIac_init*\fP functions (except \fIac_init_dynrule\fP, which is called from \fIac_create_rule\fP). .IP \fIac_deinit_rule\fP This function is called to deinitialize a rule, which uses a module. A module should not expect, that \fIac_init_*rule\fP for this rule was called before. This function is called for static and dynamic rules. .IP \fIac_deinit_autorule\fP This function is called to deinitialize an autorule, which uses a module. A module should not expect, that \fIac_init_autorule\fP was called for this autorule before. .IP \fIac_deinit\fP This function is called to deinitialize a module. A module should not expect that \fIac_*init\fP functions were called before. This function is always called after all others \fIac_deinit_*\fP functions. .IP \fIac_get_stat\fP This function is called before calls to \fIac_get_rule_stat\fP function. There is internal statistics generation number, which is changed each time when any module's \fIac_get_stat\fP function is called and its value is always greater than zero. .IP \fIac_get_rule_stat\fP This function should return statistics for the rule number \fIruleno\fP. The \fIstat_generation\fP value is the value of statistics generation number (see above for description). The \fInewstat\fP flag means, that a module should consider that this is a first invocation of this function (for example this flag is non-zero when a rule becomes active). \fIchunk\fP points to statistics returned by the module and \fI*addition\fP determines what to do with returned statistics, if it is non-zero, then returned statistics is added, else it is subtracted. Here statistics means statistics for period between two invocations of the \fIac_get_rule_stat\fP function. This function is not called if a rule which uses a module is inactive. .IP \fIac_set_autorule_active\fP This function should mark an autorule as active or inactive. If flag \fIactive\fP is equal to zero, then an autorule should be marked as inactive in a module, else an autorule should be marked as active. .IP \fIac_set_rule_active\fP The same as above, but for a rule. .IP \fIac_set_limit_active\fP The same as above, but for a limit. .IP \fIac_set_threshold_active\fP The same as above, but for a threshold. .IP \fIac_limit_event\fP This function is called when some event occurred with the limit. \fIevent\fP can be: IPA_LIMIT_EVENT_RESTART\ -\ the limit is restarted; .br IPA_LIMIT_EVENT_REACH\ \ \ -\ the limit becomes reached; .br IPA_LIMIT_EVENT_EXPIRE\ \ -\ the reached limit expires; .br IPA_LIMIT_EVENT_STARTUP_IF_REACHED\ -\ reached at startup; .br IPA_LIMIT_EVENT_STARTUP_IF_NOT_REACHED\ -\ not reached at startup; .br IPA_LIMIT_EVENT_SHUTDOWN_IF_REACHED\ -\ reached at shutdown; .br IPA_LIMIT_EVENT_SHUTDOWN_IF_NOT_REACHED\ -\ not reached at shutdown. .IP \fIac_threshold_event\fP This function is called when some event occurred with the threshold. \fIevent\fP means that threshold's counter is: IPA_THRESHOLD_EVENT_BELOW\ -\ below \fBthreshold\fP's value; .br IPA_THRESHOLD_EVENT_EQUAL\ -\ equal to \fBthreshold\fP's value; .br IPA_THRESHOLD_EVENT_ABOVE\ -\ above \fBthreshold\fP's value. .IP \fIac_create_rule\fP This function is exported to a module. A module should call this function only from the \fIac_get_stat\fP function to create a dynamic rule. \fImod_name\fP is a module's name (is used only for debugging and only in this function). \fIautoruleno\fP is a number of the autorule from which to create a dynamic rule. \fIrule_name\fP is a rule's name and \fIrule_info\fP is its description, these strings are not used by pointers, so if a module allocated memory for them, then it should release this memory itself. If everything is correct, then \fIac_init_dynrule\fP is called. This function returns 0 if a dynamic rule was created, -2 if a rule with the same name already exists and -1 if some critical error occurred, in this case a module must return -1 from \fIac_get_stat\fP. .IP \fIac_delete_rule\fP This function is exported to a module. A module should call this function only from the \fIac_get_stat\fP function to delete a dynamic rule number \fIruleno\fP previously created by the \fIac_create_rule\fP function. \fImod_name\fP is a module's name (is used only for debugging and only in this function). At some point the \fIac_deinit_rule\fP is called for the given rule. If everything is correct, then this functions returns 0. If there were problems with the deinitialization, then -1 should be returned, in this case a module must return -1 from \fIac_get_stat\fP. .PP If some function, except \fIac_create_rule\fP, returns integer value, then it should return the value -1 if an error occurred, else zero should be returned. .PP If a module does not support some function for dynamic or static rule, for autorules, for limits or thresholds, then it should set corresponding field to NULL. .PP If some function is exported to a module, then corresponding field in API structure can be set to any value (usually NULL). .PP \fBDatabase module API.\fP .PP Database module API is exported by a module to an IPA utility in the \fIipa_db_mod\fP structure: .PP .nf struct ipa_db_mod { u_int api_ver; u_int mod_flags; const char *db_name; const ipa_suppfunc *suppfunc; const ipa_memfunc *memfunc; const char *conf_prefix; ipa_conf_sect *conf_sect_tbl; ipa_conf_param *conf_param_tbl; int (*conf_init)(void); int (*conf_deinit)(void); int (*conf_event)(u_int event, u_int no, const void *arg); int (*conf_mimic_real)(void); int (*conf_inherit)(u_int rulepatno, u_int ruleno, const char *rule_name); void (*conf_show)(u_int sect_id, u_int no); int (*db_pre_init)(void); int (*db_init_dynrule)(u_int autoruleno, u_int ruleno, const char *rule_name, const char *rule_info); int (*db_init_statrule)(u_int ruleno, const char *rule_name, const char *rule_info); int (*db_init_dynlimit)(u_int autoruleno, u_int ruleno, const char *rule_name, const char *rule_info, u_int limitno, const char *limit_name, const char *limit_info); int (*db_init_statlimit)(u_int ruleno, const char *rule_name, const char *rule_info, u_int limitno, const char *limit_name, const char *limit_info); int (*db_init_dynthreshold)(u_int autoruleno, u_int ruleno, const char *rule_name, const char *rule_info, u_int thresholdno, const char *threshold_name, const char *threshold_info); int (*db_init_statthreshold)(u_int ruleno, const char *rule_name, const char *rule_info, u_int thresholdno, const char *threshold_name, const char *threshold_info); int (*db_init)(void); int (*db_get_limit_state)(u_int ruleno, u_int limitno, struct ipa_limit_state *state); int (*db_set_limit_state)(u_int ruleno, u_int limitno, const struct ipa_limit_state *state, int new_state); int (*db_get_threshold_state)(u_int ruleno, u_int thresholdno, struct ipa_threshold_state *state); int (*db_set_threshold_state)(u_int ruleno, u_int thresholdno, const struct ipa_threshold_state *state); int (*db_deinit_threshold)(u_int ruleno, u_int thresholdno); int (*db_deinit_limit)(u_int ruleno, u_int limitno); int (*db_deinit_rule)(u_int ruleno); int (*db_deinit)(void); int (*db_append_rule)(u_int ruleno, const uint64_t *cnt, const ipa_tm *ctm); int (*db_update_rule)(u_int ruleno, const uint64_t *cnt, const ipa_tm *ctm); int (*db_update_limit)(u_int ruleno, u_int limitno, const uint64_t *value, const ipa_tm *ctm); int (*db_limit_event)(u_int ruleno, u_int limitno, u_int event, const ipa_tm *etm, const ipa_tm *ctm); int (*db_update_threshold)(u_int ruleno, u_int thresholdno, const uint64_t *cnt, const ipa_tm *tm_from, const ipa_tm *tm_updated); int (*db_set_rule_active)(u_int ruleno, int active); int (*db_set_limit_active)(u_int ruleno, u_int limitno, int active); int (*db_set_threshold_active)(u_int ruleno, u_int thresholdno, int active); } .fi .IP \fIapi_ver\fP This is the version of the database module API, a module should check values of supported API versions with IPA_DB_MOD_API_VERSION during compilation. After loading a module, this version number is checked with version of used API version. .IP \fImod_flags\fP Explained above. .IP \fIdb_name\fP This is a name of the module's database. .IP \fIsuppfunc\fP Explained above. .IP \fImemfunc\fP Explained above. .IP \fIconf_prefix\fP Explained above. .IP \fIconf_sect_tbl\fP Explained above. .IP \fIconf_param_tbl\fP Explained above. .IP \fIconf_init\fP Explained above. .IP \fIconf_deinit\fP Explained above. .IP \fIconf_event\fP Explained above. .IP \fIconf_mimic_real\fP Explained above. .IP \fIconf_inherit\fP Explained above. .IP \fIconf_show\fP Explained above. .IP \fIdb_pre_init\fP This function is called after parsing a configuration file. A module should make general initialization of its database. This function always is called before other \fIdb_init*\fP functions. .IP \fIdb_init_dynrule\fP This function is called if some dynamic rule uses a module. \fIautoruleno\fP is a number of the autorule from which this dynamic rule was generated, \fIruleno\fP is a number of the dynamic rule, \fIrule_name\fP is its name and \fIrule_info\fP is its description. Only data, \fIrule_name\fP points to, will exist until \fIdb_deinit_rule\fP is called for this rule. .IP \fIdb_init_statrule\fP The same as \fIdb_init_dynrule\fP but for static rules. .IP \fIdb_init_dynlimit\fP This function is called if some limit from a dynamic rule uses a module. \fIlimitno\fP is an ordinal number of the limit in the rule, \fIlimit_name\fP is its name and \fIlimit_info\fP is its description. Rest of arguments means the same as in \fIdb_init_dynrule\fP. Only data, \fIrule_name\fP and \fIlimit_name\fP point to, will exist until \fIdb_deinit_limit\fP is called for this limit. Since a rule can use another database, than its limits use, then a module should not expect that \fIdb_init_dynrule\fP was called before for a limit's rule. If a limit's rule uses this module too, then \fIdb_init_dynrule\fP for a rule is called first. .IP \fIdb_init_statlimit\fP The same as \fIdb_init_dynlimit\fP but for limits from static rules. .IP \fIdb_init_dynthreshold\fP This function is called if some threshold from a dynamic rule uses a module. \fIthresholdno\fP is an ordinal number of the threshold in the rule, \fIthreshold_name\fP is its name and \fIthreshold_info\fP is its description. Rest of arguments means the same as in \fIdb_init_dynrule\fP. Only data, \fIrule_name\fP and \fIthreshold_name\fP point to, will exist until \fIdb_deinit_threshold\fP is called for this threshold. Since a rule can use another database, than its thresholds use, then a module should not expect that \fIdb_init_dynrule\fP was called before for a threshold's rule. If a threshold's rule uses this module too, then \fIdb_init_dynrule\fP for a rule is called first. .IP \fIdb_init_statthreshold\fP The same as \fIdb_init_dynthreshold\fP but for thresholds from static rules. .IP \fIdb_init\fP This function is called after all other \fIdb_init_stat*\fP functions. .IP \fIdb_get_limit_state\fP This function should return the current state of the limit. If a module does not have current state for the limit (for example for the new limit), then the \fIlim\fP field in \fIstate\fP should be set to zero. .IP \fIdb_set_limit_state\fP This function should set a new state for the limit. If \fInew_state\fP is zero, then current limit's state in the database should be updated, else a new limit's state should be registered. .IP \fIdb_get_threshold_state\fP This function should return the current state of the threshold. If a module does not have current state for the threshold (for example for the new threshold), then the \fIthr\fP field in \fIstate\fP should be set to zero. .IP \fIdb_set_threshold_state\fP This function should update the current state for the threshold. .IP \fIdb_deinit_threshold\fP This function is called to deinitialize a threshold, which uses a module. A module should not expect, that \fIdb_init_*threshold\fP was called for this threshold before. .IP \fIdb_deinit_limit\fP This function is called to deinitialize a limit, which uses a module. A module should not expect, that \fIdb_init_*limit\fP was called for this limit before. .IP \fIdb_deinit_rule\fP This function is called to deinitialize a rule, which uses a module. If some of rule's limits or thresholds use this module too, then \fIdb_deinit_limit\fP or \fIdb_deinit_threshold\fP is called first. A module should not expect, that \fIdb_init_*rule\fP for this rule was called before. .IP \fIdb_deinit\fP This function is called to deinitialize a module. A module should not expect that \fIdb_*init\fP functions were called before. This function is always called after all other \fIdb_deinit_*\fP functions. .IP \fIdb_append_rule\fP This function should append a new record for the given rule. \fIcnt\fP is a pointer to a new value of the rule's counter. \fIctm\fP is the current local date. This function is called before first call of the \fIdb_update_rule\fP function. .IP \fIdb_update_rule\fP This function should update a database record for the given rule. \fIcnt\fP is a pointer to a new value of the rule's counter, \fIctm\fP is the current local date. .IP \fIdb_update_limit\fP This function should update a state of the limit in the database. \fIcnt\fP is a pointer to a new value of the counter, \fIctm\fP is the current local date. IPA_LIMIT_EVENT_UPDATED date should be also updated by a module. .IP \fIdb_limit_event\fP This function should register an event \fIevent\fP for the limit in the database. The given event can take place right now or in future. \fIetm\fP is the local date of the given event and \fIctm\fP is the current local date. IPA_LIMIT_EVENT_UPDATED date should be also updated by a module. This function is called only for following limit's events IPA_LIMIT_EVENT_: RESTART_EXEC, REACH, REACH_EXEC, EXPIRE and EXPIRE_EXEC. .IP \fIdb_update_threshold\fP This function should update a state of the threshold in the database. \fIcnt\fP is a pointer to a new value of the counter, \fItm_from\fP and \fItm_updated\fP are two timestamps for the threshold. .IP \fIdb_set_rule_active\fP Explained above in \fIac_set_rule_active\fP. When a rule is marked as active, then \fIdb_append_rule\fP will be called before \fIdb_update_rule\fP. .IP \fIdb_set_limit_active\fP Explained above in \fIac_set_limit_active\fP. .IP \fIdb_set_threshold_active\fP Explained above in \fIac_set_threshold_active\fP. .PP If some function returns integer value, then it should return the value -1 if an error occurred, else zero should be returned. .PP If a database module does not support dynamic rules, limits or thresholds, then it should set corresponding \fIdb_init_dyn*\fP fields to NULL. If a database module does not support static rules, limits or thresholds, then set corresponding \fIdb_init_stat*\fP fields to NULL. .PP If a database module does not support \fIdb_get_limit_state\fP, \fIdb_get_threshold_state\fP, \fIdb_set_*active\fP function, then set corresponding field to NULL. .PP If some function is exported to a module, then corresponding field in API structure can be set to any value (usually NULL). .PP \fBStatistics module API.\fP .PP Statistics module API is exported by a module to an IPA utility in the \fIipa_st_mod\fP structure: .PP .nf struct ipa_entity_desc { char *name; char *info; }; struct ipa_rule_stat { u_int year; unsigned char mon; unsigned char mday; unsigned char h1, m1, s1; unsigned char h2, m2, s2; uint64_t cnt; }; struct ipa_st_mod { u_int api_ver; u_int mod_flags; const char *st_name; const ipa_suppfunc *suppfunc; const ipa_memfunc *memfunc; const char *conf_prefix; ipa_conf_sect *conf_sect_tbl; ipa_conf_param *conf_param_tbl; int (*conf_init)(void); int (*conf_deinit)(void); int (*conf_event)(u_int event, u_int no, const void *arg); int (*conf_mimic_real)(void); int (*conf_inherit)(u_int rulepatno, u_int ruleno, const char *rule_name); void (*conf_show)(u_int sect_id, u_int no); int (*st_pre_init)(void); int (*st_init_rule)(u_int ruleno, const char *rule_name); int (*st_init_limit)(u_int ruleno, const char *rule_name, u_int limitno, const char *limit_name); int (*st_init_threshold)(u_int ruleno, const char *rule_name, u_int thresholdno, const char *threshold_name); int (*st_init)(void); int (*st_deinit_threshold)(u_int ruleno, u_int thresholdno); int (*st_deinit_limit)(u_int ruleno, u_int limitno); int (*st_deinit_rule)(u_int ruleno); int (*st_deinit)(void); int (*st_get_rule_info)(u_int ruleno, ipa_mem_type *mem_type, char **infop); int (*st_get_limit_info)(u_int ruleno, u_int limitno, ipa_mem_type *mem_type, char **infop); int (*st_get_threshold_info)(u_int ruleno, u_int thresholdno, ipa_mem_type *mem_type, char **infop); int (*st_get_rules_list)(const char *pat, const regex_t *pat_reg, ipa_mem_type *mem_type, u_int *n, struct ipa_entity_desc **bufp); int (*st_get_limits_list)(u_int ruleno, const char *pat, const regex_t *pat_reg, ipa_mem_type *mem_type, u_int *n, struct ipa_entity_desc **bufp); int (*st_get_thresholds_list)(u_int ruleno, const char *pat, const regex_t *pat_reg, ipa_mem_type *mem_type, u_int *n, struct ipa_entity_desc **bufp); int (*st_get_rule_stat)(u_int ruleno, const ipa_tm *tm1, const ipa_tm *tm2, int exact, ipa_mem_type *mem_type, u_int *n, struct ipa_rule_stat **bufp); int (*st_get_limit_stat)(u_int ruleno, u_int limitno, const ipa_tm *tm1, const ipa_tm *tm2, ipa_mem_type *mem_type, u_int *n, struct ipa_limit_state **bufp); int (*st_get_threshold_stat)(u_int ruleno, u_int thresholdno, struct ipa_threshold_state *buf); }; .fi .IP \fIapi_ver\fP This is the version of the statistics module API, a module should check values of supported API versions with IPA_ST_MOD_API_VERSION during compilation. After loading a module, this version number is checked with version of used API version. .IP \fImod_flags\fP Explained above. .IP \fIst_name\fP This is a name of the module's statistics system. .IP \fIsuppfunc\fP Explained above. .IP \fImemfinc\fP Explained above. .IP \fIconf_prefix\fP Explained above. .IP \fIconf_sect_tbl\fP Explained above. .IP \fIconf_param_tbl\fP Explained above. .IP \fIconf_init\fP Explained above. .IP \fIconf_deinit\fP Explained above. .IP \fIconf_event\fP Explained above. .IP \fIconf_mimic_real\fP Explained above. .IP \fIconf_inherit\fP Explained above. .IP \fIconf_show\fP Explained above. .IP \fIst_pre_init\fP This function is called after parsing a configuration file. A module should make general initialization of its statistics system. This function always is called before other \fIst_init*\fP functions. .IP \fIst_init_rule\fP This function is called if a rule uses a module. \fIruleno\fP is a number of the rule, \fIrule_name\fP is its name. Data, \fIrule_name\fP points to, will exist until \fIst_deinit_rule\fP is called for this rule. This function can be called for a rule which has corresponding section in the configuration file, and for a rule which was generated on-the-fly (can be considered as a dynamic rule). .IP \fIst_init_limit\fP This function is called if some limit from a rule uses a module. \fIlimitno\fP is an ordinal number of the limit in the rule, \fIlimit_name\fP is a its name. Only data, \fIrule_name\fP and \fIlimit_name\fP point to, will exist until \fIst_deinit_limit\fP is called for this limit. Since a rule can use another statistics system, than its limits use, then a module should not expect that \fIst_init_rule\fP was called before for a limit's rule. If a limit's rule uses this module too, then \fIst_init_rule\fP for a limit's rule is called first. Like \fIst_init_rule\fP this function can be called for a rule and/or a limit which has corresponding section in the configuration file, and for a rule and/or limit which was generated on-the-fly (can be considered as a dynamic rule and/or a limit). .IP \fIst_init_threshold\fP This function is called if some threshold from a rule uses a module. \fIthresholdno\fP is an ordinal number of the threshold in the rule, \fIthreshold_name\fP is a its name. Only data, \fIrule_name\fP and \fIthreshold_name\fP point to, will exist until \fIst_deinit_threshold\fP is called for this threshold. Since a rule can use another statistics system, than its thresholds use, then a module should not expect that \fIst_init_rule\fP was called before for a threshold's rule. If a threshold's rule uses this module too, then \fIst_init_rule\fP for a threshold's rule is called first. Like \fIst_init_rule\fP this function can be called for a rule and/or a threshold which has corresponding section in the configuration file, and for a rule and/or threshold which was generated on-the-fly (can be considered as a dynamic rule and/or a threshold). .IP \fIst_init\fP This function is called after all other \fIst_init*\fP functions. .IP \fIst_deinit_threshold\fP This function is called to deinitialize a threshold, which uses a module. A module should not expect, that \fIst_init_threshold\fP was called for this threshold before. .IP \fIst_deinit_limit\fP This function is called to deinitialize a limit, which uses a module. A module should not expect, that \fIst_init_limit\fP was called for this limit before. .IP \fIst_deinit_rule\fP This function is called to deinitialize a rule, which uses a module. If some of rule's limits or thresholds use this module too, then \fIst_deinit_limit\fP or \fIst_deinit_threshold\fP is called for such rule's limits or thresholds before. A module should not expect, that \fIst_init_rule\fP for this rule was called before. .IP \fIst_deinit\fP This function is called to deinitialize a module. A module should not expect that \fIst_*init\fP functions were called before. This function is always called after all other \fIst_deinit_*\fP functions. .IP \fIst_get_rule_info\fP This function should return a description for the rule number \fIruleno\fP, pointer to a rule's description should be returned in \fI*infop\fP. If a rule does not have a description, then \fI*infop\fP should be set to NULL. .IP \fIst_get_limit_info\fP The same as \fIst_get_rule_info\fP, but for a limit. .IP \fIst_get_threshold_info\fP The same as \fIst_get_rule_info\fP, but for a threshold. .IP \fIst_get_rules_list\fP This function should return an array with rules names and descriptions. If the POSIX regular expression \fIpat\fP is not NULL, then a module should return only rules, with names which matched this regular expression (\fIpat_reg\fP is a compiled regular expression \fIpat\fP). The pointer to the array of \fIstruct\ ipa_entity_desc\fP should be returned in \fI*bufp\fP, number of entries in this array should be returned in \fI*n\fP. If number of entries is equal to zero, then \fI*bufp\fP must be NULL. .IP \fIst_get_limits_list\fP The same as \fIst_get_rules_list\fP, buf for limits. .IP \fIst_get_thresholds_list\fP The same as \fIst_get_rules_list\fP, buf for thresholds. .IP \fIst_get_rule_stat\fP This function is used for querying statistics for a rule number \fIruleno\fP for time interval from \fItm1\fP till \fItm2\fP. If \fIexact\fP is zero, then both of rule's records timestamps should be inside the given time interval, else only one of rule's records timestamps should be inside the given time interval. The pointer to the array of \fIstruct\ ipa_rule_stat\fP should be returned in \fI*bufp\fP, number of entries in this array should be returned in \fI*n\fP. If number of entries is equal to zero, then \fI*bufp\fP must be NULL. Structure \fIstruct\ ipa_rule_stat\fP represents statistics of one rule's record. In \fIstruct\ ipa_rule_stat\fP fields \fIyear\fP, \fImon\fP and \fImday\fP specify date of both timestamps of a rule's record (a new record for any rule is always appended for a new day, that's why it is enough only these three fields for dates of both timestamps). \fIt1\fP, \fIm1\fP and \fIs1\fP is time of first timestamp; \fIt2\fP, \fIm2\fP and \fIs2\fP is time of second timestamp. \fIcnt\fP is statistics for the time interval in one rule's record. .IP \fIst_get_limit_stat\fP This function is used for querying statistics for a limit number \fIlimitno\fP in a rule number \fIruleno\fP, dates when a limit was started should be in time interval from \fItm1\fP till \fItm2\fP. The pointer to the array of \fIstruct\ ipa_limit_state\fP should be returned in \fI*bufp\fP, number of entries in this array should be returned in \fI*n\fP. If number of entries is equal to zero, then \fI*bufp\fP must be NULL. If \fItm1\fP is NULL, then current limit state should be returned. If a module does not have current state for the limit, then it should set the \fIlim\fP field in \fI*bufp\fP entry to zero. .IP \fIst_get_threshold_stat\fP This function is used for querying current state for a threshold number \fIthresholdno\fP in a rule number \fIruleno\fP. If a module does not have current state for the threshold, then it should set the \fIthr\fP field in \fIbuf\fP to zero. .PP If some function returns integer value, then it should return the value -1 if an error occurred, else zero should be returned. .PP If a statistics module does not support some functions, which query statistics or description, then set corresponding fields to NULL. .PP If some function accepts \fImem_type\fP argument, then all allocated data being returned by this function should be allocated with the help from \fIipa_memfunc\fP functions with the given \fImem_type\fP. .PP If some function is exported to a module, then corresponding field in API structure can be set to any value (usually NULL). .SH SEE ALSO ipa(8), ipactl(8), ipastat(8), ipa.conf(5), ipastat.conf(5) .SH AUTHOR Andrey\ Simonenko\ .SH BUGS If you find any, please send email me.