TC-FLOWER(8)

📦
version 7.3.0 · 4 versions
, in arch rolling, nixpkgs unstable, ubuntu stonking

👑 TC-FLOWER(8) 👑

okay so bestie, this is the manual for tc-flower — the flower filter in tc(8), on Linux. It's giving flow-based traffic control realness. Let's get into it. 🦋

✨ NAME ✨

flower - flow based traffic control filter

🌸 SYNOPSIS 🌸

       tc filter ... flower [ MATCH_LIST ] [ action ACTION_SPEC ] [ classid
               CLASSID ] [ hw_tc TCID ]

       MATCH_LIST := [ MATCH_LIST ] MATCH

       MATCH := { indev ifname | verbose  | skip_sw | skip_hw  | { dst_mac |
               src_mac } MASKED_LLADDR | vlan_id VID | vlan_prio PRIORITY |
               vlan_ethtype { ipv4 | ipv6 | ETH_TYPE } | cvlan_id VID |
               cvlan_prio PRIORITY | cvlan_ethtype { ipv4 | ipv6 | ETH_TYPE } |
               pppoe_sid PSID | ppp_proto { ip | ipv6 | mpls_uc | mpls_mc |
               PPP_PROTO } | mpls LSE_LIST | mpls_label LABEL | mpls_tc TC |
               mpls_bos BOS | mpls_ttl TTL | l2tpv3_sid LSID | ip_proto { tcp |
               udp | sctp | icmp | icmpv6 | l2tp | IP_PROTO } | ip_tos
               MASKED_IP_TOS | ip_ttl MASKED_IP_TTL | { dst_ip | src_ip }
               PREFIX | { dst_port | src_port } { MASKED_NUMBER |
               min_port_number-max_port_number } | tcp_flags MASKED_TCP_FLAGS |
               type MASKED_TYPE | code MASKED_CODE | { arp_tip | arp_sip }
               IPV4_PREFIX | arp_op { request | reply | OP } | { arp_tha |
               arp_sha } MASKED_LLADDR | enc_key_id KEY-ID | { enc_dst_ip |
               enc_src_ip } { ipv4_address | ipv6_address } | enc_dst_port
               port_number | enc_tos TOS | enc_ttl TTL | { geneve_opts |
               vxlan_opts | erspan_opts | gtp_opts | pfcp_opts } OPTIONS |
               ip_flags IP_FLAGS | l2_miss L2_MISS | cfm CFM_OPTIONS |
               enc_flags ENCFLAG-LIST }

       LSE_LIST := [ LSE_LIST ] LSE

       LSE := lse depth DEPTH { label LABEL | tc TC | bos BOS | ttl TTL }

       CFM := cfm mdl LEVEL | op OPCODE

       ENCFLAG-LIST := [ ENCFLAG-LIST/ ] ENCFLAG

       ENCFLAG := { [no]tuncsum | [no]tundf | [no]tunoam | [no]tuncrit }

💖 DESCRIPTION 💖

The flower filter is out here matching flows to the set of keys you specified, and then it assigns an arbitrarily chosen class ID to packets that belong to them. And if that wasn't enough? Additionally (or alternatively, bestie, you can pick), an action from the generic action framework may be called. It's giving multi-purpose. 💅

