Interface Filters

This chapter describes the programming interface for creating interface filters, which are associated with a particular network interface, as shown in Figure 6-1.

Figure 6-1  Data Link Interface Layer
Data Link Interface Layer

Interface Filter Functions and Callbacks

An interface filter defines the following callbacks:

To attach and detach an interface filter, the following functions are defined by the interface filter KPI:

Common Caveats

There are a number of surprises that you may run into when writing an interface filter. Several of these follow:

Packet injection

When your filter injects packets, it should use the ifnet_input and ifnet_output_raw functions. If you do this, your filter should be prepared to ignore the packet it just injected, as your filter’s iff_input_func or iff_output_func callback will see this packet again immediately. You should use the mbuf_tag APIs (mbuf_tag_allocate, for example) to track these packets. If multiple filters are swallowing and reinjecting packets, you may see a given packet multiple times.

Note: When reinjecting packets, the filter must ensure that the packet header field is set in the first mbuf structure. Otherwise, the call to ifnet_input will result in a kernel panic (NULL pointer dereference).

When your iff_input_func callback is called, you may find that the packet_header field has been set to NULL. The frame_ptr parameter to iff_input_func can be used to set the packet_header field if the packet must be reinjected. To do this, use the mbuf_pkthdr_setheader function to set the packet_header field in the mbuf.

If your iff_input_func callback does not swallow a packet, it is not necessary to set the packet_header field.

Input callbacks: Header pointers and mbufs

Your filter’s input callback receives an mbuf pointer to the packet contents and a separate header pointer. The header pointer references the link-layer header, as defined by the relevant interface.

For most interfaces, the length of this header can be determined by inspecting the header length (ifnet_hdrlen) defined by the interface. For some interfaces, however, such as PPP, the header length is variable.

Output callbacks: Header pointers and mbufs

Your filter’s output callback receives the entire packet in the mbuf chain. To get the protocol layer information, your filter must know how to parse the link-layer header. For this reason, if you are writing a filter that needs to work with IP packets, you should consider writing an IP filter unless it is absolutely necessary to access link-layer information.