NAME

ipa_sdb -- database format for ipa_db_sdb(8) and ipa_st_sdb(8)

SYNOPSIS

#include "ipa_sdb_config.h"
#include <ipa_sdb.h>

DESCRIPTION

ipa_sdb is a database for IPA database module with the following features:

-: All database files and directories are stored in own database formats;
-: Each rule, limit and threshold has own directory;
-: Formats of database files are machine architecture independent;
-: Sizes of database records are relatively small: the size of a rule's record is 15 bytes, the size of a limit's record is 73 bytes and the size of a threshold's record is 30 bytes.

DATABASE FORMAT

All structures needed for direct access to database data are available in the ipa_sdb.h C-header file.

The ipa_sdb_config.h file has macros for packing structures, which are determined by the configure script (check its content). If you use another compiler than the compiler used by the configure script, then modify this file and redefine these macros.

By default main database directory is IPA_SDB_DB_DIR, but since it can be changed, then let's call it <DB>.

The ipa_db_sdb(8) and ipa_st_sdb(8) modules do not expect that any file or directory they currently use can be removed, renamed or modified by another process.

The the version number of the database format is stored in the <DB>/IPA_SDB_VERSION_FILE file. There is the IPA_SDB_FORMAT_VERSION macro variable, which is equal to the version number of the database format.

Statistics for an arbitrary rule is stored in the <DB>/<rule> directory. There are files with yyyymm like names in this directory which contain statistics per year/month.

Each <rule>/yyyymm file contains records with the following format:

struct ipa_sdb_rule_record {


    uint8_t             mday;


    uint8_t             h1;


    uint8_t             m1;


    uint8_t             s1;


    uint8_t             h2;


    uint8_t             m2;


    uint8_t             s2;


    uint32_t            c_high;


    uint32_t            c_low;
};

mday is a day of a month, h1, m1 and s1 is time when a record was added to the database, h2, m2 and s2 is time when a record was updated last time. c_high and c_low are high 32-bit part and low 32-bit part of the counter, each of these parts is represented in network byte order. Since a new record for any new day is always appended, then it is enough to have only the mday field here.

The <rule>/IPA_SDB_INFO_FILE file contains description of the rule.

Data for limits is kept in the <rule>/IPA_SDB_LIMITS_DIR directory, data for each limit is stored in the <limit> directory. There are files with yyyymm like names in this directory which contain statistics per year/month. Here year/month means year and month when a limit was started.

Each <limit>/yyyymm file contains records with the following format:

struct ipa_sdb_date_struct {


    uint16_t            year;


    uint8_t             mon;


    uint8_t             mday;


    uint8_t             hour;


    uint8_t             min;


    uint8_t             sec;
};
typedef struct ipa_sdb_date_struct ipa_sdb_date;
#define IPA_SDB_DATE_START_SET         0x01
#define IPA_SDB_DATE_RESTART_SET       0x02
#define IPA_SDB_DATE_RESTART_EXEC_SET  0x04
#define IPA_SDB_DATE_REACH_SET         0x08
#define IPA_SDB_DATE_REACH_EXEC_SET    0x10
#define IPA_SDB_DATE_EXPIRE_SET        0x20
#define IPA_SDB_DATE_EXPIRE_EXEC_SET   0x40
#define IPA_SDB_DATE_UPDATED_SET       0x80
struct ipa_sdb_limit_record {


    uint8_t             set;


    ipa_sdb_date        start;


    ipa_sdb_date        restart;


    ipa_sdb_date        restart_exec;


    ipa_sdb_date        reach;


    ipa_sdb_date        reach_exec;


    ipa_sdb_date        expire;


    ipa_sdb_date        expire_exec;


    uint32_t            l_high;


    uint32_t            l_low;


    ipa_sdb_date        updated;


    uint32_t            c_high;


    uint32_t            c_low;
};

IPA_SDB_DATE_xxx_SET bits in the set field determine which of fields with ipa_sdb_data type have actual data. start is a date when a limit was started, restart is a date when a limit will be restarted, restart_exec is a date when commands for restarted limit were run, reach is a date when a limit was reached, reach_exec is a date when commands for reached limit were run, expire is a date when a limit will expire, expire_exec is a date when commands for expired limit were run and updated is a date when a limit was updated last time.

The year field in the ipa_sdb_date structure is represented in network byte order.

l_high and l_low represent value of the limit, c_high and c_low represent value of the limit's counter. These fields have the same format as c_high and c_low fields in the ipa_sdb_rule_record structure.

The <limit>/IPA_SDB_INFO_FILE file contains description of the limit.

Data for thresholds is kept in the <rule>/IPA_SDB_THRESHOLDS_DIR directory, data for each threshold is stored in the <threshold> directory. The <threshold>/IPA_SDB_THRESHOLD_STATE file contains current threshold's state:

struct ipa_sdb_threshold_record {


    uint32_t            t_high;


    uint32_t            t_low;


    uint32_t            c_high;


    uint32_t            c_low;


    ipa_sdb_date        tm_started;


    ipa_sdb_date        tm_updated;
};

t_high and t_low represent value of the threshold, c_high and c_low represent value of the threshold's counter. These fields have the same format as c_high and c_low fields in the ipa_sdb_rule_record structure.

tm_started and tm_updated are two timestamps for the threshold.

The <threshold>/IPA_SDB_INFO_FILE file contains description of the threshold.

AUTHOR

Andrey Simonenko <simon@comsys.ntu-kpi.kiev.ua>

BUGS