From b74d136284f41f529c82bc6cde4cf880df47853e Mon Sep 17 00:00:00 2001 From: Alex 'AdUser' Z Date: Fri, 14 Oct 2016 15:00:08 +1000 Subject: [PATCH] * jail.h : doxygen comments --- src/jail.h | 103 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 76 insertions(+), 27 deletions(-) diff --git a/src/jail.h b/src/jail.h index 9a7c5b3..4318acc 100644 --- a/src/jail.h +++ b/src/jail.h @@ -15,45 +15,94 @@ #include "backend.h" typedef struct f2b_jail_t { - struct f2b_jail_t *next; - bool enabled; - time_t bantime; - time_t findtime; - time_t expiretime; - size_t maxretry; - size_t bancount; - size_t matchcount; - float incr_bantime; - float incr_findtime; - char name[CONFIG_KEY_MAX]; - char glob[PATH_MAX]; - char backend_name[CONFIG_KEY_MAX]; - char backend_init[CONFIG_VAL_MAX]; - char filter_name[CONFIG_KEY_MAX]; - char filter_init[CONFIG_VAL_MAX]; - char source_name[CONFIG_KEY_MAX]; - char source_init[CONFIG_VAL_MAX]; - f2b_source_t *source; - f2b_filter_t *filter; - f2b_backend_t *backend; - f2b_ipaddr_t *ipaddrs; + struct f2b_jail_t *next; /**< pointer to next jail */ + bool enabled; /**< option: is jail enabled */ + time_t bantime; /**< option: ban host for this time if maxretry exceeded */ + time_t findtime; /**< option: time period for counting matches */ + time_t expiretime; /**< option: forget about host after this time with on activity (not including bantime) */ + size_t maxretry; /**< option: maximum count of matches before ban */ + size_t bancount; /**< stats: total number of bans for this jail */ + size_t matchcount; /**< stats: total number of matches for this jail */ + float incr_bantime; /**< option: multiplier for bantime */ + float incr_findtime; /**< option: multiplier for finetime */ + char name[CONFIG_KEY_MAX]; /**< name of the jail */ + char glob[PATH_MAX]; /**< deprecated */ + char backend_name[CONFIG_KEY_MAX]; /**< backend name from config (eg [backend:$NAME] section) */ + char backend_init[CONFIG_VAL_MAX]; /**< backend init string (eg `backend = NAME:$INIT_STRING` line from jail section) */ + char filter_name[CONFIG_KEY_MAX]; /**< filter name from config (eg [filter:$NAME] section) */ + char filter_init[CONFIG_VAL_MAX]; /**< filter init string (eg `filter = NAME:$INIT_STRING` line from jail section) */ + char source_name[CONFIG_KEY_MAX]; /**< source name from config (eg [source:$NAME] section) */ + char source_init[CONFIG_VAL_MAX]; /**< source init string (eg `source = NAME:$INIT_STRING` line from jail section) */ + f2b_source_t *source; /**< pointer to source */ + f2b_filter_t *filter; /**< pointer to filter */ + f2b_backend_t *backend; /**< pointer to backend */ + f2b_ipaddr_t *ipaddrs; /**< list of known ip addresses */ } f2b_jail_t; +/** defined jails list */ extern f2b_jail_t *jails; void f2b_jail_parse_compound_value(const char *value, char *name, char *init); +/** + * @brief Apply defaults to jail template (affects later f2b_jail_create()) + * @param section 'defaults' section from config + */ +void f2b_jail_set_defaults(f2b_config_section_t *section); +/** + * @brief Create jail struct and init it's metadata + * @param section Jail config section + * @return Pointer to allocated jail or NULL on error + */ f2b_jail_t *f2b_jail_create (f2b_config_section_t *section); -f2b_jail_t *f2b_jail_find (f2b_jail_t *list, const char *name); -void f2b_jail_set_defaults(f2b_config_section_t *section); +/** + * @brief Find jail in jail list by name + * @param list Jails list + * @param name Jail name + * @returns Pointer to wanted jail or NULL if not found + */ +f2b_jail_t *f2b_jail_find (f2b_jail_t *list, const char *name); + +/** + * @brief Setup source, filter and backend in jail + * @param jail Jail pointer + * @param config Pointer to f2b config + * @return true on success, false on error + */ +bool f2b_jail_init(f2b_jail_t *jail, f2b_config_t *config); +/** + * @brief Jail maintenance routine + * Polls source for data, match against filter, manage matches, + * ban ips, that exceeded their limit, unban ips after bantime expire + * @param jail Jail for processing + */ +size_t f2b_jail_process (f2b_jail_t *jail); +/** + * @brief Correctly shutdown given jail + * @param jail Jail pointer + * @note Jail structure not deallocated + */ +bool f2b_jail_stop (f2b_jail_t *jail); bool f2b_jail_ban (f2b_jail_t *jail, f2b_ipaddr_t *addr); bool f2b_jail_unban (f2b_jail_t *jail, f2b_ipaddr_t *addr); -bool f2b_jail_init (f2b_jail_t *jail, f2b_config_t *config); -size_t f2b_jail_process (f2b_jail_t *jail); -bool f2b_jail_stop (f2b_jail_t *jail); +/* handler for cmsg */ +/** + * @brief Get jail status + * @param res Response buffer + * @param ressize Size of buffer above + * @param Jail pointer + */ void f2b_jail_cmd_status (char *res, size_t ressize, f2b_jail_t *jail); +/** + * @brief ipaddr manage routine in given jail + * @param res Response buffer + * @param ressize Size of buffer above + * @param Jail pointer + * @param op Operation for ipaddr >0 - ban, 0 - check, <0 - unban + * @param ip Ip address + */ void f2b_jail_cmd_ip_xxx (char *res, size_t ressize, f2b_jail_t *jail, int op, const char *ip); #endif /* F2B_JAIL_H_ */