Support eBPF live filtering on Linux

[ferrieux]

On modern Linux, eBPF is available to do advanced filtering.
In some circumstances, the extra muscle brought by filtering early and in-kernel in zero-copy mode is critical.
One such use case is filtering of live a interface with a haystack of traffic and a needle matching a complex eBPF-expressed criterion.
As a simple example that currently has no efficient solution with tcpdump, is matching an IP address against a large hashtable (like is done in netfilter with ipset or nftables sets)

It would be cool, for this case, to be able to tell tcpdump to load a separately compiled eBPF object file, and attach it to its raw socket with SO_ATTACH_BPF.

Note I'm not advocating for deeper integration, like eBPF-filtering a pcap file, since that has none of the performance requirements above, and arbitrarily complex logic in full-fledged C in userspace can be used instead.

I'm also not proposing (alas) to replicate the beautifully self-contained inline cBPF; in eBPF the heavier ELF machinery makes it unlikely anybody would want to enter a program as a list of comma-separated integers (though I, for one, would love to do it for "return XDP_DROP")

I guess the implementation is straightforward (for sufficiently recent Linux). The only thing that needs thinking I guess is the command-line API. Among possibilities:

• an extension to the pcap_filter language, like ebpf /path/to/program.o[+SEC], with the constraint that it must be alone (no mixing like "port 80 and ebpf /path/to/program.o")
• an option, like -ebpf /path/to/program.o[+SEC]

[infrastation]

For posterity, this originates from the-tcpdump-group/libpcap#1379.

From the "it would be cool" point of view, it would make sense to design such a new feature in a way to allow using cbpf-savefile(5) as a pre-compiled filter as well. In this case the pre-compiled bytecode would have to go to libpcap for the usual processing, including passing it to the kernel on certain OSes (what could possibly go wrong...).

From the "how to keep this feature working long-term?" point of view, such a feature would require some amount of work for the initial implementation and documentation, and then some recurring amount of work to support and maintain it. If the feature becomes popular, the maintenance will require notable amounts of skills and time because the intended audience would be network developers that work on advanced use cases and therefore create or run into advanced problems. Or because the VLAN headers will migrate around. Or because year 2038 will come faster than expected, etc.

Ideally there should be a developer that has a sound use case for this (at least remotely) and the time to get it done properly. Until then it would help at least to document a definition of done. For example, what would be the usual diagnostic steps to tell if a problem belongs to the loaded eBPF bytecode or elsewhere? What statistics would an eBPF filter return?

[ferrieux]

I think you're overdoing it in trying to "bring in" a chunk of responsibility that currently belongs to the Linux kernel.

The eBPF system's (or program's) "problems" are not tcpdump's responsibility, which ends at setsockopt(SO_ATTACH_BPF).
If, in writing the eBPF program, one makes a mistake that keeps/drops packets it shouldn't, then so be it. That's no different from saying in cBPF "ether[0xc:2]==800" instead of ether[0xc:2]==0x800" and being sad about the result.

IMO, agreeing to this Yalta is reasonable, as it adds very little work on the tcpdump side, and none on the kernel side, as the setsockopt() is just being used as documented.

[infrastation]

Power and responsibility normally should be in balance. Let's look for ways to keep this potential feature sustainable. If something does not work as expected, it would be nice to have an easy way for the user to tell — without opening a support ticket — that the problem certainly is at the kernel end of the socket and ideally a sense of the next place to check. Perhaps if you look through the existing open BPF-related issues in libpcap, it will make more sense.

[ferrieux]

Well, there is an easy way: just launch two instances of tcpdump in parallel, one with the filter, the other without.

[Zayed7868]

ChatGPT:

Abstract
We propose extending tcpdump to accept a separately compiled eBPF object, attach it via SO_ATTACH_BPF, and thereby leverage in‑kernel, zero‑copy filtering. This design balances minimal tcpdump‑side complexity with clear diagnostics and sustainable maintenance.

