ng_tag man page on FreeBSD

Man page or keyword search:  
man Server   9747 pages
apropos Keyword Search (all sections)
Output format
FreeBSD logo
[printable version]

NG_TAG(4)		 BSD Kernel Interfaces Manual		     NG_TAG(4)

NAME
     ng_tag — mbuf tags manipulating netgraph node type

SYNOPSIS
     #include <netgraph/ng_tag.h>

DESCRIPTION
     The tag node type allows mbuf packet tags (see mbuf_tags(9)) to be exam‐
     ined, 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 informa‐
     tion 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 destina‐
     tion hook for matching packets, a destination hook for non-matching pack‐
     ets, 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 speci‐
     fied 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” des‐
     tination 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).  Addition‐
     ally, 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 con‐
     cern).

     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 with‐
     out any tag appending.

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

HOOKS
     This node type supports any number of hooks having arbitrary names.  In
     order to allow internal optimizations, user should never try to configure
     a hook with a structure pointing to hooks which do not exist yet.	The
     safe way is to create all hooks first, then begin to configure them.

CONTROL MESSAGES
     This node type supports the generic control messages, plus the following:

     NGM_TAG_SET_HOOKIN
	     This command sets tag values which will be searched in the tag
	     list of incoming packets on a hook.  The following structure must
	     be supplied as an argument:

		 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 */
		 };

	     The hook to be updated is specified in thisHook.  Data bytes of
	     tag corresponding to specified tag_id (type) and tag_cookie are
	     placed in the tag_data array; there must be tag_len of them.
	     Matching and non-matching incoming packets are delivered out the
	     hooks named ifMatch and ifNotMatch, respectively.	If strip flag
	     is non-zero, then found tag is deleted from list of packet tags.

     NGM_TAG_GET_HOOKIN
	     This command takes an ASCII string argument, the hook name, and
	     returns the corresponding struct ng_tag_hookin as shown above.

     NGM_TAG_SET_HOOKOUT
	     This command sets tags values which will be applied to outgoing
	     packets.  The following structure must be supplied as an argu‐
	     ment:

		 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 */
		 };

	     The hook to be updated is specified in thisHook.  Other variables
	     mean basically the same as in struct ng_tag_hookin shown above,
	     except used for setting values in a new tag.

     NGM_TAG_GET_HOOKOUT
	     This command takes an ASCII string argument, the hook name, and
	     returns the corresponding struct ng_tag_hookout as shown above.

     NGM_TAG_GET_STATS
	     This command takes an ASCII string argument, the hook name, and
	     returns the statistics associated with the hook as a struct
	     ng_tag_hookstat.

     NGM_TAG_CLR_STATS
	     This command takes an ASCII string argument, the hook name, and
	     clears the statistics associated with the hook.

     NGM_TAG_GETCLR_STATS
	     This command is identical to NGM_TAG_GET_STATS, except that the
	     statistics are also atomically cleared.

     Note: statistics counters as well as three statistics messages above work
     only if code was compiled with the NG_TAG_DEBUG option.  The reason for
     this is that statistics is rarely used in practice, but still consumes
     CPU cycles for every packet.  Moreover, it is even not accurate on SMP
     systems due to lack of synchronization between threads, as this is very
     expensive.

SHUTDOWN
     This node shuts down upon receipt of a NGM_SHUTDOWN control message, or
     when all hooks have been disconnected.

EXAMPLES
     It is possible to do a simple L7 filtering by using ipfw(8) tags in con‐
     junction 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 connec‐
     tion 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(4)
     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(4).

     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 }

     Don't 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 process‐
     ing inside netgraph(4), by setting appropriate sysctl(8) variable:

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

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

HISTORY
     The ng_tag node type was implemented in FreeBSD 6.2.

AUTHORS
     Vadim Goncharov ⟨vadimnuclight@tpu.ru⟩

BUGS
     For manipulating any tags with data payload (that is, all tags with non-
     zero tag_len) one should care about non-portable machine-dependent repre‐
     sentation of tags on the low level as byte stream.	 Perhaps this should
     be done by another program rather than manually.

BSD				 June 10, 2006				   BSD
[top]

List of man pages available for FreeBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net