🎀 OPTIONS 🎀

  • action ACTION_SPEC — slaps an action from the generic actions framework onto matching packets. Go off. ✨
  • classid CLASSID — says which class matching packets get passed on to. CLASSID is in the form X:Y, and X and Y are interpreted as numbers in hexadecimal format. Periodt.
  • hw_tc TCID — picks a hardware traffic class for matching packets to go to. TCID is in the range 0 through 15. 🎀
  • indev ifname — matches on the incoming interface name. Obviously this only makes sense for forwarded flows. ifname is the name of an interface that must exist at the time of tc invocation. No fake friends. 💀
  • verbose — turns on verbose logging, including offloading errors when you're not using the skip_sw flag. Spill the tea. 🫖
  • skip_sw — do not process the filter by software. If hardware has no offload support for this filter, or TC offload is not enabled for the interface, the operation will fail. It's giving all-or-nothing. 😭
  • skip_hw — do not process the filter by hardware. Simple as that. 💅
  • dst_mac MASKED_LLADDR — match on source or destination MAC address. A mask may optionally be provided to limit the bits of the address that are matched. You give the mask by following the address with a slash and then the mask. It may be in LLADDR format, in which case it's a bitwise mask, or as a number of high bits to match. If the mask is missing, a match on all bits is assumed. 💖
  • src_mac MASKED_LLADDR — match on source or destination MAC address. Same mask rules as dst_mac, bestie: optional slash mask, LLADDR format means bitwise mask, or a number of high bits. No mask = match all bits. 🦋
  • num_of_vlans NUM — match on the number of vlan tags in the packet. NUM can be 0 or a small positive integer. Typically in the 0-4 range. 👑
  • vlan_id VID — match on vlan tag id. VID is an unsigned 12bit value in decimal format. ✨
  • vlan_prio PRIORITY — match on vlan tag priority. PRIORITY is an unsigned 3bit value in decimal format. 🌸
  • vlan_ethtype VLAN_ETH_TYPE — match on layer three protocol. VLAN_ETH_TYPE may be either ipv4, ipv6, or an unsigned 16bit value in hexadecimal format. To match on a QinQ packet, it must be 802.1Q or 802.1AD. Not me knowing QinQ lore. 💅
  • cvlan_id VID — match on QinQ inner vlan tag id. VID is an unsigned 12bit value in decimal format. 🎀
  • cvlan_prio PRIORITY — match on QinQ inner vlan tag priority. PRIORITY is an unsigned 3bit value in decimal format. 💖
  • cvlan_ethtype VLAN_ETH_TYPE — match on QinQ layer three protocol. VLAN_ETH_TYPE may be either ipv4, ipv6, or an unsigned 16bit value in hexadecimal format. ✨
  • pppoe_sid PSID — match on PPPoE session id. PSID is an unsigned 16bit value in decimal format. 🦋
  • ppp_proto PPP_PROTO — match on PPP layer three protocol. PPP_PROTO may be either ip, ipv6, mpls_uc, mpls_mc, or an unsigned 16bit value in hexadecimal format. 🌈
  • mpls LSE_LIST — match on the MPLS label stack. LSE_LIST is a list of Label Stack Entries, each introduced by the lse keyword. This option can't be used together with the standalone mpls_label, mpls_tc, mpls_bos, and mpls_ttl options. Choose your fighter. 💀
    • lse LSE_OPTIONS — match on an MPLS Label Stack Entry. LSE_OPTIONS is a list of options that describe the properties of the LSE to match. 👑
      • depth DEPTH — the depth of the Label Stack Entry to consider. Depth starts at 1 (the outermost Label Stack Entry). The maximum usable depth may be limited by the kernel. This option is mandatory. DEPTH is an unsigned 8 bit value in decimal format. 🫶
      • label LABEL — match on the MPLS Label field at the specified depth. LABEL is an unsigned 20 bit value in decimal format. 💅
      • tc TC — match on the MPLS Traffic Class field at the specified depth. TC is an unsigned 3 bit value in decimal format. ✨
      • bos BOS — match on the MPLS Bottom Of Stack field at the specified depth. BOS is a 1 bit value in decimal format. 🎀
      • ttl TTL — match on the MPLS Time To Live field at the specified depth. TTL is an unsigned 8 bit value in decimal format. 🌸
  • mpls_label LABEL — match the label id in the outermost MPLS label stack entry. LABEL is an unsigned 20 bit value in decimal format. 👑
  • mpls_tc TC — match on the MPLS TC field, which is typically used for packet priority, in the outermost MPLS label stack entry. TC is an unsigned 3 bit value in decimal format. 🔥
  • mpls_bos BOS — match on the MPLS Bottom Of Stack field in the outermost MPLS label stack entry. BOS is a 1 bit value in decimal format. 💖
  • mpls_ttl TTL — match on the MPLS Time To Live field in the outermost MPLS label stack entry. TTL is an unsigned 8 bit value in decimal format. 🦋
  • l2tpv3_sid LSID — match on L2TPv3 session id field transported over IPv4 or IPv6. LSID is an unsigned 32 bit value in decimal format. 🌈
  • ip_proto IP_PROTO — match on layer four protocol. IP_PROTO may be tcp, udp, sctp, icmp, icmpv6, l2tp, or an unsigned 8bit value in hexadecimal format. ✨
  • ip_tos MASKED_IP_TOS — match on ipv4 TOS or ipv6 traffic-class — eight bits in hexadecimal format. A mask may optionally be provided to limit the bits which are matched. A mask is provided by following the value with a slash and then the mask. If the mask is missing, a match on all bits is assumed. 💅
  • ip_ttl MASKED_IP_TTL — match on ipv4 TTL or ipv6 hop-limit — eight bits value in decimal or hexadecimal format. A mask may optionally be provided to limit the bits which are matched. Same logic is used for the mask as with matching on ip_tos. 🫶
  • dst_ip PREFIX — match on source or destination IP address. PREFIX must be a valid IPv4 or IPv6 address, depending on the protocol option to tc filter, optionally followed by a slash and the prefix length. If the prefix is missing, tc assumes a full-length host match. 👑
  • src_ip PREFIX — match on source or destination IP address. Same rules as dst_ip, bestie: valid IPv4 or IPv6 address depending on the protocol option to tc filter, optional slash and prefix length, and if the prefix is missing, tc assumes a full-length host match. 💖
  • dst_port { MASKED_NUMBER | MIN_VALUE-MAX_VALUE } — match on layer 4 protocol source or destination port number, with an optional mask. Alternatively, the minimum and maximum values can be specified to match on a range of layer 4 protocol source or destination port numbers. Only available for ip_proto values udp, tcp, and sctp, which have to be specified in beforehand. No cap. 🔥
  • src_port { MASKED_NUMBER | MIN_VALUE-MAX_VALUE } — match on layer 4 protocol source or destination port number, with an optional mask. Alternatively, the minimum and maximum values can be specified to match on a range of layer 4 protocol source or destination port numbers. Only available for ip_proto values udp, tcp, and sctp, which have to be specified in beforehand. 🌸
  • tcp_flags MASKED_TCP_FLAGS — match on TCP flags represented as a 12bit bitfield in hexadecimal format. A mask may optionally be provided to limit the bits which are matched. A mask is provided by following the value with a slash and then the mask. If the mask is missing, a match on all bits is assumed. 🎀
  • type MASKED_TYPE — match on ICMP type or code. A mask may optionally be provided to limit the bits of the address which are matched. A mask is provided by following the address with a slash and then the mask. The mask must be as a number which represents a bitwise mask. If the mask is missing, a match on all bits is assumed. Only available for ip_proto values icmp and icmpv6, which have to be specified in beforehand. 💀
  • code MASKED_CODE — match on ICMP type or code. A mask may optionally be provided to limit the bits of the address which are matched. A mask is provided by following the address with a slash and then the mask. The mask must be as a number which represents a bitwise mask. If the mask is missing, a match on all bits is assumed. Only available for ip_proto values icmp and icmpv6, which have to be specified in beforehand. 😭
  • arp_tip IPV4_PREFIX — match on ARP or RARP sender or target IP address. IPV4_PREFIX must be a valid IPv4 address optionally followed by a slash and the prefix length. If the prefix is missing, tc assumes a full-length host match. 🫶
  • arp_sip IPV4_PREFIX — match on ARP or RARP sender or target IP address. IPV4_PREFIX must be a valid IPv4 address optionally followed by a slash and the prefix length. If the prefix is missing, tc assumes a full-length host match. 💖
  • arp_op ARP_OP — match on ARP or RARP operation. ARP_OP may be request, reply, or an integer value 0, 1, or 2. A mask may optionally be provided to limit the bits of the operation which are matched. A mask is provided by following the address with a slash and then the mask. It may be provided as an unsigned 8 bit value representing a bitwise mask. If the mask is missing, a match on all bits is assumed. Periodt. 💅
  • arp_sha MASKED_LLADDR
  • arp_tha MASKED_LLADDR — match on the ARP or RARP sender or target MAC address, bestie 💖

