1 .\" Copyright (c) 2012-2017 Pekka Nikander
2 .\" Copyright (c) 2018 Retina b.v.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
36 .Nd packet filtering netgraph node using ethernet MAC addresses
39 .In netgraph/ng_macfilter.h
43 allows routing ethernet packets over different hooks based on the sender MAC
46 This processing is done when traffic flows from the
50 to one of the outgoing hooks.
51 Outbound hooks can be added to and remove from
53 and arbitrarily named.
54 By default one hook called
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.
60 keeps track of packets and bytes from and to this MAC address in the MAC table.
62 Packets are not altered in any way.
63 If hooks are not connected, packets are
66 This node type by default has an
68 hook, to be connected to the
70 hook of the NIC, and a
72 hook where packets are sent if the MAC adddress is not found in the table.
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
81 This node type supports the generic control messages, plus the
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*/
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 */
103 The given ethernet MAC address will be forwarded out the hook at id
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 */
116 struct ngm_macfilter_macs {
117 u_int32_t n; /* Number of entries in macs */
118 struct ngm_macfilter_mac macs[]; /* Macs table */
121 .It Dv NGM_MACFILTER_GETCLR_MACS Pq Ic getclrmacs
122 Same as above, but will also atomically clear the
125 .Dv packets_out , and
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 */
141 This node shuts down upon receipt of a
143 control message or when all have been disconnected.
145 The following netgraph configuration will apply
147 tag 42 to each packet that is routed over the
150 The graph looks like the following:
151 .Bd -literal -offset indent
152 /------<one>-[combiner]-<many1>--------\\
158 \\----<ether>-[macfilter]-<accepted>-----/
162 .Bd -literal -offset indent
163 ngctl mkpeer em0: macfilter lower ether
164 ngctl name em0:lower macfilter
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
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 }'
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 ] }'
187 The tag_cookie 1148380143 was retrieved from
190 .Pa /usr/include/netinet/ip_var.h .
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 }'
198 The following command can be used to retrieve the packet and byte counters :
199 .Bd -literal -offset indent
200 ngctl msg macfilter: getmacs
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 } ] }
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 .