A libbpf-based tool loads and attaches an eBPF program on a Linux host, then the user-space process exits and the program vanishes from `bpftool prog show`. What owns a loaded BPF object's lifetime, and how do you make one outlive the process that loaded it?

## BPF objects are anonymous and refcounted When the `bpf()` syscall loads a program or creates a map, the kernel returns a **file descriptor**. That fd is the handle: there is no global registry you can look a program up in by name, and the numeric IDs shown by `bpftool prog show` are informational, not owning references. The kernel keeps a reference count on each object and frees it — including the map memory, which is charged against the loader's memory accounting — as soon as the count reaches zero. Process exit closes every fd the process held. If those were the only references, the program, its maps and its attachments all disappear at once. This is deliberate and it is a *feature*: a tracing tool that segfaults must not leave kernel programs running forever with no way to find or remove them. ## The three kinds of reference 1. **An open file descriptor** in some process. The default, and the one that dies with the loader. 2. **A pin in bpffs.** The BPF filesystem is a special filesystem type (`mount -t bpf bpffs /sys/fs/bpf`) whose directory entries hold references to BPF objects. Creating one is called pinning; deleting the entry with `rm` unpins. systemd mounts bpffs at `/sys/fs/bpf` on modern distributions, so it is usually already there. 3. **An attachment that the kernel itself owns.** Attaching to a cgroup, or to a network interface hook, records the program in that object, so it survives the loader. This is why a program attached to an interface must be explicitly detached rather than merely having its loader killed — while a kprobe attached through a perf event fd goes away when that fd closes. ## Pinning from the command line ```bash bpftool prog show # find the id bpftool prog pin id 42 /sys/fs/bpf/myprog bpftool map pin id 17 /sys/fs/bpf/mymap bpftool prog show pinned /sys/fs/bpf/myprog rm /sys/fs/bpf/myprog # release the reference ``` A pinned object can be reopened later by a completely different process, which is the standard way to split a tool into a privileged loader and an unprivileged reader: the loader pins the map and exits, the reader opens the pin and polls it. ## Pinning from libbpf - `bpf_object__pin_maps(obj, "/sys/fs/bpf/mytool")` and `bpf_object__pin(obj, path)` pin everything under a directory. - `bpf_map__pin(map, path)` / `bpf_program__pin(prog, path)` pin one object. - `bpf_map__set_pin_path()` before load, or declaring `__uint(pinning, LIBBPF_PIN_BY_NAME)` in the map definition, makes libbpf pin the map automatically under `/sys/fs/bpf/<name>` — and, importantly, **reuse** an existing pin of the same name instead of creating a fresh map. That is how a tool can restart without losing accumulated map contents. - `bpf_link__pin(link, path)` persists the *attachment* for hooks that are otherwise fd-owned. Since the kernel gained `bpf_link` as a first-class object, this is the clean way to keep a tracing attachment alive across a loader restart; `bpftool link pin` does the same from the shell. There is a matching detail on the libbpf side: by default `bpf_link__destroy()` and the skeleton's `__destroy()` detach on exit. If you want persistence you must either pin, or explicitly disown the link so that destroying the user-space handle does not detach the program. ## The operational consequences Persistence cuts both ways. A pinned program is invisible to anyone who does not know to look in `/sys/fs/bpf`, and its maps still consume kernel memory. When you inherit a host and `bpftool prog show` lists programs with no owning process, the pins are where they are anchored — `ls -R /sys/fs/bpf` and `bpftool prog show pinned <path>` will tie them together. Cleanup is filesystem work: remove the pin, and the object goes away once every other reference is gone too. The common interview trap is the opposite direction: an engineer runs a tool, sees the program listed, kills the tool, and is surprised the program is gone. The correct answer is not "a bug" — it is that nothing was holding a reference, and holding one is an explicit act.