share/man/man4/ng_etf.4

   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: src/share/man/man4/ng_etf.4,v 1.3.2.1 2002/04/09 20:17:17 julian Exp $
  28 .\"
  29 .Dd February 28, 2001
  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/ng_etf.h
  37 .Sh DESCRIPTION
  38 The
  39 .Nm etf
  40 node type multiplexes and filters data between hooks on the basis
  41 of the ethertype found in an ethernet header, presumed to be in the
  42 first 14 bytes of the data.
  43 Incoming Ethernet frames are accepted on the
  44 .Em downstream
  45 hook and if the ethertype matches a value which the node has been configured
  46 to filter, the packet is forwarded out the hook which was identified
  47 at the time that value was configured.
  48 If it does not match a configured
  49 value, it is passed to the
  50 .Em nomatch
  51 hook.
  52 If the
  53 .Em nomatch
  54 hook is not connected, the packet is dropped.
  55 .Pp
  56 Packets travelling in the other direction (towards the
  57 .Em downstream
  58 hook) are also examined and filtered.
  59 If a packet has an ethertype that matches one of the values configured
  60 into the node, it must have arrived in on the hook for which that value
  61 was configured, otherwise it will be discarded.
  62 Ethertypes of values other
  63 than those configured by the control messages must have arrived via the
  64 .Em nomatch
  65 hook.
  66 .Sh HOOKS
  67 This node type supports the following hooks:
  68 .Bl -tag -width ".Em downstream"
  69 .It Em downstream
  70 Typically this hook would be connected to a
  71 .Xr ng_ether 4
  72 node, using the
  73 .Em lower
  74 hook.
  75 .It Em nomatch
  76 Typically this hook would also be connected to an
  77 .Xr ng_ether 4
  78 type node using the
  79 .Em upper
  80 hook.
  81 .It Aq Em "any legal name"
  82 Any other hook name will be accepted and can be used as the match target
  83 of an ethertype.
  84 Typically this hook would be attached to
  85 a protocol handling node that requires and generates packets
  86 with a particular set of ethertypes.
  87 .El
  88 .Sh CONTROL MESSAGES
  89 This node type supports the generic control messages, plus the following:
  90 .Bl -tag -width 4n
  91 .It Dv NGM_ETF_GET_STATUS
  92 This command returns a
  93 .Vt "struct ng_etfstat"
  94 containing node statistics for packet counts.
  95 .It Dv NGM_ETF_SET_FILTER
  96 Sets the a new ethertype filter into the node and specifies the hook to and
  97 from which packets of that type should use.
  98 The hook and ethertype
  99 are specified in a structure of type
 100 .Vt "struct ng_etffilter" :
 101 .Bd -literal -offset 4n
 102 struct ng_etffilter {
 103         char       matchhook[NG_HOOKLEN + 1]; /* hook name */
 104         u_int16_t  ethertype;                 /* catch these */
 105 };
 106 .Ed
 107 .El
 108 .Sh EXAMPLES
 109 Using
 110 .Xr ngctl 8
 111 it is possible to set a filter in place from the command line
 112 as follows:
 113 .Bd -literal -offset 4n
 114 #!/bin/sh
 115 ETHER_IF=lnc0
 116 MATCH1=0x834
 117 MATCH2=0x835
 118 cat <<DONE >/tmp/xwert
 119 # Make a new ethertype filter and attach to the ethernet lower hook.
 120 # first remove left over bits from last time.
 121 shutdown ${ETHER_IF}:lower
 122 mkpeer ${ETHER_IF}: etf lower downstream
 123 # Give it a name to easily refer to it.
 124 name ${ETHER_IF}:lower etf
 125 # Connect the nomatch hook to the upper part of the same interface.
 126 # All unmatched packets will act as if the filter is not present.
 127 connect ${ETHER_IF}: etf: upper nomatch
 128 DONE
 129 ngctl -f /tmp/xwert
 130
 131 # something to set a hook to catch packets and show them.
 132 echo "Unrecognised packets:"
 133 nghook -a etf: newproto &
 134 # Filter two random ethertypes to that hook.
 135 ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH1} }
 136 ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH2} }
 137 DONE
 138 .Ed
 139 .Sh SHUTDOWN
 140 This node shuts down upon receipt of a
 141 .Dv NGM_SHUTDOWN
 142 control 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
 149 The
 150 .Nm
 151 node type was implemented in
 152 .Fx 4.6 .
 153 .Sh AUTHORS
 154 .An Julian Elischer Aq julian@FreeBSD.org