share/man/man4/ng_tag.4

   1 .\" Copyright (c) 2006 Vadim Goncharov <vadimnuclight@tpu.ru>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd June 10, 2006
  28 .Dt NG_TAG 4
  29 .Os
  30 .Sh NAME
  31 .Nm ng_tag
  32 .Nd "mbuf tags manipulating netgraph node type"
  33 .Sh SYNOPSIS
  34 .In netgraph/ng_tag.h
  35 .Sh DESCRIPTION
  36 The
  37 .Nm tag
  38 node type allows mbuf packet tags (see
  39 .Xr mbuf_tags 9 )
  40 to be examined, stripped or applied to data travelling through a
  41 Netgraph network.
  42 Mbuf tags are used in many parts of the
  43 .Fx
  44 kernel network subsystem,
  45 including the storage of VLAN tags as described in
  46 .Xr vlan 4 ,
  47 Mandatory Access Control (MAC) labels as described in
  48 .Xr mac 9 ,
  49 IPsec policy information as described in
  50 .Xr ipsec 4 ,
  51 and packet filter tags used by
  52 .Xr pf 4 .
  53 One should also consider useful setting or checking
  54 .Xr ipfw 8
  55 tags, which are implemented as mbuf tags, too.
  56 .Pp
  57 Each node allows an arbitrary number of connections to arbitrarily
  58 named hooks.
  59 With each hook is associated a tag which will be searched in the list
  60 of all tags attached to a packet incoming to this hook, a destination hook
  61 for matching packets, a destination hook for non-matching packets,
  62 a tag which will be appended to data leaving node through this hook,
  63 and various statistics counters.
  64 .Pp
  65 The list of incoming packet's tags is traversed to find a tag with
  66 specified
  67 .Va type
  68 and
  69 .Va cookie
  70 values.
  71 Upon match, if specified
  72 .Va tag_len
  73 is non-zero,
  74 .Va tag_data
  75 of tag is checked to be identical to that specified in the hook structure.
  76 Packets with matched tags are forwarded to
  77 .Dq match
  78 destination hook, or forwarded to
  79 .Dq non-match
  80 hook otherwise.
  81 Either or both destination hooks can be an empty string, or may
  82 not exist, in which case the packet is dropped.
  83 .Pp
  84 Tag list of packets leaving the node is extended with a new tag
  85 specified in outgoing hook structure (it is possible to avoid appending
  86 a new tag to pass packet completely unchanged by specifying zero
  87 .Va type
  88 and
  89 .Va cookie
  90 values in the structure of the corresponding outgoing hook).
  91 Additionally,
  92 a tag can be stripped from incoming packet after match if
  93 .Va strip
  94 flag is set.
  95 This can be used for simple tag removal or tag replacement, if combined
  96 with tag addition on outgoing matching hook.
  97 Note that new tag is appended unconditionally, without checking if
  98 such a tag is already present in the list (it is up to user to check
  99 if this is a concern).
 100 .Pp
 101 New hooks are initially configured to drop all incoming packets
 102 (as all hook names are empty strings; zero values can be specified
 103 to forward all packets to non-matching hook),
 104 and to forward all outgoing packets without any tag appending.
 105 .Pp
 106 Data payload of packets passing through the node is completely
 107 unchanged, all operations can affect tag list only.
 108 .Sh HOOKS
 109 This node type supports any number of hooks having arbitrary names.
 110 In order to allow internal optimizations, user should never try to
 111 configure a hook with a structure pointing to hooks which do not exist yet.
 112 The safe way is to create all hooks first, then begin to configure them.
 113 .Sh CONTROL MESSAGES
 114 This node type supports the generic control messages, plus the following:
 115 .Bl -tag -width foo
 116 .It Dv NGM_TAG_SET_HOOKIN Pq Ic sethookin
 117 This command sets tag values which will be searched in the tag list of
 118 incoming packets on a hook.
 119 The following structure must be supplied as an argument:
 120 .Bd -literal -offset 4n
 121 struct ng_tag_hookin {
 122   char            thisHook[NG_HOOKSIZ];     /* name of hook */
 123   char            ifMatch[NG_HOOKSIZ];      /* match dest hook */
 124   char            ifNotMatch[NG_HOOKSIZ];   /* !match dest hook */
 125   uint8_t         strip;                    /* strip tag if found */
 126   uint32_t        tag_cookie;               /* ABI/Module ID */
 127   uint16_t        tag_id;                   /* tag ID */
 128   uint16_t        tag_len;                  /* length of data */
 129   uint8_t         tag_data[0];              /* tag data */
 130 };
 131 .Ed
 132 .Pp
 133 The hook to be updated is specified in
 134 .Va thisHook .
 135 Data bytes of tag corresponding to specified
 136 .Va tag_id
 137 (type) and
 138 .Va tag_cookie
 139 are placed in the
 140 .Va tag_data
 141 array; there must be
 142 .Va tag_len
 143 of them.
 144 Matching and non-matching incoming packets are delivered out the hooks named
 145 .Va ifMatch
 146 and
 147 .Va ifNotMatch ,
 148 respectively.
 149 If
 150 .Va strip
 151 flag is non-zero, then found tag is deleted from list of packet tags.
 152 .It Dv NGM_TAG_GET_HOOKIN Pq Ic gethookin
 153 This command takes an ASCII string argument, the hook name, and returns the
 154 corresponding
 155 .Vt "struct ng_tag_hookin"
 156 as shown above.
 157 .It Dv NGM_TAG_SET_HOOKOUT Pq Ic sethookout
 158 This command sets tags values which will be applied to outgoing
 159 packets.
 160 The following structure must be supplied as an argument:
 161 .Bd -literal -offset 4n
 162 struct ng_tag_hookout {
 163   char            thisHook[NG_HOOKSIZ];     /* name of hook */
 164   uint32_t        tag_cookie;               /* ABI/Module ID */
 165   uint16_t        tag_id;                   /* tag ID */
 166   uint16_t        tag_len;                  /* length of data */
 167   uint8_t         tag_data[0];              /* tag data */
 168 };
 169 .Ed
 170 .Pp
 171 The hook to be updated is specified in
 172 .Va thisHook .
 173 Other variables mean basically the same as in
 174 .Vt "struct ng_tag_hookin"
 175 shown above, except used for setting values in a new tag.
 176 .It Dv NGM_TAG_GET_HOOKOUT Pq Ic gethookout
 177 This command takes an ASCII string argument, the hook name, and returns the
 178 corresponding
 179 .Vt "struct ng_tag_hookout"
 180 as shown above.
 181 .It Dv NGM_TAG_GET_STATS Pq Ic getstats
 182 This command takes an ASCII string argument, the hook name, and returns the
 183 statistics associated with the hook as a
 184 .Vt "struct ng_tag_hookstat" .
 185 .It Dv NGM_TAG_CLR_STATS Pq Ic clrstats
 186 This command takes an ASCII string argument, the hook name, and clears the
 187 statistics associated with the hook.
 188 .It Dv NGM_TAG_GETCLR_STATS Pq Ic getclrstats
 189 This command is identical to
 190 .Dv NGM_TAG_GET_STATS ,
 191 except that the statistics are also atomically cleared.
 192 .El
 193 .Pp
 194 .Em Note :
 195 statistics counters as well as three statistics messages above work
 196 only if code was compiled with the
 197 .Dv NG_TAG_DEBUG
 198 option.
 199 The reason for this is that statistics is rarely used in practice,
 200 but still consumes CPU cycles for every packet.
 201 Moreover, it is even not accurate on SMP systems due to lack of
 202 synchronization between threads, as this is very expensive.
 203 .Sh SHUTDOWN
 204 This node shuts down upon receipt of a
 205 .Dv NGM_SHUTDOWN
 206 control message, or when all hooks have been disconnected.
 207 .Sh EXAMPLES
 208 It is possible to do a simple L7 filtering by using
 209 .Xr ipfw 8
 210 tags in conjunction with
 211 .Xr ng_bpf 4
 212 traffic analyzer.
 213 Example below explains how to filter DirectConnect P2P network data traffic,
 214 which cannot be done by usual means as it uses random ports.
 215 It is known that such data connection always contains a TCP packet with
 216 6-byte payload string "$Send|".
 217 So ipfw's
 218 .Cm netgraph
 219 action will be used to divert all TCP packets to an
 220 .Xr ng_bpf 4
 221 node which will check for the specified string and return non-matching
 222 packets to
 223 .Xr ipfw 8 .
 224 Matching packets are passed to
 225 .Nm
 226 node, which will set a tag and pass them back to
 227 .Xr ng_bpf 4
 228 node on a hook programmed to accept all packets and pass them back to
 229 .Xr ipfw 8 .
 230 A script provided in
 231 .Xr ng_bpf 4
 232 manual page will be used for programming node.
 233 Note that packets diverted from
 234 .Xr ipfw 8
 235 to Netgraph have no link-level header, so offsets in
 236 .Xr tcpdump 1
 237 expressions must be altered accordingly.
 238 Thus, there will be expression
 239 .Dq Li "ether[40:2]=0x244c && ether[42:4]=0x6f636b20"
 240 on incoming hook and empty expression to match all packets from
 241 .Nm .
 242 .Pp
 243 So, this is
 244 .Xr ngctl 8
 245 script for nodes creating and naming for easier access:
 246 .Bd -literal -offset 4n
 247 /usr/sbin/ngctl -f- <<-SEQ
 248         mkpeer ipfw: bpf 41 ipfw
 249         name ipfw:41 dcbpf
 250         mkpeer dcbpf: tag matched th1
 251         name dcbpf:matched ngdc
 252 SEQ
 253 .Ed
 254 .Pp
 255 Now
 256 .Dq Li ngdc
 257 node (which is of type
 258 .Nm )
 259 must be programmed to echo all packets received on the
 260 .Dq Li th1
 261 hook back, with the
 262 .Xr ipfw 8
 263 tag 412 attached.
 264 .Dv MTAG_IPFW
 265 value for
 266 .Va tag_cookie
 267 was taken from file
 268 .In netinet/ip_fw.h
 269 and value for
 270 .Va tag_id
 271 is tag number (412), with zero tag length:
 272 .Bd -literal -offset 4n
 273 ngctl msg ngdc: sethookin { thisHook=\e"th1\e" ifNotMatch=\e"th1\e" }
 274 ngctl msg ngdc: sethookout { thisHook=\e"th1\e" \e
 275   tag_cookie=1148380143 \e
 276   tag_id=412 }
 277 .Ed
 278 .Pp
 279 Do not forget to program
 280 .Xr ng_bpf 4
 281 .Dq Li ipfw
 282 hook with the above expression (see
 283 .Xr ng_bpf 4
 284 for script doing this) and
 285 .Dq Li matched
 286 hook with an empty expression:
 287 .Bd -literal -offset 4n
 288 ngctl msg dcbpf: setprogram { thisHook=\e"matched\e" ifMatch=\e"ipfw\e" \e
 289   bpf_prog_len=1 bpf_prog=[ { code=6 k=8192 } ] }
 290 .Ed
 291 .Pp
 292 After finishing with
 293 .Xr netgraph 4
 294 nodes,
 295 .Xr ipfw 8
 296 rules must be added to enable packet flow:
 297 .Bd -literal -offset 4n
 298 ipfw add 100 netgraph 41 tcp from any to any iplen 46
 299 ipfw add 110 reset tcp from any to any tagged 412
 300 .Ed
 301 .Pp
 302 Note: one should ensure that packets are returned to ipfw after processing
 303 inside
 304 .Xr netgraph 4 ,
 305 by setting appropriate
 306 .Xr sysctl 8
 307 variable:
 308 .Bd -literal -offset 4n
 309 sysctl net.inet.ip.fw.one_pass=0
 310 .Ed
 311 .Sh SEE ALSO
 312 .Xr netgraph 4 ,
 313 .Xr ng_bpf 4 ,
 314 .Xr ng_ipfw 4 ,
 315 .Xr ipfw 8 ,
 316 .Xr ngctl 8 ,
 317 .Xr mbuf_tags 9
 318 .Sh HISTORY
 319 The
 320 .Nm
 321 node type was implemented in
 322 .Fx 6.2 .
 323 .Sh AUTHORS
 324 .An Vadim Goncharov Aq Mt vadimnuclight@tpu.ru
 325 .Sh BUGS
 326 For manipulating any tags with data payload (that is, all tags with non-zero
 327 .Va tag_len )
 328 one should care about non-portable machine-dependent representation of
 329 tags on the low level as byte stream.
 330 Perhaps this should be done by another program rather than manually.