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 January 6, 2025 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.It enlarge <number-of-bytes> 125Unconditionally replace the mbuf with an mbuf of the specified size. 126.El 127.Sh SYSCTL VARIABLES 128The following variables are available: 129.Bl -tag -width indent 130.It Va net.dummymbuf.rules 131A string representing a single set of 132.Sx RULES 133shared among all 134.Nm 135hooks. 136.It Va net.dummymbuf.hits 137Number of times a rule has been applied. 138It is reset to zero upon writing. 139.El 140.Sh EXAMPLES 141As it was intended, 142.Nm 143can be found useful for firewall testing. 144A mbuf chain could be altered before it hits a firewall to test that the latter 145can handle a case respectively. 146Thus, it is important to have correct sequence of hooks. 147A test case should prepare and enable a firewall first to get its hooks linked. 148After, the 149.Xr pfilctl 8 150should be used to link 151.Nm 152hook(s) to put them in front of a firewall. 153.Pp 154The following links 155.Va dummymbuf:inet6 156hook for inbound and puts it in front of other hooks: 157.Bd -literal -offset indent 158pfilctl link -i dummymbuf:inet6 inet6 159.Ed 160.Pp 161And this does the same for outbound: 162.Bd -literal -offset indent 163pfilctl link -o -a dummymbuf:inet6 inet6 164.Ed 165.Pp 166For instance, we want to test a scenario in which the very first mbuf in a 167chain has zero m_len, to verify that a firewall can correctly read the 168packet data despite that. 169The following set of rules does it for inbound and outbound: 170.Bd -literal -offset indent 171sysctl net.dummymbuf.rules="inet6 in em0 pull-head 0; inet6 out em0 pull-head 0;" 172.Ed 173.Pp 174It is encouraged to verify 175.Va net.dummymbuf.hits 176sysctl counter along with other test assertions to make sure that 177.Nm 178really does its work and there is no false positive due to misconfiguration. 179It is a good idea to reset it before the action: 180.Bd -literal -offset indent 181sysctl net.dummymbuf.hits=0 182.Ed 183.Pp 184It is equally important to cleanup the things after the test case: 185.Bd -literal -offset indent 186pfilctl unlink -i dummymbuf:inet6 inet6 187pfilctl unlink -o dummymbuf:inet6 inet6 188sysctl net.dummymbuf.rules="" 189.Ed 190.Pp 191If a test case operates within a temporary vnet then explicit cleanup can be 192omitted, the 193.Nm 194facilities will vanish along with its vnet instance. 195.Sh DIAGNOSTICS 196.Bl -diag 197.It "dummymbuf: <filter match>: rule parsing failed: <the rule in question>" 198If everything looks fine then extra spaces removal may help due to the parser 199is kept very simple. 200.It "dummymbuf: <filter match>: mbuf operation failed: <the rule in question>" 201Incorrect operation argument has been found, mbuf allocation has failed, etc. 202.El 203.Sh SEE ALSO 204.Xr jail 2 , 205.Xr pfilctl 8 , 206.Xr mbuf 9 , 207.Xr pfil 9 , 208.Xr VNET 9 209.Sh AUTHORS 210The module and this manual page were written by 211.An Igor Ostapenko Aq Mt pm@igoro.pro . 212