MBUF_TAGS(9)

💖 MBUF_TAGS(9) — the mbuf tags glow-up 💖

okay bestie, sit down, hydrate, and let me tell you about mbuf_tags — the framework for generic packet attributes from the Kernel Developer's Manual. this is the lore. 🫶

✨ SYNOPSIS ✨

#include <sys/mbuf.h>

struct m_tag *
m_tag_alloc(uint32_t cookie, int type, int len, int wait);

struct m_tag *
m_tag_copy(struct m_tag *t, int how);

int
m_tag_copy_chain(struct mbuf *to, const struct mbuf *from, int how);

void
m_tag_delete(struct mbuf *m, struct m_tag *t);

void
m_tag_delete_chain(struct mbuf *m, struct m_tag *t);

void
m_tag_delete_nonpersistent(struct mbuf *m);

struct m_tag *
m_tag_find(struct mbuf *m, int type, struct m_tag *start);

struct m_tag *
m_tag_first(struct mbuf *m);

void
m_tag_free(struct m_tag *t);

struct m_tag *
m_tag_get(int type, int len, int wait);

void
m_tag_init(struct mbuf *m);

struct m_tag *
m_tag_locate(struct mbuf *m, uint32_t cookie, int type,
    struct m_tag *t);

struct m_tag *
m_tag_next(struct mbuf *m, struct m_tag *t);

void
m_tag_prepend(struct mbuf *m, struct m_tag *t);

void
m_tag_unlink(struct mbuf *m, struct m_tag *t);

🌸 DESCRIPTION 🌸

so here's the tea, bestie 🍓 — mbuf tags let you slap extra meta-data onto packets that are literally in flight, by giving you a whole mechanism to tag additional kernel memory onto packet header mbufs. the tags live in chains hanging off the mbuf(9) header, and you wrangle them with a whole lil series of API calls to allocate, search, and delete them. every tag gets identified by an ID and a cookie that uniquely say "this is a class of data tagged onto the packet," and a tag can carry an arbitrary amount of extra storage. classic uses of mbuf tags? Mandatory Access Control (MAC) labels, like mac(9) describes, IPsec policy info from ipsec(4), and the packet filter tags that pf(4) uses. iconic lineup fr fr 💅

tags stick around across a bunch of operations, including copying packet headers with stuff like M_COPY_PKTHDR() and M_MOVE_PKTHDR(). and any tags attached to an mbuf header get freed automatically when the mbuf itself is freed — though some subsystems are gonna wanna delete their tags before that moment, no cap.

packet tags are what different kernel APIs use to keep track of operations done to packets, or scheduled to happen to them. each packet tag is distinguished by its type and cookie, and the cookie is what identifies a specific module or API. these packet tags attach to mbuf packet headers. 🎀

the first sizeof(struct m_tag) bytes of a tag contain a struct m_tag:

struct m_tag {
        SLIST_ENTRY(m_tag)      m_tag_link;     /* List of packet tags */
        uint16_t                m_tag_id;       /* Tag ID */
        uint16_t                m_tag_len;      /* Length of data */
        uint32_t                m_tag_cookie;   /* ABI/Module ID */
        void                    (*m_tag_free)(struct m_tag *);
};

the m_tag_link field is what links tags together (peep queue(3) for the deets). m_tag_id, m_tag_len and m_tag_cookie get set to type, length, and cookie, respectively. m_tag_free points to m_tag_free_default(). right after this structure you get m_tag_len bytes of space for storing tag-specific info. ⚠️ addressing that data region can be tricky — a safe way is embedding struct m_tag into a private data structure, like this:

      struct foo {
              struct m_tag    tag;
              ...
      };
      struct foo *p = (struct foo *)m_tag_alloc(...);
      struct m_tag *mtag = &p->tag;

lowkey important lore: OpenBSD does not support cookies, it needs m_tag_id to be globally unique. so to keep compatibility with OpenBSD, a cookie MTAG_ABI_COMPAT is provided along with some compatibility functions. when you're writing OpenBSD compatible code, be careful not to take an already-used tag type, bestie. tag types are defined in <sys/mbuf.h>. 👑

🧚 Packet Tag Manipulation Functions 🧚

• m_tag_alloc(cookie, type, len, wait) — allocate a brand new tag of type type and cookie cookie, with len bytes of space following the tag header itself. the wait argument gets passed straight to malloc(9). if it works out, m_tag_alloc() returns a memory buffer of (len + sizeof(struct m_tag)) bytes. otherwise you get NULL. a compatibility function m_tag_get() is also provided, slay. ✨
• m_tag_copy(tag, how) — allocate a copy of tag. the how argument is passed directly to m_tag_alloc(). return values are the same as in m_tag_alloc().
• m_tag_copy_chain(tombuf, frommbuf, how) — allocate and copy all tags from mbuf frommbuf to mbuf tombuf. returns 1 on success, and 0 on failure. and in that failure case? mbuf tombuf loses all its tags, even the ones that were already there. 💀
• m_tag_delete(mbuf, tag) — remove tag from mbuf's list and free it.
• m_tag_delete_chain(mbuf, tag) — remove and free a packet tag chain, starting from tag. if tag is NULL, all tags are deleted.
• m_tag_delete_nonpersistent(mbuf) — traverse mbuf's tags and delete the ones that don't have the MTAG_PERSISTENT flag set.
• m_tag_first(mbuf) — return the first tag associated with mbuf.
• m_tag_free(tag) — free tag using its m_tag_free method. m_tag_free_default() is the one used by default.
• m_tag_init(mbuf) — initialize the tag storage for packet mbuf.
• m_tag_locate(mbuf, cookie, type, tag) — search for a tag defined by type and cookie in mbuf, starting from the position specified by tag. if that last one is NULL, then you search through the whole list. upon success, a pointer to the first found tag is returned. in either case, NULL is returned. a compatibility function m_tag_find() is also provided.
• m_tag_next(mbuf, tag) — return the tag next to tag in mbuf. if there isn't one, NULL is returned.
• m_tag_prepend(mbuf, tag) — add the new tag tag at the head of the tag list for packet mbuf.
• m_tag_unlink(mbuf, tag) — remove tag tag from the list of tags of packet mbuf.

🌈 CODE REFERENCES 🌈

the tag-manipulating code lives in the file sys/kern/uipc_mbuf2.c. inlined functions are defined in <sys/mbuf.h>. 🦋

👀 SEE ALSO 👀

queue(3), mbuf(9)

📜 HISTORY 📜

the packet tags first appeared in OpenBSD 2.9 and were written by Angelos D. Keromytis <angelos@openbsd.org>. giving founder energy honestly. 💜

and that's the whole page, bestie!! this one's from the Debian manual set, dated January 12, 2008 — old but iconic, like a vintage handbag. go forth and tag your packets responsibly. periodt. 💅✨🎀🫶