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_* для работы с памятью общего назначения это обёртки (wrappers) для стандартных функций работы с памятью из библиотеки (malloc(3), calloc(3), realloc(3), free(3), strdup(3) и для функции vasprintf(3), присутствующей на некоторых системах). Все эти функции выполняют дополнительные проверки. Любая память выделенная с помощью функции mem_* должна быть освобождена с помощью функции mem_free. Эти функции принимают дополнительный аргумент, называемый mem_type (тип памяти), который используется для сбора статистики об использовании памяти. Этот mem_type должен быть создан функцией mem_type_new.

Marrays используются для создания массивов некоторых элементов. Mzones используются для создание элементов одного размера. Все функции marray_* и mzone_* сами используют функции mem_*.

Функции из ipa_memfunc обнаруживают неправильные указатели и некорректные аргументы в функциях mem_*, marray_* и mzone_*. Если будет обнаружена критическая ошибка в любой из этих функций, то эта функция завершит выполнение программы с генерацией дампа памяти.

Если IPA утилиты были собраны с определённой макропеременной WITH_MEMFUNC_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 может быть изменён последующими вызовами функций marray_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_MEMFUNC_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_create_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_*threshold была вызвана прежде для этого порога.

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 это порядковый номер порога в правиле, threshold_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.