Inspect and Attach eBPF Programs to cgroups with bpftool

You will inspect the eBPF programs attached to a cgroup, distinguish directly attached programs from inherited effective programs, and safely attach or detach a program when you have the required privileges. Allow about 15 minutes for an existing setup. The examples use the bpftool-cgroup(8) interface shipped by linux-tools-common version 6.8.0-139.139 on this machine.

There is one local wrinkle: this host has the common package, but its kernel-specific bpftool executable is not installed for kernel 6.8.0-139. The checks below show how to detect that condition. Do not install packages as part of a blind copy-and-paste session. Use your normal package-management process, then repeat the checks.

1. Check the executable and kernel support

Start with read-only checks. The first command should print a path. The second prints the package version if the package database contains it:

$ command -v bpftool
$ dpkg-query -W -f='${Package} ${Version}\n' linux-tools-common
linux-tools-common 6.8.0-139.139

On this machine, command -v prints nothing because the kernel-specific executable is absent. A working installation should then report its tool and libbpf versions:

$ bpftool version
bpftool vX.Y.Z
libbpf vX.Y.Z

The exact version is host-specific. Keep it in your change record because supported attach types depend on the kernel and tool versions. If the command is missing, stop here and install the matching Linux tools package through your normal change process.

2. Confirm the cgroup path

Use an existing cgroup rather than creating one just to test an attachment. The path must be a directory in the mounted cgroup hierarchy, and reading its contents is normally harmless:

$ CGROUP='/sys/fs/cgroup/example.slice'
$ test -d "$CGROUP" && echo "cgroup exists"
cgroup exists

Replace /sys/fs/cgroup/example.slice with a real path from your host. The tree command uses the cgroup v2 mountpoint when you omit its root, but an explicit path makes a reviewable command and avoids surveying an unexpectedly large hierarchy.

Checkpoint: identify the target before proceeding. If the path is a production service cgroup, schedule the work with its owner. An attach can change how later socket, device or other kernel events are handled.

3. List programs already attached

List programs directly attached to the target with show or list. These forms are equivalent in the installed manpage:

# bpftool cgroup list "$CGROUP"
ID        AttachType        AttachFlags        Name
123       cgroup_inet_ingress  multi             ingress_filter

The output starts with the program ID, attach type, flags and program name. An empty table means that no program is directly attached at that cgroup; it does not prove that traffic is unfiltered.

Ask for the effective set when inherited programs matter:

# bpftool cgroup list "$CGROUP" effective

Effective output includes programs inherited from ancestor cgroups as well as programs attached to the target. To see paths across a hierarchy, use:

# bpftool cgroup tree "$CGROUP" effective

These inspection commands usually need elevated privileges because they query kernel BPF state. If you only need to check the path, keep that part unprivileged and use sudo only for the bpftool query.

4. Identify the program without guessing

An attach accepts a program by numeric ID, by a pinned BPF filesystem path, or by tag:

# bpftool cgroup attach "$CGROUP" cgroup_inet_ingress id 123
# bpftool cgroup attach "$CGROUP" cgroup_inet_ingress pinned /sys/fs/bpf/ingress_filter
# bpftool cgroup attach "$CGROUP" cgroup_inet_ingress tag 0123456789abcdef

Use one form, not all three. Verify the ID, pin path or tag with the program owner and with your local BPF inventory before changing state. A guessed ID is especially dangerous because IDs are host-specific and can refer to a different program after a restart.

The attach type is part of the policy. For example, cgroup_inet_ingress covers the ingress path of an internet socket, while cgroup_device covers device access. The manpage lists the complete type names and the kernel release in which each family was introduced. Do not shorten them to informal names such as ingress in the command.

5. Choose stacking behaviour before attaching

Use multi only when the programs are designed to run together:

# bpftool cgroup attach "$CGROUP" cgroup_inet_ingress id 123 multi

Programs attached with multi run in FIFO order, with the first attached program running first. With override, a program in a sub-cgroup can take precedence over the parent program. The manpage records non-default attach flags as supported by kernel 4.14 and later, but the actual attach type still needs to be supported by the running kernel.

Verify immediately:

# bpftool cgroup list "$CGROUP" effective

6. Detach the exact program when finished

Detaching changes kernel state and can remove an active control or filter. Record the original listing first. Then use the same cgroup, attach type and program identity:

# bpftool cgroup detach "$CGROUP" cgroup_inet_ingress id 123
# bpftool cgroup list "$CGROUP" effective

For a pinned program, use pinned and the same path instead of id. Detach does not delete the BPF program or its pin; it removes that attachment. If another administrator or service owns the attachment, stop and hand the recorded before-and-after listings to them rather than forcing a repair.

Common errors

bpftool: command not found means the executable is unavailable, not that the cgroup is empty. A permission error normally means the query or state change needs elevated privileges. An unknown attach type can mean that the spelling is wrong or that the running kernel predates the type. An empty direct listing with a non-empty effective listing is expected when a parent cgroup supplies the program.