Log(3)

📦
version 1.0.2 · 5 versions
, in ubuntu noble, ubuntu questing

💖 Log(3) — bestie's guide to libnetfilter_log group handling 💖

okay so this is the Log(3) page from the Library Functions Manual, and it's literally all about Group handling in libnetfilter_log. no cap, this is the one you want if you're trying to make your program actually listen to netfilter log groups. let's get into it 🫶

✨ NAME ✨

nflog_fd, nflog_callback_register, nflog_handle_packet, nflog_bind_group, nflog_unbind_group, nflog_set_mode, nflog_set_timeout, nflog_set_qthresh, nflog_set_nlbufsiz, nflog_set_flags — group handling. that's the whole squad 💅

🌸 SYNOPSIS 🌸

#include <stddef.h>
#include <libnetfilter_log/libnetfilter_log.h>

int nflog_fd (struct nflog_handle *h)
int nflog_callback_register (struct nflog_g_handle *gh, nflog_callback *cb, void *data)
int nflog_handle_packet (struct nflog_handle *h, char *buf, int len)
struct nflog_g_handle * nflog_bind_group (struct nflog_handle *h, uint16_t num)
int nflog_unbind_group (struct nflog_g_handle *gh)
int nflog_set_mode (struct nflog_g_handle *gh, uint8_t mode, uint32_t range)
int nflog_set_timeout (struct nflog_g_handle *gh, uint32_t timeout)
int nflog_set_qthresh (struct nflog_g_handle *gh, uint32_t qthresh)
int nflog_set_nlbufsiz (struct nflog_g_handle *gh, uint32_t nlbufsiz)
int nflog_set_flags (struct nflog_g_handle *gh, uint16_t flags)

🦋 Detailed Description 🦋

so once the libnetfilter_log library has been initialised (peep LibrarySetup for that part), you can bind your program to a specific group. the way you do that is with nflog_bind_group(). iconic.

then you can tune that group with nflog_set_mode() among many others. it's giving ✨customisation✨.

here's a little code snippet that binds to the group 100 — not me showing you the exact moves:

