Debian Codegraph @

upstream/debian-unstable/man8/tc-pedit.8

raw
1 .TH "Generic packet editor action in tc" 8 "12 Jan 2015" "iproute2" "Linux"
2
3 .SH NAME
4 pedit - generic packet editor action
5 .SH SYNOPSIS
6 .in +8
7 .ti -8
8 .BR tc " ... " "action pedit [ex] munge " {
9 .IR RAW_OP " | " LAYERED_OP " | " EXTENDED_LAYERED_OP " } [ " CONTROL " ]"
10
11 .ti -8
12 .IR RAW_OP " := "
13 .BI offset " OFFSET"
14 .RB "{ " u8 " | " u16 " | " u32 " } ["
15 .IR AT_SPEC " ] " CMD_SPEC
16
17 .ti -8
18 .IR AT_SPEC " := "
19 .BI at " AT " offmask " MASK " shift " SHIFT"
20
21 .ti -8
22 .IR LAYERED_OP " := { "
23 .BI ip " IPHDR_FIELD"
24 |
25 .BI ip " BEYOND_IPHDR_FIELD"
26 .RI } " CMD_SPEC"
27
28 .ti -8
29 .IR EXTENDED_LAYERED_OP " := { "
30 .BI eth " ETHHDR_FIELD"
31 |
32 .BI ip " IPHDR_FIELD"
33 |
34 .BI ip " EX_IPHDR_FIELD"
35 |
36 .BI ip6 " IP6HDR_FIELD"
37 |
38 .BI tcp " TCPHDR_FIELD"
39 |
40 .BI udp " UDPHDR_FIELD"
41 .RI } " CMD_SPEC"
42
43 .ti -8
44 .IR ETHHDR_FIELD " := { "
45 .BR src " | " dst " | " type " }"
46
47 .ti -8
48 .IR IPHDR_FIELD " := { "
49 .BR src " | " dst " | " tos " | " dsfield " | " ihl " | " protocol " |"
50 .BR precedence " | " nofrag " | " firstfrag " | " ce " | " df " }"
51
52 .ti -8
53 .IR BEYOND_IPHDR_FIELD " := { "
54 .BR dport " | " sport " | " icmp_type " | " icmp_code " }"
55
56 .ti -8
57 .IR EX_IPHDR_FIELD " := { "
58 .BR ttl " }"
59
60
61 .ti -8
62 .IR IP6HDR_FIELD " := { "
63 .BR src " | " dst " | " traffic_class " | " flow_lbl " | " payload_len " | "
64 .BR nexthdr " | " hoplimit " }"
65
66 .ti -8
67 .IR TCPHDR_FIELD " := { "
68 .BR sport " | " dport " | " flags " }"
69
70 .ti -8
71 .IR UDPHDR_FIELD " := { "
72 .BR sport " | " dport " }"
73
74 .ti -8
75 .IR CMD_SPEC " := {"
76 .BR clear " | " invert " | " set
77 .IR VAL " | "
78 .BR add
79 .IR VAL " | "
80 .BR decrement " | "
81 .BR preserve " } [ " retain
82 .IR RVAL " ]"
83
84 .ti -8
85 .IR CONTROL " := {"
86 .BR reclassify " | " pipe " | " drop " | " shot " | " continue " | " pass " | " goto " " chain " " CHAIN_INDEX " }"
87 .SH DESCRIPTION
88 The
89 .B pedit
90 action can be used to change arbitrary packet data. The location of data to
91 change can either be specified by giving an offset and size as in
92 .IR RAW_OP ,
93 or for header values by naming the header and field to edit the size is then
94 chosen automatically based on the header field size.
95 .SH OPTIONS
96 .TP
97 .B ex
98 Use extended pedit.
99 .I EXTENDED_LAYERED_OP
100 and the add/decrement
101 .I CMD_SPEC
102 are allowed only in this mode.
103 .TP
104 .BI offset " OFFSET " "\fR{ \fBu32 \fR| \fBu16 \fR| \fBu8 \fR}"
105 Specify the offset at which to change data.
106 .I OFFSET
107 is a signed integer, it's base is automatically chosen (e.g. hex if prefixed by
108 .B 0x
109 or octal if prefixed by
110 .BR 0 ).
111 The second argument specifies the length of data to change, that is four bytes
112 .RB ( u32 ),
113 two bytes
114 .RB ( u16 )
115 or a single byte
116 .RB ( u8 ).
117 .TP
118 .BI at " AT " offmask " MASK " shift " SHIFT"
119 This is an optional part of
120 .IR RAW_OP
121 which allows one to have a variable
122 .I OFFSET
123 depending on packet data at offset
124 .IR AT ,
125 which is binary ANDed with
126 .I MASK
127 and right-shifted by
128 .I SHIFT
129 before adding it to
130 .IR OFFSET .
131 .TP
132 .BI eth " ETHHDR_FIELD"
133 Change an ETH header field. The supported keywords for
134 .I ETHHDR_FIELD
135 are:
136 .RS
137 .TP
138 .B src
139 .TQ
140 .B dst
141 Source or destination MAC address in the standard format: XX:XX:XX:XX:XX:XX
142 .TP
143 .B type
144 Ether-type in numeric value
145 .RE
146 .TP
147 .BI ip " IPHDR_FIELD"
148 Change an IPv4 header field. The supported keywords for
149 .I IPHDR_FIELD
150 are:
151 .RS
152 .TP
153 .B src
154 .TQ
155 .B dst
156 Source or destination IP address, a four-byte value.
157 .TP
158 .B tos
159 .TQ
160 .B dsfield
161 .TQ
162 .B precedence
163 Type Of Service field, an eight-bit value.
164 .TP
165 .B ihl
166 Change the IP Header Length field, a four-bit value.
167 .TP
168 .B protocol
169 Next-layer Protocol field, an eight-bit value.
170 .TP
171 .B nofrag
172 .TQ
173 .B firstfrag
174 .TQ
175 .B ce
176 .TQ
177 .B df
178 .TQ
179 .B mf
180 Change IP header flags. Note that the value to pass to the
181 .B set
182 command is not just a bit value, but the full byte including the flags field.
183 Though only the relevant bits of that value are respected, the rest ignored.
184 .RE
185 .TP
186 .BI ip " BEYOND_IPHDR_FIELD"
187 Supported only for non-extended layered op. It is passed to the kernel as
188 offsets relative to the beginning of the IP header and assumes the IP header is
189 of minimum size (20 bytes). The supported keywords for
190 .I BEYOND_IPHDR_FIELD
191 are:
192 .RS
193 .TP
194 .B dport
195 .TQ
196 .B sport
197 Destination or source port numbers, a 16-bit value. Indeed, IPv4 headers don't
198 contain this information. Instead, this will set an offset which suits at least
199 TCP and UDP if the IP header is of minimum size (20 bytes). If not, this will do
200 unexpected things.
201 .TP
202 .B icmp_type
203 .TQ
204 .B icmp_code
205 Again, this allows one to change data past the actual IP header itself. It assumes
206 an ICMP header is present immediately following the (minimal sized) IP header.
207 If it is not or the latter is bigger than the minimum of 20 bytes, this will do
208 unexpected things. These fields are eight-bit values.
209 .RE
210 .TP
211 .BI ip " EX_IPHDR_FIELD"
212 Supported only when
213 .I ex
214 is used. The supported keywords for
215 .I EX_IPHDR_FIELD
216 are:
217 .RS
218 .TP
219 .B ttl
220 .RE
221 .TP
222 .BI ip6 " IP6HDR_FIELD"
223 The supported keywords for
224 .I IP6HDR_FIELD
225 are:
226 .RS
227 .TP
228 .B src
229 .TQ
230 .B dst
231 .TQ
232 .B traffic_class
233 .TQ
234 .B flow_lbl
235 .TQ
236 .B payload_len
237 .TQ
238 .B nexthdr
239 .TQ
240 .B hoplimit
241 .RE
242 .TP
243 .BI tcp " TCPHDR_FIELD"
244 The supported keywords for
245 .I TCPHDR_FIELD
246 are:
247 .RS
248 .TP
249 .B sport
250 .TQ
251 .B dport
252 Source or destination TCP port number, a 16-bit value.
253 .TP
254 .B flags
255 .RE
256 .TP
257 .BI udp " UDPHDR_FIELD"
258 The supported keywords for
259 .I UDPHDR_FIELD
260 are:
261 .RS
262 .TP
263 .B sport
264 .TQ
265 .B dport
266 Source or destination TCP port number, a 16-bit value.
267 .RE
268 .TP
269 .B clear
270 Clear the addressed data (i.e., set it to zero).
271 .TP
272 .B invert
273 Swap every bit in the addressed data.
274 .TP
275 .BI set " VAL"
276 Set the addressed data to a specific value. The size of
277 .I VAL
278 is defined by either one of the
279 .BR u32 ", " u16 " or " u8
280 keywords in
281 .IR RAW_OP ,
282 or the size of the addressed header field in
283 .IR LAYERED_OP .
284 .TP
285 .BI add " VAL"
286 Add the addressed data by a specific value. The size of
287 .I VAL
288 is defined by the size of the addressed header field in
289 .IR EXTENDED_LAYERED_OP .
290 This operation is supported only for extended layered op.
291 .TP
292 .BI decrement
293 Decrease the addressed data by one.
294 This operation is supported only for
295 .BR ip " " ttl " and " ip6 " " hoplimit "."
296 .TP
297 .B preserve
298 Keep the addressed data as is.
299 .TP
300 .BI retain " RVAL"
301 This optional extra part of
302 .I CMD_SPEC
303 allows one to exclude bits from being changed. Supported only for 32 bits fields
304 or smaller.
305 .TP
306 .I CONTROL
307 The following keywords allow one to control how the tree of qdisc, classes,
308 filters and actions is further traversed after this action.
309 .RS
310 .TP
311 .B reclassify
312 Restart with the first filter in the current list.
313 .TP
314 .B pipe
315 Continue with the next action attached to the same filter.
316 .TP
317 .B drop
318 .TQ
319 .B shot
320 Drop the packet.
321 .TP
322 .B continue
323 Continue classification with the next filter in line.
324 .TP
325 .B pass
326 Finish classification process and return to calling qdisc for further packet
327 processing. This is the default.
328 .RE
329 .SH EXAMPLES
330 Being able to edit packet data, one could do all kinds of things, such as e.g.
331 implementing port redirection. Certainly not the most useful application, but
332 as an example it should do:
333
334 First, qdiscs need to be set up to attach filters to. For the receive path, a simple
335 .B ingress
336 qdisc will do, for transmit path a classful qdisc
337 .RB ( HTB
338 in this case) is necessary:
339
340 .RS
341 .EX
342 tc qdisc replace dev eth0 root handle 1: htb
343 tc qdisc add dev eth0 ingress handle ffff:
344 .EE
345 .RE
346
347 Finally, a filter with
348 .B pedit
349 action can be added for each direction. In this case,
350 .B u32
351 is used matching on the port number to redirect from, while
352 .B pedit
353 then does the actual rewriting:
354
355 .RS
356 .EX
357 tc filter add dev eth0 parent 1: u32 \\
358 match ip dport 23 0xffff \\
359 action pedit pedit munge ip dport set 22
360 tc filter add dev eth0 parent ffff: u32 \\
361 match ip sport 22 0xffff \\
362 action pedit pedit munge ip sport set 23
363 tc filter add dev eth0 parent ffff: u32 \\
364 match ip sport 22 0xffff \\
365 action pedit ex munge ip dst set 192.168.1.199
366 tc filter add dev eth0 parent ffff: u32 \\
367 match ip sport 22 0xffff \\
368 action pedit ex munge ip6 dst set fe80::dacb:8aff:fec7:320e
369 tc filter add dev eth0 parent ffff: u32 \\
370 match ip sport 22 0xffff \\
371 action pedit ex munge eth dst set 11:22:33:44:55:66
372 tc filter add dev eth0 parent ffff: u32 \\
373 match ip dport 23 0xffff \\
374 action pedit ex munge tcp dport set 22
375 .EE
376 .RE
377
378 To rewrite just part of a field, use the
379 .B retain
380 directive. E.g. to overwrite the DSCP part of a dsfield with $DSCP, without
381 touching ECN:
382
383 .RS
384 .EX
385 tc filter add dev eth0 ingress flower ... \\
386 action pedit ex munge ip dsfield set $((DSCP << 2)) retain 0xfc
387 .EE
388 .RE
389
390 And vice versa, to set ECN to e.g. 1 without impacting DSCP:
391
392 .RS
393 .EX
394 tc filter add dev eth0 ingress flower ... \\
395 action pedit ex munge ip dsfield set 1 retain 0x3
396 .EE
397 .RE
398
399 .SH SEE ALSO
400 .BR tc (8),
401 .BR tc-htb (8),
402 .BR tc-u32 (8)