Inspect and Attach eBPF Programs to cgroups with bpftool

Find out which eBPF programs a cgroup is really running with bpftool cgroup, then attach or detach one safely. You will tell directly attached programs from inherited effective ones, and change state only when you have the 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.

One local wrinkle: this host has the common package, but the kernel-specific bpftool executable is not installed for kernel 6.8.0-139. The checks below show how to detect that. 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 has 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.

3. List programs already attached

List programs directly attached to the target with show or list. The installed manpage treats them as equivalent:

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

The columns are program ID, attach type, flags and program name. An empty table means 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 those 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 your local BPF inventory before changing state.

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 that introduced each family. 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

• multi: programs run in FIFO order, so the first attached runs first.
• override: a program in a sub-cgroup can take precedence over the parent program.
• Kernel support: the manpage records non-default attach flags as supported by kernel 4.14 and later, but the attach type itself still has 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.

Common errors

• bpftool: command not found: the executable is unavailable. That says nothing about whether the cgroup is empty.
• Permission error: the query or state change normally needs elevated privileges.
• Unknown attach type: the spelling is wrong, or the running kernel predates the type.
• Empty direct listing, non-empty effective listing: expected when a parent cgroup supplies the program.