TC-FLOW(8)

💖 Flow filter in tc(8) 💖

Okay bestie, this is the manual page for the flow filter from tc(8), the traffic control tool. We're going through the whole thing so you can see how it works. 🦋

✨ NAME ✨

flow is a flow based traffic control filter. It's lowkey iconic. 💅

🎀 SYNOPSIS 🎀

Mapping mode:

tc filter ... flow map key KEY [ OPS ] [ OPTIONS ]

Hashing mode:

tc filter ... flow hash keys KEY_LIST [ perturb secs ] [ OPTIONS
        ]

OPS := [ OPS ] OP

OPTIONS := [ divisor NUM ] [ baseclass ID ] [ match EMATCH_TREE ] [
        action ACTION_SPEC ]

KEY_LIST := [ KEY_LIST ] KEY

OP := { or | and | xor | rshift | addend } NUM

ID := X:Y

KEY := { src | dst | proto | proto-src | proto-dst | iif | priority |
        mark | nfct | nfct-src | nfct-dst | nfct-proto-src | nfct-proto-
        dst | rt-classid | sk-uid | sk-gid | vlan-tag | rxhash }

🌸 DESCRIPTION 🌸

Okay so the flow classifier is meant to level up the SFQ hashing capabilities without hard-coding brand new hash functions. ✨ It also lets you do deterministic mappings of keys to classes, which is so satisfying. 🫶

👑 OPTIONS 👑

• action ACTION_SPEC — Slap an action from the generic actions framework onto matching packets. 💅
• baseclass ID — An offset for the resulting class ID. ID can be root, none, or a hexadecimal class ID in the form [X:]Y. The X has to match the qdisc's or class's major handle, but if you leave it out, the right value gets picked automatically. If you skip the whole baseclass, Y defaults to 1. 🧚
• divisor NUM — The number of buckets to sort into. Keys get calculated modulo NUM. 🍓
• hash keys KEY-LIST — Runs a jhash2 operation over the keys in KEY-LIST. The result (modulo the divisor, if you gave one) becomes the class ID, optionally offset by baseclass. You can also set an interval in seconds after which jhash2's entropy source gets recreated, using the perturb parameter. ⏰
• map key KEY — Packet data identified by KEY gets translated into class IDs to push the packet into. The value can be mangled by OPS before it's used for the mapping. They get applied in the order listed here:
  • and NUM — Bitwise AND with the numeric value NUM. 🔥
  • or NUM — Bitwise OR with the numeric value NUM. 🔥
  • xor NUM — Bitwise XOR with the numeric value NUM. 🔥
  • rshift NUM — Shifts the value of KEY to the right by NUM bits. 🌈
  • addend NUM — Adds NUM to the value of KEY. ✨

For the or, and, xor, and rshift operations, NUM is assumed to be an unsigned, 32bit integer value. For addend, NUM can get much more complex: it can be prefixed with a minus (-) sign to subtract instead of add, and for the keys src, dst, nfct-src, and nfct-dst it can be written in IP address notation. There's an illustrating example down below in EXAMPLES. 👀

• match EMATCH_TREE — Matches packets using the extended match infrastructure. Check out tc-ematch(8) for the full scoop on the allowed syntax in EMATCH_TREE. 🦋

🌈 KEYS 🌈

In mapping mode, a single key gets used (after an optional permutation) to build a class ID. The resulting ID is deducible in most cases. In hashing mode, you can specify a bunch of keys, which then get hashed together and the output is used as the class ID. That ID is not deducible beforehand, and it may even change over time for a given flow if you gave a perturb interval. 🔮

The range of class IDs can be limited by the divisor option, which is used as a modulus. 🧮

• src, dst — Uses the source or destination address as the key. For IPv4 and TIPC, this is the actual address value. For IPv6, the 128bit address gets folded into a 32bit value by XOR'ing the four 32bit words together. In all other cases, the kernel-internal socket address is used (after folding into 32bits on 64bit systems). 🌍
• proto — Uses the layer four protocol number as the key. 🧃
• proto-src — Uses the layer four source port as the key. If it's not available, the kernel-internal socket address gets used instead. 🚪
• proto-dst — Uses the layer four destination port as the key. If that's not available, the associated kernel-internal dst_entry address gets used after XOR'ing with the packet's layer three protocol number. 🚪
• iif — Uses the incoming interface index as the key. 🛣️
• priority — Uses the packet's priority as the key. Usually this is the IP header's DSCP/ECN value. 💁‍♀️
• mark — Uses the netfilter fwmark as the key. 🏷️
• nfct — Uses the associated conntrack entry address as the key. 🕸️
• nfct-src, nfct-dst, nfct-proto-src, nfct-proto-dst — These are the conntrack-aware versions of src, dst, proto-src, and proto-dst. With NAT, these are basically the packet header's values from before NAT was applied. 🕵️‍♀️
• rt-classid — Uses the realm of the packet's destination routing table entry as the key. 🗺️
• sk-uid, sk-gid — For locally generated packets, uses the user or group ID of the originating socket as the key. 🙈
• vlan-tag — Uses the packet's vlan ID as the key. 🎀
• rxhash — Uses the flow hash as the key. 💜

🍓 EXAMPLES 🍓

Classic SFQ hash:

tc filter add ... flow hash \
     keys src,dst,proto,proto-src,proto-dst divisor 1024

Classic SFQ hash, but using information from conntrack so it works properly in combination with NAT:

tc filter add ... flow hash \
     keys nfct-src,nfct-dst,proto,nfct-proto-src,nfct-proto-dst \
     divisor 1024

Map destination IPs of 192.168.0.0/24 to classids 1-256:

tc filter add ... flow map \
     key dst addend -192.168.0.0 divisor 256

Alternative to the above:

tc filter add ... flow map \
     key dst and 0xff

The same, but in reverse order:

tc filter add ... flow map \
     key dst and 0xff xor 0xff

🦋 SEE ALSO 🦋

tc(8), tc-ematch(8), tc-sfq(8)

That's a wrap, bestie! 🫶 This page came from iproute2, dated 20 Oct 2015, and it's giving "Flow filter in tc(8)" forever. 💅✨