Support 5-tuple logging

[qdeslandes]

By default, a log action will log all the known header of a given packet, which can be large depending on the L2/3/4 headers in the packet. Potentially, users only want specific information, such as the 5-tuple (addresses, ports, and protocol), which would greatly reduce the amount of data sent back to userspace.

Implement 5-tuple logging with log 5-tuple and limit the amount of data logged to the ring buffer.

[blackdragoon26]

Hihi @qdeslandes , can i take up this issue.

[qdeslandes]

Sure, please ensure you familiarize yourself with our contributing guide which has been updated recently.

The ring buffer currently allocates a fixed number of fixed-size message, even if the user only requests a subset of the information available. This task is not about changing this behaviour, but allowing a new value for the log action: 5-tuple, which will log the packet's 5-tuple.

I can review a design proposal if you want to ensure you go in the right direction, if you already have something in mind and feel confident I'll review the PR once it's ready :)

[blackdragoon26]

Thanks @qdeslandes for assigning me and for the pointers above!
So, I went through the existing rule parsing, packet codegen, logging ABI, BPF log stub, and userspace printing path. I would like to propose the following design before starting the implementation.

Firstly, adding 5-tuple as a new bf_log_opt. The parser would store it in bf_rule.log, and packet codegen would continue passing the log options to bf_pkt_log().
Inside bf_pkt_log(), an exact BF_LOG_OPT_5_TUPLE selection would produce a new tuple-specific log variant, tentatively BF_LOG_TYPE_PACKET_5_TUPLE. Its payload would contain:

• source and destination addresses;
• source and destination ports;
• captured-field metadata.
  While, the existing common bf_log fields would continue carrying the L3/L4 protocols, rule ID, verdict, and timestamp.
  This tuple would be populated from the already parsed ctx->l3_hdr and ctx->l4_hdr. The existing BF_LOG_TYPE_PACKET path and its raw L2/L3/L4 header copies would remain unchanged.
  Both paths would continue reserving sizeof(struct bf_log), and the ring-buffer map capacity and fixed-size allocation behaviour would not change.
  Userspace would dispatch on log_type and print a compact tuple representation for the new variant.

Although, there are three semantics I would like to confirm:

1. Should 5-tuple be exclusive, rejecting combinations such as log 5-tuple,link?
2. For IPv4/IPv6 protocols without TCP/UDP ports, should the entry retain addresses and protocol while marking ports unavailable? This would be consistent with the current bf_flow_hash() extraction behavior.
3. Should log 5-tuple be rejected for cgroup_sock_addr, since those hooks cannot provide a complete source-address/source-port tuple?

Also I have attached an excalidraw diagram of the proposed path and payload layout, since that personally helps me to keep my head straight.

If this direction looks correct, I will proceed with the parser, ABI, BPF logging, userspace printing, documentation, and focused ring-buffer tests.

[blackdragoon26]

Hihi @qdeslandes, re-pinging you for the above message, thanks.

[qdeslandes]

Thanks @qdeslandes for assigning me and for the pointers above! So, I went through the existing rule parsing, packet codegen, logging ABI, BPF log stub, and userspace printing path. I would like to propose the following design before starting the implementation.

Firstly, adding 5-tuple as a new bf_log_opt. The parser would store it in bf_rule.log, and packet codegen would continue passing the log options to bf_pkt_log(). Inside bf_pkt_log(), an exact BF_LOG_OPT_5_TUPLE selection would produce a new tuple-specific log variant, tentatively BF_LOG_TYPE_PACKET_5_TUPLE. Its payload would contain:

Why this approach specifically, over implement an elf stub dedicated to 5-tuple logging?

• source and destination addresses;
• source and destination ports;
• captured-field metadata.
  While, the existing common bf_log fields would continue carrying the L3/L4 protocols, rule ID, verdict, and timestamp.
  This tuple would be populated from the already parsed ctx->l3_hdr and ctx->l4_hdr. The existing BF_LOG_TYPE_PACKET path and its raw L2/L3/L4 header copies would remain unchanged.
  Both paths would continue reserving sizeof(struct bf_log), and the ring-buffer map capacity and fixed-size allocation behaviour would not change.
  Userspace would dispatch on log_type and print a compact tuple representation for the new variant.

Although, there are three semantics I would like to confirm:

1. Should 5-tuple be exclusive, rejecting combinations such as log 5-tuple,link?

5-tuple,link would be difficult to reason about, so it's either 5-tuple, or a combination of packet layers.

2. For IPv4/IPv6 protocols without TCP/UDP ports, should the entry retain addresses and protocol while marking ports unavailable? This would be consistent with the current bf_flow_hash() extraction behavior.