---

1. Command‑Line Interface

Two alternative syntaxes were considered:

# Option 1: Dedicated command-line flag
tcpdump [global‑opts] -ebpf /path/to/filter.o[+SECTION]

# Option 2: Extended BPF syntax in pcap-style expression
tcpdump [global‑opts] 'ebpf /path/to/filter.o[+SECTION]'

We recommend (1) because it cleanly separates eBPF loading from cBPF grammar and avoids complex parser changes.

---

1.1. Syntax

# -ebpf file.o[+SEC]  
# Load the ELF object `file.o`, select section `SEC` (defaults to ".text"),  
# and attach it to the capture socket via SO_ATTACH_BPF.  
# Incompatible with other pcap-style filters.

---

2. Implementation in tcpdump

2.1. High‑level flow

Parse -ebpf

    # Reject usage if additional non-eBPF filters are supplied.
    Reject if any non‑-ebpf filter is present.

Open raw socket (as normal).

    # Create a standard capture socket.

Read ELF file

    # Parse ELF format using libelf or similar to locate the BPF section.

Attach BPF program

    # Attach the BPF program to the socket via a system call.
    ret = setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF,
                     &bpf_program_fd, sizeof(bpf_program_fd));

Proceed to capture

    # Kernel executes eBPF program for packet filtering.
    # tcpdump receives only packets passed by the eBPF logic.

---

2.2. Code sketch

#include <linux/bpf.h>         // Required for BPF program types and syscall constants
#include <sys/socket.h>        // For setsockopt and socket APIs
#include <libelf.h>            // For parsing ELF binaries
#include <fcntl.h>             // For file open flags

/**
 * Attach an eBPF program from a given ELF file section to a raw socket.
 *
 * @param path   Path to the ELF object file.
 * @param sec    Section name within ELF file (e.g., "prog_section").
 * @param sockfd File descriptor of the socket to attach the program to.
 * @return       0 on success; -1 on failure with diagnostic output.
 */
static int
attach_ebpf(const char *path, const char *sec, int sockfd)
{
    int fd, prog_fd, rc;
    struct bpf_object *obj;
    struct bpf_program *prog;

    // Open the ELF file for reading
    fd = open(path, O_RDONLY);
    if (fd < 0) {
        perror(path);  // Output error if file can't be opened
        return -1;
    }

    // Load the eBPF program from the ELF file using libbpf
    if (bpf_prog_load(path, BPF_PROG_TYPE_SOCKET_FILTER, &obj, &prog_fd)) {
        fprintf(stderr, "bpf_prog_load failed\n");
        close(fd);  // Ensure file descriptor is closed on failure
        return -1;
    }

    // Locate the user-specified program section in the ELF
    prog = bpf_object__find_program_by_title(obj, sec);
    if (!prog) {
        fprintf(stderr, "section '%s' not found\n", sec);
        bpf_object__close(obj);  // Clean up object on failure
        return -1;
    }

    // Attach the selected eBPF program to the socket
    rc = setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF,
                    &prog_fd, sizeof(prog_fd));
    if (rc < 0) {
        perror("SO_ATTACH_BPF");  // Print system error
        bpf_object__close(obj);
        return -1;
    }

    // On success, eBPF program is now active on the socket
    return 0;
}

---

3. Diagnostics and Maintainability

Early validation

• Fail at ./configure if kernel headers lack SO_ATTACH_BPF.
• At runtime, detect and report ELF parse errors or missing sections.

Minimal tcpdump responsibility

• Once setsockopt() succeeds, kernel handles the filtering logic.
• Any misbehavior in eBPF bytecode is outside tcpdump’s fault domain.

User‑level debugging

• -v/-vv modes can print the BPF program ID and section.
• Suggest running a parallel “no filter” tcpdump to isolate kernel vs. user issues.

Sustainability

