- Uniformly use .In for header file references.
[dragonfly.git] / share / man / man4 / ng_bpf.4
CommitLineData
984263bc
MD
1.\" Copyright (c) 1999 Whistle Communications, Inc.
2.\" All rights reserved.
3.\"
4.\" Subject to the following obligations and disclaimer of warranty, use and
5.\" redistribution of this software, in source or object code forms, with or
6.\" without modifications are expressly permitted by Whistle Communications;
7.\" provided, however, that:
8.\" 1. Any and all reproductions of the source or object code must include the
9.\" copyright notice above and the following disclaimer of warranties; and
10.\" 2. No rights are granted, in any manner or form, to use Whistle
11.\" Communications, Inc. trademarks, including the mark "WHISTLE
12.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as
13.\" such appears in the above copyright notice or in the software.
14.\"
15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
31.\" OF SUCH DAMAGE.
32.\"
33.\" Author: Archie Cobbs <archie@FreeBSD.org>
34.\"
35.\" $FreeBSD: src/share/man/man4/ng_bpf.4,v 1.17.2.1 2001/12/21 09:00:51 ru Exp $
44cb301e 36.\" $DragonFly: src/share/man/man4/ng_bpf.4,v 1.4 2006/05/26 19:39:39 swildner Exp $
984263bc
MD
37.\" $Whistle: ng_bpf.8,v 1.2 1999/12/03 01:57:12 archie Exp $
38.\"
39.Dd December 2, 1999
40.Dt NG_BPF 4
41.Os
42.Sh NAME
43.Nm ng_bpf
44.Nd Berkeley packet filter netgraph node type
45.Sh SYNOPSIS
46.In net/bpf.h
44cb301e 47.In netgraph/bpf/ng_bpf.h
984263bc
MD
48.Sh DESCRIPTION
49The
50.Nm bpf
51node type allows Berkeley Packet Filter (see
52.Xr bpf 4 )
53filters to be applied to data travelling through a Netgraph network.
54Each node allows an arbitrary number of connections to arbitrarily
55named hooks. With each hook is associated a
56.Xr bpf 4
57filter program which is applied to incoming data only, a destination hook
58for matching packets, a destination hook for non-matching packets,
59and various statistics counters.
60.Pp
61A
62.Xr bpf 4
63program returns an unsigned integer, which is normally interpreted as
64the length of the prefix of the packet to return. In the context of this
65node type, returning zero is considered a non-match, in which case the
66entire packet is delivered out the non-match destination hook.
67Returning a value greater than zero causes the packet to be truncated
68to that length and delivered out the match destination hook.
69Either or both destination hooks may be the empty string, or may
70not exist, in which case the packet is dropped.
71.Pp
72New hooks are initially configured to drop all packets.
73A new filter program may be installed using the
74.Dv NGM_BPF_SET_PROGRAM
75control message.
76.Sh HOOKS
77This node type supports any number of hooks having arbitrary names.
78.Sh CONTROL MESSAGES
79This node type supports the generic control messages, plus the following:
80.Bl -tag -width foo
81.It Dv NGM_BPF_SET_PROGRAM
82This command sets the filter program that will be applied to incoming
83data on a hook. The following structure must be supplied as an argument:
84.Bd -literal -offset 4n
85struct ng_bpf_hookprog {
86 char thisHook[NG_HOOKLEN+1]; /* name of hook */
87 char ifMatch[NG_HOOKLEN+1]; /* match dest hook */
88 char ifNotMatch[NG_HOOKLEN+1]; /* !match dest hook */
89 int32_t bpf_prog_len; /* #isns in program */
90 struct bpf_insn bpf_prog[0]; /* bpf program */
91};
92.Ed
93.Pp
94The hook to be updated is specified in
95.Dv thisHook .
96The BPF program is the sequence of instructions in the
97.Dv bpf_prog
98array; there must be
99.Dv bpf_prog_len
100of them.
101Matching and non-matching incoming packets are delivered out the hooks named
102.Dv ifMatch
103and
104.Dv ifNotMatch ,
105respectively. The program must be a valid
106.Xr bpf 4
107program or else
108.Er EINVAL
109is returned.
110.It Dv NGM_BPF_GET_PROGRAM
111This command takes an
112.Tn ASCII
113string argument, the hook name, and returns the
114corresponding
115.Dv "struct ng_bpf_hookprog"
116as shown above.
117.It Dv NGM_BPF_GET_STATS
118This command takes an
119.Tn ASCII
120string argument, the hook name, and returns the
121statistics associated with the hook as a
122.Dv "struct ng_bpf_hookstat" .
123.It Dv NGM_BPF_CLR_STATS
124This command takes an
125.Tn ASCII
126string argument, the hook name, and clears the
127statistics associated with the hook.
128.It Dv NGM_BPF_GETCLR_STATS
129This command is identical to
130.Dv NGM_BPF_GET_STATS ,
131except that the statistics are also atomically cleared.
132.El
133.Sh SHUTDOWN
134This node shuts down upon receipt of a
135.Dv NGM_SHUTDOWN
136control message, or when all hooks have been disconnected.
137.Sh EXAMPLES
138It is possible to configure a node from the command line, using
139.Xr tcpdump 1
140to generate raw BPF instructions which are then fed into an
141.Xr awk 1
142script to create the ASCII form of a
143.Dv NGM_BPF_SET_PROGRAM
144control message, as demonstrated here:
145.Bd -literal -offset 4n
146#!/bin/sh
147
148PATTERN="tcp dst port 80"
149NODEPATH="my_node:"
150INHOOK="hook1"
151MATCHHOOK="hook2"
152NOTMATCHHOOK="hook3"
153
154cat > /tmp/bpf.awk << xxENDxx
155{
156 if (!init) {
157 printf "bpf_prog_len=%d bpf_prog=[", \\$1;
158 init=1;
159 } else {
160 printf " { code=%d jt=%d jf=%d k=%d }", \\$1, \\$2, \\$3, \\$4;
161 }
162}
163END {
164 print " ]"
165}
166xxENDxx
167
168BPFPROG=`tcpdump -s 8192 -ddd ${PATTERN} | awk -f /tmp/bpf.awk`
169
170ngctl msg ${NODEPATH} setprogram { thisHook=\\"${INHOOK}\\" \\
171 ifMatch=\\"${MATCHHOOK}\\" \\
172 ifNotMatch=\\"${NOTMATCHHOOK}\\" \\
173 ${BPFPROG} } }
174.Ed
ac561d34
SW
175.Sh SEE ALSO
176.Xr bpf 4 ,
177.Xr netgraph 4 ,
178.Xr ngctl 8
179.Sh HISTORY
180The
181.Nm
182node type was implemented in
183.Fx 4.0 .
184.Sh AUTHORS
185.An Archie Cobbs Aq archie@FreeBSD.org
984263bc
MD
186.Sh BUGS
187When built as a loadable kernel module, this module includes the file
188.Pa net/bpf_filter.c .
189Although loading the module should fail if
190.Pa net/bpf_filter.c
191already exists in the kernel, currently it does not, and the duplicate
192copies of the file do not interfere.
193However, this may change in the future.