bpftool-cgroup(8)

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

🌸 NAME 🌸

bpftool-cgroup — the tool for inspection and simple manipulation of eBPF progs, but make it cgroup-flavored 💅 (this is page 8 of the System Manager's Manual, bestie, we're deep in the system-admin section now ✨)

✨ SYNOPSIS ✨

bpftool [OPTIONS] cgroup COMMAND

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

COMMANDS := { show | list | tree | attach | detach | help }

🎀 CGROUP COMMANDS 🎀

okay so here's the whole menu of things you can do, in their exact little outfits:

bpftool cgroup { show | list } CGROUP [effective]
bpftool cgroup tree [CGROUP_ROOT] [effective]
bpftool cgroup attach CGROUP ATTACH_TYPE PROG [ATTACH_FLAGS]
bpftool cgroup detach CGROUP ATTACH_TYPE PROG
bpftool cgroup help

PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
ATTACH_TYPE := { cgroup_inet_ingress | cgroup_inet_egress |
  cgroup_inet_sock_create | cgroup_sock_ops |
  cgroup_device | cgroup_inet4_bind | cgroup_inet6_bind |
  cgroup_inet4_post_bind | cgroup_inet6_post_bind |
  cgroup_inet4_connect | cgroup_inet6_connect |
  cgroup_unix_connect | cgroup_inet4_getpeername |
  cgroup_inet6_getpeername | cgroup_unix_getpeername |
  cgroup_inet4_getsockname | cgroup_inet6_getsockname |
  cgroup_unix_getsockname | cgroup_udp4_sendmsg |
  cgroup_udp6_sendmsg | cgroup_unix_sendmsg |
  cgroup_udp4_recvmsg | cgroup_udp6_recvmsg |
  cgroup_unix_recvmsg | cgroup_sysctl |
  cgroup_getsockopt | cgroup_setsockopt |
  cgroup_inet_sock_release }
ATTACH_FLAGS := { multi | override }

🦋 DESCRIPTION 🦋

bpftool cgroup { show | list } CGROUP [effective]

Spill the tea on every program attached to the cgroup CGROUP 💖

The output opens with the program ID, then comes the attach type, the attach flags, and the program name. Slay, an order.

If you say effective, you get the effective programs — the ones that will actually run for events inside a cgroup. That means inherited ones plus the attached ones, all together 🫶

bpftool cgroup tree [CGROUP_ROOT] [effective]

This one walks over every cgroup inside CGROUP_ROOT and lists all the attached programs. If you don't hand it a CGROUP_ROOT, bpftool just uses the cgroup v2 mountpoint. (Convenient, iconic, no notes ✨)

The output is giving very similar energy to cgroup show/list: it starts with the absolute cgroup path, then the program ID, attach type, attach flags, and program name.

Say effective and again you get the effective programs that will execute for events within a cgroup — inherited ones and attached ones 💅

bpftool cgroup attach CGROUP ATTACH_TYPE PROG [ATTACH_FLAGS]

Attach program PROG to cgroup CGROUP, using attach type ATTACH_TYPE and optional ATTACH_FLAGS. Main character move tbh.

ATTACH_FLAGS can be one of these two:

  • override — if a sub-cgroup installs some bpf program, the program in this cgroup yields to the sub-cgroup program 🙇
  • multi — if a sub-cgroup installs some bpf program, that cgroup program gets run in addition to the program in this cgroup 🔥

Now the rules, listen up:

Only one program is allowed to be attached to a cgroup with no attach flags, or with the override flag. Attach another one and the old program gets released and the new one takes its place. No cap.

Multiple programs are allowed to attach to a cgroup with multi. They run in FIFO order — first attached, first to run 👑

Non-default ATTACH_FLAGS are supported by kernel version 4.14 and later.

