NG_TAG(4)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 NG_TAG(4) — the mbuf tags manipulating netgraph node type 🎀

okay bestie, so this is a page from the Kernel Interfaces Manual, and it's literally about the ng_tag netgraph node type — the little icon that lets you peek at, strip off, or slap brand-new mbuf packet tags onto data as it zooms through a Netgraph network. ✨

✨ SYNOPSIS ✨

#include <netgraph/ng_tag.h>

🦋 DESCRIPTION 🦋

The tag node type lets you examine, strip, or apply mbuf packet tags (peep mbuf_tags(9) for the deep lore) to data travelling through a Netgraph network. Mbuf tags are lowkey everywhere in the FreeBSD kernel network subsystem — it's giving main character energy in so many places, like:

  • storing VLAN tags, as described in vlan(4)
  • Mandatory Access Control (MAC) labels, as described in mac(9)
  • IPsec policy information, as described in ipsec(4)
  • packet filter tags used by pf(4)

Also, bestie, you should also consider how useful it is to set or check ipfw(8) tags — those are implemented as mbuf tags too. 💖

Each node allows an arbitrary number of connections to arbitrarily named hooks. With each hook is associated:

  • a tag which will be searched in the list of all tags attached to a packet incoming to this hook
  • a destination hook for matching packets
  • a destination hook for non-matching packets
  • a tag which will be appended to data leaving the node through this hook
  • and various statistics counters

The list of incoming packet's tags is traversed to find a tag with the specified type and cookie values. Upon a match, if the specified tag_len is non-zero, tag_data of the tag is checked to be identical to that specified in the hook structure. Packets with matched tags are forwarded to the “match” destination hook, or forwarded to the “non-match” hook otherwise. Either or both destination hooks can be an empty string, or may not exist — and in that case the packet is dropped. 💀

The tag list of packets leaving the node is extended with a new tag specified in the outgoing hook structure. (And yes, it is possible to avoid appending a new tag and pass the packet completely unchanged — just specify zero type and cookie values in the structure of the corresponding outgoing hook. slay.) Additionally, a tag can be stripped from an incoming packet after a match if the strip flag is set. This can be used for simple tag removal, or for tag replacement if you combine it with tag addition on the outgoing matching hook. Note that the new tag is appended unconditionally, without checking if such a tag is already present in the list — so it's up to the user to check if that's a concern. 🙈

New hooks are initially configured to drop all incoming packets (because all hook names are empty strings; zero values can be specified to forward all packets to the non-matching hook), and to forward all outgoing packets without any tag appending.

Data payload of packets passing through the node is completely unchanged — all operations can affect the tag list only. Periodt. 💅

🎀 HOOKS 🎀

This node type supports any number of hooks having arbitrary names. But listen: in order to allow internal optimizations, the user should never try to configure a hook with a structure pointing to hooks which do not exist yet. The safe way is to create all the hooks first, then begin to configure them. No cap. ⭐

👑 CONTROL MESSAGES 👑

This node type supports the generic control messages, plus the following:

🔥 NGM_TAG_SET_HOOKIN (sethookin)

This command sets tag values which will be searched in the tag list of incoming packets on a hook. The following structure must be supplied as an argument:

struct ng_tag_hookin {
  char            thisHook[NG_HOOKSIZ];     /* name of hook */
  char            ifMatch[NG_HOOKSIZ];      /* match dest hook */
  char            ifNotMatch[NG_HOOKSIZ];   /* !match dest hook */
  uint8_t         strip;                    /* strip tag if found */
  uint32_t        tag_cookie;               /* ABI/Module ID */
  uint16_t        tag_id;                   /* tag ID */
  uint16_t        tag_len;                  /* length of data */
  uint8_t         tag_data[0];              /* tag data */
};

The hook to be updated is specified in thisHook. Data bytes of the tag corresponding to the specified tag_id (type) and tag_cookie are placed in the tag_data array — and there must be tag_len of them. Matching and non-matching incoming packets are delivered out the hooks named ifMatch and ifNotMatch, respectively. If the strip flag is non-zero, then the found tag is deleted from the list of packet tags. 🫶

💜 NGM_TAG_GET_HOOKIN (gethookin)

This command takes an ASCII string argument — the hook name — and returns the corresponding struct ng_tag_hookin as shown above.

🌸 NGM_TAG_SET_HOOKOUT (sethookout)

This command sets tag values which will be applied to outgoing packets. The following structure must be supplied as an argument:

struct ng_tag_hookout {
  char            thisHook[NG_HOOKSIZ];     /* name of hook */
  uint32_t        tag_cookie;               /* ABI/Module ID */
  uint16_t        tag_id;                   /* tag ID */
  uint16_t        tag_len;                  /* length of data */
  uint8_t         tag_data[0];              /* tag data */
};

