NAME

       ng_etf — Ethertype filtering netgraph node type

SYNOPSIS

       #include <netgraph.h>
       #include <netgraph/ng_etf.h>

DESCRIPTION

       The  etf  node  type multiplexes and filters data between hooks on the basis of the ethertype found in an
       Ethernet header, presumed to be in the first 14 bytes of the data.  Incoming Ethernet frames are accepted
       on the downstream hook and if the ethertype matches a value which the node has been configured to filter,
       the packet is forwarded out the hook which was identified at the time that value was configured.   If  it
       does  not  match  a  configured  value,  it  is  passed  to the nomatch hook.  If the nomatch hook is not
       connected, the packet is dropped.

       Packets travelling in the other direction (towards the downstream hook) are also examined  and  filtered.
       If  a  packet  has  an  ethertype  that  matches one of the values configured into the node, it must have
       arrived in on the hook for which that value was configured, otherwise it will be  discarded.   Ethertypes
       of values other than those configured by the control messages must have arrived via the nomatch hook.

HOOKS

       This node type supports the following hooks:

       downstream        Typically this hook would be connected to a ng_ether(4) node, using the lower hook.

       nomatch           Typically this hook would also be connected to an ng_ether(4) type node using the upper
                         hook.

       ⟨any legal name⟩  Any  other  hook  name  will  be  accepted  and  can  be used as the match target of an
                         ethertype.  Typically this hook would be attached to  a  protocol  handling  node  that
                         requires and generates packets with a particular set of ethertypes.

CONTROL MESSAGES

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

       NGM_ETF_GET_STATUS (getstatus)
             This command returns a struct ng_etfstat containing node statistics for packet counts.

       NGM_ETF_SET_FILTER (setfilter)
             Sets  the  a new ethertype filter into the node and specifies the hook to and from which packets of
             that type should use.  The hook  and  ethertype  are  specified  in  a  structure  of  type  struct
             ng_etffilter:

                 struct ng_etffilter {
                     char        matchhook[NG_HOOKSIZ];  /* hook name */
                     uint16_t    ethertype;              /* this ethertype to this hook */
                 };

EXAMPLES

       Using ngctl(8) it is possible to set a filter in place from the command line as follows:

           #!/bin/sh
           ETHER_IF=fxp0
           MATCH1=0x834
           MATCH2=0x835
           cat <<DONE >/tmp/xwert
           # Make a new ethertype filter and attach to the Ethernet lower hook.
           # first remove left over bits from last time.
           shutdown ${ETHER_IF}:lower
           mkpeer ${ETHER_IF}: etf lower downstream
           # Give it a name to easily refer to it.
           name ${ETHER_IF}:lower etf
           # Connect the nomatch hook to the upper part of the same interface.
           # All unmatched packets will act as if the filter is not present.
           connect ${ETHER_IF}: etf: upper nomatch
           DONE
           ngctl -f /tmp/xwert

           # something to set a hook to catch packets and show them.
           echo "Unrecognised packets:"
           nghook -a etf: newproto &
           # Filter two random ethertypes to that hook.
           ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH1} }
           ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH2} }

SHUTDOWN

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

SEE ALSO

       netgraph(4), ng_ether(4), ngctl(8), nghook(8)

HISTORY

       The ng_etf node type was implemented in FreeBSD 5.0.

AUTHORS

       Julian Elischer <julian@FreeBSD.org>

Debian                                          November 13, 2012                                      NG_ETF(4)