TL;DR
The tc-ematch manual documents an extended matching language used by the 'basic', 'cgroup' and 'flow' tc filters. It describes the syntax, available match modules (cmp, meta, nbyte, u32, ipset, ipt, canid), usage examples, and a few operational caveats.
What happened
The tc-ematch manual page defines a compact expression language for packet matching within traffic-control filters. Expressions are composed from terms, logical operators (and, or, not) and module calls that take module-specific arguments. The document lists the grammar elements (EXPR, TERM, MATCH, ARGS) and details individual match modules such as cmp (arithmetic comparisons of packet data), meta (metadata tests), nbyte (byte-sequence checks), u32, ipset membership tests, ipt (xtables matches) and canid for CAN frames. The page supplies example expressions and notes operational caveats — for instance, that parentheses and braces must be escaped from the shell and that ipset behavior on ifb devices treats the original incoming interface specially. The entry credits Thomas Graf for adding the infrastructure and situates the page in the iproute2 project repository.
Why it matters
- Provides a flexible, modular way to express complex packet-match conditions for tc filters.
- Integrates kernel-level metadata and external match sets (ipset, xtables) into traffic-control decisions.
- Offers primitives (byte, numeric, and metadata tests) useful for precise traffic classification.
- Documents important shell-escaping and device-specific behavior that can affect filter rules.
Key facts
- Syntax overview: EXPR := TERM [ { and | or } EXPR ], TERM := [ not ] { MATCH | '(' EXPR ')' }.
- Match modules documented include: cmp, meta, nbyte, u32, ipset, ipt and canid.
- cmp supports arithmetic comparisons on packet data with alignment, offset, layer, mask and trans options.
- meta lets rules test runtime metadata attributes such as random, loadavg_1, nf_mark, vlan and socket buffers.
- nbyte checks packet byte sequences (needle at offset) and accepts string or C-style escape sequences.
- ipset and ipt modules allow testing against ipset sets and xtables matches, respectively, using the same flag conventions as those tools.
- Special-case behavior: when ipset is used with the ifb device, the outgoing device is the ifb itself while the original incoming interface is considered the incoming interface.
- Examples are provided for common uses (cmp, meta, nbyte, u32, ipset, ipt) to illustrate syntax.
- The extended match infrastructure was contributed by Thomas Graf and the page is part of the iproute2 documentation.
What to watch next
- Ensure parentheses and braces in ematch expressions are escaped so the shell does not interpret them.
- When using ipset with an ifb device, be aware the outgoing interface reported will be the ifb device and the original interface is treated as incoming.
- Use 'tc filter add dev eth1 basic match "meta(list)"' to obtain a complete listing of available meta attributes.
Quick glossary
- tc: Traffic-control utility in Linux used to configure queuing disciplines, classes and filters for packet scheduling and shaping.
- ipset: A kernel-level set facility that stores collections of IP addresses, networks or other items for fast membership testing.
- xtables/iptables (ipt): A family of kernel/utility-based packet-matching extensions that can be used by other tooling to apply packet tests implemented in kernel modules.
- ifb: Intermediate functional block device used for ingress processing and offloading of packets; often employed to redirect traffic for shaping.
- CAN: Controller Area Network, a vehicle and industrial standard for serial communication; in this context, CAN frames can be matched by id.
Reader FAQ
What is tc-ematch used for?
It provides an extended expression language for matching packets in 'basic', 'cgroup' and 'flow' tc filters.
Which match types are documented?
The manual lists cmp, meta, nbyte, u32, ipset, ipt and canid modules.
How can I see available meta attributes?
The page shows using a command such as: tc filter add dev eth1 basic match 'meta(list)'.
Who added the extended match infrastructure?
The manual attributes the addition of the extended match infrastructure to Thomas Graf.
man7.org > Linux > man-pages Linux/UNIX system programming training tc-ematch(8) — Linux manual page NAME | SYNOPSIS | MATCHES | CAVEATS | EXAMPLE & USAGE | AUTHOR | COLOPHON ematch(8) Linux ematch(8)…
Sources
- tc-ematch(8) extended matches for use with "basic", "cgroup" or "flow" filters
- ematch – extended matches for use with "basic", "cgroup" or …
- QoS in Linux with TC and Filters
- tc-cgroup(8) — iproute2 — Debian testing
Related posts
- 77 Things Developers Can Avoid in 2026 — and 4 That Are Unavoidable
- Scientists Find Beer Bottle at Challenger Deep, Earth’s Deepest Ocean Point
- Engineered Beige Fat Cells Implanted to Outcompete and Starve Tumors