And ATTACH_TYPE can be one of:

  • ingress — ingress path of the inet socket (since 4.10)
  • egress — egress path of the inet socket (since 4.10)
  • sock_create — opening of an inet socket (since 4.10)
  • sock_ops — various socket operations (since 4.12)
  • device — device access (since 4.15)
  • bind4 — call to bind(2) for an inet4 socket (since 4.17)
  • bind6 — call to bind(2) for an inet6 socket (since 4.17)
  • post_bind4 — return from bind(2) for an inet4 socket (since 4.17)
  • post_bind6 — return from bind(2) for an inet6 socket (since 4.17)
  • connect4 — call to connect(2) for an inet4 socket (since 4.17)
  • connect6 — call to connect(2) for an inet6 socket (since 4.17)
  • connect_unix — call to connect(2) for a unix socket (since 6.7)
  • sendmsg4 — call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected udp4 socket (since 4.18)
  • sendmsg6 — call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected udp6 socket (since 4.18)
  • sendmsg_unix — call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected unix socket (since 6.7)
  • recvmsg4 — call to recvfrom(2), recvmsg(2), recvmmsg(2) for an unconnected udp4 socket (since 5.2)
  • recvmsg6 — call to recvfrom(2), recvmsg(2), recvmmsg(2) for an unconnected udp6 socket (since 5.2)
  • recvmsg_unix — call to recvfrom(2), recvmsg(2), recvmmsg(2) for an unconnected unix socket (since 6.7)
  • sysctl — sysctl access (since 5.2)
  • getsockopt — call to getsockopt (since 5.3)
  • setsockopt — call to setsockopt (since 5.3)
  • getpeername4 — call to getpeername(2) for an inet4 socket (since 5.8)
  • getpeername6 — call to getpeername(2) for an inet6 socket (since 5.8)
  • getpeername_unix — call to getpeername(2) for a unix socket (since 6.7)
  • getsockname4 — call to getsockname(2) for an inet4 socket (since 5.8)
  • getsockname6 — call to getsockname(2) for an inet6 socket (since 5.8)
  • getsockname_unix — call to getsockname(2) for a unix socket (since 6.7)
  • sock_release — closing a userspace inet socket (since 5.9)

bpftool cgroup detach CGROUP ATTACH_TYPE PROG

Detach PROG from the cgroup CGROUP, with attach type ATTACH_TYPE. Bye bestie 👋💜

bpftool prog help

Print short help message.

💅 OPTIONS 💅

  • -h, --help — print short help message (similar to bpftool help). Your lil safety net 🫶
  • -V, --version — print bpftool's version number (similar to bpftool version), the number of the libbpf version in use, and the 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).
  • -j, --json — generate JSON output. For commands that cannot produce JSON, this option has no effect. (Not everything is JSON-able, and that's fine 💅)
  • -p, --pretty — generate human-readable JSON output. Implies -j. So pretty, so readable ✨
  • -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. It's giving: everything, all at once 🍓
  • -f, --bpffs — show file names of pinned programs. Pinned prog era 🔥

🔥 EXAMPLES 🔥

Watch and learn, this is the whole ritual:

# mount -t bpf none /sys/fs/bpf/
# mkdir /sys/fs/cgroup/test.slice
# bpftool prog load ./device_cgroup.o /sys/fs/bpf/prog
# bpftool cgroup attach /sys/fs/cgroup/test.slice/ device id 1 allow_multi

# bpftool cgroup list /sys/fs/cgroup/test.slice/

   ID       AttachType      AttachFlags     Name
   1        device          allow_multi     bpf_prog1

# bpftool cgroup detach /sys/fs/cgroup/test.slice/ device id 1
# bpftool cgroup list /sys/fs/cgroup/test.slice/

   ID       AttachType      AttachFlags     Name

And then the list is just… empty. Ate and left no crumbs, literally 😭 (that blank output is the point — the detach worked 🎀)

👑 SEE ALSO 👑

Go read the whole friend group, they're all icons:

okay that's the whole page, bestie 🌈 this was bpftool-cgroup(8) from the System Manager's Manual — section 8, system administration, main character energy only 💖 go forth and attach your progs responsibly, mwah 🧚‍♀️⭐

📦 where this page comes from