Inspect and Manage eBPF Links with bpftool link

Something on this host is filtering packets or tracing syscalls through eBPF, and bpftool link shows you what is attached and where. You will find active links, inspect one as JSON, and pin one into the BPF filesystem. You will also see why link detach is an intervention and not a harmless look. Allow about fifteen minutes. Everything is read-only until the pinning step.

This guide follows the bpftool-link(8) manual installed with linux-tools-common version 6.8.0-139.139. The package is present on the reference machine, but its bpftool executable is not installed for the running kernel. That makes the output below documented output shape, not a claim that it was produced locally. Install the matching tools package before running the commands on that machine.

1. Check the tool and kernel context

Start with ordinary, read-only checks. They tell you which executable is in use and which kernel is underneath it:

$ command -v bpftool
$ uname -r
$ bpftool version

A working installation prints a bpftool version, a libbpf version and any compiled-in optional features. If it warns that bpftool is not available for the running kernel, do not substitute a different version at random. Install the distribution's matching linux-tools package and repeat the checks. The kernel supplies the link data, and support for link types varies by build and release.

Checkpoint: continue only when bpftool version succeeds. You do not need root for the version check, but visibility into every system link can depend on permissions and the host's BPF setup.

2. List active links

Use show or its synonym list with no link selector to see active links:

$ sudo bpftool link show
10: cgroup  prog 25
        cgroup_id 614  attach_type egress
        pids test_progs(223)

The first number is the link ID. The type and named attributes after it describe how the link is attached. This example is a cgroup link for program ID 25, attached with the egress type. A real host can show other link types and attributes, and an empty result just means no visible links at that moment.

The optional -f or --bpffs flag adds the file name of a pinned link when one exists:

$ sudo bpftool --bpffs link list

Tip: a link ID is not a persistent name. IDs describe currently active kernel objects. A pinned path is a filesystem reference that can keep an object available after the creating process closes its file descriptor.

3. Inspect one link as JSON

Once you have an ID, select it with id. Add --json for scripts or --pretty when a person needs readable JSON:

$ sudo bpftool --json --pretty link show id 10
[{
        "type": "cgroup",
        "prog_id": 25,
        "cgroup_id": 614,
        "attach_type": "egress",
        "pids": [{
                "pid": 223,
                "comm": "test_progs"
            }
        ]
    }
]

Use the JSON form when a monitoring script needs stable field names. Process information is kernel-dependent: the manual says bpftool can discover processes holding open file descriptors against BPF links since Linux 5.8. Absent pids data is a limit of the kernel or build. It does not prove that no process ever opened the link.

Checkpoint: the ID in the human-readable listing should match the object the JSON query returns. If the ID has vanished, the link was closed or replaced between the two commands. Query the current listing again instead of reusing a stale ID.

4. Pin a link for another process

Pinning creates a filesystem reference to an existing link. The destination must be inside a mounted bpffs filesystem, and the path must not contain a dot character. Inspect the target directory first and confirm the name is unused:

$ mountpoint /sys/fs/bpf
$ sudo test ! -e /sys/fs/bpf/example-link
$ sudo bpftool link pin id 10 /sys/fs/bpf/example-link
$ sudo bpftool --bpffs link show id 10

To undo only this pin, remove the exact pin path after checking it is the one you created:

$ sudo test -e /sys/fs/bpf/example-link
$ sudo rm /sys/fs/bpf/example-link

Warning: removing the pin removes that filesystem reference only. It does not force-detach the link if another file descriptor or reference still keeps it alive. Treat rm here as a targeted administrative change, and never use a broad wildcard in /sys/fs/bpf.

5. Treat detach as a service-impacting action

bpftool link detach force-detaches the selected link from its BPF hook. The underlying BPF program and link remain valid, and the link becomes defunct until its last open file descriptor closes. Detaching can change traffic filtering, accounting, tracing or another host control immediately, so identify the owner and capture the current listing first.

$ sudo bpftool link show id 10
$ sudo bpftool link detach id 10
$ sudo bpftool link show id 10

There is no general reattach command in this link interface. Recovery depends on whatever created the link: restart or reconfigure that owner using its documented procedure. Removing a pin is not an undo for a detach. Plan a service-specific recovery path before you use this command.

Warning: do not run the detach example against an unfamiliar production link just to test syntax. Use link show and JSON inspection first. If you cannot identify the hook owner, stop at inspection.

6. Sort out common failures

Done means