NG_ETF(4)

💖 NG_ETF(4) — the Ethertype Filtering Netgraph Node Type 💖

okay bestie, gather round, because today we're talking about ng_etf — a netgraph node type that does ethertype filtering. it's giving bouncer-at-the-club energy but for Ethernet frames, and honestly? obsessed. 🎀

---

✨ SYNOPSIS ✨

#include <netgraph.h>
#include <netgraph/ng_etf.h>

like, that's it. two includes. iconic. 💅

---

🌸 DESCRIPTION 🌸

so the etf node type does two things and does them well: it multiplexes and it filters data between hooks. what's it filtering on? the ethertype found in an Ethernet header, which it presumes lives in the first 14 bytes of the data. no cap. 🦋

here's the tea on incoming frames:

• incoming Ethernet frames get accepted on the downstream hook
• if the ethertype matches a value the node has been configured to filter → the packet is forwarded out the hook that was identified back when that value was configured ✨
• if it doesn't match a configured value → off it goes to the nomatch hook
• if the nomatch hook isn't connected → the packet is dropped. bye. 💀

now, the plot twist: packets going the other way (towards the downstream hook) also get examined and filtered. so if a packet has an ethertype matching one of the values configured into the node, it must have arrived in on the hook for which that value was configured — otherwise it gets discarded. rude but necessary.

and ethertypes that aren't among the configured values? those must have arrived via the nomatch hook. it's a whole vibe check for packets. 🔥

---

🫶 HOOKS 🫶

this node type supports the following hooks, bestie:

• downstream — typically this hook would be connected to a ng_ether(4) node, using the lower hook.
• nomatch — typically this hook would also be connected to a ng_ether(4) type node, this time using the upper hook.
• ⟨any legal name⟩ — any other hook name will be accepted, and it can be used as the match target of an ethertype. typically this hook would be attached to a protocol handling node that requires and generates packets with a particular set of ethertypes. main character hook, honestly. 👑

---

💅 CONTROL MESSAGES 💅

this node type supports the generic control messages, plus these little darlings:

• NGM_ETF_GET_STATUS (getstatus) — this command returns a struct ng_etfstat containing node statistics for packet counts. numbers! we love numbers. 📊
• NGM_ETF_SET_FILTER (setfilter) — sets the a new ethertype filter into the node and specifies the hook to and from which packets of that type should use. the hook and ethertype are specified in a structure of type struct ng_etffilter:

struct ng_etffilter {
    char        matchhook[NG_HOOKSIZ];  /* hook name */
    uint16_t    ethertype;              /* this ethertype to this hook */
};

---

🌈 EXAMPLES 🌈

using ngctl(8) it's possible to set a filter in place from the command line, like so:

#!/bin/sh
ETHER_IF=fxp0
MATCH1=0x834
MATCH2=0x835
cat <<DONE >/tmp/xwert
# Make a new ethertype filter and attach to the Ethernet lower hook.
# first remove left over bits from last time.
shutdown ${ETHER_IF}:lower
mkpeer ${ETHER_IF}: etf lower downstream
# Give it a name to easily refer to it.
name ${ETHER_IF}:lower etf
# Connect the nomatch hook to the upper part of the same interface.
# All unmatched packets will act as if the filter is not present.
connect ${ETHER_IF}: etf: upper nomatch
DONE
ngctl -f /tmp/xwert

# something to set a hook to catch packets and show them.
echo "Unrecognised packets:"
nghook -a etf: newproto &
# Filter two random ethertypes to that hook.
ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH1} }
ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH2} }

(yes, those last two lines are exactly as written — we're keeping it verbatim, bestie. 💜)

---

🎀 SHUTDOWN 🎀

this node shuts down upon receipt of a NGM_SHUTDOWN control message, or when all hooks have been disconnected. so if you ghost every single hook, the node ghosts itself. poetic. 😭

---

⭐ SEE ALSO ⭐

• netgraph(4)
• ng_ether(4)
• ngctl(8)
• nghook(8)

---

🦋 HISTORY 🦋

the ng_etf node type was implemented in FreeBSD 5.0. vintage but make it fashion. ✨

---

👑 AUTHORS 👑

Julian Elischer <julian@FreeBSD.org>

---

and that's the whole page, bestie!! this cutie came to you from the Debian edition, dated November 13, 2012 — shoutout to the NG_ETF(4) kernel interfaces manual for being the blueprint. now go filter some ethertypes, you absolute legend. 💖🦋💅🌸