man/man8/tc-flower.8

   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 mpls_label
  44 .IR LABEL " | "
  45 .B mpls_tc
  46 .IR TC " | "
  47 .B mpls_bos
  48 .IR BOS " | "
  49 .B mpls_ttl
  50 .IR TTL " | "
  51 .BR ip_proto " { " tcp " | " udp " | " sctp " | " icmp " | " icmpv6 " | "
  52 .IR IP_PROTO " } | "
  53 .B ip_tos
  54 .IR MASKED_IP_TOS " | "
  55 .B ip_ttl
  56 .IR MASKED_IP_TTL " | { "
  57 .BR dst_ip " | " src_ip " } "
  58 .IR PREFIX " | { "
  59 .BR dst_port " | " src_port " } "
  60 .IR port_number " } | "
  61 .B tcp_flags
  62 .IR MASKED_TCP_FLAGS " | "
  63 .B type
  64 .IR MASKED_TYPE " | "
  65 .B code
  66 .IR MASKED_CODE " | { "
  67 .BR arp_tip " | " arp_sip " } "
  68 .IR IPV4_PREFIX " | "
  69 .BR arp_op " { " request " | " reply " | "
  70 .IR OP " } | { "
  71 .BR arp_tha " | " arp_sha " } "
  72 .IR MASKED_LLADDR " | "
  73 .B enc_key_id
  74 .IR KEY-ID " | {"
  75 .BR enc_dst_ip " | " enc_src_ip " } { "
  76 .IR ipv4_address " | " ipv6_address " } | "
  77 .B enc_dst_port
  78 .IR port_number " | "
  79 .B enc_tos
  80 .IR TOS " | "
  81 .B enc_ttl
  82 .IR TTL " | "
  83 .B geneve_opts
  84 .IR OPTIONS " | "
  85 .BR ip_flags
  86 .IR IP_FLAGS
  87 .SH DESCRIPTION
  88 The
  89 .B flower
  90 filter matches flows to the set of keys specified and assigns an arbitrarily
  91 chosen class ID to packets belonging to them. Additionally (or alternatively) an
  92 action from the generic action framework may be called.
  93 .SH OPTIONS
  94 .TP
  95 .BI action " ACTION_SPEC"
  96 Apply an action from the generic actions framework on matching packets.
  97 .TP
  98 .BI classid " CLASSID"
  99 Specify a class to pass matching packets on to.
 100 .I CLASSID
 101 is in the form
 102 .BR X : Y ", while " X " and " Y
 103 are interpreted as numbers in hexadecimal format.
 104 .TP
 105 .BI hw_tc " TCID"
 106 Specify a hardware traffic class to pass matching packets on to. TCID is in the
 107 range 0 through 15.
 108 .TP
 109 .BI indev " ifname"
 110 Match on incoming interface name. Obviously this makes sense only for forwarded
 111 flows.
 112 .I ifname
 113 is the name of an interface which must exist at the time of
 114 .B tc
 115 invocation.
 116 .TP
 117 .BI verbose
 118 Enable verbose logging, including offloading errors when not using
 119 .B skip_sw
 120 flag.
 121 .TP
 122 .BI skip_sw
 123 Do not process filter by software. If hardware has no offload support for this
 124 filter, or TC offload is not enabled for the interface, operation will fail.
 125 .TP
 126 .BI skip_hw
 127 Do not process filter by hardware.
 128 .TP
 129 .BI dst_mac " MASKED_LLADDR"
 130 .TQ
 131 .BI src_mac " MASKED_LLADDR"
 132 Match on source or destination MAC address.  A mask may be optionally
 133 provided to limit the bits of the address which are matched. A mask is
 134 provided by following the address with a slash and then the mask. It may be
 135 provided in LLADDR format, in which case it is a bitwise mask, or as a
 136 number of high bits to match. If the mask is missing then a match on all
 137 bits is assumed.
 138 .TP
 139 .BI vlan_id " VID"
 140 Match on vlan tag id.
 141 .I VID
 142 is an unsigned 12bit value in decimal format.
 143 .TP
 144 .BI vlan_prio " PRIORITY"
 145 Match on vlan tag priority.
 146 .I PRIORITY
 147 is an unsigned 3bit value in decimal format.
 148 .TP
 149 .BI vlan_ethtype " VLAN_ETH_TYPE"
 150 Match on layer three protocol.
 151 .I VLAN_ETH_TYPE
 152 may be either
 153 .BR ipv4 ", " ipv6
 154 or an unsigned 16bit value in hexadecimal format. To match on QinQ packet, it must be 802.1Q or 802.1AD.
 155 .TP
 156 .BI cvlan_id " VID"
 157 Match on QinQ inner vlan tag id.
 158 .I VID
 159 is an unsigned 12bit value in decimal format.
 160 .TP
 161 .BI cvlan_prio " PRIORITY"
 162 Match on QinQ inner vlan tag priority.
 163 .I PRIORITY
 164 is an unsigned 3bit value in decimal format.
 165 .TP
 166 .BI cvlan_ethtype " VLAN_ETH_TYPE"
 167 Match on QinQ layer three protocol.
 168 .I VLAN_ETH_TYPE
 169 may be either
 170 .BR ipv4 ", " ipv6
 171 or an unsigned 16bit value in hexadecimal format.
 172 .TP
 173 .BI mpls_label " LABEL"
 174 Match the label id in the outermost MPLS label stack entry.
 175 .I LABEL
 176 is an unsigned 20 bit value in decimal format.
 177 .TP
 178 .BI mpls_tc " TC"
 179 Match on the MPLS TC field, which is typically used for packet priority,
 180 in the outermost MPLS label stack entry.
 181 .I TC
 182 is an unsigned 3 bit value in decimal format.
 183 .TP
 184 .BI mpls_bos " BOS"
 185 Match on the MPLS Bottom Of Stack field in the outermost MPLS label stack
 186 entry.
 187 .I BOS
 188 is a 1 bit value in decimal format.
 189 .TP
 190 .BI mpls_ttl " TTL"
 191 Match on the MPLS Time To Live field in the outermost MPLS label stack
 192 entry.
 193 .I TTL
 194 is an unsigned 8 bit value in decimal format.
 195 .TP
 196 .BI ip_proto " IP_PROTO"
 197 Match on layer four protocol.
 198 .I IP_PROTO
 199 may be
 200 .BR tcp ", " udp ", " sctp ", " icmp ", " icmpv6
 201 or an unsigned 8bit value in hexadecimal format.
 202 .TP
 203 .BI ip_tos " MASKED_IP_TOS"
 204 Match on ipv4 TOS or ipv6 traffic-class - eight bits in hexadecimal format.
 205 A mask may be optionally provided to limit the bits which are matched. A mask
 206 is provided by following the value with a slash and then the mask. If the mask
 207 is missing then a match on all bits is assumed.
 208 .TP
 209 .BI ip_ttl " MASKED_IP_TTL"
 210 Match on ipv4 TTL or ipv6 hop-limit  - eight bits value in decimal or hexadecimal format.
 211 A mask may be optionally provided to limit the bits which are matched. Same
 212 logic is used for the mask as with matching on ip_tos.
 213 .TP
 214 .BI dst_ip " PREFIX"
 215 .TQ
 216 .BI src_ip " PREFIX"
 217 Match on source or destination IP address.
 218 .I PREFIX
 219 must be a valid IPv4 or IPv6 address, depending on the \fBprotocol\fR
 220 option to tc filter, optionally followed by a slash and the prefix length.
 221 If the prefix is missing, \fBtc\fR assumes a full-length host match.
 222 .TP
 223 .BI dst_port " NUMBER"
 224 .TQ
 225 .BI src_port " NUMBER"
 226 Match on layer 4 protocol source or destination port number. Only available for
 227 .BR ip_proto " values " udp ", " tcp  " and " sctp
 228 which have to be specified in beforehand.
 229 .TP
 230 .BI tcp_flags " MASKED_TCP_FLAGS"
 231 Match on TCP flags represented as 12bit bitfield in in hexadecimal format.
 232 A mask may be optionally provided to limit the bits which are matched. A mask
 233 is provided by following the value with a slash and then the mask. If the mask
 234 is missing then a match on all bits is assumed.
 235 .TP
 236 .BI type " MASKED_TYPE"
 237 .TQ
 238 .BI code " MASKED_CODE"
 239 Match on ICMP type or code. A mask may be optionally provided to limit the
 240 bits of the address which are matched. A mask is provided by following the
 241 address with a slash and then the mask. The mask must be as a number which
 242 represents a bitwise mask If the mask is missing then a match on all bits
 243 is assumed.  Only available for
 244 .BR ip_proto " values " icmp  " and " icmpv6
 245 which have to be specified in beforehand.
 246 .TP
 247 .BI arp_tip " IPV4_PREFIX"
 248 .TQ
 249 .BI arp_sip " IPV4_PREFIX"
 250 Match on ARP or RARP sender or target IP address.
 251 .I IPV4_PREFIX
 252 must be a valid IPv4 address optionally followed by a slash and the prefix
 253 length. If the prefix is missing, \fBtc\fR assumes a full-length host
 254 match.
 255 .TP
 256 .BI arp_op " ARP_OP"
 257 Match on ARP or RARP operation.
 258 .I ARP_OP
 259 may be
 260 .BR request ", " reply
 261 or an integer value 0, 1 or 2.  A mask may be optionally provided to limit
 262 the bits of the operation which are matched. A mask is provided by
 263 following the address with a slash and then the mask. It may be provided as
 264 an unsigned 8 bit value representing a bitwise mask. If the mask is missing
 265 then a match on all bits is assumed.
 266 .TP
 267 .BI arp_sha " MASKED_LLADDR"
 268 .TQ
 269 .BI arp_tha " MASKED_LLADDR"
 270 Match on ARP or RARP sender or target MAC address.  A mask may be optionally
 271 provided to limit the bits of the address which are matched. A mask is
 272 provided by following the address with a slash and then the mask. It may be
 273 provided in LLADDR format, in which case it is a bitwise mask, or as a
 274 number of high bits to match. If the mask is missing then a match on all
 275 bits is assumed.
 276 .TP
 277 .BI enc_key_id " NUMBER"
 278 .TQ
 279 .BI enc_dst_ip " PREFIX"
 280 .TQ
 281 .BI enc_src_ip " PREFIX"
 282 .TQ
 283 .BI enc_dst_port " NUMBER"
 284 .TQ
 285 .BI enc_tos " NUMBER"
 286 .TQ
 287 .BI enc_ttl " NUMBER"
 288 .TQ
 289 .BI geneve_opts " OPTIONS"
 290 Match on IP tunnel metadata. Key id
 291 .I NUMBER
 292 is a 32 bit tunnel key id (e.g. VNI for VXLAN tunnel).
 293 .I PREFIX
 294 must be a valid IPv4 or IPv6 address optionally followed by a slash and the
 295 prefix length. If the prefix is missing, \fBtc\fR assumes a full-length
 296 host match.  Dst port
 297 .I NUMBER
 298 is a 16 bit UDP dst port. Tos
 299 .I NUMBER
 300 is an 8 bit tos (dscp+ecn) value, ttl
 301 .I NUMBER
 302 is an 8 bit time-to-live value. geneve_opts
 303 .I OPTIONS
 304 must be a valid list of comma-separated geneve options where each option
 305 consists of a key optionally followed by a slash and corresponding mask. If
 306 the masks is missing, \fBtc\fR assumes a full-length match. The options can
 307 be described in the form CLASS:TYPE:DATA/CLASS_MASK:TYPE_MASK:DATA_MASK,
 308 where CLASS is represented as a 16bit hexadecimal value, TYPE as an 8bit
 309 hexadecimal value and DATA as a variable length hexadecimal value.
 310 .TP
 311 .BI ip_flags " IP_FLAGS"
 312 .I IP_FLAGS
 313 may be either
 314 .BR frag ", " nofrag ", " firstfrag " or " nofirstfrag
 315 where frag and nofrag could be used to match on fragmented packets or not,
 316 respectively. firstfrag and nofirstfrag can be used to further distinguish
 317 fragmented packet. firstfrag can be used to indicate the first fragmented
 318 packet. nofirstfrag can be used to indicates subsequent fragmented packets
 319 or non-fragmented packets.
 320 .SH NOTES
 321 As stated above where applicable, matches of a certain layer implicitly depend
 322 on the matches of the next lower layer. Precisely, layer one and two matches
 323 (\fBindev\fR,  \fBdst_mac\fR and \fBsrc_mac\fR)
 324 have no dependency,
 325 MPLS and layer three matches
 326 (\fBmpls_label\fR, \fBmpls_tc\fR, \fBmpls_bos\fR, \fBmpls_ttl\fR,
 327 \fBip_proto\fR, \fBdst_ip\fR, \fBsrc_ip\fR, \fBarp_tip\fR, \fBarp_sip\fR,
 328 \fBarp_op\fR, \fBarp_tha\fR, \fBarp_sha\fR and \fBip_flags\fR)
 329 depend on the
 330 .B protocol
 331 option of tc filter, layer four port matches
 332 (\fBdst_port\fR and \fBsrc_port\fR)
 333 depend on
 334 .B ip_proto
 335 being set to
 336 .BR tcp ", " udp " or " sctp,
 337 and finally ICMP matches (\fBcode\fR and \fBtype\fR) depend on
 338 .B ip_proto
 339 being set to
 340 .BR icmp " or " icmpv6.
 341 .P
 342 There can be only used one mask per one prio. If user needs to specify different
 343 mask, he has to use different prio.
 344 .SH SEE ALSO
 345 .BR tc (8),
 346 .BR tc-flow (8)