1 .\" Copyright (c) 2010 Maxim Ignatenko <gelraen.ua@gmail.com>
2 .\" Copyright (c) 2010 Vadim Goncharov <vadimnuclight@tpu.ru>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd "trivial mbuf data modifying netgraph node type"
35 .In netgraph/ng_patch.h
39 node performs data modification of packets passing through it.
40 Modifications are restricted to a subset of C language operations
41 on unsigned integers of 8, 16, 32 or 64 bit size.
42 These are: set to new value (=), addition (+=), subtraction (-=),
43 multiplication (*=), division (/=), negation (= -),
44 bitwise AND (&=), bitwise OR (|=), bitwise eXclusive OR (^=),
45 shift left (<<=), shift right (>>=).
46 A negation operation is the one exception: integer is treated as signed
47 and second operand (the
50 There may be several modification operations, they are all applied
51 to a packet sequentially in order they were specified by user.
52 Data payload of packet is viewed as array of bytes, with zero offset
53 corresponding to the very first byte of packet headers, and
57 are taken as a single integer in network byte order.
59 This node type has two hooks:
60 .Bl -tag -width ".Va out"
62 Packets received on this hook are modified according to rules specified
63 in config and then forwarded to
65 hook, if it exists and connected.
66 Otherwise they are reflected back to the
70 Packets received on this hook are forwarded to
72 hook without any changes.
75 This node type supports the generic control messages, plus the following:
77 .It Dv NGM_PATCH_SETCONFIG Pq Ic setconfig
78 This command sets the sequence of modify operations
79 that will be applied to incoming data on a hook.
81 .Vt "struct ng_patch_config"
82 must be supplied as an argument:
83 .Bd -literal -offset 4n
87 uint16_t length; /* 1,2,4 or 8 bytes */
91 #define NG_PATCH_MODE_SET 1
92 #define NG_PATCH_MODE_ADD 2
93 #define NG_PATCH_MODE_SUB 3
94 #define NG_PATCH_MODE_MUL 4
95 #define NG_PATCH_MODE_DIV 5
96 #define NG_PATCH_MODE_NEG 6
97 #define NG_PATCH_MODE_AND 7
98 #define NG_PATCH_MODE_OR 8
99 #define NG_PATCH_MODE_XOR 9
100 #define NG_PATCH_MODE_SHL 10
101 #define NG_PATCH_MODE_SHR 11
103 struct ng_patch_config {
106 struct ng_patch_op ops[];
112 can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_SCTP and CSUM_UDP
113 (other values are ignored) for instructing the IP stack to recalculate the
114 corresponding checksum before transmitting packet on output interface.
117 node does not do any checksum correction by itself.
118 .It Dv NGM_PATCH_GETCONFIG Pq Ic getconfig
119 This control message obtains current set of modify operations,
121 .Vt "struct ng_patch_config" .
122 .It Dv NGM_PATCH_GET_STATS Pq Ic getstats
123 Returns node statistics as a
124 .Vt "struct ng_patch_stats" .
125 .It Dv NGM_PATCH_CLR_STATS Pq Ic clrstats
126 Clear node statistics.
127 .It Dv NGM_PATCH_GETCLR_STATS Pq Ic getclrstats
128 This command is identical to
129 .Dv NGM_PATCH_GET_STATS ,
130 except that the statistics are also atomically cleared.
133 This node shuts down upon receipt of a
135 control message, or when all hooks have been disconnected.
139 node allows to modify TTL and TOS/DSCP fields in IP packets.
140 Suppose you have two adjacent simplex links to remote network
141 (e.g.\& satellite), so that the packets expiring in between
142 will generate unwanted ICMP-replies which have to go forth, not back.
143 Thus you need to raise TTL of every packet entering link by 2
144 to ensure the TTL will not reach zero there.
149 action to inject packets going to other end of simplex link by the
153 .Bd -literal -offset 4n
154 /usr/sbin/ngctl -f- <<-SEQ
155 mkpeer ipfw: patch 200 in
156 name ipfw:200 ttl_add
157 msg ttl_add: setconfig { count=1 csum_flags=1 ops=[ \e
158 { mode=2 value=3 length=1 offset=8 } ] }
160 /sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net
167 configured to add (mode
168 .Dv NG_PATCH_MODE_ADD )
171 of 3 to a one-byte TTL field, which is 9th byte of IP packet header.
173 Another example would be two consecutive modifications of packet TOS
174 field: say, you need to clear the
180 .Bd -literal -offset 4n
181 /usr/sbin/ngctl -f- <<-SEQ
182 mkpeer ipfw: patch 300 in
183 name ipfw:300 tos_chg
184 msg tos_chg: setconfig { count=2 csum_flags=1 ops=[ \e
185 { mode=7 value=0xf7 length=1 offset=1 } \e
186 { mode=8 value=0x02 length=1 offset=1 } ] }
188 /sbin/ipfw add 160 netgraph 300 ip from any to any not dst-port 80
192 .Dv NG_PATCH_MODE_AND
193 clearing the fourth bit and then
195 setting the third bit.
199 field indicates that IP checksum (but not TCP or UDP checksum) should be
200 recalculated before transmit.
202 Note: one should ensure that packets are returned to ipfw after processing
205 by setting appropriate
208 .Bd -literal -offset 4n
209 sysctl net.inet.ip.fw.one_pass=0
218 node type was implemented in
221 .An "Maxim Ignatenko" Aq gelraen.ua@gmail.com .
222 This manual page was written by
223 .An "Vadim Goncharov" Aq vadimnuclight@tpu.ru .
225 Node blindly tries to apply every patching operation to each packet
226 (except those which offset if greater than length of the packet),
227 so be sure that you supply only the right packets to it (e.g. changing
228 bytes in the ARP packets meant to be in IP header could corrupt
229 them and make your machine unreachable from the network).
233 Output path of the IP stack assumes correct fields and lengths in the
234 packets - changing them by mistake to incorrect values can cause
235 unpredictable results including kernel panics.