bpftool-link(8)

📦
version 7.8.0+7.3.0 · 11 versions
, in arch rolling, ubuntu stonking

okay bestie, gather round, because this is bpftool-link(8) — straight out of the System Manager's Manual, section 8. It's the tool for inspection and simple manipulation of eBPF links. Yes, links. The little handles that keep your BPF program glued to its hook. Let's get into it 💅

🌸 NAME 🌸

bpftool-link — tool for inspection and simple manipulation of eBPF links 🦋

✨ SYNOPSIS ✨

bpftool [OPTIONS] link COMMAND

OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug } | {
-f | --bpffs } | { -n | --nomount } }

COMMANDS := { show | list | pin | help }

Here's the whole menu, no gatekeeping:

bpftool link { show | list } [LINK]
bpftool link pin LINK FILE
bpftool link detach LINK
bpftool link help

LINK := { id LINK_ID | pinned FILE }

👑 DESCRIPTION 👑

Show info about all your active links, bestie. If you pass LINK, it shows info about only that one link — otherwise it lists every link currently active on the system. Main character energy, one link at a time or the whole squad 🌈

The output starts with the link ID, then the link type, then zero or more named attributes — and some of those attributes depend on the type of link. Like, obviously.

Since Linux 5.8, bpftool is able to discover information about processes that hold open file descriptors (FDs) against BPF links. On kernels like that, bpftool will automatically emit this information too. It's giving ✨thorough✨.

Pin link LINK as FILE. Locking it down, keeping it safe 🎀

⚠️ Note, and this matters: FILE must be located in a bpffs mount. It must not contain a dot character ('.'), because that's reserved for future extensions of bpffs. No dots. Periodt. 💀

Force-detach link LINK. And listen: the BPF link and its underlying BPF program will stay valid, but they will be detached from the respective BPF hook, and the BPF link will transition into a defunct state until the last open file descriptor for that link is closed. So it's not dead, it's just... unmoored. Floating. 🙈

Print a short help message. That's it, that's the whole thing 🫶

🎀 OPTIONS 🎀

  • -h, --help — Print short help message (similar to bpftool help). Your little safety net 🧚
  • -V, --version — Print bpftool's version number (similar to bpftool version), the number of the libbpf version in use, and optional features that were included when bpftool was compiled. Those optional features include linking against LLVM or libbfd to provide the disassembler for JIT-ted programs (bpftool prog dump jited), and usage of BPF skeletons (some features like bpftool prog profile, or showing pids associated to BPF objects, may rely on it). Receipts on demand 🧾
  • -j, --json — Generate JSON output. For commands that can't produce JSON, this option has no effect. No effect! It simply does nothing there, bestie 😭
  • -p, --pretty — Generate human-readable JSON output. Implies -j. So it's basically -j but dressed up 💅
  • -d, --debug — Print all logs available, even debug-level information. This includes logs from libbpf as well as from the verifier, when attempting to load programs. Spill the tea, verifier ☕
  • -f, --bpffs — When showing BPF links, show file names of pinned links. Show-off behaviour, love that for us 🌟
  • -n, --nomount — Do not automatically attempt to mount any virtual file system (such as tracefs or BPF virtual file system) when necessary. Hands off the mounting, thanks 🙅‍♀️

💜 EXAMPLES 💜

okay these are the receipts, copy them exactly:

the classic vibe check

# bpftool link show

   10: cgroup  prog 25
           cgroup_id 614  attach_type egress
           pids test_progs(223)

same energy, but make it JSON

# bpftool --json --pretty link show

   [{
           "type": "cgroup",
           "prog_id": 25,
           "cgroup_id": 614,
           "attach_type": "egress",
           "pids": [{
                   "pid": 223,
                   "comm": "test_progs"
               }
           ]
       }
   ]

pinning, then peeking at the result

# bpftool link pin id 10 /sys/fs/bpf/link
# ls -l /sys/fs/bpf/

   -rw------- 1 root root 0 Apr 23 21:39 link

Look at that. Pinned. Iconic 🔥

🦋 SEE ALSO 🦋

bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8), bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8), bpftool-iter(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-prog(8), bpftool-struct_ops(8), bpftool-token(8)

The whole friend group, fr fr 💖 go read them all, they're all slaying in section 8.

and that's the page bestie! 🌈 this one lives in the System Manager's Manual as bpftool-link(8) — go forth, inspect your links, pin responsibly, and remember: no dots in the bpffs filename. mwah 💅🎀✨

📦 where this page comes from