1 .\" Copyright (c) 2006 Vadim Goncharov <vadimnuclight@tpu.ru>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd "mbuf tags manipulating netgraph node type"
38 node type allows mbuf packet tags (see
40 to be examined, stripped or applied to data travelling through a
42 Mbuf tags are used in many parts of the
44 kernel network subsystem,
45 including the storage of VLAN tags as described in
47 Mandatory Access Control (MAC) labels as described in
49 IPsec policy information as described in
51 and packet filter tags used by
53 One should also consider useful setting or checking
55 tags, which are implemented as mbuf tags, too.
57 Each node allows an arbitrary number of connections to arbitrarily
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.
65 The list of incoming packet's tags is traversed to find a tag with
71 Upon match, if specified
75 of tag is checked to be identical to that specified in the hook structure.
76 Packets with matched tags are forwarded to
78 destination hook, or forwarded to
81 Either or both destination hooks can be an empty string, or may
82 not exist, in which case the packet is dropped.
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
90 values in the structure of the corresponding outgoing hook).
92 a tag can be stripped from incoming packet after match if
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).
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.
106 Data payload of packets passing through the node is completely
107 unchanged, all operations can affect tag list only.
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.
114 This node type supports the generic control messages, plus the following:
115 .Bl -tag -width indent
116 .It Dv NGM_TAG_SET_HOOKIN
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 */
133 The hook to be updated is specified in
135 Data bytes of tag corresponding to specified
144 Matching and non-matching incoming packets are delivered out the hooks named
151 flag is non-zero, then found tag is deleted from list of packet tags.
152 .It Dv NGM_TAG_GET_HOOKIN
153 This command takes an
155 string argument, the hook name, and returns the
157 .Vt "struct ng_tag_hookin"
159 .It Dv NGM_TAG_SET_HOOKOUT
160 This command sets tags values which will be applied to outgoing
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 */
173 The hook to be updated is specified in
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
179 This command takes an
181 string argument, the hook name, and returns the
183 .Vt "struct ng_tag_hookout"
185 .It Dv NGM_TAG_GET_STATS
186 This command takes an
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
192 This command takes an
194 string argument, the hook name, and clears the
195 statistics associated with the hook.
196 .It Dv NGM_TAG_GETCLR_STATS
197 This command is identical to
198 .Dv NGM_TAG_GET_STATS ,
199 except that the statistics are also atomically cleared.
203 statistics counters as well as three statistics messages above work
204 only if code was compiled with the
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.
212 This node shuts down upon receipt of a
214 control message, or when all hooks have been disconnected.
216 It is possible to do a simple L7 filtering by using
218 tags in conjunction with
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|".
227 action will be used to divert all TCP packets to an
229 node which will check for the specified string and return non-matching
232 Matching packets are passed to
234 node, which will set a tag and pass them back to
236 node on a hook programmed to accept all packets and pass them back to
240 manual page will be used for programming node.
241 Note that packets diverted from
243 to Netgraph have no link-level header, so offsets in
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
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
258 mkpeer dcbpf: tag matched th1
259 name dcbpf:matched ngdc
265 node (which is of type
267 must be programmed to echo all packets received on the
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
287 Don't forget to program
290 hook with the above expression (see
292 for script doing this) and
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 } ] }
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
310 Note: one should ensure that packets are returned to ipfw after processing
313 by setting appropriate
316 .Bd -literal -offset 4n
317 sysctl net.inet.ip.fw.one_pass=0
329 node type was implemented in
332 .An Vadim Goncharov Aq vadimnuclight@tpu.ru
334 For manipulating any tags with data payload (that is, all tags with non-zero
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.