PageRenderTime 36ms CodeModel.GetById 14ms app.highlight 18ms RepoModel.GetById 1ms app.codeStats 0ms

/share/man/man4/ng_etf.4

https://bitbucket.org/freebsd/freebsd-head/
Forth | 154 lines | 153 code | 1 blank | 0 comment | 4 complexity | 4e43a9065e05c91d960bea48065d95bd MD5 | raw file
  1.\"
  2.\" Copyright (c) 2001, FreeBSD Inc.
  3.\" All rights reserved.
  4.\"
  5.\" Redistribution and use in source and binary forms, with or without
  6.\" modification, are permitted provided that the following conditions
  7.\" are met:
  8.\" 1. Redistributions of source code must retain the above copyright
  9.\"    notice unmodified, this list of conditions, and the following
 10.\"    disclaimer.
 11.\" 2. Redistributions in binary form must reproduce the above copyright
 12.\"    notice, this list of conditions and the following disclaimer in the
 13.\"    documentation and/or other materials provided with the distribution.
 14.\"
 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 25.\" SUCH DAMAGE.
 26.\"
 27.\" $FreeBSD$
 28.\"
 29.Dd May 16, 2006
 30.Dt NG_ETF 4
 31.Os
 32.Sh NAME
 33.Nm ng_etf
 34.Nd Ethertype filtering netgraph node type
 35.Sh SYNOPSIS
 36.In netgraph.h
 37.In netgraph/ng_etf.h
 38.Sh DESCRIPTION
 39The
 40.Nm etf
 41node type multiplexes and filters data between hooks on the basis
 42of the ethertype found in an Ethernet header, presumed to be in the
 43first 14 bytes of the data.
 44Incoming Ethernet frames are accepted on the
 45.Em downstream
 46hook and if the ethertype matches a value which the node has been configured
 47to filter, the packet is forwarded out the hook which was identified
 48at the time that value was configured.
 49If it does not match a configured
 50value, it is passed to the
 51.Em nomatch
 52hook.
 53If the
 54.Em nomatch
 55hook is not connected, the packet is dropped.
 56.Pp
 57Packets travelling in the other direction (towards the
 58.Em downstream
 59hook) are also examined and filtered.
 60If a packet has an ethertype that matches one of the values configured
 61into the node, it must have arrived in on the hook for which that value
 62was configured, otherwise it will be discarded.
 63Ethertypes of values other
 64than those configured by the control messages must have arrived via the
 65.Em nomatch
 66hook.
 67.Sh HOOKS
 68This node type supports the following hooks:
 69.Bl -tag -width ".Em downstream"
 70.It Em downstream
 71Typically this hook would be connected to a
 72.Xr ng_ether 4
 73node, using the
 74.Em lower
 75hook.
 76.It Em nomatch
 77Typically this hook would also be connected to an
 78.Xr ng_ether 4
 79type node using the
 80.Em upper
 81hook.
 82.It Aq Em "any legal name"
 83Any other hook name will be accepted and can be used as the match target
 84of an ethertype.
 85Typically this hook would be attached to
 86a protocol handling node that requires and generates packets
 87with a particular set of ethertypes.
 88.El
 89.Sh CONTROL MESSAGES
 90This node type supports the generic control messages, plus the following:
 91.Bl -tag -width 4n
 92.It Dv NGM_ETF_GET_STATUS
 93This command returns a
 94.Vt "struct ng_etfstat"
 95containing node statistics for packet counts.
 96.It Dv NGM_ETF_SET_FILTER
 97Sets the a new ethertype filter into the node and specifies the hook to and
 98from which packets of that type should use.
 99The hook and ethertype
100are specified in a structure of type
101.Vt "struct ng_etffilter" :
102.Bd -literal -offset 4n
103struct ng_etffilter {
104        char       matchhook[NG_HOOKSIZ];     /* hook name */
105        uint16_t   ethertype;	              /* catch these */
106};
107.Ed
108.El
109.Sh EXAMPLES
110Using
111.Xr ngctl 8
112it is possible to set a filter in place from the command line
113as follows:
114.Bd -literal -offset 4n
115#!/bin/sh
116ETHER_IF=fxp0
117MATCH1=0x834
118MATCH2=0x835
119cat <<DONE >/tmp/xwert
120# Make a new ethertype filter and attach to the Ethernet lower hook.
121# first remove left over bits from last time.
122shutdown ${ETHER_IF}:lower
123mkpeer ${ETHER_IF}: etf lower downstream
124# Give it a name to easily refer to it.
125name ${ETHER_IF}:lower etf
126# Connect the nomatch hook to the upper part of the same interface.
127# All unmatched packets will act as if the filter is not present.
128connect ${ETHER_IF}: etf: upper nomatch
129DONE
130ngctl -f /tmp/xwert
131
132# something to set a hook to catch packets and show them.
133echo "Unrecognised packets:"
134nghook -a etf: newproto &
135# Filter two random ethertypes to that hook.
136ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH1} }
137ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH2} }
138.Ed
139.Sh SHUTDOWN
140This node shuts down upon receipt of a
141.Dv NGM_SHUTDOWN
142control message, or when all hooks have been disconnected.
143.Sh SEE ALSO
144.Xr netgraph 4 ,
145.Xr ng_ether 4 ,
146.Xr ngctl 8 ,
147.Xr nghook 8
148.Sh HISTORY
149The
150.Nm
151node type was implemented in
152.Fx 5.0 .
153.Sh AUTHORS
154.An Julian Elischer Aq julian@FreeBSD.org