1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2024 Igor Ostapenko <pm@igoro.pro> 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.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" Note: The date here should be updated whenever a non-trivial 28.\" change is made to the manual page. 29.Dd August 2, 2024 30.Dt DUMMYMBUF 4 31.Os 32.Sh NAME 33.Nm dummymbuf 34.Nd "mbuf alteration pfil hooks" 35.Sh SYNOPSIS 36To compile the driver into the kernel, 37place the following line in the 38kernel configuration file: 39.Bd -ragged -offset indent 40.Cd "device dummymbuf" 41.Ed 42.Pp 43Alternatively, to load the driver as a 44module at boot time, place the following line in 45.Xr loader.conf 5 : 46.Bd -literal -offset indent 47dummymbuf_load="YES" 48.Ed 49.Sh DESCRIPTION 50This module is intended to test networking code in the face of unusual mbuf 51layouts. 52The special 53.Xr pfil 9 54hooks are provided for mbuf alteration and can be listed with 55.Xr pfilctl 8 56as follows: 57.Bd -literal -offset indent 58 Hook Type 59 dummymbuf:ethernet Ethernet 60 dummymbuf:inet6 IPv6 61 dummymbuf:inet IPv4 62.Ed 63.Pp 64To activate a hook it must be linked to the respective 65.Xr pfil 9 66head. 67.Xr pfilctl 8 68can be used for the linking. 69.Pp 70Each time a hook is invoked it reads a single shared set of 71.Sx RULES 72from 73.Va net.dummymbuf.rules 74sysctl. 75The rules are evaluated sequentially and each matching rule performs the 76specified operation over the mbuf. 77.Pp 78After every successfully applied operation the 79.Va net.dummymbuf.hits 80sysctl counter is increased. 81.Pp 82A hook returns an altered mbuf for further processing, but it drops a packet 83if rules parsing or an operation fails. 84Also, the first mbuf of the original chain may be changed. 85.Pp 86The module is 87.Xr VNET 9 88based, hence every 89.Xr jail 2 90provides its own set of hooks and sysctl variables. 91.Sh RULES 92The set of rules is a semicolon separated list. 93An empty string is treated as a parsing failure. 94A rule conceptually has two parts, filter and operation, with the following 95syntax: 96.Bd -literal -offset indent 97{inet | inet6 | ethernet} {in | out} <ifname> <opname>[ <opargs>]; 98.Ed 99.Ss Filter 100The first word of a rule matches 101.Xr pfil 9 102type. 103The second matches packet's direction, and the third matches the network 104interface a packet is coming from. 105.Ss Operation 106An operation may have arguments separated from its name by space. 107The available operations are: 108.Bl -tag -width indent 109.It pull-head <number-of-bytes> 110Unconditionally creates a brand new cluster-based mbuf and links it to be the 111first mbuf of the original mbuf chain, with respective packet header moving. 112After, the given number of bytes are pulled from the original mbuf chain. 113.Pp 114If it is asked to pull 0 bytes then the first mbuf of the resulting chain will 115be left empty. 116Asking to pull more than 117.Dv MCLBYTES 118is treated as an operation failure. 119If a mbuf chain has less data than asked then the entire packet is pulled with 120tail mbuf(s) left empty. 121.Pp 122As a result, only the layout of a mbuf chain is altered, its content logically 123is left intact. 124.El 125.Sh SYSCTL VARIABLES 126The following variables are available: 127.Bl -tag -width indent 128.It Va net.dummymbuf.rules 129A string representing a single set of 130.Sx RULES 131shared among all 132.Nm 133hooks. 134.It Va net.dummymbuf.hits 135Number of times a rule has been applied. 136It is reset to zero upon writing. 137.El 138.Sh EXAMPLES 139As it was intended, 140.Nm 141can be found useful for firewall testing. 142A mbuf chain could be altered before it hits a firewall to test that the latter 143can handle a case respectively. 144Thus, it is important to have correct sequence of hooks. 145A test case should prepare and enable a firewall first to get its hooks linked. 146After, the 147.Xr pfilctl 8 148should be used to link 149.Nm 150hook(s) to put them in front of a firewall. 151.Pp 152The following links 153.Va dummymbuf:inet6 154hook for inbound and puts it in front of other hooks: 155.Bd -literal -offset indent 156pfilctl link -i dummymbuf:inet6 inet6 157.Ed 158.Pp 159And this does the same for outbound: 160.Bd -literal -offset indent 161pfilctl link -o -a dummymbuf:inet6 inet6 162.Ed 163.Pp 164For instance, we want to test a scenario in which the very first mbuf in a 165chain has zero m_len, to verify that a firewall can correctly read the 166packet data despite that. 167The following set of rules does it for inbound and outbound: 168.Bd -literal -offset indent 169sysctl net.dummymbuf.rules="inet6 in em0 pull-head 0; inet6 out em0 pull-head 0;" 170.Ed 171.Pp 172It is encouraged to verify 173.Va net.dummymbuf.hits 174sysctl counter along with other test assertions to make sure that 175.Nm 176really does its work and there is no false positive due to misconfiguration. 177It is a good idea to reset it before the action: 178.Bd -literal -offset indent 179sysctl net.dummymbuf.hits=0 180.Ed 181.Pp 182It is equally important to cleanup the things after the test case: 183.Bd -literal -offset indent 184pfilctl unlink -i dummymbuf:inet6 inet6 185pfilctl unlink -o dummymbuf:inet6 inet6 186sysctl net.dummymbuf.rules="" 187.Ed 188.Pp 189If a test case operates within a temporary vnet then explicit cleanup can be 190omitted, the 191.Nm 192facilities will vanish along with its vnet instance. 193.Sh DIAGNOSTICS 194.Bl -diag 195.It "dummymbuf: <filter match>: rule parsing failed: <the rule in question>" 196If everything looks fine then extra spaces removal may help due to the parser 197is kept very simple. 198.It "dummymbuf: <filter match>: mbuf operation failed: <the rule in question>" 199Incorrect operation argument has been found, mbuf allocation has failed, etc. 200.El 201.Sh SEE ALSO 202.Xr jail 2 , 203.Xr pfilctl 8 , 204.Xr mbuf 9 , 205.Xr pfil 9 , 206.Xr VNET 9 207.Sh AUTHORS 208The module and this manual page were written by 209.An Igor Ostapenko Aq Mt pm@igoro.pro . 210