From 56d5d732b987d8584b2b49943cdd7d8c2376804f Mon Sep 17 00:00:00 2001 From: Pablo Neira Ayuso Date: Sat, 11 Apr 2009 16:57:01 +0200 Subject: doc: add libnetfilter_log doxygen documentation and update copyright notice This patch adds the libnetfilter_log documentation in doxygen format. I have also added myself to the copyright header in the libnetfilter_log.c file according to my contributions available in the git repository. Signed-off-by: Pablo Neira Ayuso --- configure.in | 2 +- doxygen.cfg.in | 184 +++++++++++++++++++++ src/libnetfilter_log.c | 436 ++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 616 insertions(+), 6 deletions(-) create mode 100644 doxygen.cfg.in diff --git a/configure.in b/configure.in index 94bf52e..cdde6ad 100644 --- a/configure.in +++ b/configure.in @@ -31,5 +31,5 @@ LIBNFLOG_LIBS="$LIBNFNETLINK_LIBS" AC_SUBST(LIBNFLOG_LIBS) dnl Output the makefile -AC_OUTPUT(Makefile src/Makefile include/Makefile include/libnetfilter_log/Makefile utils/Makefile libnetfilter_log.pc) +AC_OUTPUT(Makefile src/Makefile include/Makefile include/libnetfilter_log/Makefile utils/Makefile libnetfilter_log.pc doxygen.cfg) diff --git a/doxygen.cfg.in b/doxygen.cfg.in new file mode 100644 index 0000000..37bfa7c --- /dev/null +++ b/doxygen.cfg.in @@ -0,0 +1,184 @@ +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = @PACKAGE@ +PROJECT_NUMBER = @VERSION@ +OUTPUT_DIRECTORY = doxygen +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +TYPEDEF_HIDES_STRUCT = NO +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +INPUT = . +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.c +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +HTML_DYNAMIC_SECTIONS = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +GENERATE_MAN = YES +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +GENERATE_AUTOGEN_DEF = NO +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +CLASS_DIAGRAMS = YES +MSCGEN_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = YES +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +SEARCHENGINE = NO diff --git a/src/libnetfilter_log.c b/src/libnetfilter_log.c index cad78aa..49033a2 100644 --- a/src/libnetfilter_log.c +++ b/src/libnetfilter_log.c @@ -1,6 +1,7 @@ /* libnetfilter_log.c: generic library for access to NFLOG * * (C) 2005 by Harald Welte + * (C) 2005, 2008-2010 by Pablo Neira Ayuso * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License version 2 @@ -31,6 +32,35 @@ #include #include +/** + * \mainpage + * + * libnetfilter_log is a userspace library providing interface to packets + * that have been logged by the kernel packet filter. It is is part of a + * system that deprecates the old syslog/dmesg based packet logging. + * + * libnetfilter_log homepage is: + * http://netfilter.org/projects/libnetfilter_log/ + * + * \section Dependencies + * libnetfilter_log requires libnfnetlink and a kernel that includes the + * nfnetlink_log subsystem (i.e. 2.6.14 or later). + * + * \section Main Features + * - receiving to-be-logged packets from the kernel nfnetlink_log subsystem + * + * \section Git Tree + * The current development version of libnetfilter_log can be accessed + * at https://git.netfilter.org/cgi-bin/gitweb.cgi?p=libnetfilter_log.git + * + * \section Using libnetfilter_log + * + * To write your own program using libnetfilter_log, you should start by + * reading the doxygen documentation (start by \link LibrarySetup \endlink + * page) and nfulnl_test.c source file. + * + */ + struct nflog_handle { struct nfnl_handle *nfnlh; @@ -144,11 +174,69 @@ struct nfnl_handle *nflog_nfnlh(struct nflog_handle *h) return h->nfnlh; } +/** + * + * \defgroup Log Group handling + * + * Once libnetfilter_log library has been initialised (See + * \link LibrarySetup \endlink), it is possible to bind the program to + * a specific group. This can be done using nflog_bind_group(). + * + * The group can then be tuned via nflog_set_mode() among many others. + * + * Here's a little code snippet that binds to the group 100: + * \verbatim + printf("binding this socket to group 0\n"); + qh = nflog_bind_group(h, 0); + if (!qh) { + fprintf(stderr, "no handle for grup 0\n"); + exit(1); + } + + printf("setting copy_packet mode\n"); + if (nflog_set_mode(qh, NFULNL_COPY_PACKET, 0xffff) < 0) { + fprintf(stderr, "can't set packet copy mode\n"); + exit(1); + } +\endverbatim + * + * Next step is the handling of incoming packets which can be done via a loop: + * + * \verbatim + fd = nflog_fd(h); + + while ((rv = recv(fd, buf, sizeof(buf), 0)) && rv >= 0) { + printf("pkt received (len=%u)\n", rv); + nflog_handle_packet(h, buf, rv); + } +\endverbatim + * + * Data and information about the packet can be fetch by using message parsing + * functions (See \link Parsing \endlink). + * @{ + */ + +/** + * nflog_fd - get the file descriptor associated with the nflog handler + * \param log handler obtained via call to nflog_open() + * + * \return a file descriptor for the netlink connection associated with the + * given log connection handle. The file descriptor can then be used for + * receiving the logged packets for processing. + * + * This function returns a file descriptor that can be used for communication + * over the netlink connection associated with the given log connection + * handle. + */ int nflog_fd(struct nflog_handle *h) { return nfnl_fd(nflog_nfnlh(h)); } +/** + * @} + */ + struct nflog_handle *nflog_open_nfnl(struct nfnl_handle *nfnlh) { struct nflog_handle *h; @@ -183,6 +271,21 @@ out_free: return NULL; } +/** + * \addtogroup LibrarySetup + * @{ + */ + +/** + * nflog_open - open a nflog handler + * + * This function obtains a netfilter log connection handle. When you are + * finished with the handle returned by this function, you should destroy + * it by calling nflog_close(). A new netlink connection is obtained internally + * and associated with the log connection handle returned. + * + * \return a pointer to a new log handle or NULL on failure. + */ struct nflog_handle *nflog_open(void) { struct nfnl_handle *nfnlh; @@ -204,6 +307,10 @@ struct nflog_handle *nflog_open(void) return lh; } +/** + * @} + */ + int nflog_callback_register(struct nflog_g_handle *gh, nflog_callback *cb, void *data) { @@ -218,6 +325,23 @@ int nflog_handle_packet(struct nflog_handle *h, char *buf, int len) return nfnl_handle_packet(h->nfnlh, buf, len); } +/** + * \addtogroup LibrarySetup + * + * When the program has finished with libnetfilter_log, it has to call + * the nflog_close() function to release all associated resources. + * + * @{ + */ + +/** + * nflog_close - close a nflog handler + * \param h Netfilter log handle obtained via call to nflog_open() + * + * This function closes the nflog handler and free associated resources. + * + * \return 0 on success, non-zero on failure. + */ int nflog_close(struct nflog_handle *h) { int ret = nfnl_close(h->nfnlh); @@ -225,19 +349,51 @@ int nflog_close(struct nflog_handle *h) return ret; } -/* bind nf_log from a specific protocol family */ +/** + * nflog_bind_pf - bind a nflog handler to a given protocol family + * \param h Netfilter log handle obtained via call to nflog_open() + * \param pf protocol family to bind to nflog handler obtained from nflog_open() + * + * Binds the given log connection handle to process packets belonging to + * the given protocol family (ie. PF_INET, PF_INET6, etc). + * + * \return integer inferior to 0 in case of failure + */ int nflog_bind_pf(struct nflog_handle *h, u_int16_t pf) { return __build_send_cfg_msg(h, NFULNL_CFG_CMD_PF_BIND, 0, pf); } -/* unbind nf_log from a specific protocol family */ + +/** + * nflog_unbind_pf - unbind nflog handler from a protocol family + * \param h Netfilter log handle obtained via call to nflog_open() + * \param pf protocol family to unbind family from + * + * Unbinds the given nflog handle from processing packets belonging + * to the given protocol family. + */ int nflog_unbind_pf(struct nflog_handle *h, u_int16_t pf) { return __build_send_cfg_msg(h, NFULNL_CFG_CMD_PF_UNBIND, 0, pf); } -/* bind this socket to a specific group number */ +/** + * @} + */ + +/** + * \addtogroup Log Group handling + * @{ + */ + +/** + * nflog_bind_group - bind a new handle to a specific group number. + * \param h Netfilter log handle obtained via call to nflog_open() + * \param num the number of the group to bind to + * + * \return a nflog_g_handle pointing to the newly created group + */ struct nflog_g_handle * nflog_bind_group(struct nflog_handle *h, u_int16_t num) { @@ -263,7 +419,21 @@ nflog_bind_group(struct nflog_handle *h, u_int16_t num) return gh; } -/* unbind this socket from a specific group number */ +/** + * @} + */ + +/** + * \addtogroup Log Group handling + * @{ + */ + +/** + * nflog_unbind_group - unbind a group handle. + * \param gh Netfilter log group handle obtained via nflog_bind_group() + * + * \return -1 in case of error and errno is explicity in case of error. + */ int nflog_unbind_group(struct nflog_g_handle *gh) { int ret = __build_send_cfg_msg(gh->h, NFULNL_CFG_CMD_UNBIND, gh->id, 0); @@ -275,6 +445,21 @@ int nflog_unbind_group(struct nflog_g_handle *gh) return ret; } +/** + * nflog_set_mode - set the amount of packet data that nflog copies to userspace + * \param qh Netfilter log handle obtained by call to nflog_bind_group(). + * \param mode the part of the packet that we are interested in + * \param range size of the packet that we want to get + * + * Sets the amount of data to be copied to userspace for each packet logged + * to the given group. + * + * - NFULNL_COPY_NONE - do not copy any data + * - NFULNL_COPY_META - copy only packet metadata + * - NFULNL_COPY_PACKET - copy entire packet + * + * \return -1 on error; >= otherwise. + */ int nflog_set_mode(struct nflog_g_handle *gh, u_int8_t mode, u_int32_t range) { @@ -296,6 +481,18 @@ int nflog_set_mode(struct nflog_g_handle *gh, return nfnl_query(gh->h->nfnlh, &u.nmh); } +/** + * nflog_set_timeout - set the maximum time to push log buffer for this group + * \param gh Netfilter log handle obtained by call to nflog_bind_group(). + * \param timeout Time to wait until the log buffer is pushed to userspace + * + * This function allows to set the maximum time that nflog waits until it + * pushes the log buffer to userspace if no new logged packets have occured. + * Basically, nflog implements a buffer to reduce the computational cost + * of delivering the log message to userspace. + * + * \return -1 in case of error and errno is explicity set. + */ int nflog_set_timeout(struct nflog_g_handle *gh, u_int32_t timeout) { union { @@ -311,6 +508,16 @@ int nflog_set_timeout(struct nflog_g_handle *gh, u_int32_t timeout) return nfnl_query(gh->h->nfnlh, &u.nmh); } +/** + * nflog_set_qthresh - set the maximum amount of logs in buffer for this group + * \param gh Netfilter log handle obtained by call to nflog_bind_group(). + * \param qthresh Maximum number of log entries + * + * This function determines the maximum number of log entries in the buffer + * until it is pushed to userspace. + * + * \return -1 in case of error and errno is explicity set. + */ int nflog_set_qthresh(struct nflog_g_handle *gh, u_int32_t qthresh) { union { @@ -326,6 +533,16 @@ int nflog_set_qthresh(struct nflog_g_handle *gh, u_int32_t qthresh) return nfnl_query(gh->h->nfnlh, &u.nmh); } +/** + * nflog_set_nlbufsiz - set the size of the nflog buffer for this group + * \param gh Netfilter log handle obtained by call to nflog_bind_group(). + * \param nlbufsiz Size of the nflog buffer + * + * This function sets the size (in bytes) of the buffer that is used to + * stack log messages in nflog. + * + * \return -1 in case of error and errno is explicity set. + */ int nflog_set_nlbufsiz(struct nflog_g_handle *gh, u_int32_t nlbufsiz) { union { @@ -348,6 +565,18 @@ int nflog_set_nlbufsiz(struct nflog_g_handle *gh, u_int32_t nlbufsiz) return status; } +/** + * nflog_set_flags - set the nflog flags for this group + * \param gh Netfilter log handle obtained by call to nflog_bind_group(). + * \param flags Flags that you want to set + * + * There are two existing flags: + * + * - NFULNL_CFG_F_SEQ: This enables local nflog sequence numbering. + * - NFULNL_CFG_F_SEQ_GLOBAL: This enables global nflog sequence numbering. + * + * \return -1 in case of error and errno is explicity set. + */ int nflog_set_flags(struct nflog_g_handle *gh, u_int16_t flags) { union { @@ -363,34 +592,91 @@ int nflog_set_flags(struct nflog_g_handle *gh, u_int16_t flags) return nfnl_query(gh->h->nfnlh, &u.nmh); } +/** + * @} + */ + +/** + * \defgroup Parsing Message parsing functions + * @{ + */ +/** + * nflog_get_msg_packet_hdr - return the metaheader that wraps the packet + * \param nfad Netlink packet data handle passed to callback function + * + * \return the netfilter log netlink packet header for the given nflog_data + * argument. Typically, the nflog_data value is passed as the 3rd parameter + * to the callback function set by a call to nflog_callback_register(). + * + * The nfulnl_msg_packet_hdr structure is defined in libnetfilter_log.h as: + *\verbatim + struct nfulnl_msg_packet_hdr { + u_int16_t hw_protocol; // hw protocol (network order) + u_int8_t hook; // netfilter hook + u_int8_t _pad; + } __attribute__ ((packed)); +\endverbatim + */ struct nfulnl_msg_packet_hdr *nflog_get_msg_packet_hdr(struct nflog_data *nfad) { return nfnl_get_pointer_to_data(nfad->nfa, NFULA_PACKET_HDR, struct nfulnl_msg_packet_hdr); } - +/** + * nflog_get_hwtype - get the hardware link layer type from logging data + * \param nfad pointer to logging data + * + * \return the hardware link layer type. + */ u_int16_t nflog_get_hwtype(struct nflog_data *nfad) { return ntohs(nfnl_get_data(nfad->nfa, NFULA_HWTYPE, u_int16_t)); } +/** + * nflog_get_hwhdrlen - get the length of the hardware link layer header + * \param nfad pointer to logging data + * + * \return the size of the hardware link layer header + */ u_int16_t nflog_get_msg_packet_hwhdrlen(struct nflog_data *nfad) { return ntohs(nfnl_get_data(nfad->nfa, NFULA_HWLEN, u_int16_t)); } +/** + * nflog_get_msg_packet_hwhdr - get the hardware link layer header + * \param nfad pointer to logging data + * + * \return the hardware link layer header + */ char *nflog_get_msg_packet_hwhdr(struct nflog_data *nfad) { return nfnl_get_pointer_to_data(nfad->nfa, NFULA_HWHEADER, char); } +/** + * nflog_get_nfmark - get the packet mark + * \param nfad Netlink packet data handle passed to callback function + * + * \return the netfilter mark currently assigned to the logged packet. + */ u_int32_t nflog_get_nfmark(struct nflog_data *nfad) { return ntohl(nfnl_get_data(nfad->nfa, NFULA_MARK, u_int32_t)); } +/** + * nflog_get_timestamp - get the packet timestamp + * \param nfad Netlink packet data handle passed to callback function + * \param tv structure to fill with timestamp info + * + * Retrieves the received timestamp when the given logged packet. + * + * \return 0 on success, a negative value on failure. + */ int nflog_get_timestamp(struct nflog_data *nfad, struct timeval *tv) { struct nfulnl_msg_packet_timestamp *uts; @@ -406,32 +692,100 @@ int nflog_get_timestamp(struct nflog_data *nfad, struct timeval *tv) return 0; } +/** + * nflog_get_indev - get the interface that the packet was received through + * \param nfad Netlink packet data handle passed to callback function + * + * \return The index of the device the packet was received via. If the + * returned index is 0, the packet was locally generated or the input + * interface is not known (ie. POSTROUTING?). + * + * \warning all nflog_get_dev() functions return 0 if not set, since linux + * only allows ifindex >= 1, see net/core/dev.c:2600 (in 2.6.13.1) + */ u_int32_t nflog_get_indev(struct nflog_data *nfad) { return ntohl(nfnl_get_data(nfad->nfa, NFULA_IFINDEX_INDEV, u_int32_t)); } +/** + * nflog_get_physindev - get the physical interface that the packet was received + * \param nfad Netlink packet data handle passed to callback function + * + * \return The index of the physical device the packet was received via. + * If the returned index is 0, the packet was locally generated or the + * physical input interface is no longer known (ie. POSTROUTING?). + */ u_int32_t nflog_get_physindev(struct nflog_data *nfad) { return ntohl(nfnl_get_data(nfad->nfa, NFULA_IFINDEX_PHYSINDEV, u_int32_t)); } +/** + * nflog_get_outdev - gets the interface that the packet will be routed out + * \param nfad Netlink packet data handle passed to callback function + * + * \return The index of the device the packet will be sent out. If the + * returned index is 0, the packet is destined for localhost or the output + * interface is not yet known (ie. PREROUTING?). + */ u_int32_t nflog_get_outdev(struct nflog_data *nfad) { return ntohl(nfnl_get_data(nfad->nfa, NFULA_IFINDEX_OUTDEV, u_int32_t)); } +/** + * nflog_get_physoutdev - get the physical interface that the packet output + * \param nfad Netlink packet data handle passed to callback function + * + * The index of the physical device the packet will be sent out. If the + * returned index is 0, the packet is destined for localhost or the + * physical output interface is not yet known (ie. PREROUTING?). + * + * \return The index of physical interface that the packet output will be + * routed out. + */ u_int32_t nflog_get_physoutdev(struct nflog_data *nfad) { return ntohl(nfnl_get_data(nfad->nfa, NFULA_IFINDEX_PHYSOUTDEV, u_int32_t)); } +/** + * nflog_get_packet_hw - get hardware address + * \param nfad Netlink packet data handle passed to callback function + * + * Retrieves the hardware address associated with the given packet. + * For ethernet packets, the hardware address returned (if any) will be the + * MAC address of the packet source host. The destination MAC address is not + * known until after POSTROUTING and a successful ARP request, so cannot + * currently be retrieved. + * + * The nfulnl_msg_packet_hw structure is defined in libnetfilter_log.h as: + * \verbatim + struct nfulnl_msg_packet_hw { + u_int16_t hw_addrlen; + u_int16_t _pad; + u_int8_t hw_addr[8]; + } __attribute__ ((packed)); +\endverbatim + */ struct nfulnl_msg_packet_hw *nflog_get_packet_hw(struct nflog_data *nfad) { return nfnl_get_pointer_to_data(nfad->nfa, NFULA_HWADDR, struct nfulnl_msg_packet_hw); } +/** + * nflog_get_payload - get payload of the logged packet + * \param nfad Netlink packet data handle passed to callback function + * \param data Pointer of pointer that will be pointed to the payload + * + * Retrieve the payload for a logged packet. The actual amount and type of + * data retrieved by this function will depend on the mode set with the + * nflog_set_mode() function. + * + * \return -1 on error, otherwise > 0. + */ int nflog_get_payload(struct nflog_data *nfad, char **data) { *data = nfnl_get_pointer_to_data(nfad->nfa, NFULA_PAYLOAD, char); @@ -441,11 +795,24 @@ int nflog_get_payload(struct nflog_data *nfad, char **data) return -1; } +/** + * nflog_get_prefix - get the logging string prefix + * \param nfad Netlink packet data handle passed to callback function + * + * \return the string prefix that is specified as argument to the iptables' + * NFLOG target. + */ char *nflog_get_prefix(struct nflog_data *nfad) { return nfnl_get_pointer_to_data(nfad->nfa, NFULA_PREFIX, char); } +/** + * nflog_get_uid - get the UID of the user that has generated the packet + * \param nfad Netlink packet data handle passed to callback function + * + * \return the UID of the user that has genered the packet, if any. + */ int nflog_get_uid(struct nflog_data *nfad, u_int32_t *uid) { if (!nfnl_attr_present(nfad->nfa, NFULA_UID)) @@ -455,6 +822,12 @@ int nflog_get_uid(struct nflog_data *nfad, u_int32_t *uid) return 0; } +/** + * nflog_get_gid - get the GID of the user that has generated the packet + * \param nfad Netlink packet data handle passed to callback function + * + * \return the GID of the user that has genered the packet, if any. + */ int nflog_get_gid(struct nflog_data *nfad, u_int32_t *gid) { if (!nfnl_attr_present(nfad->nfa, NFULA_GID)) @@ -464,6 +837,14 @@ int nflog_get_gid(struct nflog_data *nfad, u_int32_t *gid) return 0; } +/** + * nflog_get_seq - get the local nflog sequence number + * \param nfad Netlink packet data handle passed to callback function + * + * You must enable this via nflog_set_flags(). + * + * \return the local nflog sequence number. + */ int nflog_get_seq(struct nflog_data *nfad, u_int32_t *seq) { if (!nfnl_attr_present(nfad->nfa, NFULA_SEQ)) @@ -473,6 +854,14 @@ int nflog_get_seq(struct nflog_data *nfad, u_int32_t *seq) return 0; } +/** + * nflog_get_seq_global - get the global nflog sequence number + * \param nfad Netlink packet data handle passed to callback function + * + * You must enable this via nflog_set_flags(). + * + * \return the global nflog sequence number. + */ int nflog_get_seq_global(struct nflog_data *nfad, u_int32_t *seq) { if (!nfnl_attr_present(nfad->nfa, NFULA_SEQ_GLOBAL)) @@ -482,6 +871,10 @@ int nflog_get_seq_global(struct nflog_data *nfad, u_int32_t *seq) return 0; } +/** + * @} + */ + #define SNPRINTF_FAILURE(ret, rem, offset, len) \ do { \ if (ret < 0) \ @@ -493,6 +886,35 @@ do { \ rem -= ret; \ } while (0) +/** + * \defgroup Printing + * @{ + */ + +/** + * nflog_snprintf_xml - print the logged packet in XML format into a buffer + * \param buf The buffer that you want to use to print the logged packet + * \param rem The size of the buffer that you have passed + * \param tb Netlink packet data handle passed to callback function + * \param flags The flag that tell what to print into the buffer + * + * This function supports the following flags: + * + * - NFLOG_XML_PREFIX: include the string prefix + * - NFLOG_XML_HW: include the hardware link layer address + * - NFLOG_XML_MARK: include the packet mark + * - NFLOG_XML_DEV: include the device information + * - NFLOG_XML_PHYSDEV: include the physical device information + * - NFLOG_XML_PAYLOAD: include the payload (in hexadecimal) + * - NFLOG_XML_TIME: include the timestamp + * - NFLOG_XML_ALL: include all the logging information (all flags set) + * + * You can combine this flags with an binary OR. + * + * \return -1 in case of failure, otherwise the length of the string that + * would have been printed into the buffer (in case that there is enough + * room in it). See snprintf() return value for more information. + */ int nflog_snprintf_xml(char *buf, size_t rem, struct nflog_data *tb, int flags) { struct nfulnl_msg_packet_hdr *ph; @@ -639,3 +1061,7 @@ int nflog_snprintf_xml(char *buf, size_t rem, struct nflog_data *tb, int flags) return len; } + +/** + * @} + */ -- cgit v1.2.3