diff options
Diffstat (limited to 'static/freebsd/man4/dummymbuf.4 3.html')
| -rw-r--r-- | static/freebsd/man4/dummymbuf.4 3.html | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/static/freebsd/man4/dummymbuf.4 3.html b/static/freebsd/man4/dummymbuf.4 3.html new file mode 100644 index 00000000..0ac85716 --- /dev/null +++ b/static/freebsd/man4/dummymbuf.4 3.html @@ -0,0 +1,182 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DUMMYMBUF(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">DUMMYMBUF(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">dummymbuf</code> — <span class="Nd">mbuf + alteration pfil hooks</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp">To compile the driver into the kernel, place the following line in + the kernel configuration file:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">device dummymbuf</code></div> +<p class="Pp">Alternatively, to load the driver as a module at boot time, place + the following line in <a class="Xr">loader.conf(5)</a>:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>dummymbuf_load="YES"</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">This module is intended to test networking code in the face of + unusual mbuf layouts. The special <a class="Xr">pfil(9)</a> hooks are + provided for mbuf alteration and can be listed with + <a class="Xr">pfilctl(8)</a> as follows:</p> +<div class="Bd Pp Bd-indent Li"> +<pre> Hook Type + dummymbuf:ethernet Ethernet + dummymbuf:inet6 IPv6 + dummymbuf:inet IPv4</pre> +</div> +<p class="Pp">To activate a hook it must be linked to the respective + <a class="Xr">pfil(9)</a> head. <a class="Xr">pfilctl(8)</a> can be used for + the linking.</p> +<p class="Pp">Each time a hook is invoked it reads a single shared set of + <a class="Sx" href="#RULES">RULES</a> from + <var class="Va">net.dummymbuf.rules</var> sysctl. The rules are evaluated + sequentially and each matching rule performs the specified operation over + the mbuf.</p> +<p class="Pp">After every successfully applied operation the + <var class="Va">net.dummymbuf.hits</var> sysctl counter is increased.</p> +<p class="Pp">A hook returns an altered mbuf for further processing, but it + drops a packet if rules parsing or an operation fails. Also, the first mbuf + of the original chain may be changed.</p> +<p class="Pp">The module is <a class="Xr">VNET(9)</a> based, hence every + <a class="Xr">jail(2)</a> provides its own set of hooks and sysctl + variables.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RULES"><a class="permalink" href="#RULES">RULES</a></h1> +<p class="Pp">The set of rules is a semicolon separated list. An empty string is + treated as a parsing failure. A rule conceptually has two parts, filter and + operation, with the following syntax:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>{inet | inet6 | ethernet} {in | out} <ifname> <opname>[ <opargs>];</pre> +</div> +<section class="Ss"> +<h2 class="Ss" id="Filter"><a class="permalink" href="#Filter">Filter</a></h2> +<p class="Pp">The first word of a rule matches <a class="Xr">pfil(9)</a> type. + The second matches packet's direction, and the third matches the network + interface a packet is coming from.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Operation"><a class="permalink" href="#Operation">Operation</a></h2> +<p class="Pp">An operation may have arguments separated from its name by space. + The available operations are:</p> +<dl class="Bl-tag"> + <dt>pull-head <number-of-bytes></dt> + <dd>Unconditionally creates a brand new cluster-based mbuf and links it to be + the first mbuf of the original mbuf chain, with respective packet header + moving. After, the given number of bytes are pulled from the original mbuf + chain. + <p class="Pp">If it is asked to pull 0 bytes then the first mbuf of the + resulting chain will be left empty. Asking to pull more than + <code class="Dv">MCLBYTES</code> is treated as an operation failure. If + a mbuf chain has less data than asked then the entire packet is pulled + with tail mbuf(s) left empty.</p> + <p class="Pp">As a result, only the layout of a mbuf chain is altered, its + content logically is left intact.</p> + </dd> + <dt>enlarge <number-of-bytes></dt> + <dd>Unconditionally replace the mbuf with an mbuf of the specified size.</dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYSCTL_VARIABLES"><a class="permalink" href="#SYSCTL_VARIABLES">SYSCTL + VARIABLES</a></h1> +<p class="Pp">The following variables are available:</p> +<dl class="Bl-tag"> + <dt id="net.dummymbuf.rules"><var class="Va">net.dummymbuf.rules</var></dt> + <dd>A string representing a single set of + <a class="Sx" href="#RULES">RULES</a> shared among all + <code class="Nm">dummymbuf</code> hooks.</dd> + <dt id="net.dummymbuf.hits"><var class="Va">net.dummymbuf.hits</var></dt> + <dd>Number of times a rule has been applied. It is reset to zero upon + writing.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">As it was intended, <code class="Nm">dummymbuf</code> can be found + useful for firewall testing. A mbuf chain could be altered before it hits a + firewall to test that the latter can handle a case respectively. Thus, it is + important to have correct sequence of hooks. A test case should prepare and + enable a firewall first to get its hooks linked. After, the + <a class="Xr">pfilctl(8)</a> should be used to link + <code class="Nm">dummymbuf</code> hook(s) to put them in front of a + firewall.</p> +<p class="Pp">The following links <var class="Va">dummymbuf:inet6</var> hook for + inbound and puts it in front of other hooks:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>pfilctl link -i dummymbuf:inet6 inet6</pre> +</div> +<p class="Pp">And this does the same for outbound:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>pfilctl link -o -a dummymbuf:inet6 inet6</pre> +</div> +<p class="Pp">For instance, we want to test a scenario in which the very first + mbuf in a chain has zero m_len, to verify that a firewall can correctly read + the packet data despite that. The following set of rules does it for inbound + and outbound:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>sysctl net.dummymbuf.rules="inet6 in em0 pull-head 0; inet6 out em0 pull-head 0;"</pre> +</div> +<p class="Pp">It is encouraged to verify + <var class="Va">net.dummymbuf.hits</var> sysctl counter along with other + test assertions to make sure that <code class="Nm">dummymbuf</code> really + does its work and there is no false positive due to misconfiguration. It is + a good idea to reset it before the action:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>sysctl net.dummymbuf.hits=0</pre> +</div> +<p class="Pp">It is equally important to cleanup the things after the test + case:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>pfilctl unlink -i dummymbuf:inet6 inet6 +pfilctl unlink -o dummymbuf:inet6 inet6 +sysctl net.dummymbuf.rules=""</pre> +</div> +<p class="Pp">If a test case operates within a temporary vnet then explicit + cleanup can be omitted, the <code class="Nm">dummymbuf</code> facilities + will vanish along with its vnet instance.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<dl class="Bl-diag"> + <dt>dummymbuf: <filter match>: rule parsing failed: <the rule in + question></dt> + <dd>If everything looks fine then extra spaces removal may help due to the + parser is kept very simple.</dd> + <dt>dummymbuf: <filter match>: mbuf operation failed: <the rule in + question></dt> + <dd>Incorrect operation argument has been found, mbuf allocation has failed, + etc.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">jail(2)</a>, <a class="Xr">pfilctl(8)</a>, + <a class="Xr">mbuf(9)</a>, <a class="Xr">pfil(9)</a>, + <a class="Xr">VNET(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The module and this manual page were written by + <span class="An">Igor Ostapenko</span> + <<a class="Mt" href="mailto:pm@igoro.pro">pm@igoro.pro</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 6, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |