IPA_MOD(3) IPA_MOD(3)
НАИМЕНОВАНИЕ
ipa_mod -- API модулей IPA
СИНТАКСИС
#include <ipa_mod.h>
ОПИСАНИЕ
Эта страница документации описывает API всех типов IPA модулей. Будем
называть любой IPA модуль просто ``модулем''. Информация, представлен-
ная в этом фале, в основном для разработчиков, но она может быть инте-
ресна любому, кто желает понять как утилиты IPA работают с IPA моду-
лями.
Эта страница документации содержит описания следующих API:
ipa_memfunc API версия 1 (IPA_MEMFUNC_API_VERSION);
ipa_ac_mod API версия 2 (IPA_AC_MOD_API_VERSION);
ipa_db_mod API версия 2 (IPA_DB_MOD_API_VERSION);
ipa_st_mod API версия 2 (IPA_ST_MOD_API_VERSION).
Именование символов в модулях
Любой модуль это файл с именем подобным foobar-x.y.z.so. После
загрузки модуля при помощи функции dlopen(3) или аналогичной, IPA ути-
лита убирает номер версии и суффикс из имени файла модуля и пытается
найти символ foobar_ac_mod, foobar_db_mod или foobar_st_mod в модуле
если модуль является модулем учёта, базы данных или статистики. Если
модуль содержит искомый символ, то он принимается за IPA модуль.
Затем найдены указатель (void *) преобразуется в один из трёх указате-
лей (struct ipa_XX_mod *). Структуры struct ipa_XX_mod определяют API
между IPA утилитами и модулями.
Такой метод именования символов в модулях позволяет хранить несколько
модулей различных типов в одном файле. Также возможно создать линки с
различными именами на файл модуля, чтобы следовать заданной схеме име-
нования.
Однопотоковые и многопотоковые модули
Любой модуль может быть однопотоковым или многопотоковым. Если модуль
не может быть заблокирован в какой-то из своих функций, то он может
быть спроектирован как однопотоковый. Если ожидается, что модуль может
быть заблокирован в какой-то из своих функций или если модуль должен
постоянно осуществлять мониторинг некоторого события, то этот модуль
должен быть спроектирован как многопотоковый. В качестве альтернативы
модуль может вызвать fork(2) и использовать некоторую форму IPC, чтобы
взаимодействовать с новым процессом из какой-либо своей функции и
используемая функция для организации IPC должна быть неблокируемая.
Если модуль однопотоковый, то он может использовать сигналы в личных
целях (например SIGALRM, чтобы реализовать таймаут), за исключением
сигналов, используемых IPA утилитой, которая загрузила этот модуль.
Если модель многопотоковый, то ему не разрешается использовать сигналы.
Очень важно вернуться из функции модуля как можно быстрее, так как IPA
утилиты ожидают, что функции модуля не будут блокироваться. Если
модуль проводит слишком много времени в своих функциях, то временные
отметки статистики и реакция на запланированные события не будут очень
точными в IPA утилитах.
Даже если модуль не спроектирован как многопотоковый, то другие модули
могут быть многопотоковыми. Все загружаемые модуль должны быть либо
однопотоковыми, либо многопотоковыми. Таким образом любой однопотоко-
вый модуль должен быть готовым для сборки как многопотоковый. Модуль
всегда должен устанавливать правильный флаг в своей структуре API, для
того, чтобы сообщить является он однопотоковым или многопотоковым.
Утилиты IPA созданы как однопотоковые, но если используется хотя бы
один многопотоковый модуль, то они должны быть собраны как многопотоко-
вые. В многопотоковом режиме функции из ipa_memfunc, которая экспорти-
руется IPA утилитами, становятся готовыми к многопотоковой работе.
Модулям разрешается создавать потоки только после фазы конфигурации.
Экспортируемые модулю функции работы с памятью
API модулей требуют определённой организации данных в модулях. Функции
ipa_memfunc экспортируются модуля и пытаются помочь модулю в работе с
памятью. Модуль свободен в выборе использовать или нет эти функции. В
некоторых функциях требуется использования функций из ipa_memfunc.
Существуют четыре типа функций в ipa_memfunc: функции инициализации и
деинициализации, функции работы с памятью общего назначения, функции
работы с mzone и функции работы с marray.
Функции mem_* для работы с памятью общего назначения это обёртки (wrap-
pers) для стандартных функций работы с памятью из библиотеки (mal-
loc(3), calloc(3), realloc(3), free(3), strdup(3) и для функции
vasprintf(3), присутствующей на некоторых системах). Все эти функции
выполняют дополнительные проверки. Любая память выделенная с помощью
функции mem_* должна быть освобождена с помощью функции mem_free. Эти
функции принимают дополнительный аргумент, называемый mem_type (тип
памяти), который используется для сбора статистики об использовании
памяти. Этот mem_type должен быть создан функцией mem_type_new.
Marrays используются для создания массивов некоторых элементов. Mzones
используются для создание элементов одного размера. Все функции mar-
ray_* и mzone_* сами используют функции mem_*.
Функции из ipa_memfunc обнаруживают неправильные указатели и некоррект-
ные аргументы в функциях mem_*, marray_* и mzone_*. Если будет обнару-
жена критическая ошибка в любой из этих функций, то эта функция завер-
шит выполнение программы с генерацией дампа памяти.
Если IPA утилиты были собраны с определённой макропеременной WITH_MEM-
FUNC_DEBUG, то выделяемая и освобождаемая память заполняется случайными
байтами, таким образом, если некоторая часть кода продолжает использо-
вать уже освобождённую память, то вероятно, что эта ошибка будет обна-
ружена. Также mem_realloc в этом случае является эквивалентом такой
последовательности: malloc(3) для новой области памяти, memcpy(3) дан-
ных в новую область памяти, free(3) для старой области памяти.
Любая IPA утилита во время завершения работы и во время реконфигурации
проверяет размер выделенной и не освобождённой памяти, если этот размер
не равен нулю, то посылается отладочное сообщение. Если какая-то mzone
или marray не был деинициализирован, то также посылается отладочное
сообщение с соответствующим именем.
Структура ipa_memfunc имеет следующий формат:
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
Версия API ipa_memfunc, модуль должен проверить версии поддержи-
ваемых API с IPA_MEMFUNC_API_VERSION во время компиляции.
memfunc_init
Потомок модуля может вызвать эту функцию чтобы инициализировать
другие ipa_memfunc функции.
memfunc_deinit
Потомок модуля может вызвать эту функцию чтобы освободить всю
память в mzone и marray, и деинициализировать собственные струк-
туры ipa_memfunc. Если флаг foreign не равен нулю, то все сооб-
щения об утечке памяти не будут выводится и статистика об
использовании памяти будет обнулена. Заметьте, что эта и преды-
дущая функция могут быть вызваны только в потомке модуля.
m_parser
Это указатель на mem_type используемый в парсере во время раз-
бора конфигурационного файла.
mem_type_new
Создать новый mem_type, name это короткое имя для нового
mem_type, desc это его описание (обычно несколько слов) и flags
это флажки для нового mem_type. На данный момент определён
только один флаг IPA_MEMFUNC_FLAG_PTHREAD, который должен быть
установлен если память с этим mem_type будет выделяться или
освобождаться в нескольких потоках асинхронно. Эта функция воз-
вращает указатель на новый mem_type или NULL в случае ошибки.
mem_malloc
Аналог malloc(3).
mem_calloc
Аналог calloc(3).
mem_realloc
Аналог realloc(3).
mem_strdup
Аналог strdup(3).
mem_vasprintf
Аналог vasprintf(3) присутствующей на некоторых системах. Эта
функция устанавливает в *buf_ptr указатель на буфер достаточного
объёма для хранения форматированной строки и возвращает число
символов в буфере (не включая последний символ `\0'). Если не
удалось выделить достаточного объёма памяти, то эта функция воз-
вращает -1 и устанавливает в *buf_ptr NULL. Аргументы format и
ap аналогичны аргументам в функции vprintf(3).
mem_free
Аналог free(3).
marray_init
Создать marray, name это имя marray, desc это его описание
(обычно несколько слов) name и desc должны существовать, пока
marray не будет деинициализирован. flags определяет флажки для
нового marray, на данный момент определён только один флаг
IPA_MEMFUNC_FLAG_PTHREAD, этот флаг должен быть определён, если
элементы из этого marray будет выделяться и освобождаться
несколькими потоками асинхронно. arr это указатель памяти где
необходимо сохранять указатель на действительный массив элемен-
тов. isize это размер одного элемента в массиве. nitems обо-
значает количество элементов, под которое необходимо изначально
выделить память. nalloc обозначает количество элементов, кото-
рое необходимо выделять, если в marray не осталось ни одного
свободного элемента. Если вы не уверены в значениях этих аргу-
ментов, то установите их в 1. Эта функция возвращает указатель
на только что созданный marray или NULL, если возникла какая-то
ошибка. Заметьте, что указатель сохранённый в памяти указывае-
мой arr может быть изменён последующими вызовами функций mar-
ray_alloc и marray_free.
marray_deinit
Освободить память занимаемую marray. Если модуль не вызовет эту
функцию, то IPA утилита сообщит об утечке памяти и деинициализи-
рует marray модуля, но эта деинициализация не означает, что
утечка памяти не возможна, так как деинициализация marray не
освобождает память, на которую, возможно, указывают элементы
массива. Если marray равен NULL, то эта функция ничего не
делает.
marray_alloc
Выделить память для нового элемента в marray. Если fixed не
равен нулю, то *idxp должен указывать быть желаемым индексом
нового элемента в marray, иначе эта функция должна выделить
память для элемента с наименьшим возможным индексом и сохранить
этот индекс в *idxp. Эта функция возвращает 0, если память под
новый элемент была выделена и -1, в случае ошибки. Обычно
модуль вызывает эту функцию с ненулевым значением fixed.
marray_free
Вернуть прежде выделенный элемент с индексом idx в marray.
marray_minimize
Попробовать минимизировать память, занимаемую marray. Такая
минимизация возможна, так как marray_alloc и marray_free пыта-
ются держать дополнительную память для новых элементов.
marray_check_index
Эта функция проверяет был ли выделен элемент с индексом idx в
marray и если он не был выделен, то возвращается 0, иначе воз-
вращается ненулевое значение.
marray_nused
Функция возвращает количество выделенных элементов в marray.
mzone_init
Создать mzone, name это имя mzone, desc это её описание (обычно
несколько слов). name и desc должны существовать, пока mzone не
будет деинициализирована. flags означает тоже самое, что и в
функции marray_init, mzone также воспринимает ещё флаг IPA_MEM-
FUNC_FLAG_OPTIMIZE, этот флаг должен быть установлен, если в
mzone будет много элементов. isize это размер одного элемента в
mzone. nitems обозначает количество элементов, под которое
необходимо изначально выделить память. nalloc обозначает коли-
чество элементов, которое необходимо выделять, если в mzone не
осталось ни одного свободного элемента. Если вы не уверены в
значениях этих аргументов, то установите их в 1. Эта функция
возвращает указатель на только что созданную mzone или NULL, ес-
ли возникла какая-то ошибка.
mzone_deinit
Освободить память занимаемую mzone. Если модуль не вызовет эту
функцию, то IPA утилита сообщит об утечке памяти и деинициализи-
рует mzone модуля, но эта деинициализация не означает, что
утечка памяти не возможна, так как деинициализация mzone не
освобождает память, на которую, возможно, указывают элементы
массива. Если mzone равен NULL, то эта функция ничего не
делает.
mzone_alloc
Выделить новый элемент в mzone. Эта функция возвращает указа-
тель на новый элемент или NULL, если возникла ошибка.
mzone_free
Вернуть прежде выделенный элемент указываемый ptr в mzone.
mzone_nused
Функция возвращает количество выделенных элементов в mzone.
Экспортируемые модулю функции поддержки
Иногда модулю необходимо добавить макропеременную в некоторую секцию
конфигурационного файла, или необходимо вывести собственные параметры,
когда IPA утилита выводит разобранный конфигурационный файл, или необ-
ходимо послать лог-сообщение. Так как модулю не известно каким образом
это сделать, IPA утилита, использующая этот модуль, экспортирует модулю
функции ipa_memfunc:
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
Эта функция выводит строку в кавычках.
print_bytes
Эта функция выводит байты.
print_time
Эта функция выводит время.
print_value
Эта функция выводит байты, время или 64-битовое беззнаковое
целое, если value_type равно IPA_CONF_TYPE_BYTES,
IPA_CONF_TYPE_TIME или IPA_CONF_TYPE_UINT64 соответственно.
print_boolean
Эта функция выводит логическое значение.
print_space
Эта функция выводит один пробельный символ, если он не был выве-
ден прежде.
print_param_name
Эта функция выводит имя параметра param, с конфигурационным пре-
фиксом prefix. Если параметр не имеет конфигурационного пре-
фикса, то prefix должен быть равен NULL.
print_param_args
Эта vprintf(3) подобная функция выводит аргументы параметра,
может вызываться несколько раз для одного и того же параметра.
print_param_end
Эта функция должна быть вызвана после вывода всех аргументов
параметра.
print_sect_name
Эта функция выводит имя секции sect с конфигурационным префиксом
prefix. Если секция не имеет конфигурационного префикса, то
prefix должен быть равен NULL.
print_sect_args
Эта vprintf(3) подобная функция выводит аргументы секции, может
вызываться несколько раз для одной и той же секции.
print_sect_begin
Эта функция должна быть вызвана после вывода всех аргументов
секции.
print_sect_end
Эта функция должна быть вызвана в конце секции модуля.
open_log, close_log
Если необходимо запустить другой процесс (посредством fork(2)),
то порождённый процесс может использовать функцию logmsg (опи-
сана ниже), но если ему необходимо закрыть какие-то дескрипторы,
а затем использовать систему лог-сообщений, то этот процесс дол-
жен вызвать сначала функцию close_log, а затем open_log. Созда-
ние дескриптора для отправки лог-сообщений задерживается до тех
пор пока не будет послано первое сообщение.
logmsg Модуль должен использовать эту функцию для вывода лог-сообщений
в любой части своего кода, но только не в функциях по обработке
конфигурации. mod_name это имя модуля. priority это приоритет
сообщения: IPA_LOG_INFO, IPA_LOG_WARNING или IPA_LOG_ERR. code
это значение errno(2) или 0 если нет состояния ошибки. format и
ap это vprintf(3) подобные аргументы.
logconferr
Модуль должен использовать эту функцию для вывода сообщений об
ошибках во время разбора конфигурационного файла. Аргументы
аналогичны аргументам функции logmsg.
local_sym_add
Создать локальную макропеременную с именем sym и значением val,
если copy_flag не равен нулю, то будет выделена память и sym и
val будут скопированы в эту память, иначе будут использоваться
оригинальные указатели. Эта функция возвращает 0, если макропе-
ременная была создана и -1, если произошла ошибка выделения
памяти.
local_sym_del
Удалить локальную макропеременную с именем sym. Если не суще-
ствует локальной макропеременной с именем sym, то возвращается
-1, иначе 0. У модуля есть выбор не вызывать эту функцию, так
как IPA утилита вызовет её автоматически.
global_sym_add
Аналогично local_sym_add, но для глобальных макропеременных.
global_sym_del
Аналогично local_sym_del, но для глобальных макропеременных.
Описание конфигурационной секции
Структура ipa_conf_sect определена следующим образом:
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
Имя секции.
sect_id
Идентификатор секции, значение которого локально для модуля.
Это значение должно быть больше чем IPA_CONF_SECT_CUSTOM_OFFSET.
arg_nargs
Число аргументов секции. Установите это поле в 0, если секция
не должна иметь ни одного аргумента. Если секция может иметь
переменное число аргументов, то необходимо установить в этом
поле отрицательное число, абсолютное значение которого равно
минимально допустимому числу аргументов секции.
arg_pattern
Аргумент секции должен соответствовать данному регулярному выра-
жению POSIX (расширенный формат). Если такого регулярного выра-
жения нет, то это поле следует установить в NULL.
arg_regexp
Указатель на переменную типа regex_t. Если arg_pattern не NULL,
то это значение тоже должно быть не NULL. Возможно разделять
регулярные выражения между секциями и параметрами и не тратить
лишней памяти для дополнительных переменных. В этом случае
только одна секция или параметр должна иметь указатель в
arg_pattern, все другие секции и параметры должны установить
arg_pattern в NULL.
arg_type
Тип аргумента. Определены следующие типы:
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 - строка;
IPA_CONF_TYPE_BYTES - байты;
IPA_CONF_TYPE_TIME - время;
IPA_CONF_TYPE_VALUE - значение;
IPA_CONF_TYPE_PER_CENT - процент;
IPA_CONF_TYPE_BOOLEAN - логическое значение;
IPA_CONF_TYPE_MISC - без формата.
Обычно модуль использует регулярное выражение (поле arg_regexp)
с типом аргумента IPA_CONF_TYPE_MISC и не использует регулярного
выражения с другими типами аргумента. IPA_CONF_TYPE_VALUE обо-
значает байты, время или uint64_t значение. См. ниже детали.
sect_where
Это поле определяет где секция должна быть расположена, это ука-
затель на массив 'unsigned int' значений, каждое значение это
идентификатор секции, последний элемент в этом массиве должен
быть равен нулю. Предопределены следующие идентификаторы сек-
ций:
IPA_CONF_SECT_ROOT - нет секции;
IPA_CONF_SECT_GLOBAL - секция global;
IPA_CONF_SECT_RULE - секция rule;
IPA_CONF_SECT_LIMIT - секция limit;
IPA_CONF_SECT_THRESHOLD - секция threshold;
IPA_CONF_SECT_AUTORULE - секция autorule;
IPA_CONF_SECT_RULEPAT - секция rulepat;
IPA_CONF_SECT_RESTART - секция restart;
IPA_CONF_SECT_REACH - секция reach;
IPA_CONF_SECT_EXPIRE - секция expire;
IPA_CONF_SECT_STARTUP - секция startup;
IPA_CONF_SECT_SHUTDOWN - секция shutdown;
IPA_CONF_SECT_IF_REACHED - секция if_reached;
IPA_CONF_SECT_IF_NOT_REACHED - секция if_not_reached;
IPA_CONF_SECT_IF_ALL_REACHED - секция if_all_reached;
IPA_CONF_SECT_IF_ANY_REACHED - секция if_any_reached;
IPA_CONF_SECT_IF_ALL_NOT_REACHED - секция if_all_not_reached;
IPA_CONF_SECT_IF_ANY_NOT_REACHED - секция if_any_not_reached;
IPA_CONF_SECT_BELOW_THRESHOLD - секция below_threshold;
IPA_CONF_SECT_EQUAL_THRESHOLD - секция equal_threshold;
IPA_CONF_SECT_ABOVE_THRESHOLD - секция above_threshold.
arg_parse
Эта функция вызывается для обработки аргументов. Модуль может
установить это поле в NULL, если для секции нет такой функции.
arg это указатель на данные, которые зависят от значения
arg_type и функция arg_parse должна выполнить следующие преобра-
зования типов:
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.
Если значение arg_type равно IPA_CONF_TYPE_STRING, то arg явля-
ется указателем на память, в которую скопировано значение строки
(без кавычек), эта память выделяется при помощи mem_malloc с
mem_type m_parser и модуль должен освободить эту память если он
в ней не нуждается при помощи mem_free. В других случаях функ-
ция arg_parse должна копировать необходимые данные и не исполь-
зовать данные по указателям, также разрешено модифицировать дан-
ные на которые указывает arg. Если значение arg_type равно
IPA_CONF_TYPE_MISC, то arg не будет начинаться с пробельных сим-
волов и не будет заканчиваться пробельными символами, также
между любыми двумя аргументами в arg будет всего один символ
` '. Если значение arg_type равно IPA_CONF_TYPE_VALUE, то arg
указывает на массив, первый элемент которого имеет значение
IPA_CONF_TYPE_BYTES, IPA_CONF_TYPE_TIME или
IPA_CONF_TYPE_UINT64, второй элемент это само значение.
Описание конфигурационного параметра
Структура ipa_conf_param определена следующим образом:
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
Имя параметра.
arg_nargs
Объяснено выше.
arg_pattern
Объяснено выше.
arg_regexp
Объяснено выше.
arg_type
Объяснено выше.
param_where
Объяснено выше для sect_where.
arg_parse
Объяснено выше.
Структура для представления дат
Структура ipa_tm определена следующим образом:
typedef struct tm ipa_tm;
Только следующие поля в структуре ipa_tm могут быть использованы:
tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec и tm_wday. Эти поля
определяют локальную дату. tm_year равно реальному значению года и
tm_mon равно реальному значению месяца.
Состояние лимита
Состояние лимита описывается структурой ipa_limit_state:
struct ipa_limit_state {
uint64_t lim;
uint64_t cnt;
unsigned int event_date_set;
ipa_tm event_date[IPA_LIMIT_EVENT_NUM];
};
lim Значение параметра limit.
cnt Значение счётчика лимита.
event_date_set
Это битовое поле, которое определяет действительные элементы в
массиве event_date, каждый IPA_LIMIT_EVENT_xxx элемент в массиве
event_date имеет соответствующий бит IPA_LIMIT_EVENT_xxx_SET в
event_date_set.
event_date
Это массив дат событий лимита. В этом массиве определены следу-
ющие элементы:
IPA_LIMIT_EVENT_START - дата, когда лимит был запущен;
IPA_LIMIT_EVENT_RESTART - дата, когда лимит будет перезапущен
или был перезапущен;
IPA_LIMIT_EVENT_RESTART_EXEC - дата, когда были запущены команды
для перезапущенного лимита;
IPA_LIMIT_EVENT_REACH - дата, когда лимит был достигнут;
IPA_LIMIT_EVENT_REACH_EXEC - дата, когда были запущены команды
для достигнутого лимита;
IPA_LIMIT_EVENT_EXPIRE - дата, когда истечёт срок достигнутого
лимита и лимит будет перезапущен или дата, когда истёк срок
достигнутого лимита и он был перезапущен;
IPA_LIMIT_EVENT_EXPIRE_EXEC - дата, когда были запущены команды
для лимита, у которого истёк срок с момента достижения.
IPA_LIMIT_EVENT_UPDATED - дата, когда лимита был обновлён в
последний раз.
Состояние порога
Состояние порога описывается структурой ipa_threshold_state:
struct ipa_threshold_state {
uint64_t thr;
uint64_t cnt;
ipa_tm tm_from;
ipa_tm tm_updated;
};
thr Значение параметра threshold.
cnt Значение счётчика порога.
tm_from, tm_updated
Две временные отметки порога.
API модуля учёта
API модуля учёта экспортируется модулем IPA утилите в структуре
ipa_ac_mod:
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
Версия API модуля учёта, модуль должен проверять версии поддер-
живаемых API с IPA_AC_MOD_API_VERSION во время компиляции.
После загрузки модуля этот номер версии сравнивается с версией
используемого API.
mod_flags
Флажки определяющие режимы работы модуля. Определён только один
флаг IPA_MOD_FLAG_PTHREAD_SAFE и он должен быть установлен если
модуль может работать в многопотоковой версии IPA утилиты.
ac_name
Имя системы учёта модуля.
suppfunc
Указатель на структуру ipa_suppfunc, которая экспортируется
модулю.
memfunc
Указатель на структуру ipa_memfunc, которая экспортируется
модулю.
conf_prefix
Конфигурационный префикс для секций и параметров модуля. Если у
модуля нет конфигурационного префикса, то установите это поле в
NULL.
conf_sect_tbl
Указатель на массив ipa_conf_sect структур, которые определяют
секции модуля. Последний элемент в этом массиве должен иметь
sect_name равное NULL. Если у модуля нет секций, то установите
это поле в NULL.
conf_param_tbl
Указатель на массив ipa_conf_param структур, которые определяют
параметры модуля. Последний элемент в этом массиве должен иметь
param_name равное NULL. Если у модуля нет параметров, то уста-
новите это поле в NULL.
conf_init
Эта функция вызывается после того, как модуль загружен.
conf_deinit
Эта функция вызывается после того, как обработан весь конфигура-
ционный файл.
conf_event
Эта функция вызывается каждый раз, когда происходит некоторое
событие во время конфигурации. conf_event описывает событие
конфигурации. Конфигурационные события позволяют модулю узнать
для какой секции принадлежит его параметр или секция. Опреде-
лены следующие события конфигурации:
IPA_CONF_EVENT_GLOBAL_BEGIN - начало секции global;
IPA_CONF_EVENT_GLOBAL_END - конец секции global;
IPA_CONF_EVENT_RULE_BEGIN - начало секции rule, arg это указа-
тель на строку с именем правила и должен быть преобразован в
(const char *), no это порядковый номер этой секции в конфигура-
ционном файле, начиная с 0;
IPA_CONF_EVENT_RULE_END - конец секции rule;
IPA_CONF_EVENT_LIMIT_BEGIN - начало секции limit, arg указывает
на строку с именем лимита и должен быть преобразован в
(const char *), no это порядковый номер этой секции в текущей
секции, начиная с 0;
IPA_CONF_EVENT_LIMIT_END - конец секции limit;
IPA_CONF_EVENT_THRESHOLD_BEGIN - начало секции threshold, arg
указывает на строку с именем порога и должен быть преобразован в
(const char *), no это порядковый номер этой секции в текущей
секции, начиная с 0;
IPA_CONF_EVENT_THRESHOLD_END - конец секции threshold;
IPA_CONF_EVENT_AUTORULE_BEGIN - начало секции autorule, arg ука-
зывает на строку с именем автоправила и должен быть преобразован
в (const char *), no это порядковый номер этой секции в конфигу-
рационном файле, начиная с 0;
IPA_CONF_EVENT_AUTORULE_END - конец секции autorule;
IPA_CONF_EVENT_RULEPAT_BEGIN - начала секции rulepat, arg указы-
вает на регулярное выражение POSIX и должен быть преобразован в
(const char *), no это порядковый номер этой секции в конфигура-
ционном файле, начиная с 0;
IPA_CONF_EVENT_RULEPAT_END - конец секции rulepat;
IPA_CONF_EVENT_CUSTOM_SECT_BEGIN - начало собственной секции
модуля, no это идентификатор секции модуля;
IPA_CONF_EVENT_CUSTOM_SECT_END - конец собственной секции
модуля.
Существуют события конфигурации IPA_CONF_EVENT_xxx_BEGIN для
остальных секций IPA_CONF_SECT_xxx, но для этих событий модуль
должен игнорировать аргументы no и arg.
Для каждого перечисленного события конфигурации есть соответ-
ствующее событие IPA_CONF_EVENT_xxx_END, которое получает анало-
гичные аргументы.
conf_mimic_real
Если эта функция вызвана, то модуль должен сымитировать реальную
конфигурацию.
conf_inherit
В этой функции модуль должен унаследовать все установки из сек-
ции rulepat номер rulepatno для правила номер ruleno с именем
rule_name. Если эта функция вызывается до ac_pre_init, то
модуль должен использовать функцию logconferr для сообщений о
возникших ошибках, иначе должна быть использована функция
logmsg.
conf_show
Эта функция вызывается, когда IPA утилита выводит обработанный
конфигурационный файл. sect_id это идентификатор секции. no
это порядковый номер секции с данным идентификатором. Если
модуль имеет конфигурацию в секции с данным идентификатором, то
он должен вывести эту конфигурацию. Модуль не должен напрямую
выводить свою конфигурацию, вместо этого следует использовать
функции из структуры suppfunc.
ac_pre_init
Эта функция вызывается после обработки конфигурационного файла.
Модуль должен выполнить предварительную инициализацию своей
системы учёта. Эта функция всегда вызывается перед остальными
функциями ac_init*.
ac_init_autorule
Эта функция вызывается, если некоторое автоправило использует
модуль. autoruleno это номер автоправила, autorule_name это его
имя.
ac_init_dynrule
Эта функция вызывается, если некоторое динамическое правило
использует модуль. autoruleno это номер автоправила из которого
было сгенерировано динамическое правило, ruleno это номер дина-
мического правила, rule_name это его имя. Данные на которые
указывает rule_name будут существовать до тех пор пока не будет
вызвана ac_deinit_rule для этого правила. Эта функция вызыва-
ется тогда, когда модуль вызывает ac_create_rule из ac_get_stat.
ac_init_statrule
Тоже самое что и ac_init_dynrule, только для статических правил
и эта функция вызывается после фазы конфигурации.
ac_init
Эта функция вызывается после все остальных функций ac_init* (за
исключением ac_init_dynrule, которая вызывается из ac_cre-
ate_rule).
ac_deinit_rule
Эта функция вызывается при деинициализации правила, использую-
щего модуль. Модуль не должен ожидать, что функция
ac_init_*rule была вызвана прежде для этого правила. Эта функ-
ция вызывается для статических и динамических правил.
ac_deinit_autorule
Эта функция вызывается при деинициализации автоправила, исполь-
зующего модуль. Модуль не должен ожидать, что функция
ac_init_autorule была вызвана прежде для этого автоправила.
ac_deinit
Эта функция вызывается при деинициализации модуля. Модуль не
должен ожидать, что функции ac_*init были вызваны прежде. Эта
функция всегда вызывается после всех остальных функций
ac_deinit_*.
ac_get_stat
Эта функция вызывается перед вызовом функции ac_get_rule_stat.
ctm это текущая локальная дата. Существует внутренний номер
генерации статистики, который изменяется всякий раз когда вызы-
вается функция ac_get_stat любого из модулей и его значение все-
гда больше нуля.
ac_get_rule_stat
Эта функция должна возвращать статистику для правила номер
ruleno. Значение stat_generation это номер генерации статистики
(см. описание выше). Флаг newstat обозначает, что модуль должен
рассматривать, что это первый вызов этой функции (например, этот
флаг не равен нулю когда правило становится активным). chunk
указывает на статистику возвращаемую модулем и *addition опреде-
ляет действие со статистикой, если его значение не равно нулю,
то возвращаемая статистика добавляется, иначе вычитается. Здесь
под статистикой понимается статистика за период между двумя
вызовами функции ac_get_rule_stat. Эта функция не вызывается
если правило, которое использует этот модуль, неактивно.
ac_set_autorule_active
Эта функция должна отметить автоправило как активное или неак-
тивное. Если флаг active равен нулю, то автоправило должно быть
отмечено как неактивное в модуле, иначе как активное.
ac_set_rule_active
Аналогично предыдущему, только для правила.
ac_set_limit_active
Аналогично предыдущему, только для лимита.
ac_set_threshold_active
Аналогично предыдущему, только для порога.
ac_limit_event
Эта функция вызывается когда происходит некоторое событие с
лимитом. Событие event может быть:
IPA_LIMIT_EVENT_RESTART - лимит перезапущен;
IPA_LIMIT_EVENT_REACH - лимит достигнут;
IPA_LIMIT_EVENT_EXPIRE - достигнутый лимит перезапущен;
IPA_LIMIT_EVENT_STARTUP_IF_REACHED - достигнутый при старте;
IPA_LIMIT_EVENT_STARTUP_IF_NOT_REACHED - не достигнутый при старте;
IPA_LIMIT_EVENT_SHUTDOWN_IF_REACHED - достигнутый во время останова;
IPA_LIMIT_EVENT_SHUTDOWN_IF_NOT_REACHED - не достигнутый во время останова.
ac_threshold_event
Эта функция вызывается когда происходит некоторое событие с
порогом. Событие event означает, что значение счётчика порога:
IPA_THRESHOLD_EVENT_BELOW - ниже значения threshold;
IPA_THRESHOLD_EVENT_EQUAL - равно значению threshold;
IPA_THRESHOLD_EVENT_ABOVE - выше значения threshold.
ac_create_rule
Эта функция экспортируется модулю.
Модуль должен вызывать эту функцию только из функции ac_get_stat
чтобы создать динамическое правило. mod_name это имя модуля
(используется только для отладки и только в этой функции).
autoruleno это номер автоправила из которого необходимо сгенери-
ровать динамическое правило. rule_name это имя правила,
rule_info это его описание, эти строки не используются по указа-
телям, поэтому если модуль выделил память для них, то он должен
сам освободить эту память. Если не произошла какая-нибудь
ошибка, то вызывается ac_init_dynrule.
Эта функция возвращает 0, если динамическое правило было
создано, -2 если правило с данным именем уже существует и -1 ес-
ли произошла какая-то критическая ошибка, в этом случае модуль
обязан вернуть -1 из ac_get_stat.
ac_delete_rule
Эта функция экспортируется модулю.
Модуль должен вызывать эту функцию только из функции ac_get_stat
чтобы деинициализировать динамическое правило номер ruleno
созданное прежде функцией ac_create_rule. mod_name это имя
модуля (используется только для отладки и только в этой функ-
ции). Для данного правила в какой-то момент будет вызвана функ-
ция ac_deinit_rule.
Если не произошла какая-нибудь ошибка, то эта функция возвращает
0. Если возникли проблемы с деинициализацией, то возвращается
-1, в этом случае модуль обязан вернуть -1 из ac_get_stat.
Если какая-то функция, кроме ac_create_rule, возвращает числовое значе-
ние, то в случае успешного выполнения эта функция должна вернуть значе-
ние 0, иначе должно быть возвращено значение -1.
Если модуль не поддерживает какую-то функцию для статического или дина-
мического правила, для автоправила, для лимита или порога, то он должен
установить соответствующее поле в NULL.
Если какая-то функция экспортируется модулю, то соответствующее поле
может быть установлено в любое значение (обычно NULL).
API модуля базы данных
API модуля базы данных экспортируется модулем IPA утилите в структуре
ipa_db_mod:
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
Версия API модуля базы данных, модуль должен проверять версии
поддерживаемых API с IPA_DB_MOD_API_VERSION во время компиляции.
После загрузки модуля этот номер версии сравнивается с версией
используемого API.
mod_flags
Объяснено выше.
db_name
Имя базы данных модуля.
suppfunc
Объяснено выше.
memfunc
Объяснено выше.
conf_prefix
Объяснено выше.
conf_sect_tbl
Объяснено выше.
conf_param_tbl
Объяснено выше.
conf_init
Объяснено выше.
conf_deinit
Объяснено выше.
conf_event
Объяснено выше.
conf_mimic_real
Объяснено выше.
conf_inherit
Объяснено выше.
conf_show
Объяснено выше.
db_pre_init
Эта функция вызывается после обработки конфигурационного файла.
Модуль должен выполнить общую инициализацию своей базы данных.
Эта функция всегда вызывается перед остальными функциями
db_init*.
db_init_dynrule
Эта функция вызывается, если некоторое динамическое правило
использует модуль. autoruleno это номер автоправила из которого
было сгенерировано динамическое правило, ruleno это номер дина-
мического правила, rule_name это имя правила, rule_info это опи-
сание правила. Только данные на которые указывает rule_name
будут существовать до тех пор пока не будет вызвана
db_deinit_rule для этого правила.
db_init_statrule
Тоже самое что и db_init_dynrule, только для статических правил.
db_init_dynlimit
Эта функция вызывается, если некоторый лимит из динамического
правила использует модуль. limitno это порядковый номер лимита
в правиле, limit_name это его имя и limit_info это его описание.
Остальные аргументы означают тоже самое что и в db_init_dynrule.
Только данные на которые указывают rule_name и limit_name будут
существовать до тех пор пока не будет вызвана db_deinit_limit
для этого лимита. Так как правило может использовать другую
базу данных, то модуль не должен ожидать, что функция
db_init_dynrule была вызвана прежде для правила лимита. Если
правило лимита также использует этот модуль, то db_init_dynrule
для правила вызывается первой.
db_init_statlimit
Тоже самое что и db_init_dynlimit, только для лимитов статиче-
ских правил.
db_init_dynthreshold
Эта функция вызывается, если некоторый порог из динамического
правила использует модуль. thresholdno это порядковый номер
порога в правиле, threshold_name это его имя и threshold_info
это его описание. Остальные аргументы означают тоже самое что и
в db_init_dynrule. Только данные на которые указывают rule_name
и threshold_name будут существовать до тех пор пока не будет
вызвана db_deinit_threshold для этого порога. Так как правило
может использовать другую базу данных, то модуль не должен ожи-
дать, что функция db_init_dynrule была вызвана прежде для пра-
вила порога. Если правило порога также использует этот модуль,
то db_init_dynrule для правила вызывается первой.
db_init_threshold
Тоже самое что и db_init_dynthreshold, только для порогов стати-
ческих правил.
db_init
Эта функция вызывается после все остальных функций
db_init_stat*.
db_get_limit_state
Эта функция должна возвращать текущее состояние лимита. Если
модуль не имеет текущего состояния лимита, то функция должна
вернуть нуль. Если модуль имеет текущее состояние лимита, то
функция должна вернуть 1.
db_set_limit_state
Эта функция должна установить новое состояние лимита. Если
new_state равно нуль, то текущее состояние лимита в базе данных
должно быть обновлено, иначе должно быть зарегистрировано новое
состояние лимита.
db_get_threshold_state
Эта функция должна возвращать текущее состояние порога. Если
модуль не имеет текущего состояния порога, то функция должна
вернуть нуль. Если модуль имеет текущее состояние порога, то
функция должна вернуть 1.
db_set_threshold_state
Эта функция должна обновить текущее состояние порога.
db_deinit_threshold
Эта функция вызывается при деинициализации порога, использующего
модуль. Модуль не должен ожидать, что функция db_init_*thresh-
old была вызвана прежде для этого порога.
db_deinit_limit
Эта функция вызывается при деинициализации лимита, использующего
модуль. Модуль не должен ожидать, что функция db_init_*limit
была вызвана прежде для этого лимита.
db_deinit_rule
Эта функция вызывается при деинициализации правила, использую-
щего модуль. Если какой-то лимит или порог правила также
использует этот модуль, то функция db_deinit_limit или
db_deinit_threshold вызывается первой. Модуль не должен ожи-
дать, что функция db_init_*rule была вызвана прежде для этого
правила.
db_deinit
Эта функция вызывается при деинициализации модуля. Модуль не
должен ожидать, что функции db_*init были вызваны прежде. Эта
функция всегда вызывается после всех остальных функций
db_deinit_*.
db_append_rule
Эта функция должна добавлять новую запись в базу данных для
заданного правила. cnt это указатель на новое значение счётчика
правила. ctm это текущая локальная дата. Эта функция вызыва-
ется перед первым вызовом функции db_update_rule.
db_update_rule
Эта функция должна обновлять запись в базе данных для данного
правила. cnt это указатель на новое значение счётчика, ctm это
текущая локальная дата.
db_update_limit
Эта функция должна обновлять состояние лимита в базе данных.
cnt это указатель на новое значение счётчика, ctm это текущая
локальная дата. Модуль также должен обновить дату
IPA_LIMIT_EVENT_UPDATED.
db_limit_event
Эта функция должна регистрировать событие event для лимита в
базе данных. Данное событие может происходить прямо сейчас или
в будущем. etm равно локальной дате данного события, а ctm
равно текущей локальной дате. Модуль также должен обновить дату
IPA_LIMIT_EVENT_UPDATED. Эта функция вызывается только для сле-
дующих событий лимита IPA_LIMIT_EVENT_: RESTART_EXEC, REACH,
REACH_EXEC, EXPIRE и EXPIRE_EXEC.
db_update_threshold
Эта функция должна обновлять состояние порога в базе данных.
cnt это указатель на новое значение счётчика, tm_from и
tm_updated это две временные отметки порога.
db_set_rule_active
Объяснено выше в ac_set_rule_active. Если правило помечается
как активное, то db_append_rule будет вызвана перед
db_update_rule.
db_set_limit_active
Объяснено выше в ac_set_limit_active.
db_set_threshold_active
Объяснено выше в ac_set_threshold_active.
Если какая-то функция возвращает числовое значение, то в случае ошибки
необходимо вернуть значение -1, иначе функция должна вернуть значение 0
(если соответствующее описание не определяет другого значения).
Если модуль базы данных не поддерживает динамических правил, лимитов
или порогов, то он должен установить соответствующее поле db_init_dyn*
в NULL. Если модуль базы данных не поддерживает статических правил,
лимитов или порогов, то необходимо установить соответствующее поле
db_init_stat* в NULL.
Если модуль базы данных не поддерживает функцию db_get_limit_state,
db_get_threshold_state, db_set_*active, то необходимо установить соот-
ветствующее поле в NULL.
Если какая-то функция экспортируется модулю, то соответствующее поле
может быть установлено в любое значение (обычно NULL).
API модуля статистики
API модуля статистики экспортируется модулем IPA утилите в структуре
ipa_st_mod:
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
Версия API модуля статистики модуль должен проверять версии под-
держиваемых API с IPA_ST_MOD_API_VERSION во время компиляции.
После загрузки модуля этот номер версии сравнивается с версией
используемого API.
mod_flags
Объяснено выше.
st_name
Имя системы статистики модуля.
suppfunc
Объяснено выше.
memfunc
Объяснено выше.
conf_prefix
Объяснено выше.
conf_sect_tbl
Объяснено выше.
conf_param_tbl
Объяснено выше.
conf_init
Объяснено выше.
conf_deinit
Объяснено выше.
conf_event
Объяснено выше.
conf_mimic_real
Объяснено выше.
conf_inherit
Объяснено выше.
conf_show
Объяснено выше.
st_pre_init
Эта функция вызывается после обработки конфигурационного файла.
Модуль должен выполнить общую инициализацию своей системы стати-
стики. Эта функция всегда вызывается перед остальными функциями
st_init*.
st_init_rule
Эта функция вызывается, если некоторое правило использует
модуль. ruleno это номер правила, rule_name это его имя. Дан-
ные на которые указывает rule_name будут существовать пока не
будет вызвана функция st_deinit_rule для этого правила. Эта
функция может быть вызвана для правила, которое имеет соответ-
ствующую секцию в конфигурационном файле и для правила, которое
было сгенерировано на лету (можно рассматривать как динамическое
правило).
st_init_limit
Эта функция вызывается, если некоторый лимит использует модуль.
limitno это порядковый номер лимита в правиле, limit_name это
его имя. Только данные на которые указывает rule_name и
limit_name будут существовать пока не будет вызвана функция
st_deinit_limit для этого лимита. Так как правило может исполь-
зовать другую систему статистики, то модуль не должен ожидать,
что функция st_init_rule была вызвана прежде для правила лимита.
Если правило лимита также использует этот модуль, то
st_init_rule для правила вызывается первой. Подобно
st_init_rule эта функция может быть вызвана для правила и/или
лимита, которое имеет соответствующую секцию в конфигурационном
файле и для правила и/или лимита, которое было сгенерировано на
лету (могут рассматриваться как динамическое правило и/или
лимит).
st_init_threshold
Эта функция вызывается, если некоторый порог использует модуль.
thresholdno это порядковый номер порога в правиле, thresh-
old_name это его имя. Только данные на которые указывает
rule_name и threshold_name будут существовать пока не будет
вызвана функция st_deinit_threshold для этого порога. Так как
правило может использовать другую систему статистики, то модуль
не должен ожидать, что функция st_init_rule была вызвана прежде
для правила порога. Если правило порога также использует этот
модуль, то st_init_rule для правила вызывается первой. Подобно
st_init_rule эта функция может быть вызвана для правила и/или
порога, которое имеет соответствующую секцию в конфигурационном
файле и для правила и/или порога, которое было сгенерировано на
лету (могут рассматриваться как динамическое правило и/или
порог).
st_init
Эта функция вызывается после все остальных функций st_init*.
st_deinit_threshold
Эта функция вызывается при деинициализации порога, использующего
модуль. Модуль не должен ожидать, что функция st_init_threshold
была вызвана прежде для этого порога.
st_deinit_limit
Эта функция вызывается при деинициализации лимита, использующего
модуль. Модуль не должен ожидать, что функция st_init_limit
была вызвана прежде для этого лимита.
st_deinit_rule
Эта функция вызывается при деинициализации правила, использую-
щего модуль. Если какой-то лимит или порог правила также
использует этот модуль, то функция st_deinit_limit или
st_deinit_threshold вызывается первой. Модуль не должен ожи-
дать, что функция st_init_rule была вызвана прежде для этого
правила.
st_deinit
Эта функция вызывается при деинициализации модуля. Модуль не
должен ожидать, что функции st_*init были вызваны прежде. Эта
функция всегда вызывается после всех остальных функций
st_deinit_*.
st_get_rule_info
Эта функция должна вернуть описание для правила номер ruleno,
указатель на описание правила должен быть сохранён в *info_ptr.
Если правило не имеет описания, то *info_ptr должно быть уста-
новлено в NULL.
st_get_limit_info
Тоже самое что и st_get_rule_info, только для лимита.
st_get_threshold_info
Тоже самое что и st_get_rule_info, только для порога.
st_get_rules_list
Эта функция должна вернуть массив с именами и описаниями правил.
Если регулярное выражение POSIX pat не NULL, то модуль должен
вернуть только правила с именами, соответствующими этому регу-
лярному выражению (pat_reg это скомпилированное регулярное выра-
жение pat). Указатель на массив структур struct ipa_entity_desc
должен быть сохранён в *buf_ptr, число элементов массива должно
быть сохранено в *n. Если число элементов массива равно нулю,
то *buf_ptr должно быть установлено в NULL.
st_get_limits_list
Тоже самое что и st_get_rules_list, только для лимитов.
st_get_thresholds_list
Тоже самое что и st_get_rules_list, только для порогов.
st_get_rule_stat
Эта функция используется для запроса статистики для правила
номер ruleno за временной интервал с tm1 по tm2. Если exact
равно нулю, то обе временные отметки записей правила должны быть
внутри данного временного интервала, иначе только одна из вре-
менных отметок записей правила должна быть внутри данного вре-
менного интервала. Указатель на массив структур
struct ipa_rule_stat должен быть сохранён в *buf_ptr, число эле-
ментов массива должно быть сохранено в *n. Если число элементов
массива равно нулю, то *buf_ptr должно быть установлено в NULL.
В структуре struct ipa_rule_stat поля year, mon и mday опреде-
ляют дату обоих временных отметок записи правила (новая запись
для правила всегда добавляется для нового дня, поэтому доста-
точно всего трёх полей для обоих временных отметок). t1, m1 и
s1 это время первой временной отметки, t2, m2 и s1 это время
второй временной отметки. cnt это статистика одной записи пра-
вила.
st_get_limit_stat
Эта функция используется для запроса статистики для лимита номер
limitno из правила номер ruleno, даты когда лимит был запущен
должны быть в интервале от tm1 до tm2. Указатель на массив
структур struct ipa_limit_state должен быть сохранён в *buf_ptr,
число элементов массива должно быть сохранено в *n. Если число
элементов массива равно нулю, то значение *buf_ptr должно быть
установлено в NULL. Если tm1 равно NULL, то должно быть возвра-
щено текущее состояние лимита.
st_get_threshold_stat
Эта функция используется для запроса текущего состояния для
порога номер thresholdno из правила номер ruleno. Если модуль
не имеет текущего состояния порога, то функция должна вернуть
нуль. Если модуль имеет текущее состояние порога, то функция
должна вернуть 1.
Если какая-то функция возвращает числовое значение, то в случае ощибки
необходимо вернуть значение -1, иначе функция должна вернуть значение 0
(если соответствующее описание не определяет другого значения).
Если модуль статистики не поддерживает какие-то функции по запросу ста-
тистики или описания, то необходимо установить соответствующие поля в
NULL.
Если какая-то функция принимает аргумент mem_type, то вся память выде-
ляемая этой функцией и возвращаемая как результат должна быть выделена
с помощью функций ipa_memfunc с типом памяти mem_type.
Если какая-то функция экспортируется модулю, то соответствующее поле
может быть установлено в любое значение (обычно NULL).
ДРУГИЕ ИСТОЧНИКИ
ipa(8), ipactl(8), ipastat(8), ipa.conf(5), ipastat.conf(5)
АВТОР
Andrey Simonenko <simon@comsys.ntu-kpi.kiev.ua>
НЕДОРАБОТКИ
Если вы обнаружите какие-либо ошибки, то, пожалуйста, сообщите мне по
email.
5 декабря 2010 г. IPA_MOD(3)