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 41The 42.Nm macfilter 43allows routing ethernet packets over different hooks based on the sender MAC 44address. 45.Pp 46This processing is done when traffic flows from the 47.Dq ether 48hook through 49.Nm macfilter 50to one of the outgoing hooks. 51Outbound hooks can be added to and remove from 52.Nm macfilter 53and arbitrarily named. 54By default one hook called 55.Dq default 56is present and used for all packets which have no MAC address in the MAC table. 57By adding MAC addresses to the MAC table traffic coming from this host can be 58directed out other hooks. 59.Nm macfilter 60keeps track of packets and bytes from and to this MAC address in the MAC table. 61.Pp 62Packets are not altered in any way. 63If hooks are not connected, packets are 64dropped. 65.Sh HOOKS 66This node type by default has an 67.Dv ether 68hook, to be connected to the 69.Dv lower 70hook of the NIC, and a 71.Dv default 72hook where packets are sent if the MAC adddress is not found in the table. 73.Nm macfilter 74supports up to 75.Dv NG_MACFILTER_UPPER_NUM 76hooks to be connected to the NIC's upper hook. 77Other nodes can be inserted to provide additional processing. 78All outbound can be combined back into one by using 79.Dv ng_one2many . 80.Sh CONTROL MESSAGES 81This node type supports the generic control messages, plus the 82following: 83.Bl -tag -width foo 84.It Dv NGM_MACFILTER_RESET Pq Ic reset 85Resets the MAC table in the node. 86.It Dv NGM_MACFILTER_DIRECT Pq Ic direct 87Takes the following argument struct: 88.Bd -literal -offset indent 89struct ngm_macfilter_direct { 90 u_char ether[ETHER_ADDR_LEN]; /* MAC address */ 91 u_char hookname[NG_HOOKSIZ]; /* Upper hook name*/ 92}; 93.Ed 94The given ethernet MAC address will be forwarded out the named hook. 95.It Dv NGM_MACFILTER_DIRECT_HOOKID Pq Ic directi 96Takes the following argument struct: 97.Bd -literal -offset indent 98struct ngm_macfilter_direct_hookid { 99 u_char ether[ETHER_ADDR_LEN]; /* MAC address */ 100 u_int16_t hookid; /* Upper hook hookid */ 101}; 102.Ed 103The 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 106Returns the list of MAC addresses in the node in the following structure: 107.Bd -literal -offset indent 108struct 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}; 116struct 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 122Same 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 127fields in the table. 128.It Dv NGM_MACFILTER_CLR_STATS Pq Ic clrmacs 129Will clear the per MAC address packet and byte counters. 130.It Dv NGM_MACFILTER_GET_HOOKS Pq Ic gethooks 131Will return a list of hooks and their hookids in an array of the following struct's: 132.Bd -literal -offset indent 133struct 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 141This node shuts down upon receipt of a 142.Dv NGM_SHUTDOWN 143control message or when all have been disconnected. 144.Sh EXAMPLES 145The following netgraph configuration will apply 146.Xr ipfw 8 147tag 42 to each packet that is routed over the 148.Dq accepted 149hook. 150The 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 161Commands: 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 : 187The tag_cookie 1148380143 was retrieved from 188.Dv MTAG_IPFW 189in 190.Pa /usr/include/netinet/ip_var.h . 191.Pp 192The 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 198The 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 203It 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 218The original version of this code was written by Pekka Nikander, and 219subsequently modified heavily by 220.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . 221.Sh BUGS 222None known. 223