share/man/man4/ng_macfilter.4

   1 .\" Copyright (c) 2012-2017 Pekka Nikander
   2 .\" Copyright (c) 2018 Retina b.v.
   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, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. Neither the name of the University nor the names of its contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd December 10, 2018
  32 .Dt NG_MACFILTER 4
  33 .Os
  34 .Sh NAME
  35 .Nm ng_macfilter
  36 .Nd packet filtering netgraph node using ethernet MAC addresses
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In netgraph/ng_macfilter.h
  40 .Sh DESCRIPTION
  41 The
  42 .Nm macfilter
  43 allows routing ethernet packets over different hooks based on the sender MAC
  44 address.
  45 .Pp
  46 This processing is done when traffic flows from the
  47 .Dq ether
  48 hook trough
  49 .Nm macfilter
  50 to one of the outgoing hooks.
  51 Outbound hooks can be added to and remove from
  52 .Nm macfilter
  53 and arbitrarily named.
  54 By default one hook called
  55 .Dq default
  56 is present and used for all packets which have no MAC address in the MAC table.
  57 By adding MAC addresses to the MAC table traffic coming from this host can be
  58 directed out other hooks.
  59 .Nm macfilter
  60 keeps track of packets and bytes from and to this MAC address in the MAC table.
  61 .Pp
  62 Packets are not altered in any way.
  63 If hooks are not connected, packets are
  64 dropped.
  65 .Sh HOOKS
  66 This node type by default has an
  67 .Dv ether
  68 hook, to be connected to the
  69 .Dv lower
  70 hook of the NIC, and a
  71 .Dv default
  72 hook where packets are sent if the MAC adddress is not found in the table.
  73 .Nm macfilter
  74 supports up to
  75 .Dv NG_MACFILTER_UPPER_NUM
  76 hooks to be connected to the NIC's upper hook.
  77 Other nodes can be inserted to provide additional processing.
  78 All outbound can be combined back into one by using
  79 .Dv ng_one2many .
  80 .Sh CONTROL MESSAGES
  81 This node type supports the generic control messages, plus the
  82 following:
  83 .Bl -tag -width foo
  84 .It Dv NGM_MACFILTER_RESET Pq Ic reset
  85 Resets the MAC table in the node.
  86 .It Dv NGM_MACFILTER_DIRECT Pq Ic direct
  87 Takes the following argument struct:
  88 .Bd -literal -offset indent
  89 struct ngm_macfilter_direct {
  90     u_char      ether[ETHER_ADDR_LEN];          /* MAC address */
  91     u_char      hookname[NG_HOOKSIZ];           /* Upper hook name*/
  92 };
  93 .Ed
  94 The given ethernet MAC address will be forwarded out the named hook.
  95 .It Dv NGM_MACFILTER_DIRECT_HOOKID Pq Ic directi
  96 Takes the following argument struct:
  97 .Bd -literal -offset indent
  98 struct ngm_macfilter_direct_hookid {
  99     u_char      ether[ETHER_ADDR_LEN];          /* MAC address */
 100     u_int16_t   hookid;                         /* Upper hook hookid */
 101 };
 102 .Ed
 103 The given ethernet MAC address will be forwarded out the hook at id
 104 .Dv hookid .
 105 .It Dv NGM_MACFILTER_GET_MACS Pq Ic getmacs
 106 Returns the list of MAC addresses in the node in the following structure:
 107 .Bd -literal -offset indent
 108 struct ngm_macfilter_mac {
 109     u_char      ether[ETHER_ADDR_LEN];          /* MAC address */
 110     u_int16_t   hookid;                         /* Upper hook hookid */
 111     u_int64_t   packets_in;                     /* packets in from downstream */
 112     u_int64_t   bytes_in;                       /* bytes in from upstream */
 113     u_int64_t   packets_out;                    /* packets out towards downstream */
 114     u_int64_t   bytes_out;                      /* bytes out towards downstream */
 115 };
 116 struct ngm_macfilter_macs {
 117     u_int32_t   n;                              /* Number of entries in macs */
 118     struct ngm_macfilter_mac macs[];            /* Macs table */
 119 };
 120 .Ed
 121 .It Dv NGM_MACFILTER_GETCLR_MACS Pq Ic getclrmacs
 122 Same as above, but will also atomically clear the
 123 .Dv packets_in ,
 124 .Dv bytes_in ,
 125 .Dv packets_out , and
 126 .Dv bytes_out
 127 fields in the table.
 128 .It Dv NGM_MACFILTER_CLR_STATS Pq Ic clrmacs
 129 Will clear the per MAC address packet and byte counters.
 130 .It Dv NGM_MACFILTER_GET_HOOKS Pq Ic gethooks
 131 Will return a list of hooks and their hookids in an array of the following struct's:
 132 .Bd -literal -offset indent
 133 struct ngm_macfilter_hook {
 134     u_char      hookname[NG_HOOKSIZ];           /* Upper hook name*/
 135     u_int16_t   hookid;                         /* Upper hook hookid */
 136     u_int32_t   maccnt;                         /* Number of mac addresses associated with hook */
 137 };
 138 .Ed
 139 .El
 140 .Sh SHUTDOWN
 141 This node shuts down upon receipt of a
 142 .Dv NGM_SHUTDOWN
 143 control message or when all have been disconnected.
 144 .Sh EXAMPLES
 145 The following netgraph configuration will apply
 146 .Xr ipfw 8
 147 tag 42 to each packet that is routed over the
 148 .Dq accepted
 149 hook.
 150 The graph looks like the following:
 151 .Bd -literal -offset indent
 152     /------<one>-[combiner]-<many1>--------\\
 153 <upper>               |                    <out>
 154   /                <many0>                    \\
 155 [em0]                 |                    [tagger]
 156   \\               <default>                   /
 157 <lower>               |                     <in>
 158     \\----<ether>-[macfilter]-<accepted>-----/
 159 .Ed
 160 .Pp
 161 Commands:
 162 .Bd -literal -offset indent
 163   ngctl mkpeer em0: macfilter lower ether
 164   ngctl name em0:lower macfilter
 165
 166   # Funnel both streams back into ether:upper
 167   ngctl mkpeer em0: one2many upper one
 168   ngctl name em0:upper recombiner
 169   # Connect macfilter:default to recombiner:many0
 170   ngctl connect macfilter: recombiner: default many0
 171   # Connect macfilter:accepted to tagger:in
 172   ngctl mkpeer macfilter: tag accepted in
 173   ngctl name macfilter:accepted tagger
 174   # Connect tagger:out to recombiner:many1
 175   ngctl connect tagger: recombiner: out many1
 176
 177   # Mark tag all traffic through tagger in -> out with an ipfw tag 42
 178   ngctl msg tagger: sethookin '{ thisHook="in" ifNotMatch="out" }'
 179   ngctl msg tagger: sethookout '{ thisHook="out" tag_cookie=1148380143 tag_id=42 }'
 180
 181   # Pass traffic from ether:upper / combiner:one via combiner:many0 on to
 182   # macfilter:default and on to ether:lower.
 183   ngctl msg recombiner: setconfig '{ xmitAlg=3 failAlg=1 enabledLinks=[ 1 1 ] }'
 184 .Ed
 185 .Pp
 186 .Em Note :
 187 The tag_cookie 1148380143 was retrieved from
 188 .Dv MTAG_IPFW
 189 in
 190 .Pa /usr/include/netinet/ip_var.h .
 191 .Pp
 192 The following command can be used to add a MAC address to be output via
 193 .Dv macfilter:accepted :
 194 .Bd -literal -offset indent
 195   ngctl msg macfilter: direct '{ hookname="known" ether=08:00:27:92:eb:aa }'
 196 .Ed
 197 .Pp
 198 The following command can be used to retrieve the packet and byte counters :
 199 .Bd -literal -offset indent
 200   ngctl msg macfilter: getmacs
 201 .Ed
 202 .Pp
 203 It will return the contents of the MAC table:
 204 .Bd -literal -offset indent
 205   Rec'd response "getmacs" (4) from "[54]:":
 206   Args: { n=1 macs=[ { ether=08:00:27:92:eb:aa hookid=1 packets_in=3571 bytes_in=592631 packets_out=3437 bytes_out=777142 } ] }
 207 .Ed
 208 .Sh SEE ALSO
 209 .Xr divert 4 ,
 210 .Xr ipfw 4 ,
 211 .Xr netgraph 4 ,
 212 .Xr ng_ether 4 ,
 213 .Xr ng_one2many 4 ,
 214 .Xr ng_tag 4 ,
 215 .Xr ngctl 8
 216 .Sh AUTHORS
 217 .An -nosplit
 218 The original version of this code was written by Pekka Nikander, and
 219 subsequently modified heavily by
 220 .An Nick Hibma Aq Mt n_hibma@FreeBSD.org .
 221 .Sh BUGS
 222 None known.