So here's the tea on the mask: you can optionally slap a mask on there to limit which bits of the address get matched. How? Follow the address with a / and then the mask. The mask can come in LLADDR format — in which case it's a bitwise mask — or you can just give a number of high bits to match. And if you don't give a mask at all? Match on all bits, assumed, periodt.

  • enc_key_id NUMBER
  • enc_dst_ip PREFIX
  • enc_src_ip PREFIX
  • enc_dst_port NUMBER
  • enc_tos NUMBER
  • enc_ttl NUMBER
  • geneve_opts OPTIONS
  • vxlan_opts OPTIONS
  • erspan_opts OPTIONS
  • gtp_opts OPTIONS
  • pfcp_opts OPTIONS — all of these match on IP tunnel metadata ✨

Okay so the shared lore for that whole little squad above, because it's giving "one description, many flags":

  • Key id NUMBER is a 32 bit tunnel key id (like, the VNI for a VXLAN tunnel, iykyk).
  • PREFIX has to be a valid IPv4 or IPv6 address, optionally followed by a / and the prefix length. If the prefix is missing, tc assumes a full-length host match.
  • Dst port NUMBER is a 16 bit UDP dst port.
  • Tos NUMBER is an 8 bit tos (dscp+ecn) value, and ttl NUMBER is an 8 bit time-to-live value.

