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.

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

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.

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

• It changes state. The pin command normally needs elevated privileges.
• It attaches nothing. It does not add a program or change the link's hook. It creates a persistent reference to the selected link.
• Name it for its owner. Pick a name that explains ownership and purpose, and check the path before running the command. The example name has no dot, as the manual requires.
• No bpffs, no pin. If bpffs is not mounted, stop and involve the host administrator. The --nomount option tells bpftool not to attempt automatic mounting of virtual filesystems. It suits controlled environments, but it does not make an unavailable bpffs path usable.

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

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.

6. Sort out common failures

• No executable. The manpage package can be installed while the kernel-specific bpftool binary is missing. Check bpftool version and install the matching tools package.
• No links listed. There may be no active links, or your permissions may hide some. Compare with the service or agent expected to own the link.
• Pin rejected. Check that bpffs is mounted, the destination is inside it, the parent exists, the name is unused and the path contains no dot.
• Stale ID. Link IDs are not durable names. Re-run the listing immediately before acting on an ID.
• Unexpected service behaviour. Inspect the link owner and attachment attributes before considering detach. A force-detach can remove an enforcement or observability hook without stopping the process that created it.