NG_ETHER(4)

🦋 ng_ether — Ethernet netgraph node type 💅

okay bestie so this is the manual page for ng_ether, and it's from the Kernel Interfaces Manual (that's the section 4 vibe, iykyk). It's genuinely iconic and honestly kind of underrated, so let's get into it ✨

---

🌸 SYNOPSIS 🌸

#include <netgraph/ng_ether.h>

that's literally it, bestie. one include and you're in. 🫶

---

✨ DESCRIPTION ✨

so, the ether netgraph node type is the thing that lets Ethernet interfaces vibe with the netgraph(4) networking subsystem. the moment the ng_ether module gets loaded into the kernel, a node just appears — automatically — for every single Ethernet interface in the system. and each node will try to name itself after the interface it's attached to. main character energy fr fr 💅

there are three hooks supported: lower, upper, and orphans. also, the hook name divert can be used as an alias for lower — that's there purely for backward compatibility. in reality those two names are literally the same hook, no cap.

• lower — this one's the connection to the raw Ethernet device. when it's connected, all incoming packets get forwarded to this hook instead of being passed to the kernel for upper layer processing. writing to this hook = a raw Ethernet frame gets transmitted by the device. and normal outgoing packets? not affected at all by lower being connected. 💖
• upper — the connection to the upper protocol layers. when it's connected, all outgoing packets get forwarded to this hook instead of being transmitted by the device. writing to this hook = a raw Ethernet frame gets received by the kernel, exactly as if it had come in over the wire. and normal incoming packets aren't affected by upper being connected. 🎀
• orphans — basically lower's sibling, except that only unrecognized packets get written to this hook (the ones that would otherwise just get discarded), while other normal incoming traffic is unaffected. and if unrecognized packets get written to upper, they'll be forwarded back out to orphans — but only if it's connected. 🦋

in all cases, frames are raw Ethernet frames with the standard 14 byte Ethernet header (but no checksum).

and when no hooks are connected? upper and lower are in effect connected together, so packets just flow normally upwards and downwards. it's giving "we're all connected" 🌈

---

🎀 HOOKS 🎀

this node type supports the following hooks, bestie:

• lower — Connection to the lower device link layer. 💜
• upper — Connection to the upper protocol layers. ⭐
• orphans — Like lower, but only receives unrecognized packets. 🙈

---

👑 CONTROL MESSAGES 👑

this node type supports the generic control messages, plus all of these:

• NGM_ETHER_GET_IFNAME (getifname) — Returns the name of the associated interface as a NUL-terminated ASCII string. Normally this is the same as the name of the node. 💖
• NGM_ETHER_GET_IFINDEX (getifindex) — Returns the global index of the associated interface as a 32 bit integer.
• NGM_ETHER_GET_ENADDR (getenaddr) — Returns the device's unique six byte Ethernet address. 🎀
• NGM_ETHER_SET_ENADDR (setenaddr) — Sets the device's unique six byte Ethernet address. This control message is equivalent to using the SIOCSIFLLADDR ioctl(2) system call.
• NGM_ETHER_SET_PROMISC (setpromisc) — Enable or disable promiscuous mode. This message includes a single 32 bit integer flag that enables or disables promiscuous mode on the interface. Any non-zero value enables promiscuous mode. 👀
• NGM_ETHER_GET_PROMISC (getpromisc) — Get the current value of the node's promiscuous flag. The returned value is always either one or zero. Note: this flag reflects the node's own promiscuous setting and does not necessarily reflect the promiscuous state of the actual interface, which can be affected by other means (e.g., bpf(4)). 💀 so don't get it twisted!!
• NGM_ETHER_SET_AUTOSRC (setautosrc) — Sets the automatic source address override flag. This message includes a single 32 bit integer flag that causes all outgoing packets to have their source Ethernet address field overwritten with the device's unique Ethernet address. If this flag is set to zero, the source address in outgoing packets is not modified. The default setting for this flag is disabled. 🍓
• NGM_ETHER_GET_AUTOSRC (getautosrc) — Get the current value of the node's source address override flag. The returned value is always either one or zero.
• NGM_ETHER_ADD_MULTI (addmulti) — Join Ethernet multicast group. This control message is equivalent to using the SIOCADDMULTI ioctl(2) system call. 🫶
• NGM_ETHER_DEL_MULTI (delmulti) — Leave Ethernet multicast group. This control message is equivalent to using the SIOCDELMULTI ioctl(2) system call. 🦋
• NGM_ETHER_DETACH (detach) — Detach from underlying Ethernet interface and shut down node. 😭

---

💀 SHUTDOWN 💀

upon receipt of the NGM_SHUTDOWN control message, all hooks are disconnected, promiscuous mode is disabled — but the node is not removed. like, it's still there. lurking. 🙈

the node can only be shut down using the NGM_ETHER_DETACH control message. and if the interface itself gets detached (e.g., because of PC Card removal), then the node disappears as well. gone. poof. ✨

---

🔥 EXAMPLES 🔥

this command dumps all unrecognized packets received by the fxp0 interface to standard output, decoded in hex and ASCII:

nghook -a fxp0: orphans

this command sends the contents of sample.pkt out the interface fxp0:

cat sample.pkt | nghook fxp0: orphans

and these commands insert an ng_tee(4) node between the lower and upper protocol layers, which can be used for tracing packet flow, statistics, etc. — honestly kind of a slay:

ngctl mkpeer fxp0: tee lower right
ngctl connect fxp0: lower upper left

---

🌈 SEE ALSO 🌈

arp(4), netgraph(4), netintro(4), ifconfig(8), ngctl(8), nghook(8)

---

💜 AUTHORS 💜

• Julian Elischer <julian@FreeBSD.org>
• Archie Cobbs <archie@FreeBSD.org>

absolute icons, both of them 👑

---

🙈 BUGS 🙈

the automatic KLD module loading mechanism that works for most other Netgraph node types does not work for the ether node type — and here's why: ether nodes aren't created on demand. instead, they're created when Ethernet interfaces are attached, or when the KLD is first loaded. so therefore, if the KLD isn't statically compiled into the kernel, you have to load the KLD manually in order to bring the ether nodes into existence. no shortcuts bestie, you gotta do it yourself 😭💅

---

okay that's the whole page!! go forth and netgraph, bestie 🧚💖

this gorgeous little page is from Debian, dated June 23, 2011 — yes she's been serving since 2011 and she still eats 💅🫶