Introduction to eBPF on Android for Network Filtering

Extended Berkeley Packet Filter (eBPF) has revolutionized kernel-level programming, offering a safe, efficient, and programmable way to extend kernel functionality without recompiling the kernel. On Android, eBPF presents a powerful paradigm for advanced network filtering, security monitoring, and performance analysis. Its ability to run custom code within the kernel’s network stack allows for granular control over network traffic, enabling sophisticated firewalls, traffic shaping, and deep packet inspection with minimal overhead. However, developing and debugging eBPF programs, especially for network filtering on the diverse Android ecosystem, comes with unique challenges.

Android’s customized kernels, stringent SELinux policies, and often limited userspace tooling complicate the eBPF development lifecycle. While the core eBPF verifier ensures program safety, understanding its rejection messages and effectively debugging program logic requires a systematic approach. This article provides an expert-level guide to troubleshooting common network filtering issues encountered when developing eBPF programs on Android.

Common Pitfalls in eBPF Network Filtering on Android

1. Kernel Compatibility and Configuration

Android devices run a wide array of Linux kernels, often with varying eBPF feature sets and configurations. An eBPF program compiled for a newer kernel or with specific `CONFIG_BPF_FEATURES` might fail to load or behave unexpectedly on an older or differently configured Android kernel. Key areas to check include:

• Kernel Version: Verify the target Android device’s kernel version (`uname -r`) and ensure it supports the necessary eBPF features (e.g., specific helper functions, map types).
• BPF Configurations: Ensure kernel configuration options like `CONFIG_BPF`, `CONFIG_BPF_SYSCALL`, `CONFIG_NET_CLS_BPF`, `CONFIG_BPF_JIT` are enabled. These can often be inspected via `/proc/config.gz` if available, or by checking kernel source code for the device.

2. SELinux Restrictions

SELinux on Android is a Mandatory Access Control (MAC) system that heavily restricts kernel operations, including eBPF program loading and map interactions. Even with root privileges, SELinux might prevent an eBPF program from being loaded or attached, or restrict access to maps. Symptoms include `Permission denied` errors or mysterious failures.

• Audit Logs: Always check `adb shell dmesg | grep ‘avc:’` or `adb shell auditctl -l` (if auditd is running) for SELinux denials.
• Context: Ensure the process loading/attaching the eBPF program has the necessary SELinux context and permissions. This often requires careful policy adjustments, which can be complex on production Android.

3. Inadequate Tooling and `libbpf` Availability

Unlike standard Linux distributions, Android devices often lack `bpftool`, `iproute2` with BPF support, or a readily available `libbpf` in their userspace. This makes loading, inspecting, and managing eBPF programs challenging.

• Cross-compilation: You might need to cross-compile `libbpf` and `bpftool` for your Android target architecture.
• Custom Loaders: Often, a custom userspace C/C++ loader program using the raw `bpf()` syscall or a minimal `libbpf` port is required.

4. Incorrect Attach Points and Contexts

Network filtering eBPF programs typically attach to Traffic Control (TC) ingress/egress hooks or socket-related hooks. Misunderstanding the context or available helper functions at a specific attach point is a common source of errors.

• TC Filters: For `tc` filters, the `bpf_prog_type` is `BPF_PROG_TYPE_SCHED_CLS`. Helper functions like `bpf_skb_load_bytes`, `bpf_skb_store_bytes`, `bpf_clone_redirect` operate on `sk_buff` structures.
• Socket Filters: For socket-level filtering (`SO_ATTACH_BPF`), the `bpf_prog_type` is `BPF_PROG_TYPE_SOCKET_FILTER`.
• XDP (eXpress Data Path): While highly performant, XDP support on Android kernels is less common and requires specific kernel configurations.

Debugging Methodology and Tools

1. Initial Checks and Kernel Logs

Start by checking kernel logs for immediate errors during program load or attachment.

adb shell dmesg | grep -i bpf

This will reveal verifier output, which is crucial for understanding why a program failed to load (e.g., invalid instruction, out of bounds access, excessive complexity). Look for messages like ‘BPF: R0 type invalid’ or ‘BPF: function call with incorrect arguments’.

2. In-Program Debugging with `bpf_trace_printk`

The most straightforward way to debug eBPF program logic is by using `bpf_trace_printk`. This helper function prints messages to the kernel trace buffer, accessible via `dmesg` or `trace_pipe`.

Example eBPF C code snippet:

#include <linux/bpf.h> #include <linux/pkt_cls.h> #include <bpf/bpf_helpers.h>  SEC("tc") int my_bpf_filter(struct __sk_buff *skb) {     // Trace initial packet length     bpf_trace_printk("BPF: Pkt len: %dn", skb->len);      // Example: Drop IPv6 packets     if (skb->protocol == bpf_htons(ETH_P_IPV6)) {         bpf_trace_printk("BPF: Dropping IPv6 packetn");         return TC_ACT_SHOT; // Drop packet     }      // Example: Log source IP for IPv4 packets     if (skb->protocol == bpf_htons(ETH_P_IP)) {         __u32 ip_src;         bpf_skb_load_bytes(skb, ETH_HLEN + offsetof(struct iphdr, saddr), &ip_src, sizeof(ip_src));         bpf_trace_printk("BPF: IPv4 Pkt from: %xn", bpf_ntohl(ip_src));     }      return TC_ACT_OK; // Allow packet }  char _license[] SEC("license") = "GPL";

To view the output:

adb shell "cat /sys/kernel/debug/tracing/trace_pipe | grep BPF"

This command continuously streams the trace buffer and filters for lines containing