printf('binding this socket to group 100\0);
gh = nflog_bind_group(h, 100);
if (!gh) {
        fprintf(stderr, 'no handle for group 100\0);
        exit(1);
}

printf('setting copy_packet mode\0);
if (nflog_set_mode(gh, NFULNL_COPY_PACKET, 0xffff) < 0) {
        fprintf(stderr, 'can't set packet copy mode\0);
        exit(1);
}

next step is handling the incoming packets, and bestie, that's just a loop:

fd = nflog_fd(h);

while ((rv = recv(fd, buf, sizeof(buf), 0)) && rv >= 0) {
        printf('pkt received (len=%u)\0, rv);
        nflog_handle_packet(h, buf, rv);
}

and then you can fetch data and info about the packet using the message parsing functions. slay.

See also:

  • LibrarySetup man page (man nflog_open)
  • Parsing man page (man nflog_get_gid)

👑 Function Documentation 👑

🎀 struct nflog_g_handle * nflog_bind_group (struct nflog_handle * h, uint16_t num)

nflog_bind_group — bind a new handle to a specific group number. basically matchmaking but for handles and groups 💞

Parameters

  • h — netfilter log handle you got from calling nflog_open()
  • num — the number of the group to bind to

Returns

  • an nflog_g_handle for the newly created group, or NULL if it failed 😭

Errors

  • EBUSY — this process has already binded to the group
  • EOPNOTSUPP — request rejected by kernel. either another process has already binded to the group, or this process is not running as root
Definition at line 464 of file libnetfilter_log.c.

🎀 int nflog_callback_register (struct nflog_g_handle * gh, nflog_callback * cb, void * data)

nflog_callback_register — register function to process packets. like setting your ringtone but for packets 📞

Parameters

  • gh — netfilter log group handle you got by calling nflog_bind_group()
  • cb — callback function to call for each logged packet
  • data — custom data to pass to the callback function

Returns

  • 0
Definition at line 343 of file libnetfilter_log.c.

🎀 int nflog_fd (struct nflog_handle * h)

nflog_fd — get the file descriptor associated with the nflog handler.

Parameters

  • h — handler you got from calling nflog_open()

Returns

  • a file descriptor for the netlink connection associated with the given log connection handle. you can then use that file descriptor for receiving the logged packets so you can process them. it's the plug 🔌
Definition at line 245 of file libnetfilter_log.c.

🎀 int nflog_handle_packet (struct nflog_handle * h, char * buf, int len)

nflog_handle_packet — handle a packet received from the nflog subsystem.

Parameters

  • h — netfilter log handle you got from calling nflog_open()
  • buf — nflog data received from the kernel
  • len — length of packet data in buffer

triggers an associated callback for each packet contained in buf. you can read data from the queue using nflog_fd() and recv(). peep the example code in the Detailed Description above ⬆️

Returns

  • 0 on success, -1 if either the callback returned -ve or buf contains corrupt data. errno is not reliably set — caller should zeroise first if interested. fr fr, don't trust it blindly 🙈
Definition at line 366 of file libnetfilter_log.c.

🎀 int nflog_set_flags (struct nflog_g_handle * gh, uint16_t flags)

nflog_set_flags — set the nflog flags for this group.

Parameters

  • gh — netfilter log group handle you got by calling nflog_bind_group().
  • 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.
  • NFULNL_CFG_F_CONNTRACK: this enables to acquire related conntrack.

Returns

  • 0 on success, -1 on failure with errno set.

Errors

  • from underlying calls, in exceptional circumstances
Definition at line 664 of file libnetfilter_log.c.

🎀 int nflog_set_mode (struct nflog_g_handle * gh, uint8_t mode, uint32_t range)

nflog_set_mode — set the amount of packet data that nflog copies to userspace.

Parameters

  • gh — netfilter log group handle you got by calling nflog_bind_group().
  • mode — the part of the packet that we are interested in
  • 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

Returns

  • 0 on success, -1 on failure with errno set.

Errors

  • from underlying calls, in exceptional circumstances
Definition at line 534 of file libnetfilter_log.c.

🎀 int nflog_set_nlbufsiz (struct nflog_g_handle * gh, uint32_t nlbufsiz)

nflog_set_nlbufsiz — set the size of the nflog buffer for this group.

Parameters

  • gh — netfilter log group handle you got by calling nflog_bind_group().
  • 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.

Warning — the use of this function is strongly discouraged. the default buffer size (which is one memory page) provides the optimum results in terms of performance. do not use this function in your applications. bestie, just don't 😭 this is the one time i'm telling you to not touch the thing.

Returns

  • 0 on success, -1 on failure with errno set.

Errors

  • from underlying calls, in exceptional circumstances
Definition at line 627 of file libnetfilter_log.c.

🎀 int nflog_set_qthresh (struct nflog_g_handle * gh, uint32_t qthresh)

nflog_set_qthresh — set the maximum amount of logs in buffer for this group.

Parameters

  • gh — netfilter log group handle you got by calling nflog_bind_group().
  • qthresh — maximum number of log entries

this function determines the maximum number of log entries in the buffer until it is pushed to userspace. like a lil queue that overflows on purpose 💅

Returns

  • 0 on success, -1 on failure with errno set.

Errors

  • from underlying calls, in exceptional circumstances
Definition at line 596 of file libnetfilter_log.c.

🎀 int nflog_set_timeout (struct nflog_g_handle * gh, uint32_t timeout)

nflog_set_timeout — set the maximum time to push log buffer for this group.

Parameters

  • gh — netfilter log group handle you got by calling nflog_bind_group().
  • timeout — time to wait until the log buffer is pushed to userspace

this function allows you 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. it's efficiency, your honour ⏳

Returns

  • 0 on success, -1 on failure with errno set.

Errors

  • from underlying calls, in exceptional circumstances
Definition at line 569 of file libnetfilter_log.c.

🎀 int nflog_unbind_group (struct nflog_g_handle * gh)

nflog_unbind_group — unbind a group handle. it's giving closure, we love to see it 🦋

Parameters

  • gh — netfilter log group handle you got via nflog_bind_group()

Returns

  • 0 on success, -1 on failure with errno set.

Errors

  • from underlying calls, in exceptional circumstances
Definition at line 506 of file libnetfilter_log.c.

🌈 Author 🌈

generated automatically by Doxygen for libnetfilter_log from the source code. the robots did this one, i just made it cute ✨

and that's the whole page bestie!! this was libnetfilter_log Version 1.0.2, filed under Log(3), and it's iconic. go bind some groups, set some modes, and remember: do NOT touch nflog_set_nlbufsiz. mwah 💋🎀

📦 where this page comes from