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.\" $FreeBSD$ 31.\" 32.Dd January 28, 2019 33.Dt PFIL 9 34.Os 35.Sh NAME 36.Nm pfil , 37.Nm pfil_head_register , 38.Nm pfil_head_unregister , 39.Nm pfil_link , 40.Nm pfil_run_hooks 41.Nd packet filter interface 42.Sh SYNOPSIS 43.In sys/param.h 44.In sys/mbuf.h 45.In net/pfil.h 46.Ft pfil_head_t 47.Fn pfil_head_register "struct pfil_head_args *args" 48.Ft void 49.Fn pfil_head_unregister "struct pfil_head_t *head" 50.Ft pfil_hook_t 51.Fn pfil_add_hook "struct pfil_hook_args *" 52.Ft void 53.Fn pfil_remove_hook "pfil_hook_t" 54.Ft int 55.Fn pfil_link "struct pfil_link_args *args" 56.Ft int 57.Fn pfil_run_hooks "phil_head_t *" "pfil_packet_t" "struct ifnet *" "int" "struct inpcb *" 58.Sh DESCRIPTION 59The 60.Nm 61framework allows for a specified function or a list of functions 62to be invoked for every incoming or outgoing packet for a particular 63network I/O stream. 64These hooks may be used to implement a firewall or perform packet 65transformations. 66.Pp 67Packet filtering points, for historical reasons named 68.Em heads , 69are registered with 70.Fn pfil_head_register . 71The function is supplied with special versioned 72.Vt struct pfil_head_args 73structure that specifies type and features of the head as well as 74human readable name. 75If the filtering point to be ever destroyed, the subsystem that 76created it must unregister it with call to 77.Fn pfil_head_unregister . 78.Pp 79Packet filtering systems may register arbitrary number of filters, 80for historical reasons named 81.Em hooks . 82To register a new hook 83.Fn pfil_add_hook 84with special versioned 85.Vt struct pfil_hook_args 86structure is called. 87The structure specifies type and features of the hook, pointer to 88the actual filtering function and user readable name of the filtering 89module and ruleset name. 90Later hooks can be removed with 91.Fn pfil_remove_hook 92functions. 93.Pp 94To connect existing 95.Em hook 96to an existing 97.Em head 98function 99.Fn pfil_link 100shall be used. 101The function is supplied with versioned 102.Vt struct pfil_link_args 103structure that specifies either literal names of hook and head or 104pointers to them. 105Typically 106.Fn pfil_link 107is called by filtering modules to autoregister their default ruleset 108and default filtering points. 109It also serves on the kernel side of 110.Xr ioctl 2 111when user changes 112.Nm 113configuration with help of 114.Xr pfilctl 8 115utility. 116.Pp 117For every packet traveling through a 118.Em head 119the latter shall invoke 120.Fn pfil_run_hooks . 121The function can accept either 122.Vt struct mbuf * 123pointer or a 124.Vt void * 125pointer and length. 126In case if a hooked filtering module cannot understand 127.Vt void * 128pointer 129.Nm 130will provide it with a fake one. 131All calls to 132.Fn pfil_run_hooks 133are performed in network 134.Xr epoch 9 . 135.Sh HEADS (filtering points) 136By default kernel creates the following heads: 137.Bl -tag -width "ethernet" 138.It inet 139IPv4 packets. 140.It inet6 141IPv6 packets. 142.It ethernet 143Link-layer packets. 144.El 145.Pp 146Default rulesets are automatically linked to these heads to preserve 147historical behaviour. 148.Sh SEE ALSO 149.Xr ipfilter 4 , 150.Xr ipfw 4 , 151.Xr pf 4 , 152.Xr pfilctl 8 153.Sh HISTORY 154The 155.Nm 156interface first appeared in 157.Nx 1.3 . 158The 159.Nm 160interface was imported into 161.Fx 5.2 . 162In 163.Fx 13.0 164the interface was significantly rewritten. 165