What is netgraph?

Netgraph(4) in FreeBSD is a powerful and flexible in-kernel networking subsystem. It offers a method for combining protocol and link-level drivers, a modular approach to implementing new protocols, and a common framework for kernel entities to communicate.

The fundamental concept in Netgraph(4) is the use of nodes and hooks, where each node has a specific type, and nodes are interconnected through hooks. Each node type is documented in its man pages. $ apropos netgraph OR $ man -k netgraph.

In this article, we will explore ng_ether(4), ng_bridge(4), and ng_eiface(4), along with some hands-on examples.

What do you need to follow along?

FreeBSD installed on a laptop, desktop, or in a VM and an extra network interface. If using physical hardware or a VM, you'll need at least two interfaces. One will be the default interface, and the second interface will be used for Netgraph. If your second interface is not connected, please use a virtual NIC.

Let’s Start...

Before we dive into Netgraph, note that ngctl(8) utility is provided, which is used to create, query, and connect hooks.

kldstat
First, check if the Netgraph kernel module is loaded.

$ kldstat

If you haven’t run ngctl(8) previously, you may not see any kernel modules starting with ng_*. However, if you’re using a desktop environment, you might see modules like ng_ubt and ng_bluetooth already loaded.

Let’s run ngctl(8) now and observe its output, as well as the output of kldstat:

$ doas ngctl list OR $ doas ngctl lists

The output:

There are no netgraph nodes

Below, modules related to Netgraph are dynamically loaded:

$ kldstat
Id Refs Address    Size     Name
1   34  0xffffffff80200000  24e8d8  kernel
2    1  0xffffffff822f2000  34230   ng_socket.ko

The ng_socket(4) node type enables user-mode processes to interact with the kernel’s Netgraph(4) networking subsystem through the BSD socket interface. In this case, ngctl(8) utility has created the socket for us.

Let’s load the ng_ether(4) kernel module and observe its status:

$ doas kldload ng_ether.ko
$ kldstat

Output:

Id Refs Address    Size     Name
1   35  0xffffffff80200000  24e8d8  kernel
2    1  0xffffffff822f2000  34230   ng_socket.ko
3    1  0xffffffff82326000  22520   ng_ether.ko

Run the list command again:

$ doas ngctl list OR $ doas ngctl ls

Output:

There are 3 total nodes:
  Name: ngctl15427 Type: ether ID: 00000001 Num hooks: 0

Each node has a type, which is a static property of the node determined at node creation time.

Nodes are connected by pairs of hooks, allowing bidirectional data flow. Each node can have multiple hooks and assign its own meaning to them.

Once the ng_ether module is loaded into the kernel, a node is automatically created for each Ethernet interface on the system. Each node will try to name itself after the associated interface.

We can now run commands non-interactively or in interactive mode.

$ doas ngctl OR $ ngctl

You’ll see an interactive prompt ready for commands.

Let’s learn `ng_ether(4)`, `ng_bridge(4)`, and `ng_eiface(4)`.

Let’s make productive use of ng_ether(4) by creating ng_bridge(4) and linking it to ng_ether’s lower hook.

First, let’s take some time to understand what ng_ether and ng_bridge are.

ng_ether(4) provides three hooks: lower, upper, and orphans.
Illustration:
Lower Hook – Incoming Flow
Connected to the raw Ethernet device.

Upper Hook – Outgoing Flow
Connected to upper protocol layers (e.g., the kernel).

ng_bridge(4) provides unlimited hooks: link0, link1, ... linkN.

Let’s do hands-on `ng_ether(4)` and `ng_bridge(4)`

$ doas ngctl mkpeer vtnet1: bridge lower link0
$ doas ngctl list
$ doas ngctl show vtnet1:

Output:

Name: ngctl00001 Type: bridge ID: 00000002
  Hook: lower -> bridge0

Interactive Mode

Assign a name to the bridge:

$ doas ngctl name vtnet1:lower bridge0
$ show bridge0: OR $ show firstbridge

Non-Interactive Mode

Connecting to another hook:

$ doas ngctl connect vtnet1: bridge0: upper link1
$ doas ngctl show bridge0:
$ doas ngctl show vtnet1:

Creating an `ng_eiface`

Now, create an eiface to connect a user-space process:

$ doas ngctl mkpeer bridge: eiface ether ether
$ doas ifconfig ngeth0

Additional Notes:

Use jail to test the setup and bridge interfaces:

$ doas jail -c name=first host.hostname=first.home.arpa persist

Assign IPs for testing.

Source:
Fiddling with FreeBSD - Netgraph https://x.com/padukajorat/status/1868566280523137408/photo/1