share/man/man4/ng_bpf.4

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