• Upstream dependencies limited to standard libbpf/libelf.
• Documentation in man tcpdump and bpf-savefile(5) pointers.
• Regression tests: verify that invalid ELF or missing SO_ATTACH_BPF generates a clear error.

---

4. Example Usage

# Step 1: Compile your C-based filter program into eBPF format
# -O2        = Optimize for performance
# -target bpf = Compile for BPF backend
# -c          = Compile only, don't link
clang -O2 -target bpf -c filter.c -o filter.o

# Step 2: Run tcpdump and attach the compiled filter
# eth0 = interface to capture from
# filter.o+prog_section = ELF file and section containing the eBPF program
tcpdump -i eth0 -ebpf filter.o+prog_section

Upon success, tcpdump displays packets allowed by the eBPF logic. Others are dropped in-kernel, enhancing performance and precision.

---

Conclusion
This feature delivers substantial performance gains for “needle‑in‑haystack” filtering by pushing logic into the kernel while preserving tcpdump’s architectural simplicity and offering precise failure diagnostics. Maintenance burden remains minimal, confined to core BPF attach logic and documentation.

[guyharris]

On modern Linux, eBPF is available to do advanced filtering.
In some circumstances, the extra muscle brought by filtering early and in-kernel in zero-copy mode is critical.

Presumably meaning that if eBPF filtering is done by user-mode code after the traffic has been provided by the kernel, you wouldn't get the benefits of in-kernel filter, i.e. preventing packets not passing the filter from being copied by the kernel to the shared buffer.

I guess the implementation is straightforward (for sufficiently recent Linux).

As in:

1. have tcpdump call pcap_fileno() after pcap_activate() succeeds;
2. if that fails, report that eBPF filtreing isn't supported;
3. if that succeeds, attempt to attach the eBPF filer to the descriptor returned by pcap_fileno();
4. if that fails in a way that indicates that the descriptor doesn't refer to a socket, report that eBPF filtering isn't supported;
5. if it fails in some other way, report that;
6. if that succeeds, do the rest of the work (except perhaps for setting the filter to the compiled cBPF program) and capture.

[guyharris]

From the "it would be cool" point of view, it would make sense to design such a new feature in a way to allow using cbpf-savefile(5) as a pre-compiled filter as well. In this case the pre-compiled bytecode would have to go to libpcap for the usual processing, including passing it to the kernel on certain OSes (what could possibly go wrong...).

Given that filtering with cBPF code is supported for most capture devices (and, if it's not supported on any, that's a bug and we should fix the corresponding pcap-XXX.c module to do filtering in userland), that would probably best be done in libpcap with a call that would read in a cBPF savefile and fill in a struct bpf_program that could then be used in a pcap_setfilter() call.

[guyharris]

If something does not work as expected, it would be nice to have an easy way for the user to tell — without opening a support ticket — that the problem certainly is at the kernel end of the socket and ideally a sense of the next place to check.

For problems of the "the kernel rejects the eBPF filter" type, we should do our best to translate errnos into error messages that tell the user what the problem is.

For problems of the "the kernel accepts the eBPF filter but it doesn't do what the user intended", we should close any support ticket with "we handed your filter to the kernel; if that doesn't do what you want, that's a problem either with your filter or with the kernel eBPF mechanism, that's not a problem with tcpdump as tcpdump's code isn't involved", so that it's not something on our to-do list to "fix", and perhaps let people add information to the issue if they want to offer debugging help to the user who reported that their eBPF program wasn't doing what they expected.

[guyharris]

Open raw socket (as normal).

    # Create a standard capture socket.

@ChatGPT: you're assuming here that tcpdump opens raw sockets rather than opening capture devices. The latter may or may not involve opening a socket.

[infrastation]

The software-generated comment includes a number of other factual errors and is not a good contribution to the case. @Zayed7868, if you want to make genuine contributions, please take your time to do your homework, to study the project and to prepare your own comments. Otherwise your account will be banned and reported.