1.\" $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz Exp $ 2.\" 3.\" Copyright (c) 2019 Gleb Smirnoff <glebius@FreeBSD.org> 4.\" Copyright (c) 1996 Matthew R. Green 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. The name of the author may not be used to endorse or promote products 16.\" derived from this software without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 25.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 26.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd January 28, 2019 31.Dt PFIL 9 32.Os 33.Sh NAME 34.Nm pfil , 35.Nm pfil_head_register , 36.Nm pfil_head_unregister , 37.Nm pfil_link , 38.Nm pfil_run_hooks 39.Nd packet filter interface 40.Sh SYNOPSIS 41.In sys/param.h 42.In sys/mbuf.h 43.In net/pfil.h 44.Ft pfil_head_t 45.Fn pfil_head_register "struct pfil_head_args *args" 46.Ft void 47.Fn pfil_head_unregister "struct pfil_head_t *head" 48.Ft pfil_hook_t 49.Fn pfil_add_hook "struct pfil_hook_args *" 50.Ft void 51.Fn pfil_remove_hook "pfil_hook_t" 52.Ft int 53.Fn pfil_link "struct pfil_link_args *args" 54.Ft int 55.Fn pfil_run_hooks "phil_head_t *" "pfil_packet_t" "struct ifnet *" "int" "struct inpcb *" 56.Sh DESCRIPTION 57The 58.Nm 59framework allows for a specified function or a list of functions 60to be invoked for every incoming or outgoing packet for a particular 61network I/O stream. 62These hooks may be used to implement a firewall or perform packet 63transformations. 64.Pp 65Packet filtering points, for historical reasons named 66.Em heads , 67are registered with 68.Fn pfil_head_register . 69The function is supplied with special versioned 70.Vt struct pfil_head_args 71structure that specifies type and features of the head as well as 72human readable name. 73If the filtering point to be ever destroyed, the subsystem that 74created it must unregister it with call to 75.Fn pfil_head_unregister . 76.Pp 77Packet filtering systems may register arbitrary number of filters, 78for historical reasons named 79.Em hooks . 80To register a new hook 81.Fn pfil_add_hook 82with special versioned 83.Vt struct pfil_hook_args 84structure is called. 85The structure specifies type and features of the hook, pointer to 86the actual filtering function and user readable name of the filtering 87module and ruleset name. 88Later hooks can be removed with 89.Fn pfil_remove_hook 90functions. 91.Pp 92To connect existing 93.Em hook 94to an existing 95.Em head 96function 97.Fn pfil_link 98shall be used. 99The function is supplied with versioned 100.Vt struct pfil_link_args 101structure that specifies either literal names of hook and head or 102pointers to them. 103Typically 104.Fn pfil_link 105is called by filtering modules to autoregister their default ruleset 106and default filtering points. 107It also serves on the kernel side of 108.Xr ioctl 2 109when user changes 110.Nm 111configuration with help of 112.Xr pfilctl 8 113utility. 114.Pp 115For every packet traveling through a 116.Em head 117the latter shall invoke 118.Fn pfil_run_hooks . 119The function can accept either 120.Vt struct mbuf * 121pointer or a 122.Vt void * 123pointer and length. 124In case if a hooked filtering module cannot understand 125.Vt void * 126pointer 127.Nm 128will provide it with a fake one. 129All calls to 130.Fn pfil_run_hooks 131are performed in network 132.Xr epoch 9 . 133.Sh HEADS (filtering points) 134By default kernel creates the following heads: 135.Bl -tag -width "ethernet" 136.It inet 137IPv4 packets. 138.It inet6 139IPv6 packets. 140.It ethernet 141Link-layer packets. 142.El 143.Pp 144Default rulesets are automatically linked to these heads to preserve 145historical behaviour. 146.Sh SEE ALSO 147.Xr ipfilter 4 , 148.Xr ipfw 4 , 149.Xr pf 4 , 150.Xr pfilctl 8 151.Sh HISTORY 152The 153.Nm 154interface first appeared in 155.Nx 1.3 . 156The 157.Nm 158interface was imported into 159.Fx 5.2 . 160In 161.Fx 13.0 162the interface was significantly rewritten. 163