1.\" $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz Exp $ 2.\" 3.\" Copyright (c) 1996 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following 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.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" 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 March 10, 2018 32.Dt PFIL 9 33.Os 34.Sh NAME 35.Nm pfil , 36.Nm pfil_head_register , 37.Nm pfil_head_unregister , 38.Nm pfil_head_get , 39.Nm pfil_add_hook , 40.Nm pfil_add_hook_flags , 41.Nm pfil_remove_hook , 42.Nm pfil_remove_hook_flags , 43.Nm pfil_run_hooks , 44.Nm pfil_rlock , 45.Nm pfil_runlock , 46.Nm pfil_wlock , 47.Nm pfil_wunlock 48.Nd packet filter interface 49.Sh SYNOPSIS 50.In sys/param.h 51.In sys/mbuf.h 52.In net/if.h 53.In net/pfil.h 54.Bd -literal 55typedef int (*pfil_func_t)(void *arg, struct mbuf **mp, struct ifnet *, int dir, struct inpcb); 56.Bd -literal 57typedef int (*pfil_func_flags_t)(void *arg, struct mbuf **mp, struct ifnet *, int dir, int flags, struct inpcb); 58.Ft int 59.Fn pfil_head_register "struct pfil_head *head" 60.Ft int 61.Fn pfil_head_unregister "struct pfil_head *head" 62.Ft "struct pfil_head *" 63.Fn pfil_head_get "int af" "u_long dlt" 64.Ft int 65.Fn pfil_add_hook "pfil_func_t" "void *arg" "struct pfil_head *" 66.Ft int 67.Fn pfil_add_hook_flags "pfil_func_flags_t" "void *arg" "int flags" "struct pfil_head *" 68.Ft int 69.Fn pfil_remove_hook "pfil_func_t" "void *arg" "struct pfil_head *" 70.Ft int 71.Fn pfil_remove_hook_flags "pfil_func_flags_t" "void *arg" "int flags" "struct pfil_head *" 72.Ft int 73.Fn pfil_run_hooks "struct pfil_head *head" "struct mbuf **mp" "struct ifnet *" "int dir" "int flags" "struct inpcb *" 74.Ft void 75.Fn pfil_rlock "struct pfil_head *" "struct rm_priotracker *" 76.Ft void 77.Fn pfil_runlock "struct pfil_head *" "struct rm_priotracker *" 78.Ft void 79.Fn pfil_wlock "struct pfil_head *" 80.Ft void 81.Fn pfil_wunlock "struct pfil_head *" 82.Ed 83.Sh DESCRIPTION 84The 85.Nm 86framework allows for a specified function to be invoked for every 87incoming or outgoing packet for a particular network I/O stream. 88These hooks may be used to implement a firewall or perform packet 89transformations. 90.Pp 91Packet filtering points are registered with 92.Fn pfil_head_register . 93Filtering points are identified by a key 94.Pq Vt "void *" 95and a data link type 96.Pq Vt int 97in the 98.Vt pfil_head 99structure. 100Packet filters use the key and data link type to look up the filtering 101point with which they register themselves. 102The key is unique to the filtering point. 103The data link type is a 104.Xr bpf 4 105DLT constant indicating what kind of header is present on the packet 106at the filtering point. 107Each filtering point uses common per-VNET rmlock by default. 108This can be changed by specifying 109.Vt PFIL_FLAG_PRIVATE_LOCK 110as 111.Vt "flags" 112field in the 113.Vt pfil_head 114structure. 115Note that specifying private lock can break filters sharing the same 116ruleset and/or state between different data link types. 117Filtering points may be unregistered with the 118.Fn pfil_head_unregister 119function. 120.Pp 121Packet filters register/unregister themselves with a filtering point 122with the 123.Fn pfil_add_hook 124and 125.Fn pfil_remove_hook 126functions, respectively. 127.I 128The head is looked up using the 129.Fn pfil_head_get 130function, which takes the key and data link type that the packet filter 131expects. 132Filters may provide an argument to be passed to the filter when 133invoked on a packet. 134.Pp 135When a filter is invoked, the packet appears just as if it 136.Dq came off the wire . 137That is, all protocol fields are in network byte order. 138The filter is called with its specified argument, the pointer to the 139pointer to the 140.Vt mbuf 141containing the packet, the pointer to the network 142interface that the packet is traversing, and the direction 143.Dv ( PFIL_IN 144or 145.Dv PFIL_OUT ) 146that the packet is traveling. 147The 148.Vt flags 149argument will indicate if an outgoing packet is simply being forwarded with the 150value PFIL_FWD. 151The filter may change which mbuf the 152.Vt "mbuf\ **" 153argument references. 154The filter returns an error (errno) if the packet processing is to stop, or 0 155if the processing is to continue. 156If the packet processing is to stop, it is the responsibility of the 157filter to free the packet. 158.Pp 159Every filter hook is called with 160.Nm 161read lock held. 162All heads uses the same lock within the same VNET instance. 163Packet filter can use this lock instead of own locking model to 164improve performance. 165Since 166.Nm 167uses 168.Xr rmlock 9 169.Fn pfil_rlock 170and 171.Fn pfil_runlock 172require 173.Va struct rm_priotracker 174to be passed as argument. 175Filter can acquire and release writer lock via 176.Fn pfil_wlock 177and 178.Fn pfil_wunlock 179functions. 180See 181.Xr rmlock 9 182for more details. 183.Sh FILTERING POINTS 184Currently, filtering points are implemented for the following link types: 185.Pp 186.Bl -tag -width "AF_INET6" -offset XXX -compact 187.It AF_INET 188IPv4 packets. 189.It AF_INET6 190IPv6 packets. 191.It AF_LINK 192Link-layer packets. 193.El 194.Sh RETURN VALUES 195If successful, 196.Fn pfil_head_get 197returns the 198.Vt pfil_head 199structure for the given key/dlt. 200The 201.Fn pfil_add_hook 202and 203.Fn pfil_remove_hook 204functions 205return 0 if successful. 206If called with flag 207.Dv PFIL_WAITOK , 208.Fn pfil_remove_hook 209is expected to always succeed. 210.Pp 211The 212.Fn pfil_head_unregister 213function 214might sleep! 215.Sh SEE ALSO 216.Xr bpf 4 , 217.Xr if_bridge 4 , 218.Xr rmlock 9 219.Sh HISTORY 220The 221.Nm 222interface first appeared in 223.Nx 1.3 . 224The 225.Nm 226input and output lists were originally implemented as 227.In sys/queue.h 228.Dv LIST 229structures; 230however this was changed in 231.Nx 1.4 232to 233.Dv TAILQ 234structures. 235This change was to allow the input and output filters to be processed in 236reverse order, to allow the same path to be taken, in or out of the kernel. 237.Pp 238The 239.Nm 240interface was changed in 1.4T to accept a 3rd parameter to both 241.Fn pfil_add_hook 242and 243.Fn pfil_remove_hook , 244introducing the capability of per-protocol filtering. 245This was done primarily in order to support filtering of IPv6. 246.Pp 247In 1.5K, the 248.Nm 249framework was changed to work with an arbitrary number of filtering points, 250as well as be less IP-centric. 251.Pp 252Fine-grained locking was added in 253.Fx 5.2 . 254.Nm 255lock export was added in 256.Fx 10.0 . 257.Sh BUGS 258When a 259.Vt pfil_head 260is being modified, no traffic is diverted 261(to avoid deadlock). 262This means that traffic may be dropped unconditionally for a short period 263of time. 264.Fn pfil_run_hooks 265will return 266.Er ENOBUFS 267to indicate this. 268