FreeBSD Manual Pages
IPA_MOD(3) Library Functions Manual IPA_MOD(3) NAME ipa_mod -- IPA modules APIs SYNOPSIS #include <ipa_mod.h> DESCRIPTION This manual page describes API of IPA modules. Let's call any IPA mod- ule simply ``a module''. Information given in this manual page is mainly for developers, but it can be interesting for anybody who wishes to understand how IPA utilities work with IPA modules. This manual page has descriptions of the following APIs: ipa_memfunc API version 1 (IPA_MEMFUNC_API_VERSION); ipa_ac_mod API version 2 (IPA_AC_MOD_API_VERSION); ipa_db_mod API version 2 (IPA_DB_MOD_API_VERSION); ipa_st_mod API version 2 (IPA_ST_MOD_API_VERSION). Module's symbols naming Any module is stored in a file with the name like foobar-x.y.z.so. Af- ter 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 foobar_ac_mod, foobar_db_mod or foo- bar_st_mod 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. Then found (void *) pointer to a symbol is converted to one of three (struct ipa_XX_mod *) pointers. Structures ipa_XX_mod determine APIs between IPA utilities and modules. 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. Single-threaded and multi-threaded modules Any module can be single-threaded or multi-threaded. If a module does not block in its functions, then it can be built as single-threaded. If a module can block in some of its functions or if a module needs 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. 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. 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 time- stamps of statistics and reaction on some planned events will be not very accurate in IPA utilities. 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. 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 ipa_memfunc, which is exported by IPA utilities to modules, become thread-safe. Modules are allowed to create threads only after the configuration phase. Exported memory allocation functions for a module Modules APIs require some type of organization of data in modules. ipa_memfunc functions are exported to a module and try 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 re- quired to use functions from ipa_memfunc. There are four types of functions from ipa_memfunc: initialization and deinitialization functions, functions for general purpose memory allo- cation, functions for working with mzones and functions for working with marrays. Functions mem_* for general purpose memory allocation are wrappers for standard library memory allocation functions malloc(3), calloc(3), re- alloc(3), free(3), strdup(3) and for vasprintf(3) function, found on some systems. Any memory allocated with some of mem_* functions should be freed with mem_free function. These functions accept extra one ar- gument, called mem_type (memory type), which is used for collecting statistics about memory usage. This mem_type should be created by the mem_type_new function. Marrays (memory arrays) are used for creating arrays of items. Mzones (memory zones) are used for creating items of the same size. All mar- ray_* and mzone_* functions internally use mem_* memory allocation functions. Functions from ipa_memfunc detect wrong pointers and incorrect argu- ments in mem_*, marray_* and mzone_* functions. If some critical error is found in any of these functions, then this function terminates exe- cution of a program and a core dump is generated. If IPA utilities were built with defined WITH_MEMFUNC_DEBUG macro vari- able, 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 mem_realloc in this case is equivalent to malloc(3) new memory area, memcpy(3) data to new mem- ory area, free(3) old memory area. 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. The ipa_memfunc has following format: 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 { unsigned 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, unsigned 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 **buf_ptr, 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, unsigned int flags, void **arr, size_t isize, unsigned int nitems, unsigned int nalloc); void (*marray_deinit)(ipa_marray *marray); int (*marray_alloc)(ipa_marray *marray, unsigned int *idxp, int fixed); void (*marray_free)(ipa_marray *marray, unsigned int idx); void (*marray_minimize)(ipa_marray *marray); int (*marray_check_index)(ipa_marray *marray, unsigned int idx); unsigned int (*marray_nused)(ipa_marray *marray); ipa_mzone *(*mzone_init)(const char *name, const char *desc, unsigned int flags, size_t isize, unsigned int nitems, unsigned int nalloc); void (*mzone_deinit)(ipa_mzone *mzone); void *(*mzone_alloc)(ipa_mzone *mzone); void (*mzone_free)(ipa_mzone *mzone, void *ptr); unsigned int (*mzone_nused)(ipa_mzone *mzone); } ipa_memfunc; api_ver Version of the ipa_memfunc API, a module should check values of supported API versions with IPA_MEMFUNC_API_VERSION during com- pilation. memfunc_init A child of a module can call this function to initialize all other ipa_memfunc functions. memfunc_deinit A child of a module can call this function to free all memory allocated in mzones and marrays, and deinitialize all other ipa_memfunc own structures. If foreign flag is non-zero, then all messages about memory leaks will be suppressed and statis- tics about memory usage will be flushed. Note that this and previous functions can be called only in a child of some module. m_parser This is a pointer to mem_type used by a parser to allocate mem- ory during configuration file parsing. mem_type_new Create new mem_type, name is a short name for new mem_type, desc is its description (usually several words). name and desc should exist until marray is deinitialized. flags are ORed flags for new mem_type. Currently only one flag IPA_MEM- FUNC_FLAG_PTHREAD is defined, which should be set if memory of this mem_type will be allocated or freed by several threads asynchronously. This function returns a pointer to new mem_type or NULL if an error occurred. mem_malloc Analogous to malloc(3). mem_calloc Analogous to calloc(3). mem_realloc Analogous to realloc(3). mem_strdup Analogous to strdup(3). mem_vasprintf Analogous to vasprintf(3) found on some systems. This function sets *buf_ptr to be a pointer to a buffer sufficiently large to hold the formatted string and returns the number of characters in a buffer (not including the trailing `\0'). If sufficient space cannot be allocated, this function will return -1 and set *buf_ptr to be a NULL pointer. format and ap are the same argu- ments as for vprintf(3). mem_free Analogous to free(3). marray_init Create marray, name is a name of marray, desc is its description (usually several words). name and desc should exist until mar- ray is deinitialized. flags determines ORed flags for new mar- ray, currently only one flag IPA_MEMFUNC_FLAG_PTHREAD is de- fined, this flag must be set if items from this marray can be allocated and freed by several threads asynchronously. arr is a pointer where to store the pointer to the actual array of items. isize is a size of one item in marray. nitems means number of items to allocate initially. nalloc 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 oc- curred. Note that the pointer saved in memory pointed by arr can be changed by next marray_alloc and marray_free functions calls. marray_deinit Release memory used by marray. 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 marray is NULL, then this function does nothing. marray_alloc Allocate a new item in marray. If fixed is non-zero, then *idxp should be a desired index number of a new item in marray, else this function will allocate an item with the lowest possible un- used index number and save this index number in *idxp. This function returns 0 if a new item was allocated and -1 if an er- ror occurred. Usually a module calls this function with non- zero value of the fixed argument. marray_free Return previously allocated item with index idx to marray. marray_minimize Try to minimize memory used by marray. Such minimization is possible because marray_alloc and marray_free try to keep extra memory for future items allocations. marray_check_index This function checks whether an item with the idx index was al- located previously in marray. If an item was allocated, then 0 is returned, else non-zero value is returned. marray_nused Return number of allocated items in marray. mzone_init Create mzone, name is a name of mzone, desc is its description (usually several words). name and desc should exist until mar- ray is deinitialized. flags means the same as in marray_init function, mzone also accepts IPA_MEMFUNC_FLAG_OPTIMIZE, this flag should be set if it will be many items in mzone. isize is a size of one item in mzone. nitems means number of items to allocate initially. nalloc 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. mzone_deinit Release memory used by mzone. 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 mzone is NULL, then this function does nothing. mzone_alloc Allocate a new item from mzone. This function returns a pointer to a new item or NULL if an error occurred. mzone_free Return previously allocated item pointed by ptr to mzone. mzone_nused Return number of allocated items from mzone. Exported support functions for a module 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 mes- sage. Since a module does not know how to do this, an IPA utility, which uses this module, exports ipa_suppfunc functions to a module: 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, unsigned int value_type); void (*print_boolean)(int value); void (*print_space)(void); 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)(const char *sym); int (*global_sym_add)(char *sym, char *val, int copy_flag); int (*global_sym_del)(const char *sym); } ipa_suppfunc; print_string This function prints a string with quotes. print_bytes This function prints bytes value. print_time This function prints time value. print_value This function prints bytes, time or 64-bit unsigned number if value_type is IPA_CONF_TYPE_BYTES, IPA_CONF_TYPE_TIME or IPA_CONF_TYPE_UINT64 respectively. print_boolean This function prints boolean value. print_space This function prints one space character if it was not printed yet. print_param_name This function outputs a parameter's name param with configura- tion prefix prefix. If a parameter does not have a configura- tion prefix, then prefix should be NULL. print_param_args This vprintf(3)-like function outputs parameter's arguments. It can be invoked several times for the same parameter. print_param_end This function should be called after outputting all parameter's arguments. print_sect_name This function outputs a section's name sect with configuration prefix prefix. If a section does not have a configuration pre- fix, then prefix should be NULL. print_sect_args This vprintf(3)-like function outputs section's arguments. It can be invoked several times for the same section. print_sect_begin This function should be called after outputting all section's arguments. print_sect_end This function should be called at the end of a module's section. open_log, close_log If a module needs to fork another process, then that process can use logmsg function (described below), but if it needs to close some descriptors and then use log system again, then it should call close_log and then open_log function. Creation of the file descriptor for sending log messages is delayed until the first message is sent. logmsg A module should use this function for sending log messages from any part of its code, but not from configuration file parsing functions. mod_name is a module's name. priority is a priority of the message: IPA_LOG_INFO, IPA_LOG_WARNING or IPA_LOG_ERR. code is the errno(2) value or 0 if there is not any error condi- tion. format and ap are vprintf(3)-like arguments. logconferr A module should use this function for sending messages about er- rors during configuration file parsing. Arguments means the same as for logmsg function. local_sym_add Create a local macro variable with name sym and value val, if copy_flag is non-zero, then memory will be allocated and sym and val will be copied to it, else original pointers will be used. This function returns 0 if a macro variable was created and -1 if memory could not be allocated. local_sym_del Delete a local macro variable with name sym. If there is no lo- cal 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 local_sym_add function, because an IPA utility automatically handles this. global_sym_add Like local_sym_add, but for global macro variables. global_sym_del Like local_sym_del, but for global macro variables. Configuration section description The ipa_conf_sect structure is defined as: typedef struct { const char *sect_name; unsigned int sect_id; int arg_nargs; const char *arg_pattern; regex_t *arg_regexp; unsigned int arg_type; const unsigned int *sect_where; int (*arg_parse)(void *arg); } ipa_conf_sect; sect_name This is a name of the section. sect_id This is a section ID, which is local for a module. This value should be greater than IPA_CONF_SECT_CUSTOM_OFFSET. arg_nargs 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 mini- mal number of arguments a section should have. arg_pattern A section's argument should match the given extended POSIX regu- lar expression. If there is not such expression, then this field should be set to NULL. arg_regexp This is a pointer to the variable with regex_t type. if arg_pattern is not NULL, then this field also should not be NULL. It is possible share some regular expression between sec- tions and parameters and do not waste memory for extra vari- ables. In this case only one section or parameter must have valid pointer in arg_pattern, all others sections and parameters must set arg_pattern to NULL. arg_type This is a type of the argument. There are following types: IPA_CONF_TYPE_INT32 - int32_t; IPA_CONF_TYPE_UINT32 - uint32_t; IPA_CONF_TYPE_INT64 - int64_t; IPA_CONF_TYPE_UINT64 - uint64_t; IPA_CONF_TYPE_STRING - a string; IPA_CONF_TYPE_BYTES - bytes; IPA_CONF_TYPE_TIME - time; IPA_CONF_TYPE_VALUE - value; IPA_CONF_TYPE_PER_CENT - per cent; IPA_CONF_TYPE_BOOLEAN - boolean; IPA_CONF_TYPE_MISC - without any format. Usually a module uses a regular expression (field arg_regexp) 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. sect_where This field determines where this section should be placed, it is a pointer to an array of 'unsigned 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; IPA_CONF_SECT_GLOBAL - the global section; IPA_CONF_SECT_RULE - the rule section; IPA_CONF_SECT_LIMIT - the limit section; IPA_CONF_SECT_THRESHOLD - the threshold section; IPA_CONF_SECT_AUTORULE - the autorule section; IPA_CONF_SECT_RULEPAT - the rulepat section; IPA_CONF_SECT_RESTART - the restart section; IPA_CONF_SECT_REACH - the reach section; IPA_CONF_SECT_EXPIRE - the expire section; IPA_CONF_SECT_STARTUP - the startup section; IPA_CONF_SECT_SHUTDOWN - the shutdown section; IPA_CONF_SECT_IF_REACHED - the if_reached section; IPA_CONF_SECT_IF_NOT_REACHED - the if_not_reached section; IPA_CONF_SECT_IF_ALL_REACHED - the if_all_reached section; IPA_CONF_SECT_IF_ANY_REACHED - the if_any_reached section; IPA_CONF_SECT_IF_ALL_NOT_REACHED - the if_all_not_reached section; IPA_CONF_SECT_IF_ANY_NOT_REACHED - the if_any_not_reached section; IPA_CONF_SECT_BELOW_THRESHOLD - the below_threshold section; IPA_CONF_SECT_EQUAL_THRESHOLD - the equal_threshold section; IPA_CONF_SECT_ABOVE_THRESHOLD - the above_threshold section. arg_parse 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. arg is a pointer to some data, which depends on arg_type, and arg_parse function should perform following casts: IPA_CONF_TYPE_INT32 - *(int32_t *)arg; IPA_CONF_TYPE_UINT32 - *(uint32_t *)arg; IPA_CONF_TYPE_INT64 - *(int64_t *)arg; IPA_CONF_TYPE_UINT64 - *(uint64_t *)arg; IPA_CONF_TYPE_STRING - *(char **)arg; IPA_CONF_TYPE_BYTES - *(uint64_t *)arg; IPA_CONF_TYPE_TIME - *(uint64_t *)arg; IPA_CONF_TYPE_VALUE - *(uint64_t *)arg, *((uint64_t *)arg + 1); IPA_CONF_TYPE_BOOLEAN - *(int *)arg; IPA_CONF_TYPE_MISC - *(char **)arg. If arg_type is IPA_CONF_TYPE_STRING, then arg is a pointer to the allocated memory with the parsed string (whithout quotes) by mem_malloc function with m_parser mem_type, and a module should free this memory if it does not need it by mem_free function. In other cases arg_parse function should copy any needed data and do not use data by pointers, also it is allowed to modify data arg points to. If arg_type is IPA_CONF_TYPE_MISC, then there are not space characters at the beginning and at the tail of arg, also there is only one ` ' character between any two ar- guments in arg. If arg_type is IPA_CONF_TYPE_VALUE, then arg 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. Configuration parameter description The ipa_conf_param structure is defined as: typedef struct { const char *param_name; int arg_nargs; const char *arg_pattern; regex_t *arg_regexp; unsigned int arg_type; const unsigned int *param_where; int (*arg_parse)(void *arg); } ipa_conf_param; param_name This is a name of the parameter. arg_nargs Explained above. arg_pattern Explained above. arg_regexp Explained above. arg_type Explained above. param_where Explained above for sect_where. arg_parse Explained above. Structure for representing dates The ipa_tm structure is defined as: typedef struct tm ipa_tm; Only following fields in the ipa_tm structure can be used: tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec and tm_wday. These fields de- termine some local date. tm_year is equal to the real value of the year and tm_mon is equal to the real value of the month. Limit's state The state of any limit is kept in the ipa_limit_state structure: struct ipa_limit_state { uint64_t lim; uint64_t cnt; unsigned int event_date_set; ipa_tm event_date[IPA_LIMIT_EVENT_NUM]; }; lim This is a value of the limit parameter. cnt This is a value of the limit's counter. event_date_set This is a bits filed, which determines valid entries in event_date array, each IPA_LIMIT_EVENT_xxx element in event_date array has corresponding IPA_LIMIT_EVENT_xxx_SET bit in event_date_set. event_date 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. Threshold's state The state of any threshold is kept in the ipa_threshold_state struc- ture: struct ipa_threshold_state { uint64_t thr; uint64_t cnt; ipa_tm tm_from; ipa_tm tm_updated; }; thr This is a value of the threshold parameter. cnt This is a value of the threshold's counter. tm_from, tm_updated Two timestamps for the threshold. Accounting module API Accounting module API is exported by a module to an IPA utility in the ipa_ac_mod structure: struct ipa_ac_mod { unsigned int api_ver; unsigned 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)(unsigned int event, unsigned int no, const void *arg); int (*conf_mimic_real)(void); int (*conf_inherit)(unsigned int rulepatno, unsigned int ruleno, const char *rule_name); void (*conf_show)(unsigned int sect_id, unsigned int no); int (*ac_pre_init)(void) int (*ac_init_autorule)(unsigned int autoruleno, const char *autorule_name); int (*ac_init_dynrule)(unsigned int autoruleno, unsigned int ruleno, const char *rule_name); int (*ac_init_statrule)(unsigned int ruleno, const char *rule_name); int (*ac_init)(void); int (*ac_deinit_rule)(unsigned int ruleno); int (*ac_deinit_autorule)(unsigned int autoruleno); int (*ac_deinit)(void); int (*ac_get_stat)(const struct ipa_tm *); int (*ac_get_rule_stat)(unsigned int stat_generation, int newstat, unsigned int ruleno, int *addition, uint64_t *chunk); int (*ac_set_autorule_active)(unsigned int autoruleno, int active); int (*ac_set_rule_active)(unsigned int ruleno, int active); int (*ac_set_limit_active)(unsigned int ruleno, unsigned int limitno, int active); int (*ac_set_threshold_active)(unsigned int ruleno, unsigned int thresholdno, int active); int (*ac_limit_event)(unsigned int ruleno, unsigned int limitno, unsigned int event); int (*ac_threshold_event)(unsigned int ruleno, unsigned int thresholdno, unsigned int event); int (*ac_create_rule)(const char *mod_name, unsigned int autoruleno, unsigned int *ruleno, const char *rule_name, const char *rule_info); void (*ac_delete_rule)(const char *mod_name, unsigned int ruleno); }; api_ver 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 mod- ule, this version number is checked with version of used API version. mod_flags 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. ac_name This is a name of the module's accounting system. suppfunc This is a pointer to ipa_suppfunc structure, which is exported to a module. memfunc This is a pointer to ipa_memfunc structure, which is exported to a module. conf_prefix This is a configuration prefix for module's sections and parame- ters. If a module does not have a configuration prefix, then set this field to NULL. conf_sect_tbl This is a pointer to the array of the ipa_conf_sect structures, which describe module's sections. Last item in this table should have sect_name equal to NULL. If a module does not have sections, then set this field to NULL. conf_param_tbl This is a pointer to the array of the ipa_param_sect structures, which describe module's parameters. Last item in this table should have param_name equal to NULL. If a module does not have parameters, then set this field to NULL. conf_init After loading a module, this function is called. conf_deinit After parsing a configuration file, this function is called. conf_event This function is called each time when some configuration event occurs. conf_event describes a configuration event. Configura- tion events allows a module to know for which section its para- meter or section belongs. There are following configuration events: IPA_CONF_EVENT_GLOBAL_BEGIN - the begin of the global section; IPA_CONF_EVENT_RULE_BEGIN - the begin of the rule section, arg points to a string with the rule's name and should be casted to (const char *), no is an ordinal number of this section, start- ing from 0; IPA_CONF_EVENT_LIMIT_BEGIN - the begin of the limit section, arg points to a string with the limit's name and should be casted to (const char *), no is an ordinal number of this section in the current section, starting from 0; IPA_CONF_EVENT_THRESHOLD_BEGIN - the begin of the threshold sec- tion, arg points to a string with the threshold's name and should be casted to (const char *), no is an ordinal number of this section in the current section, starting from 0; IPA_CONF_EVENT_AUTORULE_BEGIN - the begin of the autorule sec- tion, arg points to a string with the autorule's name and should be casted to (const char *), no is an ordinal number of this section, starting from 0; IPA_CONF_EVENT_RULEPAT_BEGIN - the begin of the rulepat section, arg points to a POSIX regular expression and should be casted to (const char *), no is an ordinal number of this section, start- ing from 0; IPA_CONF_EVENT_CUSTOM_SECT_BEGIN - the begin of some module's section, no is the ID of a module's section, arg should be ig- nored; There are IPA_CONF_EVENT_xxx_BEGIN configuration events for other of IPA_CONF_SECT_xxx sections, but no and arg should be ignored by a module for them. For all above listed configuration events there are correspond- ing IPA_CONF_EVENT_xxx_END configuration events, with the same arguments. conf_mimic_real If this function is called, then a module should mimic real con- figuration. conf_inherit In this function a module should inherit all settings from the rulepat section number rulepatno for the rule number ruleno with name rule_name. This function is called before ac_pre_init, then a module should use logconferr function for reporting about occurred errors, else logmsg function should be used. conf_show This function is called when IPA utility outputs the parsed con- figuration file. sect_id is the ID of a section. no is an or- dinal number of a section with the given section ID. If a mod- ule has some configuration for this section, then it should out- put this configuration. A module should not directly output any configuration, instead it should use one of the functions from the suppfunc structure. ac_pre_init 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 ac_init* functions. ac_init_autorule This function is called if some autorule uses a module. autoru- leno is a number of the autorule, autorule_name is its name. ac_init_dynrule This function is called if some dynamic rule uses a module. au- toruleno is a number of the autorule from which this dynamic rule was generated, ruleno is a number of the dynamic rule, rule_name is its name. Data, rule_name points to, will exist until ac_deinit_rule is called for this rule. This function is called when a module calls ac_create_rule from ac_get_stat. ac_init_statrule The same as ac_init_dynrule but for static rules and is called after configuration phase. ac_init This function is called after all other ac_init* functions (ex- cept ac_init_dynrule, which is called from ac_create_rule). ac_deinit_rule This function is called to deinitialize a rule, which uses a module. A module should not expect, that ac_init_*rule for this rule was called before. This function is called for static and dynamic rules. ac_deinit_autorule This function is called to deinitialize an autorule, which uses a module. A module should not expect, that ac_init_autorule was called for this autorule before. ac_deinit This function is called to deinitialize a module. A module should not expect that ac_*init functions were called before. This function is always called after all others ac_deinit_* functions. ac_get_stat This function is called before calls to ac_get_rule_stat func- tion. ctm is the current local date. There is internal statis- tics generation number, which is changed each time when any mod- ule's ac_get_stat function is called and its value is always greater than zero. ac_get_rule_stat This function should return statistics for the rule number ru- leno. The stat_generation value is the value of statistics gen- eration number (see above for description). The newstat flag means, that a module should consider that this is a first invo- cation of this function (for example this flag is non-zero when a rule becomes active). chunk points to statistics returned by the module and *addition 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 ac_get_rule_stat func- tion. This function is not called if a rule which uses a module is inactive. ac_set_autorule_active This function should mark an autorule as active or inactive. If flag active is equal to zero, then an autorule should be marked as inactive in a module, else an autorule should be marked as active. ac_set_rule_active The same as above, but for a rule. ac_set_limit_active The same as above, but for a limit. ac_set_threshold_active The same as above, but for a threshold. ac_limit_event This function is called when some event occurred with the limit. event can be: IPA_LIMIT_EVENT_RESTART - the limit is restarted; IPA_LIMIT_EVENT_REACH - the limit becomes reached; IPA_LIMIT_EVENT_EXPIRE - the reached limit expires; IPA_LIMIT_EVENT_STARTUP_IF_REACHED - reached at startup; IPA_LIMIT_EVENT_STARTUP_IF_NOT_REACHED - not reached at startup; IPA_LIMIT_EVENT_SHUTDOWN_IF_REACHED - reached at shutdown; IPA_LIMIT_EVENT_SHUTDOWN_IF_NOT_REACHED - not reached at shutdown. ac_threshold_event This function is called when some event occurred with the threshold. event means that threshold's counter is: IPA_THRESHOLD_EVENT_BELOW - below threshold's value; IPA_THRESHOLD_EVENT_EQUAL - equal to threshold's value; IPA_THRESHOLD_EVENT_ABOVE - above threshold's value. ac_create_rule This function is exported to a module. A module should call this function only from the ac_get_stat function to create a dynamic rule. mod_name is a module's name (is used only for debugging and only in this function). autoru- leno is a number of the autorule from which to create a dynamic rule. rule_name is a rule's name and rule_info is its descrip- tion, these strings are not used by pointers, so if a module al- located memory for them, then it should release this memory it- self. If everything is correct, then ac_init_dynrule 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 ac_get_stat. ac_delete_rule This function is exported to a module. A module should call this function only from the ac_get_stat function to delete a dynamic rule number ruleno previously cre- ated by the ac_create_rule function. mod_name is a module's name (is used only for debugging and only in this function). At some point the ac_deinit_rule 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 ac_get_stat. If some function, except ac_create_rule, returns integer value, then it should return the value -1 if an error occurred, else zero should be returned. If a module does not support some function for dynamic or static rule, for autorules, for limits or thresholds, then it should set correspond- ing field to NULL. If some function is exported to a module, then corresponding field in API structure can be set to any value (usually NULL). Database module API Database module API is exported by a module to an IPA utility in the ipa_db_mod structure: struct ipa_db_mod { unsigned int api_ver; unsigned 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)(unsigned int event, unsigned int no, const void *arg); int (*conf_mimic_real)(void); int (*conf_inherit)(unsigned int rulepatno, unsigned int ruleno, const char *rule_name); void (*conf_show)(unsigned int sect_id, unsigned int no); int (*db_pre_init)(void); int (*db_init_dynrule)(unsigned int autoruleno, unsigned int ruleno, const char *rule_name, const char *rule_info); int (*db_init_statrule)(unsigned int ruleno, const char *rule_name, const char *rule_info); int (*db_init_dynlimit)(unsigned int autoruleno, unsigned int ruleno, const char *rule_name, const char *rule_info, unsigned int limitno, const char *limit_name, const char *limit_info); int (*db_init_statlimit)(unsigned int ruleno, const char *rule_name, const char *rule_info, unsigned int limitno, const char *limit_name, const char *limit_info); int (*db_init_dynthreshold)(unsigned int autoruleno, unsigned int ruleno, const char *rule_name, const char *rule_info, unsigned int thresholdno, const char *threshold_name, const char *threshold_info); int (*db_init_statthreshold)(unsigned int ruleno, const char *rule_name, const char *rule_info, unsigned int thresholdno, const char *threshold_name, const char *threshold_info); int (*db_init)(void); int (*db_get_limit_state)(unsigned int ruleno, unsigned int limitno, struct ipa_limit_state *state); int (*db_set_limit_state)(unsigned int ruleno, unsigned int limitno, const struct ipa_limit_state *state, int new_state); int (*db_get_threshold_state)(unsigned int ruleno, unsigned int thresholdno, struct ipa_threshold_state *state); int (*db_set_threshold_state)(unsigned int ruleno, unsigned int thresholdno, const struct ipa_threshold_state *state); int (*db_deinit_threshold)(unsigned int ruleno, unsigned int thresholdno); int (*db_deinit_limit)(unsigned int ruleno, unsigned int limitno); int (*db_deinit_rule)(unsigned int ruleno); int (*db_deinit)(void); int (*db_append_rule)(unsigned int ruleno, const uint64_t *cnt, const ipa_tm *ctm); int (*db_update_rule)(unsigned int ruleno, const uint64_t *cnt, const ipa_tm *ctm); int (*db_update_limit)(unsigned int ruleno, unsigned int limitno, const uint64_t *value, const ipa_tm *ctm); int (*db_limit_event)(unsigned int ruleno, unsigned int limitno, unsigned int event, const ipa_tm *etm, const ipa_tm *ctm); int (*db_update_threshold)(unsigned int ruleno, unsigned int thresholdno, const uint64_t *cnt, const ipa_tm *tm_from, const ipa_tm *tm_updated); int (*db_set_rule_active)(unsigned int ruleno, int active); int (*db_set_limit_active)(unsigned int ruleno, unsigned int limitno, int active); int (*db_set_threshold_active)(unsigned int ruleno, unsigned int thresholdno, int active); } api_ver This is the version of the database module API, a module should check values of supported API versions with IPA_DB_MOD_API_VER- SION during compilation. After loading a module, this version number is checked with version of used API version. mod_flags Explained above. db_name This is a name of the module's database. suppfunc Explained above. memfunc Explained above. conf_prefix Explained above. conf_sect_tbl Explained above. conf_param_tbl Explained above. conf_init Explained above. conf_deinit Explained above. conf_event Explained above. conf_mimic_real Explained above. conf_inherit Explained above. conf_show Explained above. db_pre_init 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 db_init* functions. db_init_dynrule This function is called if some dynamic rule uses a module. au- toruleno is a number of the autorule from which this dynamic rule was generated, ruleno is a number of the dynamic rule, rule_name is its name and rule_info is its description. Only data, rule_name points to, will exist until db_deinit_rule is called for this rule. db_init_statrule The same as db_init_dynrule but for static rules. db_init_dynlimit This function is called if some limit from a dynamic rule uses a module. limitno is an ordinal number of the limit in the rule, limit_name is its name and limit_info is its description. Rest of arguments means the same as in db_init_dynrule. Only data, rule_name and limit_name point to, will exist until db_deinit_limit is called for this limit. Since a rule can use another database, than its limits use, then a module should not expect that db_init_dynrule was called before for a limit's rule. If a limit's rule uses this module too, then db_init_dyn- rule for a rule is called first. db_init_statlimit The same as db_init_dynlimit but for limits from static rules. db_init_dynthreshold This function is called if some threshold from a dynamic rule uses a module. thresholdno is an ordinal number of the thresh- old in the rule, threshold_name is its name and threshold_info is its description. Rest of arguments means the same as in db_init_dynrule. Only data, rule_name and threshold_name point to, will exist until db_deinit_threshold is called for this threshold. Since a rule can use another database, than its thresholds use, then a module should not expect that db_init_dynrule was called before for a threshold's rule. If a threshold's rule uses this module too, then db_init_dynrule for a rule is called first. db_init_statthreshold The same as db_init_dynthreshold but for thresholds from static rules. db_init This function is called after all other db_init_stat* functions. db_get_limit_state This function should return the current state of the limit. If a module does not have current state for the limit, then the re- turn value should be zero. If a module has current state for the limit, then the return value should be 1. db_set_limit_state This function should set a new state for the limit. If new_state is zero, then current limit's state in the database should be updated, else a new limit's state should be regis- tered. db_get_threshold_state This function should return the current state of the threshold. If a module does not have current state for the threshold, then the return value should be zero. If a module has current state for the threshold, then the return value should be 1. db_set_threshold_state This function should update the current state for the threshold. db_deinit_threshold This function is called to deinitialize a threshold, which uses a module. A module should not expect, that db_init_*threshold was called for this threshold before. db_deinit_limit This function is called to deinitialize a limit, which uses a module. A module should not expect, that db_init_*limit was called for this limit before. db_deinit_rule 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 db_deinit_limit or db_deinit_threshold is called first. A module should not expect, that db_init_*rule for this rule was called before. db_deinit This function is called to deinitialize a module. A module should not expect that db_*init functions were called before. This function is always called after all other db_deinit_* func- tions. db_append_rule This function should append a new record for the given rule. cnt is a pointer to a new value of the rule's counter. ctm is the current local date. This function is called before first call of the db_update_rule function. db_update_rule This function should update a database record for the given rule. cnt is a pointer to a new value of the rule's counter, ctm is the current local date. db_update_limit This function should update a state of the limit in the data- base. cnt is a pointer to a new value of the counter, ctm is the current local date. IPA_LIMIT_EVENT_UPDATED date should be also updated by a module. db_limit_event This function should register an event event for the limit in the database. The given event can take place right now or in future. etm is the local date of the given event and ctm 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. db_update_threshold This function should update a state of the threshold in the database. cnt is a pointer to a new value of the counter, tm_from and tm_updated are two timestamps for the threshold. db_set_rule_active Explained above in ac_set_rule_active. When a rule is marked as active, then db_append_rule will be called before db_up- date_rule. db_set_limit_active Explained above in ac_set_limit_active. db_set_threshold_active Explained above in ac_set_threshold_active. If some function returns integer value, then it should return the value -1 if an error occurred, else zero should be returned (if corresponding description does not specify another value). If a database module does not support dynamic rules, limits or thresh- olds, then it should set corresponding db_init_dyn* fields to NULL. If a database module does not support static rules, limits or thresholds, then set corresponding db_init_stat* fields to NULL. If a database module does not support db_get_limit_state, db_get_threshold_state, db_set_*active function, then set corresponding field to NULL. If some function is exported to a module, then corresponding field in API structure can be set to any value (usually NULL). Statistics module API Statistics module API is exported by a module to an IPA utility in the ipa_st_mod structure: struct ipa_entity_desc { char *name; char *info; }; struct ipa_rule_stat { unsigned 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 { unsigned int api_ver; unsigned 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)(unsigned int event, unsigned int no, const void *arg); int (*conf_mimic_real)(void); int (*conf_inherit)(unsigned int rulepatno, unsigned int ruleno, const char *rule_name); void (*conf_show)(unsigned int sect_id, unsigned int no); int (*st_pre_init)(void); int (*st_init_rule)(unsigned int ruleno, const char *rule_name); int (*st_init_limit)(unsigned int ruleno, const char *rule_name, unsigned int limitno, const char *limit_name); int (*st_init_threshold)(unsigned int ruleno, const char *rule_name, unsigned int thresholdno, const char *threshold_name); int (*st_init)(void); int (*st_deinit_threshold)(unsigned int ruleno, unsigned int thresholdno); int (*st_deinit_limit)(unsigned int ruleno, unsigned int limitno); int (*st_deinit_rule)(unsigned int ruleno); int (*st_deinit)(void); int (*st_get_rule_info)(unsigned int ruleno, ipa_mem_type *mem_type, char **info_ptr); int (*st_get_limit_info)(unsigned int ruleno, unsigned int limitno, ipa_mem_type *mem_type, char **info_ptr); int (*st_get_threshold_info)(unsigned int ruleno, unsigned int thresholdno, ipa_mem_type *mem_type, char **info_ptr); int (*st_get_rules_list)(const char *pat, const regex_t *pat_reg, ipa_mem_type *mem_type, unsigned int *n, struct ipa_entity_desc **buf_ptr); int (*st_get_limits_list)(unsigned int ruleno, const char *pat, const regex_t *pat_reg, ipa_mem_type *mem_type, unsigned int *n, struct ipa_entity_desc **buf_ptr); int (*st_get_thresholds_list)(unsigned int ruleno, const char *pat, const regex_t *pat_reg, ipa_mem_type *mem_type, unsigned int *n, struct ipa_entity_desc **buf_ptr); int (*st_get_rule_stat)(unsigned int ruleno, const ipa_tm *tm1, const ipa_tm *tm2, int exact, ipa_mem_type *mem_type, unsigned int *n, struct ipa_rule_stat **buf_ptr); int (*st_get_limit_stat)(unsigned int ruleno, unsigned int limitno, const ipa_tm *tm1, const ipa_tm *tm2, ipa_mem_type *mem_type, unsigned int *n, struct ipa_limit_state **buf_ptr); int (*st_get_threshold_stat)(unsigned int ruleno, unsigned int thresholdno, struct ipa_threshold_state *buf); }; api_ver 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 mod- ule, this version number is checked with version of used API version. mod_flags Explained above. st_name This is a name of the module's statistics system. suppfunc Explained above. memfinc Explained above. conf_prefix Explained above. conf_sect_tbl Explained above. conf_param_tbl Explained above. conf_init Explained above. conf_deinit Explained above. conf_event Explained above. conf_mimic_real Explained above. conf_inherit Explained above. conf_show Explained above. st_pre_init This function is called after parsing a configuration file. A module should make general initialization of its statistics sys- tem. This function always is called before other st_init* func- tions. st_init_rule This function is called if a rule uses a module. ruleno is a number of the rule, rule_name is its name. Data, rule_name points to, will exist until st_deinit_rule is called for this rule. This function can be called for a rule which has corre- sponding section in the configuration file, and for a rule which was generated on-the-fly (can be considered as a dynamic rule). st_init_limit This function is called if some limit from a rule uses a module. limitno is an ordinal number of the limit in the rule, limit_name is a its name. Only data, rule_name and limit_name point to, will exist until st_deinit_limit is called for this limit. Since a rule can use another statistics system, than its limits use, then a module should not expect that st_init_rule was called before for a limit's rule. If a limit's rule uses this module too, then st_init_rule for a limit's rule is called first. Like st_init_rule this function can be called for a rule and/or a limit which has corresponding section in the configura- tion 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). st_init_threshold This function is called if some threshold from a rule uses a module. thresholdno is an ordinal number of the threshold in the rule, threshold_name is a its name. Only data, rule_name and threshold_name point to, will exist until st_deinit_thresh- old is called for this threshold. Since a rule can use another statistics system, than its thresholds use, then a module should not expect that st_init_rule was called before for a threshold's rule. If a threshold's rule uses this module too, then st_init_rule for a threshold's rule is called first. Like st_init_rule 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 thresh- old). st_init This function is called after all other st_init* functions. st_deinit_threshold This function is called to deinitialize a threshold, which uses a module. A module should not expect, that st_init_threshold was called for this threshold before. st_deinit_limit This function is called to deinitialize a limit, which uses a module. A module should not expect, that st_init_limit was called for this limit before. st_deinit_rule 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 st_deinit_limit or st_deinit_threshold is called for such rule's limits or thresholds before. A module should not expect, that st_init_rule for this rule was called before. st_deinit This function is called to deinitialize a module. A module should not expect that st_*init functions were called before. This function is always called after all other st_deinit_* func- tions. st_get_rule_info This function should return a description for the rule number ruleno, pointer to a rule's description should be returned in *info_ptr. If a rule does not have a description, then *info_ptr should be set to NULL. st_get_limit_info The same as st_get_rule_info, but for a limit. st_get_threshold_info The same as st_get_rule_info, but for a threshold. st_get_rules_list This function should return an array with rules names and de- scriptions. If the POSIX regular expression pat is not NULL, then a module should return only rules, with names which matched this regular expression (pat_reg is a compiled regular expres- sion pat). The pointer to the array of struct ipa_entity_desc should be returned in *buf_ptr, number of entries in this array should be returned in *n. If number of entries is equal to zero, then *buf_ptr must be NULL. st_get_limits_list The same as st_get_rules_list, buf for limits. st_get_thresholds_list The same as st_get_rules_list, buf for thresholds. st_get_rule_stat This function is used for querying statistics for a rule number ruleno for time interval from tm1 till tm2. If exact 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 struct ipa_rule_stat should be returned in *buf_ptr, number of entries in this array should be returned in *n. If number of entries is equal to zero, then *buf_ptr must be NULL. Structure struct ipa_rule_stat represents statistics of one rule's record. In struct ipa_rule_stat fields year, mon and mday 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 time- stamps). t1, m1 and s1 is time of first timestamp; t2, m2 and s2 is time of second timestamp. cnt is statistics for the time interval in one rule's record. st_get_limit_stat This function is used for querying statistics for a limit number limitno in a rule number ruleno, dates when a limit was started should be in time interval from tm1 till tm2. The pointer to the array of struct ipa_limit_state should be returned in *buf_ptr, number of entries in this array should be returned in *n. If number of entries is equal to zero, then *buf_ptr must be NULL. If tm1 is NULL, then current limit state should be re- turned. st_get_threshold_stat This function is used for querying current state for a threshold number thresholdno in a rule number ruleno. If a module does not have current state for the threshold, then the return value should be 0. If a module has current state for the threshold, then the return value should be 1. If some function returns integer value, then it should return the value -1 if an error occurred, else zero should be returned (if corresponding description does not specify another value). If a statistics module does not support some functions, which query statistics or description, then set corresponding fields to NULL. If some function accepts mem_type argument, then all allocated data be- ing returned by this function should be allocated with the help from ipa_memfunc functions with the given mem_type. If some function is exported to a module, then corresponding field in API structure can be set to any value (usually NULL). SEE ALSO ipa(8), ipactl(8), ipastat(8), ipa.conf(5), ipastat.conf(5) AUTHOR Andrey Simonenko <simon@comsys.ntu-kpi.kiev.ua> BUGS If you find any, please send email me. December 5, 2010 IPA_MOD(3)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHOR | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ipa_mod&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>