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
 154 .Tn ASCII
 155 string argument, the hook name, and returns the
 156 corresponding
 157 .Vt "struct ng_tag_hookin"
 158 as shown above.
 159 .It Dv NGM_TAG_SET_HOOKOUT Pq Ic sethookout
 160 This command sets tags values which will be applied to outgoing
 161 packets.
 162 The following structure must be supplied as an argument:
 163 .Bd -literal -offset 4n
 164 struct ng_tag_hookout {
 165   char            thisHook[NG_HOOKSIZ];     /* name of hook */
 166   uint32_t        tag_cookie;               /* ABI/Module ID */
 167   uint16_t        tag_id;                   /* tag ID */
 168   uint16_t        tag_len;                  /* length of data */
 169   uint8_t         tag_data[0];              /* tag data */
 170 };
 171 .Ed
 172 .Pp
 173 The hook to be updated is specified in
 174 .Va thisHook .
 175 Other variables mean basically the same as in
 176 .Vt "struct ng_tag_hookin"
 177 shown above, except used for setting values in a new tag.
 178 .It Dv NGM_TAG_GET_HOOKOUT Pq Ic gethookout
 179 This command takes an
 180 .Tn ASCII
 181 string argument, the hook name, and returns the
 182 corresponding
 183 .Vt "struct ng_tag_hookout"
 184 as shown above.
 185 .It Dv NGM_TAG_GET_STATS Pq Ic getstats
 186 This command takes an
 187 .Tn ASCII
 188 string argument, the hook name, and returns the
 189 statistics associated with the hook as a
 190 .Vt "struct ng_tag_hookstat" .
 191 .It Dv NGM_TAG_CLR_STATS Pq Ic clrstats
 192 This command takes an
 193 .Tn ASCII
 194 string argument, the hook name, and clears the
 195 statistics associated with the hook.
 196 .It Dv NGM_TAG_GETCLR_STATS Pq Ic getclrstats
 197 This command is identical to
 198 .Dv NGM_TAG_GET_STATS ,
 199 except that the statistics are also atomically cleared.
 200 .El
 201 .Pp
 202 .Em Note:
 203 statistics counters as well as three statistics messages above work
 204 only if code was compiled with the
 205 .Dv NG_TAG_DEBUG
 206 option.
 207 The reason for this is that statistics is rarely used in practice,
 208 but still consumes CPU cycles for every packet.
 209 Moreover, it is even not accurate on SMP systems due to lack of
 210 synchronization between threads, as this is very expensive.
 211 .Sh SHUTDOWN
 212 This node shuts down upon receipt of a
 213 .Dv NGM_SHUTDOWN
 214 control message, or when all hooks have been disconnected.
 215 .Sh EXAMPLES
 216 It is possible to do a simple L7 filtering by using
 217 .Xr ipfw 8
 218 tags in conjunction with
 219 .Xr ng_bpf 4
 220 traffic analyzer.
 221 Example below explains how to filter DirectConnect P2P network data traffic,
 222 which cannot be done by usual means as it uses random ports.
 223 It is known that such data connection always contains a TCP packet with
 224 6-byte payload string "$Send|".
 225 So ipfw's
 226 .Cm netgraph
 227 action will be used to divert all TCP packets to an
 228 .Xr ng_bpf 4
 229 node which will check for the specified string and return non-matching
 230 packets to
 231 .Xr ipfw 8 .
 232 Matching packets are passed to
 233 .Xr ng_tag 4
 234 node, which will set a tag and pass them back to
 235 .Xr ng_bpf 4
 236 node on a hook programmed to accept all packets and pass them back to
 237 .Xr ipfw 8 .
 238 A script provided in
 239 .Xr ng_bpf 4
 240 manual page will be used for programming node.
 241 Note that packets diverted from
 242 .Xr ipfw 8
 243 to Netgraph have no link-level header, so offsets in
 244 .Xr tcpdump 1
 245 expressions must be altered accordingly.
 246 Thus, there will be expression
 247 .Dq Li "ether[40:2]=0x244c && ether[42:4]=0x6f636b20"
 248 on incoming hook and empty expression to match all packets from
 249 .Xr ng_tag 4 .
 250 .Pp
 251 So, this is
 252 .Xr ngctl 8
 253 script for nodes creating and naming for easier access:
 254 .Bd -literal -offset 4n
 255 /usr/sbin/ngctl -f- <<-SEQ
 256         mkpeer ipfw: bpf 41 ipfw
 257         name ipfw:41 dcbpf
 258         mkpeer dcbpf: tag matched th1
 259         name dcbpf:matched ngdc
 260 SEQ
 261 .Ed
 262 .Pp
 263 Now
 264 .Dq Li ngdc
 265 node (which is of type
 266 .Nm )
 267 must be programmed to echo all packets received on the
 268 .Dq Li th1
 269 hook back, with the
 270 .Xr ipfw 8
 271 tag 412 attached.
 272 .Dv MTAG_IPFW
 273 value for
 274 .Va tag_cookie
 275 was taken from file
 276 .In netinet/ip_fw.h
 277 and value for
 278 .Va tag_id
 279 is tag number (412), with zero tag length:
 280 .Bd -literal -offset 4n
 281 ngctl msg ngdc: sethookin { thisHook=\e"th1\e" ifNotMatch=\e"th1\e" }
 282 ngctl msg ngdc: sethookout { thisHook=\e"th1\e" \e
 283   tag_cookie=1148380143 \e
 284   tag_id=412 }
 285 .Ed
 286 .Pp
 287 Do not forget to program
 288 .Xr ng_bpf 4
 289 .Dq Li ipfw
 290 hook with the above expression (see
 291 .Xr ng_bpf 4
 292 for script doing this) and
 293 .Dq Li matched
 294 hook with an empty expression:
 295 .Bd -literal -offset 4n
 296 ngctl msg dcbpf: setprogram { thisHook=\e"matched\e" ifMatch=\e"ipfw\e" \e
 297   bpf_prog_len=1 bpf_prog=[ { code=6 k=8192 } ] }
 298 .Ed
 299 .Pp
 300 After finishing with
 301 .Xr netgraph 4
 302 nodes,
 303 .Xr ipfw 8
 304 rules must be added to enable packet flow:
 305 .Bd -literal -offset 4n
 306 ipfw add 100 netgraph 41 tcp from any to any iplen 46
 307 ipfw add 110 reset tcp from any to any tagged 412
 308 .Ed
 309 .Pp
 310 Note: one should ensure that packets are returned to ipfw after processing
 311 inside
 312 .Xr netgraph 4 ,
 313 by setting appropriate
 314 .Xr sysctl 8
 315 variable:
 316 .Bd -literal -offset 4n
 317 sysctl net.inet.ip.fw.one_pass=0
 318 .Ed
 319 .Sh SEE ALSO
 320 .Xr netgraph 4 ,
 321 .Xr ng_bpf 4 ,
 322 .Xr ng_ipfw 4 ,
 323 .Xr ipfw 8 ,
 324 .Xr ngctl 8 ,
 325 .Xr mbuf_tags 9
 326 .Sh HISTORY
 327 The
 328 .Nm
 329 node type was implemented in
 330 .Fx 6.2 .
 331 .Sh AUTHORS
 332 .An Vadim Goncharov Aq vadimnuclight@tpu.ru
 333 .Sh BUGS
 334 For manipulating any tags with data payload (that is, all tags with non-zero
 335 .Va tag_len )
 336 one should care about non-portable machine-dependent representation of
 337 tags on the low level as byte stream.
 338 Perhaps this should be done by another program rather than manually.