Manual Pages  — NG_TAG

#include <netgraph/ng_tag.h>

The tag node type allows mbuf packet tags (see mbuf_tags(9)) to be examined, stripped or applied to data travelling through a Netgraph network. Mbuf tags are used in many parts of the FreeBSD kernel network subsystem, including the storage of VLAN tags as described in vlan(4), Mandatory Access Control (MAC) labels as described in mac(9), IPsec policy information as described in ipsec(4), and packet filter tags used by pf(4). One should also consider useful setting or checking ipfw(8) tags, which are implemented as mbuf tags, too.

Each node allows an arbitrary number of connections to arbitrarily named hooks. With each hook is associated a tag which will be searched in the list of all tags attached to a packet incoming to this hook, a destination hook for matching packets, a destination hook for non-matching packets, a tag which will be appended to data leaving node through this hook, and various statistics counters.

The list of incoming packet's tags is traversed to find a tag with specified type and cookie values. Upon match, if specified tag_len is non-zero, tag_data of tag is checked to be identical to that specified in the hook structure. Packets with matched tags are forwarded to "match" destination hook, or forwarded to "non-match" hook otherwise. Either or both destination hooks can be an empty string, or may not exist, in which case the packet is dropped.

Tag list of packets leaving the node is extended with a new tag specified in outgoing hook structure (it is possible to avoid appending a new tag to pass packet completely unchanged by specifying zero type and cookie values in the structure of the corresponding outgoing hook). Additionally, a tag can be stripped from incoming packet after match if strip flag is set. This can be used for simple tag removal or tag replacement, if combined with tag addition on outgoing matching hook. Note that new tag is appended unconditionally, without checking if such a tag is already present in the list (it is up to user to check if this is a concern).

New hooks are initially configured to drop all incoming packets (as all hook names are empty strings; zero values can be specified to forward all packets to non-matching hook), and to forward all outgoing packets without any tag appending.

Data payload of packets passing through the node is completely unchanged, all operations can affect tag list only.

struct ng_tag_hookin {
  char            thisHook[NG_HOOKSIZ];     /* name of hook */
  char            ifMatch[NG_HOOKSIZ];      /* match dest hook */
  char            ifNotMatch[NG_HOOKSIZ];   /* !match dest hook */
  uint8_t         strip;                    /* strip tag if found */
  uint32_t        tag_cookie;               /* ABI/Module ID */
  uint16_t        tag_id;                   /* tag ID */
  uint16_t        tag_len;                  /* length of data */
  uint8_t         tag_data[0];              /* tag data */
};

struct ng_tag_hookout {
  char            thisHook[NG_HOOKSIZ];     /* name of hook */
  uint32_t        tag_cookie;               /* ABI/Module ID */
  uint16_t        tag_id;                   /* tag ID */
  uint16_t        tag_len;                  /* length of data */
  uint8_t         tag_data[0];              /* tag data */
};

It is possible to do a simple L7 filtering by using ipfw(8) tags in conjunction with ng_bpf(4) traffic analyzer. Example below explains how to filter DirectConnect P2P network data traffic, which cannot be done by usual means as it uses random ports. It is known that such data connection always contains a TCP packet with 6-byte payload string "$Send|". So ipfw's netgraph action will be used to divert all TCP packets to an ng_bpf(4) node which will check for the specified string and return non-matching packets to ipfw(8). Matching packets are passed to ng_tag node, which will set a tag and pass them back to ng_bpf(4) node on a hook programmed to accept all packets and pass them back to ipfw(8). A script provided in ng_bpf(4) manual page will be used for programming node. Note that packets diverted from ipfw(8) to Netgraph have no link-level header, so offsets in tcpdump(1) expressions must be altered accordingly. Thus, there will be expression "ether[40:2]=0x244c && ether[42:4]=0x6f636b20" on incoming hook and empty expression to match all packets from ng_tag.

So, this is ngctl(8) script for nodes creating and naming for easier access:

/usr/sbin/ngctl -f- <<-SEQ
        mkpeer ipfw: bpf 41 ipfw
        name ipfw:41 dcbpf
        mkpeer dcbpf: tag matched th1
        name dcbpf:matched ngdc
SEQ

Now "ngdc" node (which is of type ng_tag) must be programmed to echo all packets received on the "th1" hook back, with the ipfw(8) tag 412 attached. MTAG_IPFW value for tag_cookie was taken from file <netinet/ip_fw.h> and value for tag_id is tag number (412), with zero tag length:

ngctl msg ngdc: sethookin { thisHook=\"th1\" ifNotMatch=\"th1\" }
ngctl msg ngdc: sethookout { thisHook=\"th1\" \
  tag_cookie=1148380143 \
  tag_id=412 }

Do not forget to program ng_bpf(4) "ipfw" hook with the above expression (see ng_bpf(4) for script doing this) and "matched" hook with an empty expression:

ngctl msg dcbpf: setprogram { thisHook=\"matched\" ifMatch=\"ipfw\" \
  bpf_prog_len=1 bpf_prog=[ { code=6 k=8192 } ] }

After finishing with netgraph(4) nodes, ipfw(8) rules must be added to enable packet flow:

ipfw add 100 netgraph 41 tcp from any to any iplen 46
ipfw add 110 reset tcp from any to any tagged 412

Note: one should ensure that packets are returned to ipfw after processing inside netgraph(4), by setting appropriate sysctl(8) variable:

sysctl net.inet.ip.fw.one_pass=0

netgraph(4), ng_bpf(4), ng_ipfw(4), ipfw(8), ngctl(8), mbuf_tags(9)