Debian Codegraph @

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

raw
1 .TH "Flower filter in tc" 8 "22 Oct 2015" "iproute2" "Linux"
2
3 .SH NAME
4 flower \- flow based traffic control filter
5 .SH SYNOPSIS
6 .in +8
7 .ti -8
8 .BR tc " " filter " ... " flower " [ "
9 .IR MATCH_LIST " ] [ "
10 .B action
11 .IR ACTION_SPEC " ] [ "
12 .B classid
13 .IR CLASSID " ] [ "
14 .B hw_tc
15 .IR TCID " ]"
16
17
18 .ti -8
19 .IR MATCH_LIST " := [ " MATCH_LIST " ] " MATCH
20
21 .ti -8
22 .IR MATCH " := { "
23 .B indev
24 .IR ifname " | "
25 .BR verbose
26 .RI " | "
27 .BR skip_sw " | " skip_hw
28 .RI " | { "
29 .BR dst_mac " | " src_mac " } "
30 .IR MASKED_LLADDR " | "
31 .B vlan_id
32 .IR VID " | "
33 .B vlan_prio
34 .IR PRIORITY " | "
35 .BR vlan_ethtype " { " ipv4 " | " ipv6 " | "
36 .IR ETH_TYPE " } | "
37 .B cvlan_id
38 .IR VID " | "
39 .B cvlan_prio
40 .IR PRIORITY " | "
41 .BR cvlan_ethtype " { " ipv4 " | " ipv6 " | "
42 .IR ETH_TYPE " } | "
43 .B pppoe_sid
44 .IR PSID " | "
45 .BR ppp_proto " { " ip " | " ipv6 " | " mpls_uc " | " mpls_mc " | "
46 .IR PPP_PROTO " } | "
47 .B mpls
48 .IR LSE_LIST " | "
49 .B mpls_label
50 .IR LABEL " | "
51 .B mpls_tc
52 .IR TC " | "
53 .B mpls_bos
54 .IR BOS " | "
55 .B mpls_ttl
56 .IR TTL " | "
57 .B l2tpv3_sid
58 .IR LSID " | "
59 .BR ip_proto " { " tcp " | " udp " | " sctp " | " icmp " | " icmpv6 " | " l2tp " | "
60 .IR IP_PROTO " } | "
61 .B ip_tos
62 .IR MASKED_IP_TOS " | "
63 .B ip_ttl
64 .IR MASKED_IP_TTL " | { "
65 .BR dst_ip " | " src_ip " } "
66 .IR PREFIX " | { "
67 .BR dst_port " | " src_port " } { "
68 .IR MASKED_NUMBER " | "
69 .IR min_port_number-max_port_number " } | "
70 .B tcp_flags
71 .IR MASKED_TCP_FLAGS " | "
72 .B type
73 .IR MASKED_TYPE " | "
74 .B code
75 .IR MASKED_CODE " | { "
76 .BR arp_tip " | " arp_sip " } "
77 .IR IPV4_PREFIX " | "
78 .BR arp_op " { " request " | " reply " | "
79 .IR OP " } | { "
80 .BR arp_tha " | " arp_sha " } "
81 .IR MASKED_LLADDR " | "
82 .B enc_key_id
83 .IR KEY-ID " | {"
84 .BR enc_dst_ip " | " enc_src_ip " } { "
85 .IR ipv4_address " | " ipv6_address " } | "
86 .B enc_dst_port
87 .IR port_number " | "
88 .B enc_tos
89 .IR TOS " | "
90 .B enc_ttl
91 .IR TTL " | "
92 {
93 .B geneve_opts
94 |
95 .B vxlan_opts
96 |
97 .B erspan_opts
98 |
99 .B gtp_opts
100 |
101 .B pfcp_opts
102 }
103 .IR OPTIONS " | "
104 .BR ip_flags
105 .IR IP_FLAGS " | "
106 .B l2_miss
107 .IR L2_MISS " | "
108 .BR cfm
109 .IR CFM_OPTIONS " | "
110 .BR enc_flags
111 .IR ENCFLAG-LIST " }"
112
113 .ti -8
114 .IR LSE_LIST " := [ " LSE_LIST " ] " LSE
115
116 .ti -8
117 .IR LSE " := "
118 .B lse depth
119 .IR DEPTH " { "
120 .B label
121 .IR LABEL " | "
122 .B tc
123 .IR TC " | "
124 .B bos
125 .IR BOS " | "
126 .B ttl
127 .IR TTL " }"
128
129 .ti -8
130 .IR CFM " := "
131 .B cfm mdl
132 .IR LEVEL " | "
133 .B op
134 .IR OPCODE "
135
136 .ti -8
137 .IR ENCFLAG-LIST " := [ " ENCFLAG-LIST "/ ] " ENCFLAG
138
139 .ti -8
140 .IR ENCFLAG " := { "
141 .BR [no]tuncsum " | "
142 .BR [no]tundf " | "
143 .BR [no]tunoam " | "
144 .BR [no]tuncrit " } "
145
146 .SH DESCRIPTION
147 The
148 .B flower
149 filter matches flows to the set of keys specified and assigns an arbitrarily
150 chosen class ID to packets belonging to them. Additionally (or alternatively) an
151 action from the generic action framework may be called.
152 .SH OPTIONS
153 .TP
154 .BI action " ACTION_SPEC"
155 Apply an action from the generic actions framework on matching packets.
156 .TP
157 .BI classid " CLASSID"
158 Specify a class to pass matching packets on to.
159 .I CLASSID
160 is in the form
161 .BR X : Y ", while " X " and " Y
162 are interpreted as numbers in hexadecimal format.
163 .TP
164 .BI hw_tc " TCID"
165 Specify a hardware traffic class to pass matching packets on to. TCID is in the
166 range 0 through 15.
167 .TP
168 .BI indev " ifname"
169 Match on incoming interface name. Obviously this makes sense only for forwarded
170 flows.
171 .I ifname
172 is the name of an interface which must exist at the time of
173 .B tc
174 invocation.
175 .TP
176 .BI verbose
177 Enable verbose logging, including offloading errors when not using
178 .B skip_sw
179 flag.
180 .TP
181 .BI skip_sw
182 Do not process filter by software. If hardware has no offload support for this
183 filter, or TC offload is not enabled for the interface, operation will fail.
184 .TP
185 .BI skip_hw
186 Do not process filter by hardware.
187 .TP
188 .BI dst_mac " MASKED_LLADDR"
189 .TQ
190 .BI src_mac " MASKED_LLADDR"
191 Match on source or destination MAC address. A mask may be optionally
192 provided to limit the bits of the address which are matched. A mask is
193 provided by following the address with a slash and then the mask. It may be
194 provided in LLADDR format, in which case it is a bitwise mask, or as a
195 number of high bits to match. If the mask is missing then a match on all
196 bits is assumed.
197 .TP
198 .BI num_of_vlans " NUM"
199 Match on the number of vlan tags in the packet.
200 .I NUM
201 can be 0 or small positive integer. Typically in 0-4 range.
202 .TP
203 .BI vlan_id " VID"
204 Match on vlan tag id.
205 .I VID
206 is an unsigned 12bit value in decimal format.
207 .TP
208 .BI vlan_prio " PRIORITY"
209 Match on vlan tag priority.
210 .I PRIORITY
211 is an unsigned 3bit value in decimal format.
212 .TP
213 .BI vlan_ethtype " VLAN_ETH_TYPE"
214 Match on layer three protocol.
215 .I VLAN_ETH_TYPE
216 may be either
217 .BR ipv4 ", " ipv6
218 or an unsigned 16bit value in hexadecimal format. To match on QinQ packet, it must be 802.1Q or 802.1AD.
219 .TP
220 .BI cvlan_id " VID"
221 Match on QinQ inner vlan tag id.
222 .I VID
223 is an unsigned 12bit value in decimal format.
224 .TP
225 .BI cvlan_prio " PRIORITY"
226 Match on QinQ inner vlan tag priority.
227 .I PRIORITY
228 is an unsigned 3bit value in decimal format.
229 .TP
230 .BI cvlan_ethtype " VLAN_ETH_TYPE"
231 Match on QinQ layer three protocol.
232 .I VLAN_ETH_TYPE
233 may be either
234 .BR ipv4 ", " ipv6
235 or an unsigned 16bit value in hexadecimal format.
236 .TP
237 .BI pppoe_sid " PSID"
238 Match on PPPoE session id.
239 .I PSID
240 is an unsigned 16bit value in decimal format.
241 .TP
242 .BI ppp_proto " PPP_PROTO"
243 Match on PPP layer three protocol.
244 .I PPP_PROTO
245 may be either
246 .BR ip ", " ipv6 ", " mpls_uc ", " mpls_mc
247 or an unsigned 16bit value in hexadecimal format.
248 .TP
249 .BI mpls " LSE_LIST"
250 Match on the MPLS label stack.
251 .I LSE_LIST
252 is a list of Label Stack Entries, each introduced by the
253 .BR lse " keyword."
254 This option can't be used together with the standalone
255 .BR mpls_label ", " mpls_tc ", " mpls_bos " and " mpls_ttl " options."
256 .RS
257 .TP
258 .BI lse " LSE_OPTIONS"
259 Match on an MPLS Label Stack Entry.
260 .I LSE_OPTIONS
261 is a list of options that describe the properties of the LSE to match.
262 .RS
263 .TP
264 .BI depth " DEPTH"
265 The depth of the Label Stack Entry to consider. Depth starts at 1 (the
266 outermost Label Stack Entry). The maximum usable depth may be limited by the
267 kernel. This option is mandatory.
268 .I DEPTH
269 is an unsigned 8 bit value in decimal format.
270 .TP
271 .BI label " LABEL"
272 Match on the MPLS Label field at the specified
273 .BR depth .
274 .I LABEL
275 is an unsigned 20 bit value in decimal format.
276 .TP
277 .BI tc " TC"
278 Match on the MPLS Traffic Class field at the specified
279 .BR depth .
280 .I TC
281 is an unsigned 3 bit value in decimal format.
282 .TP
283 .BI bos " BOS"
284 Match on the MPLS Bottom Of Stack field at the specified
285 .BR depth .
286 .I BOS
287 is a 1 bit value in decimal format.
288 .TP
289 .BI ttl " TTL"
290 Match on the MPLS Time To Live field at the specified
291 .BR depth .
292 .I TTL
293 is an unsigned 8 bit value in decimal format.
294 .RE
295 .RE
296
297 .TP
298 .BI mpls_label " LABEL"
299 Match the label id in the outermost MPLS label stack entry.
300 .I LABEL
301 is an unsigned 20 bit value in decimal format.
302 .TP
303 .BI mpls_tc " TC"
304 Match on the MPLS TC field, which is typically used for packet priority,
305 in the outermost MPLS label stack entry.
306 .I TC
307 is an unsigned 3 bit value in decimal format.
308 .TP
309 .BI mpls_bos " BOS"
310 Match on the MPLS Bottom Of Stack field in the outermost MPLS label stack
311 entry.
312 .I BOS
313 is a 1 bit value in decimal format.
314 .TP
315 .BI mpls_ttl " TTL"
316 Match on the MPLS Time To Live field in the outermost MPLS label stack
317 entry.
318 .I TTL
319 is an unsigned 8 bit value in decimal format.
320 .TP
321 .BI l2tpv3_sid " LSID"
322 Match on L2TPv3 session id field transported over IPv4 or IPv6.
323 .I LSID
324 is an unsigned 32 bit value in decimal format.
325 .TP
326 .BI ip_proto " IP_PROTO"
327 Match on layer four protocol.
328 .I IP_PROTO
329 may be
330 .BR tcp ", " udp ", " sctp ", " icmp ", " icmpv6 ", " l2tp
331 or an unsigned 8bit value in hexadecimal format.
332 .TP
333 .BI ip_tos " MASKED_IP_TOS"
334 Match on ipv4 TOS or ipv6 traffic-class - eight bits in hexadecimal format.
335 A mask may be optionally provided to limit the bits which are matched. A mask
336 is provided by following the value with a slash and then the mask. If the mask
337 is missing then a match on all bits is assumed.
338 .TP
339 .BI ip_ttl " MASKED_IP_TTL"
340 Match on ipv4 TTL or ipv6 hop-limit - eight bits value in decimal or hexadecimal format.
341 A mask may be optionally provided to limit the bits which are matched. Same
342 logic is used for the mask as with matching on ip_tos.
343 .TP
344 .BI dst_ip " PREFIX"
345 .TQ
346 .BI src_ip " PREFIX"
347 Match on source or destination IP address.
348 .I PREFIX
349 must be a valid IPv4 or IPv6 address, depending on the \fBprotocol\fR
350 option to tc filter, optionally followed by a slash and the prefix length.
351 If the prefix is missing, \fBtc\fR assumes a full-length host match.
352 .TP
353 .IR \fBdst_port " { " MASKED_NUMBER " | " " MIN_VALUE-MAX_VALUE " }
354 .TQ
355 .IR \fBsrc_port " { " MASKED_NUMBER " | " " MIN_VALUE-MAX_VALUE " }
356 Match on layer 4 protocol source or destination port number, with an
357 optional mask. Alternatively, the minimum and maximum values can be
358 specified to match on a range of layer 4 protocol source or destination
359 port numbers. Only available for
360 .BR ip_proto " values " udp ", " tcp " and " sctp
361 which have to be specified in beforehand.
362 .TP
363 .BI tcp_flags " MASKED_TCP_FLAGS"
364 Match on TCP flags represented as 12bit bitfield in in hexadecimal format.
365 A mask may be optionally provided to limit the bits which are matched. A mask
366 is provided by following the value with a slash and then the mask. If the mask
367 is missing then a match on all bits is assumed.
368 .TP
369 .BI type " MASKED_TYPE"
370 .TQ
371 .BI code " MASKED_CODE"
372 Match on ICMP type or code. A mask may be optionally provided to limit the
373 bits of the address which are matched. A mask is provided by following the
374 address with a slash and then the mask. The mask must be as a number which
375 represents a bitwise mask If the mask is missing then a match on all bits
376 is assumed. Only available for
377 .BR ip_proto " values " icmp " and " icmpv6
378 which have to be specified in beforehand.
379 .TP
380 .BI arp_tip " IPV4_PREFIX"
381 .TQ
382 .BI arp_sip " IPV4_PREFIX"
383 Match on ARP or RARP sender or target IP address.
384 .I IPV4_PREFIX
385 must be a valid IPv4 address optionally followed by a slash and the prefix
386 length. If the prefix is missing, \fBtc\fR assumes a full-length host
387 match.
388 .TP
389 .BI arp_op " ARP_OP"
390 Match on ARP or RARP operation.
391 .I ARP_OP
392 may be
393 .BR request ", " reply
394 or an integer value 0, 1 or 2. A mask may be optionally provided to limit
395 the bits of the operation which are matched. A mask is provided by
396 following the address with a slash and then the mask. It may be provided as
397 an unsigned 8 bit value representing a bitwise mask. If the mask is missing
398 then a match on all bits is assumed.
399 .TP
400 .BI arp_sha " MASKED_LLADDR"
401 .TQ
402 .BI arp_tha " MASKED_LLADDR"
403 Match on ARP or RARP sender or target MAC address. A mask may be optionally
404 provided to limit the bits of the address which are matched. A mask is
405 provided by following the address with a slash and then the mask. It may be
406 provided in LLADDR format, in which case it is a bitwise mask, or as a
407 number of high bits to match. If the mask is missing then a match on all
408 bits is assumed.
409 .TP
410 .BI enc_key_id " NUMBER"
411 .TQ
412 .BI enc_dst_ip " PREFIX"
413 .TQ
414 .BI enc_src_ip " PREFIX"
415 .TQ
416 .BI enc_dst_port " NUMBER"
417 .TQ
418 .BI enc_tos " NUMBER"
419 .TQ
420 .BI enc_ttl " NUMBER"
421 .TQ
422 .BR
423 .TP
424 .BI ct_state " CT_STATE"
425 .TQ
426 .BI ct_zone " CT_MASKED_ZONE"
427 .TQ
428 .BI ct_mark " CT_MASKED_MARK"
429 .TQ
430 .BI ct_label " CT_MASKED_LABEL"
431 Matches on connection tracking info
432 .RS
433 .TP
434 .I CT_STATE
435 Match the connection state, and can be combination of [{+|-}flag] flags, where flag can be one of
436 .RS
437 .TP
438 trk - Tracked connection.
439 .TP
440 new - New connection.
441 .TP
442 est - Established connection.
443 .TP
444 rpl - The packet is in the reply direction, meaning that it is in the opposite direction from the packet that initiated the connection.
445 .TP
446 inv - The state is invalid. The packet couldn't be associated to a connection.
447 .TP
448 rel - The packet is related to an existing connection.
449 .TP
450 Example: +trk+est
451 .RE
452 .TP
453 .I CT_MASKED_ZONE
454 Match the connection zone, and can be masked.
455 .TP
456 .I CT_MASKED_MARK
457 32bit match on the connection mark, and can be masked.
458 .TP
459 .I CT_MASKED_LABEL
460 128bit match on the connection label, and can be masked.
461 .RE
462 .TP
463 .BI geneve_opts " OPTIONS"
464 .TQ
465 .BI vxlan_opts " OPTIONS"
466 .TQ
467 .BI erspan_opts " OPTIONS"
468 .TQ
469 .BI gtp_opts " OPTIONS"
470 .TQ
471 .BI pfcp_opts " OPTIONS"
472 Match on IP tunnel metadata. Key id
473 .I NUMBER
474 is a 32 bit tunnel key id (e.g. VNI for VXLAN tunnel).
475 .I PREFIX
476 must be a valid IPv4 or IPv6 address optionally followed by a slash and the
477 prefix length. If the prefix is missing, \fBtc\fR assumes a full-length
478 host match. Dst port
479 .I NUMBER
480 is a 16 bit UDP dst port. Tos
481 .I NUMBER
482 is an 8 bit tos (dscp+ecn) value, ttl
483 .I NUMBER
484 is an 8 bit time-to-live value. geneve_opts
485 .I OPTIONS
486 must be a valid list of comma-separated geneve options where each option
487 consists of a key optionally followed by a slash and corresponding mask. If
488 the masks is missing, \fBtc\fR assumes a full-length match. The options can
489 be described in the form CLASS:TYPE:DATA/CLASS_MASK:TYPE_MASK:DATA_MASK,
490 where CLASS is represented as a 16bit hexadecimal value, TYPE as an 8bit
491 hexadecimal value and DATA as a variable length hexadecimal value.
492 vxlan_opts
493 .I OPTIONS
494 doesn't support multiple options, and it consists of a key followed by a slash
495 and corresponding mask. If the mask is missing, \fBtc\fR assumes a full-length
496 match. The option can be described in the form GBP/GBP_MASK, where GBP is
497 represented as a 32bit number.
498 erspan_opts
499 .I OPTIONS
500 doesn't support multiple options, and it consists of a key followed by a slash
501 and corresponding mask. If the mask is missing, \fBtc\fR assumes a full-length
502 match. The option can be described in the form
503 VERSION:INDEX:DIR:HWID/VERSION:INDEX_MASK:DIR_MASK:HWID_MASK, where VERSION is
504 represented as a 8bit number, INDEX as an 32bit number, DIR and HWID as a 8bit
505 number. Multiple options is not supported. Note INDEX/INDEX_MASK is used when
506 VERSION is 1, and DIR/DIR_MASK and HWID/HWID_MASK are used when VERSION is 2.
507 gtp_opts
508 .I OPTIONS
509 doesn't support multiple options, and it consists of a key followed by a slash
510 and corresponding mask. If the mask is missing, \fBtc\fR assumes a full-length
511 match. The option can be described in the form PDU_TYPE:QFI/PDU_TYPE_MASK:QFI_MASK
512 where both PDU_TYPE and QFI are represented as a 8bit hexadecimal values.
513 pfcp_opts
514 .I OPTIONS
515 does not support multiple options. It consists of a key followed by a slash
516 and corresponding mask. If the mask is missing, \fBtc\fR assumes a full-length
517 match. The option can be described in the form TYPE:SEID/TYPE_MASK:SEID_MASK
518 where TYPE is represented as a 8bit number, SEID is represented by 64bit. Both
519 TYPE and SEID are provided in hex.
520 .TP
521 .BI ip_flags " IP_FLAGS"
522 .I IP_FLAGS
523 may be either
524 .BR frag ", " nofrag ", " firstfrag " or " nofirstfrag
525 where frag and nofrag could be used to match on fragmented packets or not,
526 respectively. firstfrag and nofirstfrag can be used to further distinguish
527 fragmented packet. firstfrag can be used to indicate the first fragmented
528 packet. nofirstfrag can be used to indicates subsequent fragmented packets
529 or non-fragmented packets.
530 .TP
531
532 .BI l2_miss " L2_MISS"
533 Match on layer 2 miss in the bridge driver's FDB / MDB. \fIL2_MISS\fR may be 0
534 or 1. When 1, match on packets that encountered a layer 2 miss. When 0, match
535 on packets that were forwarded using an FDB / MDB entry. Note that broadcast
536 packets do not encounter a miss since a lookup is not performed for them.
537 .TP
538
539 .BI cfm " CFM_OPTIONS"
540 Match on Connectivity Fault Management (CFM) fields.
541 .I CFM_OPTIONS
542 is a list of options that describe the properties of the CFM information
543 fields to match.
544 .RS
545 .TP
546 .BI mdl " LEVEL "
547 Match on the Maintenance Domain (MD) level field.
548 \fILEVEL\fR is an unsigned 3 bit value in decimal format.
549 .TP
550 .BI op " OPCODE "
551 Match on the CFM opcode field. \fIOPCODE\fR is an unsigned 8 bit value in
552 decimal format.
553 .RE
554 .TP
555 .BI enc_flags " ENCFLAG-LIST "
556 Match on tunnel control flags.
557 .I ENCFLAG-LIST
558 is a list of the following tunnel control flags:
559 .BR [no]tuncsum ", "
560 .BR [no]tundf ", "
561 .BR [no]tunoam ", "
562 .BR [no]tuncrit ", "
563 each separated by '/'.
564 .TP
565
566 .SH NOTES
567 As stated above where applicable, matches of a certain layer implicitly depend
568 on the matches of the next lower layer. Precisely, layer one and two matches
569 (\fBindev\fR, \fBdst_mac\fR, \fBsrc_mac\fR and \fBenc_flags\fR)
570 have no dependency,
571 MPLS and layer three matches
572 (\fBmpls\fR, \fBmpls_label\fR, \fBmpls_tc\fR, \fBmpls_bos\fR, \fBmpls_ttl\fR,
573 \fBip_proto\fR, \fBdst_ip\fR, \fBsrc_ip\fR, \fBarp_tip\fR, \fBarp_sip\fR,
574 \fBarp_op\fR, \fBarp_tha\fR, \fBarp_sha\fR and \fBip_flags\fR)
575 depend on the
576 .B protocol
577 option of tc filter, layer four port matches
578 (\fBdst_port\fR and \fBsrc_port\fR)
579 depend on
580 .B ip_proto
581 being set to
582 .BR tcp ", " udp " or " sctp,
583 and finally ICMP matches (\fBcode\fR and \fBtype\fR) depend on
584 .B ip_proto
585 being set to
586 .BR icmp " or " icmpv6.
587 .P
588 There can be only used one mask per one prio. If user needs to specify different
589 mask, he has to use different prio.
590 .SH SEE ALSO
591 .BR tc (8),
592 .BR tc-flow (8)