diff options
Diffstat (limited to 'static/freebsd/man4/ng_bpf.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ng_bpf.4 3.html | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/static/freebsd/man4/ng_bpf.4 3.html b/static/freebsd/man4/ng_bpf.4 3.html new file mode 100644 index 00000000..d9e08f5d --- /dev/null +++ b/static/freebsd/man4/ng_bpf.4 3.html @@ -0,0 +1,211 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NG_BPF(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">NG_BPF(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">ng_bpf</code> — <span class="Nd">Berkeley + packet filter netgraph node type</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">sys/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">net/bpf.h</a>></code> + <br/> + <code class="In">#include <<a class="In">netgraph.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">netgraph/ng_bpf.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">bpf</code> node type allows Berkeley Packet + Filter (see <a class="Xr">bpf(4)</a>) filters to be applied to data + travelling through a Netgraph network. Each node allows an arbitrary number + of connections to arbitrarily named hooks. With each hook is associated a + <a class="Xr">bpf(4)</a> filter program which is applied to incoming data + only, a destination hook for matching packets, a destination hook for + non-matching packets, and various statistics counters.</p> +<p class="Pp">A <a class="Xr">bpf(4)</a> program returns an unsigned integer, + which is normally interpreted as the length of the prefix of the packet to + return. In the context of this node type, returning zero is considered a + non-match, in which case the entire packet is delivered out the non-match + destination hook. Returning a value greater than zero causes the packet to + be truncated to that length and delivered out the match destination hook. + Either or both destination hooks may be the empty string, or may not exist, + in which case the packet is dropped.</p> +<p class="Pp">New hooks are initially configured to drop all packets. A new + filter program may be installed using the + <code class="Dv">NGM_BPF_SET_PROGRAM</code> control message.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HOOKS"><a class="permalink" href="#HOOKS">HOOKS</a></h1> +<p class="Pp">This node type supports any number of hooks having arbitrary + names.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CONTROL_MESSAGES"><a class="permalink" href="#CONTROL_MESSAGES">CONTROL + MESSAGES</a></h1> +<p class="Pp">This node type supports the generic control messages, plus the + following:</p> +<dl class="Bl-tag"> + <dt id="NGM_BPF_SET_PROGRAM"><a class="permalink" href="#NGM_BPF_SET_PROGRAM"><code class="Dv">NGM_BPF_SET_PROGRAM</code></a> + (<code class="Ic">setprogram</code>)</dt> + <dd>This command sets the filter program that will be applied to incoming data + on a hook. The following structure must be supplied as an argument: + <div class="Bd Pp Bd-indent Li"> + <pre>struct ng_bpf_hookprog { + char thisHook[NG_HOOKSIZ]; /* name of hook */ + char ifMatch[NG_HOOKSIZ]; /* match dest hook */ + char ifNotMatch[NG_HOOKSIZ]; /* !match dest hook */ + int32_t bpf_prog_len; /* #insns in program */ + struct bpf_insn bpf_prog[]; /* bpf program */ +};</pre> + </div> + <p class="Pp">The hook to be updated is specified in + <code class="Dv">thisHook</code>. The BPF program is the sequence of + instructions in the <code class="Dv">bpf_prog</code> array; there must + be <code class="Dv">bpf_prog_len</code> of them. Matching and + non-matching incoming packets are delivered out the hooks named + <code class="Dv">ifMatch</code> and <code class="Dv">ifNotMatch</code>, + respectively. The program must be a valid <a class="Xr">bpf(4)</a> + program or else <code class="Er">EINVAL</code> is returned.</p> + </dd> + <dt id="NGM_BPF_GET_PROGRAM"><a class="permalink" href="#NGM_BPF_GET_PROGRAM"><code class="Dv">NGM_BPF_GET_PROGRAM</code></a> + (<code class="Ic">getprogram</code>)</dt> + <dd>This command takes an ASCII string argument, the hook name, and returns + the corresponding <code class="Dv">struct ng_bpf_hookprog</code> as shown + above.</dd> + <dt id="NGM_BPF_GET_STATS"><a class="permalink" href="#NGM_BPF_GET_STATS"><code class="Dv">NGM_BPF_GET_STATS</code></a> + (<code class="Ic">getstats</code>)</dt> + <dd>This command takes an ASCII string argument, the hook name, and returns + the statistics associated with the hook as a <code class="Dv">struct + ng_bpf_hookstat</code>.</dd> + <dt id="NGM_BPF_CLR_STATS"><a class="permalink" href="#NGM_BPF_CLR_STATS"><code class="Dv">NGM_BPF_CLR_STATS</code></a> + (<code class="Ic">clrstats</code>)</dt> + <dd>This command takes an ASCII string argument, the hook name, and clears the + statistics associated with the hook.</dd> + <dt id="NGM_BPF_GETCLR_STATS"><a class="permalink" href="#NGM_BPF_GETCLR_STATS"><code class="Dv">NGM_BPF_GETCLR_STATS</code></a> + (<code class="Ic">getclrstats</code>)</dt> + <dd>This command is identical to <code class="Dv">NGM_BPF_GET_STATS</code>, + except that the statistics are also atomically cleared.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SHUTDOWN"><a class="permalink" href="#SHUTDOWN">SHUTDOWN</a></h1> +<p class="Pp">This node shuts down upon receipt of a + <code class="Dv">NGM_SHUTDOWN</code> control message, or when all hooks have + been disconnected.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">It is possible to configure a node from the command line, using + <a class="Xr">tcpdump(1)</a> to generate raw BPF instructions which are then + transformed into the ASCII form of a + <code class="Dv">NGM_BPF_SET_PROGRAM</code> control message, as demonstrated + here:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>#!/bin/sh + +PATTERN="tcp dst port 80" +NODEPATH="my_node:" +INHOOK="hook1" +MATCHHOOK="hook2" +NOTMATCHHOOK="hook3" + +BPFPROG=$( tcpdump -s 8192 -p -ddd ${PATTERN} | \ + ( read len ; \ + echo -n "bpf_prog_len=$len " ; \ + echo -n "bpf_prog=[" ; \ + while read code jt jf k ; do \ + echo -n " { code=$code jt=$jt jf=$jf k=$k }" ; \ + done ; \ + echo " ]" ) ) + +ngctl msg ${NODEPATH} setprogram { thisHook=\"${INHOOK}\" \ + ifMatch=\"${MATCHHOOK}\" \ + ifNotMatch=\"${NOTMATCHHOOK}\" \ + ${BPFPROG} }</pre> +</div> +<p class="Pp">Based on the previous example, it is possible to prevent a jail + (or a VM) from spoofing by allowing only traffic that has the expected + ethernet and IP addresses:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>#!/bin/sh + +NODEPATH="my_node:" +JAIL_MAC="0a:00:de:ad:be:ef" +JAIL_IP="128.66.1.42" +JAIL_HOOK="jail" +HOST_HOOK="host" +DEBUG_HOOK="nomatch" + +bpf_prog() { + local PATTERN=$1 + + tcpdump -s 8192 -p -ddd ${PATTERN} | ( + read len + echo -n "bpf_prog_len=$len " + echo -n "bpf_prog=[" + while read code jt jf k ; do + echo -n " { code=$code jt=$jt jf=$jf k=$k }" + done + echo " ]" + ) +} + +# Prevent jail from spoofing (filter packets coming from jail) +ngctl msg ${NODEPATH} setprogram { \ + thisHook=\"${JAIL_HOOK}\" \ + ifMatch=\"${HOST_HOOK}\" \ + ifNotMatch=\"${DEBUG_HOOK}\" \ + $(bpf_prog "ether src ${JAIL_MAC} && src ${JAIL_IP}") \ +} + +# Prevent jail from receiving spoofed packets (filter packets +# coming from host) +ngctl msg ${NODEPATH} setprogram { \ + thisHook=\"${HOST_HOOK}\" \ + ifMatch=\"${JAIL_HOOK}\" \ + ifNotMatch=\"${DEBUG_HOOK}\" \ + $(bpf_prog "ether dst ${JAIL_MAC} && dst ${JAIL_IP}") \ +}</pre> +</div> +</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">bpf(4)</a>, <a class="Xr">netgraph(4)</a>, + <a class="Xr">ngctl(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">ng_bpf</code> node type was implemented in + <span class="Ux">FreeBSD 4.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Archie Cobbs</span> + <<a class="Mt" href="mailto:archie@FreeBSD.org">archie@FreeBSD.org</a>></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">When built as a loadable kernel module, this module includes the + file <span class="Pa">net/bpf_filter.c</span>. Although loading the module + should fail if <span class="Pa">net/bpf_filter.c</span> already exists in + the kernel, currently it does not, and the duplicate copies of the file do + not interfere. However, this may change in the future.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 20, 2020</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |