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$
  36 .\" $Whistle: ng_bpf.8,v 1.2 1999/12/03 01:57:12 archie Exp $
  37 .\"
  38 .Dd September 20, 2020
  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 sys/types.h
  46 .In net/bpf.h
  47 .In netgraph.h
  48 .In netgraph/ng_bpf.h
  49 .Sh DESCRIPTION
  50 The
  51 .Nm bpf
  52 node type allows Berkeley Packet Filter (see
  53 .Xr bpf 4 )
  54 filters to be applied to data travelling through a Netgraph network.
  55 Each node allows an arbitrary number of connections to arbitrarily
  56 named hooks.
  57 With each hook is associated a
  58 .Xr bpf 4
  59 filter program which is applied to incoming data only, a destination hook
  60 for matching packets, a destination hook for non-matching packets,
  61 and various statistics counters.
  62 .Pp
  63 A
  64 .Xr bpf 4
  65 program returns an unsigned integer, which is normally interpreted as
  66 the length of the prefix of the packet to return.
  67 In the context of this
  68 node type, returning zero is considered a non-match, in which case the
  69 entire packet is delivered out the non-match destination hook.
  70 Returning a value greater than zero causes the packet to be truncated
  71 to that length and delivered out the match destination hook.
  72 Either or both destination hooks may be the empty string, or may
  73 not exist, in which case the packet is dropped.
  74 .Pp
  75 New hooks are initially configured to drop all packets.
  76 A new filter program may be installed using the
  77 .Dv NGM_BPF_SET_PROGRAM
  78 control message.
  79 .Sh HOOKS
  80 This node type supports any number of hooks having arbitrary names.
  81 .Sh CONTROL MESSAGES
  82 This node type supports the generic control messages, plus the following:
  83 .Bl -tag -width foo
  84 .It Dv NGM_BPF_SET_PROGRAM Pq Ic setprogram
  85 This command sets the filter program that will be applied to incoming
  86 data on a hook.
  87 The following structure must be supplied as an argument:
  88 .Bd -literal -offset 4n
  89 struct ng_bpf_hookprog {
  90   char            thisHook[NG_HOOKSIZ];     /* name of hook */
  91   char            ifMatch[NG_HOOKSIZ];      /* match dest hook */
  92   char            ifNotMatch[NG_HOOKSIZ];   /* !match dest hook */
  93   int32_t         bpf_prog_len;             /* #insns in program */
  94   struct bpf_insn bpf_prog[];               /* bpf program */
  95 };
  96 .Ed
  97 .Pp
  98 The hook to be updated is specified in
  99 .Dv thisHook .
 100 The BPF program is the sequence of instructions in the
 101 .Dv bpf_prog
 102 array; there must be
 103 .Dv bpf_prog_len
 104 of them.
 105 Matching and non-matching incoming packets are delivered out the hooks named
 106 .Dv ifMatch
 107 and
 108 .Dv ifNotMatch ,
 109 respectively.
 110 The program must be a valid
 111 .Xr bpf 4
 112 program or else
 113 .Er EINVAL
 114 is returned.
 115 .It Dv NGM_BPF_GET_PROGRAM Pq Ic getprogram
 116 This command takes an ASCII
 117 string argument, the hook name, and returns the
 118 corresponding
 119 .Dv "struct ng_bpf_hookprog"
 120 as shown above.
 121 .It Dv NGM_BPF_GET_STATS Pq Ic getstats
 122 This command takes an ASCII
 123 string argument, the hook name, and returns the
 124 statistics associated with the hook as a
 125 .Dv "struct ng_bpf_hookstat" .
 126 .It Dv NGM_BPF_CLR_STATS Pq Ic clrstats
 127 This command takes an ASCII
 128 string argument, the hook name, and clears the
 129 statistics associated with the hook.
 130 .It Dv NGM_BPF_GETCLR_STATS Pq Ic getclrstats
 131 This command is identical to
 132 .Dv NGM_BPF_GET_STATS ,
 133 except that the statistics are also atomically cleared.
 134 .El
 135 .Sh SHUTDOWN
 136 This node shuts down upon receipt of a
 137 .Dv NGM_SHUTDOWN
 138 control message, or when all hooks have been disconnected.
 139 .Sh EXAMPLES
 140 It is possible to configure a node from the command line, using
 141 .Xr tcpdump 1
 142 to generate raw BPF instructions which are then transformed
 143 into the ASCII form of a
 144 .Dv NGM_BPF_SET_PROGRAM
 145 control message, as demonstrated here:
 146 .Bd -literal -offset 4n
 147 #!/bin/sh
 148
 149 PATTERN="tcp dst port 80"
 150 NODEPATH="my_node:"
 151 INHOOK="hook1"
 152 MATCHHOOK="hook2"
 153 NOTMATCHHOOK="hook3"
 154
 155 BPFPROG=$( tcpdump -s 8192 -p -ddd ${PATTERN} | \\
 156            ( read len ; \\
 157              echo -n "bpf_prog_len=$len " ; \\
 158              echo -n "bpf_prog=[" ; \\
 159              while read code jt jf k ; do \\
 160                  echo -n " { code=$code jt=$jt jf=$jf k=$k }" ; \\
 161              done ; \\
 162              echo " ]" ) )
 163
 164 ngctl msg ${NODEPATH} setprogram { thisHook=\\"${INHOOK}\\" \\
 165   ifMatch=\\"${MATCHHOOK}\\" \\
 166   ifNotMatch=\\"${NOTMATCHHOOK}\\" \\
 167   ${BPFPROG} }
 168 .Ed
 169 .Pp
 170 Based on the previous example, it is possible to prevent a jail (or a VM)
 171 from spoofing by allowing only traffic that has the expected ethernet and
 172 IP addresses:
 173 .Bd -literal -offset 4n
 174 #!/bin/sh
 175
 176 NODEPATH="my_node:"
 177 JAIL_MAC="0a:00:de:ad:be:ef"
 178 JAIL_IP="128.66.1.42"
 179 JAIL_HOOK="jail"
 180 HOST_HOOK="host"
 181 DEBUG_HOOK="nomatch"
 182
 183 bpf_prog() {
 184     local PATTERN=$1
 185
 186     tcpdump -s 8192 -p -ddd ${PATTERN} | (
 187         read len
 188         echo -n "bpf_prog_len=$len "
 189         echo -n "bpf_prog=["
 190         while read code jt jf k ; do
 191             echo -n " { code=$code jt=$jt jf=$jf k=$k }"
 192         done
 193         echo " ]"
 194     )
 195 }
 196
 197 # Prevent jail from spoofing (filter packets coming from jail)
 198 ngctl msg ${NODEPATH} setprogram {                        \\
 199     thisHook=\\"${JAIL_HOOK}\\"                             \\
 200     ifMatch=\\"${HOST_HOOK}\\"                              \\
 201     ifNotMatch=\\"${DEBUG_HOOK}\\"                          \\
 202     $(bpf_prog "ether src ${JAIL_MAC} && src ${JAIL_IP}") \\
 203 }
 204
 205 # Prevent jail from receiving spoofed packets (filter packets
 206 # coming from host)
 207 ngctl msg ${NODEPATH} setprogram {                        \\
 208     thisHook=\\"${HOST_HOOK}\\"                             \\
 209     ifMatch=\\"${JAIL_HOOK}\\"                              \\
 210     ifNotMatch=\\"${DEBUG_HOOK}\\"                          \\
 211     $(bpf_prog "ether dst ${JAIL_MAC} && dst ${JAIL_IP}") \\
 212 }
 213 .Ed
 214 .Sh SEE ALSO
 215 .Xr bpf 4 ,
 216 .Xr netgraph 4 ,
 217 .Xr ngctl 8
 218 .Sh HISTORY
 219 The
 220 .Nm
 221 node type was implemented in
 222 .Fx 4.0 .
 223 .Sh AUTHORS
 224 .An Archie Cobbs Aq Mt archie@FreeBSD.org
 225 .Sh BUGS
 226 When built as a loadable kernel module, this module includes the file
 227 .Pa net/bpf_filter.c .
 228 Although loading the module should fail if
 229 .Pa net/bpf_filter.c
 230 already exists in the kernel, currently it does not, and the duplicate
 231 copies of the file do not interfere.
 232 However, this may change in the future.