The hook to be updated is specified in thisHook. The other variables mean basically the same as in struct ng_tag_hookin shown above, except they're used for setting values in a new tag. ✨

🦋 NGM_TAG_GET_HOOKOUT (gethookout)

This command takes an ASCII string argument — the hook name — and returns the corresponding struct ng_tag_hookout as shown above.

🍓 NGM_TAG_GET_STATS (getstats)

This command takes an ASCII string argument — the hook name — and returns the statistics associated with the hook as a struct ng_tag_hookstat.

🌈 NGM_TAG_CLR_STATS (clrstats)

This command takes an ASCII string argument — the hook name — and clears the statistics associated with the hook.

⭐ NGM_TAG_GETCLR_STATS (getclrstats)

This command is identical to NGM_TAG_GET_STATS, except that the statistics are also atomically cleared.

💀 Note: the statistics counters, as well as the three statistics messages above, work only if the code was compiled with the NG_TAG_DEBUG option. The reason for this? Statistics are rarely used in practice but still consume CPU cycles for every single packet. Moreover, they're not even accurate on SMP systems due to lack of synchronization between threads — because that would be very expensive. 😭

🧚 SHUTDOWN 🧚

This node shuts down upon receipt of an NGM_SHUTDOWN control message, or when all hooks have been disconnected.

🔥 EXAMPLES 🔥

It is possible to do a simple L7 filtering by using ipfw(8) tags in conjunction with the ng_bpf(4) traffic analyzer. The example below explains how to filter DirectConnect P2P network data traffic — which cannot be done by usual means, because it uses random ports. It is known that such a data connection always contains a TCP packet with the 6-byte payload string "$Send|". So ipfw's netgraph action will be used to divert all TCP packets to an ng_bpf(4) node, which will check for the specified string and return non-matching packets to ipfw(8). Matching packets are passed to the ng_tag node, which will set a tag and pass them back to the ng_bpf(4) node on a hook programmed to accept all packets and pass them back to ipfw(8). A script provided in the ng_bpf(4) manual page will be used for programming the node. Note that packets diverted from ipfw(8) to Netgraph have no link-level header, so offsets in tcpdump(1) expressions must be altered accordingly. Thus, there will be the expression "ether[40:2]=0x244c && ether[42:4]=0x6f636b20" on the incoming hook, and an empty expression to match all packets from ng_tag.

So, this is the ngctl(8) script for creating and naming the nodes, for easier access:

/usr/sbin/ngctl -f- <<-SEQ
        mkpeer ipfw: bpf 41 ipfw
        name ipfw:41 dcbpf
        mkpeer dcbpf: tag matched th1
        name dcbpf:matched ngdc
SEQ

Now the “ngdc” node (which is of type ng_tag) must be programmed to echo all packets received on the “th1” hook back, with the ipfw(8) tag 412 attached. The MTAG_IPFW value for tag_cookie was taken from the file <netinet/ip_fw.h>, and the value for tag_id is the tag number (412), with zero tag length:

ngctl msg ngdc: sethookin { thisHook=\"th1\" ifNotMatch=\"th1\" }
ngctl msg ngdc: sethookout { thisHook=\"th1\" \
  tag_cookie=1148380143 \
  tag_id=412 }

Do not forget to program the ng_bpf(4) “ipfw” hook with the above expression (see ng_bpf(4) for the script doing this) and the “matched” hook with an empty expression:

ngctl msg dcbpf: setprogram { thisHook=\"matched\" ifMatch=\"ipfw\" \
  bpf_prog_len=1 bpf_prog=[ { code=6 k=8192 } ] }

After finishing with the netgraph(4) nodes, ipfw(8) rules must be added to enable packet flow:

ipfw add 100 netgraph 41 tcp from any to any iplen 46
ipfw add 110 reset tcp from any to any tagged 412
⭐ Note: one should ensure that packets are returned to ipfw after processing inside netgraph(4), by setting the appropriate sysctl(8) variable: sysctl net.inet.ip.fw.one_pass=0

🫶 SEE ALSO 🫶

netgraph(4), ng_bpf(4), ng_ipfw(4), ipfw(8), ngctl(8), mbuf_tags(9)

💖 HISTORY 💖

The ng_tag node type was implemented in FreeBSD 6.2.

🌟 AUTHORS 🌟

Vadim Goncharov <vadimnuclight@tpu.ru>

🙈 BUGS 🙈

For manipulating any tags with data payload (that is, all tags with non-zero tag_len), one should care about the non-portable, machine-dependent representation of tags on the low level as a byte stream. Perhaps this should be done by another program rather than manually. 😭

and that's the whole page, bestie — mwah 💋 this one came from the Debian edition, dated June 10, 2006. go forth and tag responsibly 🎀✨🦋

📦 where this page comes from