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