bf_flow_hash is only called for L3=(IPv4|IPv6) and L4=(UDP|TCP), the corresponding matcher is meta.flow_probability (see the doc). 5-tuple logging should follow the same behaviour: ignore packets which are not IPv(4|6) and TCP|UDP.

3. Should log 5-tuple be rejected for cgroup_sock_addr, since those hooks cannot provide a complete source-address/source-port tuple?

Yes, for now we can stick to packet-based hooks.

Also I have attached an excalidraw diagram of the proposed path and payload layout, since that personally helps me to keep my head straight.

If this direction looks correct, I will proceed with the parser, ABI, BPF logging, userspace printing, documentation, and focused ring-buffer tests.

[blackdragoon26]

Ohhh okay, yeah that makes sense. Thanks for the review @qdeslandes .

My initial reason for using the existing bf_pkt_log() stub was to reuse its common record reservation, common-field initialisation, and access to the already parsed L3/L4 headers.

However, I agree now that a dedicated ELF stub provides a cleaner and simpler separation between raw-header and tuple payload generation. It also avoids adding a tuple-specific runtime branch to the existing packet logger.

So, I will revise the design, that packet codegen selects either the existing BF_ELFSTUB_PKT_LOG or a dedicated 5-tuple logging stub based on the rule’s log mode.

And semantics will be:

• 5-tuple will be exclusive from the packet-layer options;
• tuple logging will only emit entries for IPv4/IPv6 with TCP/UDP, following the guards used by meta.flow_probability;
• cgroup_sock_addr will remain unsupported for this mode;
• the fixed-size struct bf_log reservation and ring-buffer capacity will remain unchanged.

Thanks for clarifying the bf_flow_hash() call-site behaviour; my bad, I had overlooked the protocol guards around that call.
With this resolution, if anything else is not there, I think I can begin working on PR.

[qdeslandes]

Ohhh okay, yeah that makes sense. Thanks for the review @qdeslandes .

My initial reason for using the existing bf_pkt_log() stub was to reuse its common record reservation, common-field initialisation, and access to the already parsed L3/L4 headers.

However, I agree now that a dedicated ELF stub provides a cleaner and simpler separation between raw-header and tuple payload generation. It also avoids adding a tuple-specific runtime branch to the existing packet logger.

So, I will revise the design, that packet codegen selects either the existing BF_ELFSTUB_PKT_LOG or a dedicated 5-tuple logging stub based on the rule’s log mode.

And semantics will be:

• 5-tuple will be exclusive from the packet-layer options;
• tuple logging will only emit entries for IPv4/IPv6 with TCP/UDP, following the guards used by meta.flow_probability;
• cgroup_sock_addr will remain unsupported for this mode;
• the fixed-size struct bf_log reservation and ring-buffer capacity will remain unchanged.

Thanks for clarifying the bf_flow_hash() call-site behaviour; my bad, I had overlooked the protocol guards around that call.
With this resolution, if anything else is not there, I think I can begin working on PR.

SGTM :)

I additionally, can you share more about your AI usage for this design, and the discussion we had? Did you you AI at all? We're still calibrating our AI usage policy (see https://bpfilter.io/developers/contributing.html for the current policy), and your approach to this issue is IMO a good example of properly interacting with an open source project.

[blackdragoon26]

Cool I will start working on PR @qdeslandes ,
Oh yes, I use currently Codex GPT5.6 Sol right now, and its mostly to understand and create excalidraw flowcharts for my own understanding first(i love diagrams) and get the context of codebase, and I also use as assist while writing code, and formatting of my very bad english messages and tech jargon usage.

[blackdragoon26]

I gave it a read, https://bpfilter.io/developers/contributing.html ,
And I am looking forward contribute here for a very long time, so um I am sorry if my AI usage was a concern but I will have AI disclosure in my PRs so that, people can have context of LLM utilisation.

[qdeslandes]

I gave it a read, https://bpfilter.io/developers/contributing.html , And I am looking forward contribute here for a very long time, so um I am sorry if my AI usage was a concern but I will have AI disclosure in my PRs so that, people can have context of LLM utilisation.

Sorry, I wasn't clear enough. AI use is not frowned upon on this repo, we use it as well. Only unattended bots (Hermes, OpenClaw) interacting directly with us without human involvement is forbidden, which doesn't seem to be the case here.

No disclosure is required when discussing an issue (as autonomous bots generally won't interact though the GH issue), it was mostly out of curiosity on my end :)

[blackdragoon26]

Haha, I really appreciate it @qdeslandes.
Thanks