xref: /freebsd/share/man/man4/ng_bpf.4 (revision ae83180158c4c937f170e31eff311b18c0286a93)
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$
36.\" $Whistle: ng_bpf.8,v 1.2 1999/12/03 01:57:12 archie Exp $
37.\"
38.Dd December 2, 1999
39.Dt NG_BPF 4
40.Os
41.Sh NAME
42.Nm ng_bpf
43.Nd Berkeley packet filter netgraph node type
44.Sh SYNOPSIS
45.In net/bpf.h
46.In netgraph/ng_bpf.h
47.Sh DESCRIPTION
48The
49.Nm bpf
50node type allows Berkeley Packet Filter (see
51.Xr bpf 4 )
52filters to be applied to data travelling through a Netgraph network.
53Each node allows an arbitrary number of connections to arbitrarily
54named hooks.  With each hook is associated a
55.Xr bpf 4
56filter program which is applied to incoming data only, a destination hook
57for matching packets, a destination hook for non-matching packets,
58and various statistics counters.
59.Pp
60A
61.Xr bpf 4
62program returns an unsigned integer, which is normally interpreted as
63the length of the prefix of the packet to return.  In the context of this
64node type, returning zero is considered a non-match, in which case the
65entire packet is delivered out the non-match destination hook.
66Returning a value greater than zero causes the packet to be truncated
67to that length and delivered out the match destination hook.
68Either or both destination hooks may be the empty string, or may
69not exist, in which case the packet is dropped.
70.Pp
71New hooks are initially configured to drop all packets.
72A new filter program may be installed using the
73.Dv NGM_BPF_SET_PROGRAM
74control message.
75.Sh HOOKS
76This node type supports any number of hooks having arbitrary names.
77.Sh CONTROL MESSAGES
78This node type supports the generic control messages, plus the following:
79.Bl -tag -width foo
80.It Dv NGM_BPF_SET_PROGRAM
81This command sets the filter program that will be applied to incoming
82data on a hook.  The following structure must be supplied as an argument:
83.Bd -literal -offset 4n
84struct ng_bpf_hookprog {
85  char            thisHook[NG_HOOKLEN+1];   /* name of hook */
86  char            ifMatch[NG_HOOKLEN+1];    /* match dest hook */
87  char            ifNotMatch[NG_HOOKLEN+1]; /* !match dest hook */
88  int32_t         bpf_prog_len;             /* #isns in program */
89  struct bpf_insn bpf_prog[0];              /* bpf program */
90};
91.Ed
92.Pp
93The hook to be updated is specified in
94.Dv thisHook .
95The BPF program is the sequence of instructions in the
96.Dv bpf_prog
97array; there must be
98.Dv bpf_prog_len
99of them.
100Matching and non-matching incoming packets are delivered out the hooks named
101.Dv ifMatch
102and
103.Dv ifNotMatch ,
104respectively.  The program must be a valid
105.Xr bpf 4
106program or else
107.Er EINVAL
108is returned.
109.It Dv NGM_BPF_GET_PROGRAM
110This command takes an
111.Tn ASCII
112string argument, the hook name, and returns the
113corresponding
114.Dv "struct ng_bpf_hookprog"
115as shown above.
116.It Dv NGM_BPF_GET_STATS
117This command takes an
118.Tn ASCII
119string argument, the hook name, and returns the
120statistics associated with the hook as a
121.Dv "struct ng_bpf_hookstat" .
122.It Dv NGM_BPF_CLR_STATS
123This command takes an
124.Tn ASCII
125string argument, the hook name, and clears the
126statistics associated with the hook.
127.It Dv NGM_BPF_GETCLR_STATS
128This command is identical to
129.Dv NGM_BPF_GET_STATS ,
130except that the statistics are also atomically cleared.
131.El
132.Sh SHUTDOWN
133This node shuts down upon receipt of a
134.Dv NGM_SHUTDOWN
135control message, or when all hooks have been disconnected.
136.Sh EXAMPLES
137It is possible to configure a node from the command line, using
138.Xr tcpdump 1
139to generate raw BPF instructions which are then fed into an
140.Xr awk 1
141script to create the ASCII form of a
142.Dv NGM_BPF_SET_PROGRAM
143control message, as demonstrated here:
144.Bd -literal -offset 4n
145#!/bin/sh
146
147PATTERN="tcp dst port 80"
148NODEPATH="my_node:"
149INHOOK="hook1"
150MATCHHOOK="hook2"
151NOTMATCHHOOK="hook3"
152
153cat > /tmp/bpf.awk << xxENDxx
154{
155  if (!init) {
156    printf "bpf_prog_len=%d bpf_prog=[", \\$1;
157    init=1;
158  } else {
159    printf " { code=%d jt=%d jf=%d k=%d }", \\$1, \\$2, \\$3, \\$4;
160  }
161}
162END {
163  print " ]"
164}
165xxENDxx
166
167BPFPROG=`tcpdump -s 8192 -ddd ${PATTERN} | awk -f /tmp/bpf.awk`
168
169ngctl msg ${NODEPATH} setprogram { thisHook=\\"${INHOOK}\\" \\
170  ifMatch=\\"${MATCHHOOK}\\" \\
171  ifNotMatch=\\"${NOTMATCHHOOK}\\" \\
172  ${BPFPROG} } }
173.Ed
174.Sh BUGS
175When built as a loadable kernel module, this module includes the file
176.Pa net/bpf_filter.c .
177Although loading the module should fail if
178.Pa net/bpf_filter.c
179already exists in the kernel, currently it does not, and the duplicate
180copies of the file do not interfere.
181However, this may change in the future.
182.Sh HISTORY
183The
184.Nm
185node type was implemented in
186.Fx 4.0 .
187.Sh SEE ALSO
188.Xr bpf 4 ,
189.Xr netgraph 4 ,
190.Xr ngctl 8
191.Sh AUTHORS
192.An Archie Cobbs Aq archie@FreeBSD.org
193