]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man4/ng_patch.4
disk(9): Fix a few mandoc related errors
[FreeBSD/FreeBSD.git] / share / man / man4 / ng_patch.4
1 .\" Copyright (c) 2010 Maxim Ignatenko <gelraen.ua@gmail.com>
2 .\" Copyright (c) 2010 Vadim Goncharov <vadimnuclight@tpu.ru>
3 .\" Copyright (c) 2015 Dmitry Vagin <daemon.hammer@ya.ru>
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\"
27 .\" $FreeBSD$
28 .\"
29 .Dd November 17, 2015
30 .Dt NG_PATCH 4
31 .Os
32 .Sh NAME
33 .Nm ng_patch
34 .Nd "trivial mbuf data modifying netgraph node type"
35 .Sh SYNOPSIS
36 .In netgraph/ng_patch.h
37 .Sh DESCRIPTION
38 The
39 .Nm patch
40 node performs data modification of packets passing through it.
41 Modifications are restricted to a subset of C language operations
42 on unsigned integers of 8, 16, 32 or 64 bit size.
43 These are: set to new value (=), addition (+=), subtraction (-=),
44 multiplication (*=), division (/=), negation (= -),
45 bitwise AND (&=), bitwise OR (|=), bitwise eXclusive OR (^=),
46 shift left (<<=), shift right (>>=).
47 A negation operation is the one exception: integer is treated as signed
48 and second operand (the
49 .Va value )
50 is not used.
51 If there is more than one modification operation, they are applied
52 to packets sequentially in the order they were specified by the user.
53 The data payload of a packet is viewed as an array of bytes, with a zero offset
54 corresponding to the very first byte of packet headers, and the
55 .Va length
56 bytes beginning from
57 .Va offset
58 as a single integer in network byte order.
59 An additional offset can be optionally
60 requested at configuration time to account for packet type.
61 .Sh HOOKS
62 This node type has two hooks:
63 .Bl -tag -width ".Va out"
64 .It Va in
65 Packets received on this hook are modified according to rules specified
66 in the configuration and then forwarded to the
67 .Ar out
68 hook, if it exists.
69 Otherwise they are reflected back to the
70 .Ar in
71 hook.
72 .It Va out
73 Packets received on this hook are forwarded to the
74 .Ar in
75 hook without any changes.
76 .El
77 .Sh CONTROL MESSAGES
78 This node type supports the generic control messages, plus the following:
79 .Bl -tag -width foo
80 .It Dv NGM_PATCH_SETDLT Pq Ic setdlt
81 Sets the data link type on the
82 .Va in
83 hook (to help calculate relative offset). Currently, supported types are
84 .Cm DLT_RAW
85 (raw IP datagrams , no offset applied, the default) and
86 .Cm DLT_EN10MB
87 (Ethernet). DLT_ definitions can be found in
88 .In net/bpf.h .
89 If you want to work on the link layer header you must use no additional offset by specifying
90 .Cm DLT_RAW .
91 If
92 .Cm EN10MB
93 is specified, then the optional additional offset will take into account the Ethernet header and a QinQ header if present.
94 .It Dv NGM_PATCH_GETDLT Pq Ic getdlt
95 This control message returns the data link type of the
96 .Va in
97 hook.
98 .It Dv NGM_PATCH_SETCONFIG Pq Ic setconfig
99 This command sets the sequence of modify operations
100 that will be applied to incoming data on a hook.
101 The following
102 .Vt "struct ng_patch_config"
103 must be supplied as an argument:
104 .Bd -literal -offset 4n
105 struct ng_patch_op {
106         uint32_t        offset;
107         uint16_t        length; /* 1,2,4 or 8 bytes */
108         uint16_t        mode;
109         uint64_t        value;
110 };
111 /* Patching modes */
112 #define NG_PATCH_MODE_SET       1
113 #define NG_PATCH_MODE_ADD       2
114 #define NG_PATCH_MODE_SUB       3
115 #define NG_PATCH_MODE_MUL       4
116 #define NG_PATCH_MODE_DIV       5
117 #define NG_PATCH_MODE_NEG       6
118 #define NG_PATCH_MODE_AND       7
119 #define NG_PATCH_MODE_OR        8
120 #define NG_PATCH_MODE_XOR       9
121 #define NG_PATCH_MODE_SHL       10
122 #define NG_PATCH_MODE_SHR       11
123
124 struct ng_patch_config {
125         uint32_t        count;
126         uint32_t        csum_flags;
127         uint32_t        relative_offset;
128         struct ng_patch_op ops[];
129 };
130 .Ed
131 .Pp
132 The
133 .Va csum_flags
134 can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_SCTP and CSUM_UDP
135 (other values are ignored) for instructing the IP stack to recalculate the
136 corresponding checksum before transmitting packet on output interface.
137 The
138 .Nm
139 node does not do any checksum correction by itself.
140 .It Dv NGM_PATCH_GETCONFIG Pq Ic getconfig
141 This control message returns the current set of modify operations,
142 in the form of a
143 .Vt "struct ng_patch_config" .
144 .It Dv NGM_PATCH_GET_STATS Pq Ic getstats
145 Returns the node's statistics as a
146 .Vt "struct ng_patch_stats" .
147 .It Dv NGM_PATCH_CLR_STATS Pq Ic clrstats
148 Clears the node's statistics.
149 .It Dv NGM_PATCH_GETCLR_STATS Pq Ic getclrstats
150 This command is identical to
151 .Dv NGM_PATCH_GET_STATS ,
152 except that the statistics are also atomically cleared.
153 .El
154 .Sh SHUTDOWN
155 This node shuts down upon receipt of a
156 .Dv NGM_SHUTDOWN
157 control message, or when all hooks have been disconnected.
158 .Sh EXAMPLES
159 This
160 .Nm
161 node was designed to modify TTL and TOS/DSCP fields in IP packets.
162 As an example,
163 suppose you have two adjacent simplex links to a remote network
164 (e.g.\& satellite), so that the packets expiring in between
165 will generate unwanted ICMP-replies which have to go forth, not back.
166 Thus you need to raise TTL of every packet entering link by 2
167 to ensure the TTL will not reach zero there.
168 To achieve this you can set an
169 .Xr ipfw 8
170 rule to use the
171 .Cm netgraph
172 action to inject packets which are going to the simplex link into the patch node, by using the
173 following
174 .Xr ngctl 8
175 script:
176 .Bd -literal -offset 4n
177 /usr/sbin/ngctl -f- <<-SEQ
178         mkpeer ipfw: patch 200 in
179         name ipfw:200 ttl_add
180         msg ttl_add: setconfig { count=1 csum_flags=1 ops=[     \e
181                 { mode=2 value=3 length=1 offset=8 } ] }
182 SEQ
183 /sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net
184 .Ed
185 .Pp
186 Here the
187 .Dq Li ttl_add
188 node of type
189 .Nm
190 is configured to add (mode
191 .Dv NG_PATCH_MODE_ADD )
192 a
193 .Va value
194 of 3 to a one-byte TTL field, which is 9th byte of IP packet header.
195 .Pp
196 Another example would be two consecutive modifications of packet TOS
197 field: say, you need to clear the
198 .Dv IPTOS_THROUGHPUT
199 bit and set the
200 .Dv IPTOS_MINCOST
201 bit.
202 So you do:
203 .Bd -literal -offset 4n
204 /usr/sbin/ngctl -f- <<-SEQ
205         mkpeer ipfw: patch 300 in
206         name ipfw:300 tos_chg
207         msg tos_chg: setconfig { count=2 csum_flags=1 ops=[     \e
208                 { mode=7 value=0xf7 length=1 offset=1 }         \e
209                 { mode=8 value=0x02 length=1 offset=1 } ] }
210 SEQ
211 /sbin/ipfw add 160 netgraph 300 ip from any to any not dst-port 80
212 .Ed
213 .Pp
214 This first does
215 .Dv NG_PATCH_MODE_AND
216 clearing the fourth bit and then
217 .Dv NG_PATCH_MODE_OR
218 setting the third bit.
219 .Pp
220 In both examples the
221 .Va csum_flags
222 field indicates that IP checksum (but not TCP or UDP checksum) should be
223 recalculated before transmit.
224 .Pp
225 Note: one should ensure that packets are returned to ipfw after processing
226 inside
227 .Xr netgraph 4 ,
228 by setting appropriate
229 .Xr sysctl 8
230 variable:
231 .Bd -literal -offset 4n
232 sysctl net.inet.ip.fw.one_pass=0
233 .Ed
234 .Sh SEE ALSO
235 .Xr netgraph 4 ,
236 .Xr ng_ipfw 4 ,
237 .Xr ngctl 8
238 .Sh HISTORY
239 The
240 .Nm
241 node type was implemented in
242 .Fx 8.1 .
243 .Sh AUTHORS
244 .An "Maxim Ignatenko" Aq gelraen.ua@gmail.com .
245 .Pp
246 Relative offset code by
247 .An "DMitry Vagin"
248 .Pp
249 This manual page was written by
250 .An "Vadim Goncharov" Aq vadimnuclight@tpu.ru .
251 .Sh BUGS
252 The node blindly tries to apply every patching operation to each packet
253 (except those which offset if greater than length of the packet),
254 so be sure that you supply only the right packets to it (e.g. changing
255 bytes in the ARP packets meant to be in IP header could corrupt
256 them and make your machine unreachable from the network).
257 .Pp
258 .Em !!! WARNING !!!
259 .Pp
260 The output path of the IP stack assumes correct fields and lengths in the
261 packets - changing them by to incorrect values can cause
262 unpredictable results including kernel panics.