Now the individual vibes, one by one 🎀

  • geneve_opts OPTIONS — has to be a valid list of comma-separated geneve options, where each option is a key optionally followed by a / and the corresponding mask. No mask? tc assumes a full-length match. You can describe the options in the form CLASS:TYPE:DATA/CLASS_MASK:TYPE_MASK:DATA_MASK, where CLASS is a 16bit hexadecimal value, TYPE is an 8bit hexadecimal value, and DATA is a variable length hexadecimal value. 💅
  • vxlan_opts OPTIONS — does not support multiple options, bestie. It's one key followed by a / and the corresponding mask. No mask = full-length match assumed. The option goes in the form GBP/GBP_MASK, where GBP is a 32bit number.
  • erspan_opts OPTIONS — also does not support multiple options, and again it's a key followed by a / and the corresponding mask. Mask missing → full-length match. Form is VERSION:INDEX:DIR:HWID/VERSION:INDEX_MASK:DIR_MASK:HWID_MASK, where VERSION is an 8bit number, INDEX is an 32bit number, and DIR and HWID are 8bit numbers. Multiple options is not supported. Also important: INDEX/INDEX_MASK gets used when VERSION is 1, and DIR/DIR_MASK and HWID/HWID_MASK get used when VERSION is 2. 👑
  • gtp_opts OPTIONS — does not support multiple options, and yes, it's a key followed by a / and corresponding mask, and yes, no mask means full-length match. The form is PDU_TYPE:QFI/PDU_TYPE_MASK:QFI_MASK where both PDU_TYPE and QFI are 8bit hexadecimal values.
  • pfcp_opts OPTIONS — does not support multiple options. It's a key followed by a / and corresponding mask. If the mask is missing, tc assumes a full-length match. The option goes TYPE:SEID/TYPE_MASK:SEID_MASK where TYPE is an 8bit number and SEID is represented by 64bit. Both TYPE and SEID come in hex. 🫶
  • ct_state CT_STATE
  • ct_zone CT_MASKED_ZONE
  • ct_mark CT_MASKED_MARK
  • ct_label CT_MASKED_LABEL — matches on connection tracking info 🦋

CT_STATE

Match the connection state, and it can be a combination of [{+|-}flag] flags, where flag can be one of:

  • trk — tracked connection.
  • new — new connection.
  • est — established connection.
  • rpl — the packet is in the reply direction, meaning it's going the opposite way from the packet that initiated the connection.
  • inv — the state is invalid. The packet couldn't be associated to a connection.
  • rel — the packet is related to an existing connection.

Example: +trk+est ✨

CT_MASKED_ZONE

Match the connection zone, and yeah, it can be masked. 💅

CT_MASKED_MARK

32bit match on the connection mark, and it can be masked too.

CT_MASKED_LABEL

128bit match on the connection label, and yes bestie, maskable. 🌈

  • ip_flags IP_FLAGS — IP_FLAGS can be either frag, nofrag, firstfrag or nofirstfrag, where frag and nofrag get used to match on fragmented packets or not, respectively. firstfrag and nofirstfrag are here to further distinguish fragmented packets: firstfrag flags the first fragmented packet, and nofirstfrag flags subsequent fragmented packets or non-fragmented packets. 🔥
  • l2_miss L2_MISS — match on layer 2 miss in the bridge driver's FDB / MDB. L2_MISS may be 0 or 1. When 1, match on packets that hit a layer 2 miss. When 0, match on packets that were forwarded using an FDB / MDB entry. > Heads up: broadcast packets do not encounter a miss, because a lookup isn't performed for them. 💀
  • cfm CFM_OPTIONS — match on Connectivity Fault Management (CFM) fields. CFM_OPTIONS is a list of options describing the properties of the CFM information fields to match. 👑

mdl LEVEL

Match on the Maintenance Domain (MD) level field. LEVEL is an unsigned 3 bit value in decimal format.

op OPCODE

Match on the CFM opcode field. OPCODE is an unsigned 8 bit value in decimal format.

  • enc_flags ENCFLAG-LIST — match on tunnel control flags. ENCFLAG-LIST is a list of these tunnel control flags: [no]tuncsum, [no]tundf, [no]tunoam, [no]tuncrit, each one separated by /. 🌸

💭 NOTES 💭

So, like we said above wherever it applies: matches of a certain layer implicitly depend on the matches of the next lower layer. Precisely, bestie, here's the dependency chart of the group chat:

  • Layer one and two matches (indev, dst_mac, src_mac and enc_flags) have no dependency. Free spirits. 🦋
  • MPLS and layer three matches (mpls, mpls_label, mpls_tc, mpls_bos, mpls_ttl, ip_proto, dst_ip, src_ip, arp_tip, arp_sip, arp_op, arp_tha, arp_sha and ip_flags) depend on the protocol option of tc filter.
  • Layer four port matches (dst_port and src_port) depend on ip_proto being set to tcp, udp or sctp.
  • And finally, ICMP matches (code and type) depend on ip_proto being set to icmp or icmpv6. 🎀

Also, and this is the one, okay: there can be only one mask per one prio. If a user needs to specify a different mask, they have to use a different prio. No cap. 😭

👀 SEE ALSO 👀

tc(8), tc-flow(8)

And that's the whole page, bestie, you ate it 💖 It's from iproute2, dated 22 Oct 2015, and the title is Flower filter in tc(8). Go forth and filter, main character 🫶✨👑

📦 where this page comes from