A node that allows ethernet type packets to be filtered to different

hooks depending on ethertype. Great for prototyping protocols.
connects to the lower and upper hooks of an ethernet type of node.

Obtained from: Monzoon Networks.
	Thanks to Andre Oppermann, May 2001.

1 files changed, 150 insertions, 0 deletions

diff --git a/share/man/man4/ng_etf.4 b/share/man/man4/ng_etf.4
new file mode 100644
index 0000000..3a94eef
--- /dev/null
+++ b/share/man/man4/ng_etf.4
@@ -0,0 +1,150 @@
+.\"
+.\" Copyright (c) 2001, FreeBSD Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice unmodified, this list of conditions, and the following
+.\"    disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" 	$FreeBSD$
+.\"
+.\"
+.Dd February 28, 2001
+.Dt NG_ETF 4
+.Os FreeBSD
+.Sh NAME
+.Nm ng_etf
+.Nd Ethertype filtering netgraph node type
+.Sh SYNOPSIS
+.Fd #include <netgraph/ng_etf.h>
+.Sh DESCRIPTION
+The
+.Nm 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
+.Em 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 
+.Em nomatch
+hook. If the
+.Em nomatch
+hook is not connected, the packet is dropped.
+.Pp
+Packets travelling in the other direction  (towards the
+.Em downstream
+hook) are also examined and filtered.
+If a packet has an ethertype that matches one of he values configured
+into the node, it must have arrived in on the hook for which that value
+was configured. Ethertypes of values other than those configured
+by the conreol messages mus have arrived via the 
+.Em nomatch
+hook.
+.Sh HOOKS
+This node type supports the following hooks:
+.Pp
+.Bl -tag -width foobar
+.It Em downstream
+Typically this hook would be connected to a
+.Xr ng_ether 4
+node, using the 
+.Em lower
+hook.
+.It Em nomatch
+Typically this hook would also be connected to an
+.Xr ng_ether 4
+type node using the 
+.Em upper
+hook.
+.It Em <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.
+.El
+.Sh CONTROL MESSAGES
+This node type supports the generic control messages, plus the following:
+.Bl -tag -width foo
+.It Em NGM_ETF_GET_STATUS
+This command returns a
+.Em "struct ng_etfstat"
+containing node statistics for packet counts.
+.It Em NGM_ETF_SET_FILTER
+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 struct of type
+.Em "struct ng_etffilter" :
+.Bd -literal -offset 4n
+struct ng_etffilter {
+        char       matchhook[NG_HOOKLEN + 1]; /* hook name */
+        u_int16_t  ethertype;	              /* catch these */
+};
+.Ed
+.El
+.Sh EXAMPLES
+Using ngcontrol it is possible to set a filter in place from the command line
+as follows:
+.Bd -literal -offset 4n
+#!/bin/sh
+ETHER_IF=lnc0
+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 an dshow 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} }
+DONE
+
+.Ed
+.Sh SHUTDOWN
+This node shuts down upon receipt of a
+.Em NGM_SHUTDOWN
+control message, or when all hooks have been disconnected.
+.Sh SEE ALSO
+.Xr netgraph 4 ,
+.Xr ng_ether 4 ,
+.Xr ngctl 8
+.Xr nghook 8
+.Sh HISTORY
+The
+.Nm
+node type was implemented in
+.Fx 5.0 .
+.Sh AUTHORS
+.An Julian Elischer Aq julian@FreeBSD.org