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, 0 insertions, 182 deletions
diff --git a/static/freebsd/man4/dummymbuf.4 3.html b/static/freebsd/man4/dummymbuf.4 3.html deleted file mode 100644 index 0ac85716..00000000 --- a/static/freebsd/man4/dummymbuf.4 3.html +++ /dev/null @@ -1,182 +0,0 @@ -<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> |