tc-ematch

The ematch syntax is used as part of the tc filter add command. The general structure for adding an ematch filter is:

tc filter add dev DEV parent PARENT_ID protocol PROTOCOL prio PRIORITY ematch [EM_CLASSID] [EM_OPTIONS] <match_type> <match_options>

Where:
match_type can be bpf or u32 (most commonly).
match_options are specific to the chosen match_type, e.g., file FILENAME for BPF programs.

match LABEL
    References an existing ematch filter by its unique LABEL, allowing for reuse or chaining of match expressions.

result LABEL
    Assigns a unique LABEL to the current ematch filter, making it referencable by other filters.

index INDEX
    Assigns a specific, numerical INDEX to the ematch filter. This can be used for explicit management or replacement.

donotdisturb
    When specified with an INDEX, prevents the current command from replacing an existing filter with the same INDEX.

noinline
    Specific to BPF, this option prevents the BPF program from being inlined into the kernel's filter chain, potentially useful for debugging or specific performance tuning.

prio PRIORITY
    Assigns a numeric PRIORITY to the ematch filter. Filters with lower priority numbers are evaluated first.

bpf file FILENAME
    Specifies that a Berkeley Packet Filter (BPF) program, loaded from FILENAME, should be used for packet matching. This enables highly custom and complex classification logic.

u32
    Indicates that universal 32-bit matching logic should be used. While u32 is a separate filter type, ematch can wrap its functionality to integrate it into more complex ematch expressions.

The tc-ematch component is an advanced filtering mechanism within the Linux traffic control (tc) framework. It allows administrators to define highly flexible and powerful packet classification rules by extending beyond the capabilities of standard filters like u32 or fw.

While tc provides a variety of filter types, ematch specializes in leveraging external matching logic. Its primary power comes from its ability to integrate with Berkeley Packet Filter (BPF) programs. This means that complex packet inspection and classification rules can be written in a BPF program (often compiled from C code) and then loaded into the kernel via ematch, providing an unparalleled level of customizability.

Beyond BPF, ematch can also act as a wrapper for other match types, such as u32, providing a unified interface for defining complex filter expressions. It is not a standalone command but rather an option used within the tc filter add command, allowing administrators to direct packets to specific qdiscs or classes based on custom criteria.

Using tc-ematch, especially with BPF programs, requires a good understanding of network packet structures and BPF programming. Errors in BPF programs can lead to unexpected behavior or performance issues. Kernel support for BPF and ematch is essential. Debugging complex ematch filters can be challenging, often requiring tools like bpftool or kernel tracing capabilities.

The core strength of tc-ematch lies in its seamless integration with Berkeley Packet Filter (BPF). This allows users to write highly specialized packet analysis and classification logic in a high-level language (like C, then compiled to BPF bytecode) and load it directly into the kernel's data path. This provides unparalleled flexibility for matching based on complex header fields, payload content, or even custom state.

ematch filters can be combined with other tc filters and chained together. The match and result labels provide a mechanism to create intricate logical flows, where the result of one ematch filter can influence the evaluation of subsequent filters in the chain, enabling multi-stage classification.

The ematch functionality was introduced into the iproute2 suite to address the growing need for more flexible and powerful packet classification within the Linux kernel's traffic control subsystem. While basic filters like u32 were powerful for fixed-offset matching, they lacked the expressiveness for dynamic, protocol-aware, or stateful matching. The integration of Berkeley Packet Filter (BPF) capabilities via ematch revolutionized traffic classification, allowing custom C-compiled BPF programs to be loaded into the kernel, enabling complex matching logic previously unattainable. Its development paralleled the increasing prominence and capabilities of BPF within the Linux kernel, becoming a cornerstone for advanced network policy enforcement.

tc(8), tc-filter(8), tc-u32(8), bpftool(8), bpf(2)