1.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
  2
  3================
  4bpftool-cgroup
  5================
  6-------------------------------------------------------------------------------
  7tool for inspection and simple manipulation of eBPF progs
  8-------------------------------------------------------------------------------
  9
 10:Manual section: 8
 11
 12.. include:: substitutions.rst
 13
 14SYNOPSIS
 15========
 16
 17**bpftool** [*OPTIONS*] **cgroup** *COMMAND*
 18
 19*OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } }
 20
 21*COMMANDS* :=
 22{ **show** | **list** | **tree** | **attach** | **detach** | **help** }
 23
 24CGROUP COMMANDS
 25===============
 26
 27| **bpftool** **cgroup** { **show** | **list** } *CGROUP* [**effective**]
 28| **bpftool** **cgroup tree** [*CGROUP_ROOT*] [**effective**]
 29| **bpftool** **cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
 30| **bpftool** **cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
 31| **bpftool** **cgroup help**
 32|
 33| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* }
 34| *ATTACH_TYPE* := { **cgroup_inet_ingress** | **cgroup_inet_egress** |
 35|     **cgroup_inet_sock_create** | **cgroup_sock_ops** |
 36|     **cgroup_device** | **cgroup_inet4_bind** | **cgroup_inet6_bind** |
 37|     **cgroup_inet4_post_bind** | **cgroup_inet6_post_bind** |
 38|     **cgroup_inet4_connect** | **cgroup_inet6_connect** |
 39|     **cgroup_unix_connect** | **cgroup_inet4_getpeername** |
 40|     **cgroup_inet6_getpeername** | **cgroup_unix_getpeername** |
 41|     **cgroup_inet4_getsockname** | **cgroup_inet6_getsockname** |
 42|     **cgroup_unix_getsockname** | **cgroup_udp4_sendmsg** |
 43|     **cgroup_udp6_sendmsg** | **cgroup_unix_sendmsg** |
 44|     **cgroup_udp4_recvmsg** | **cgroup_udp6_recvmsg** |
 45|     **cgroup_unix_recvmsg** | **cgroup_sysctl** |
 46|     **cgroup_getsockopt** | **cgroup_setsockopt** |
 47|     **cgroup_inet_sock_release** }
 48| *ATTACH_FLAGS* := { **multi** | **override** }
 49
 50DESCRIPTION
 51===========
 52bpftool cgroup { show | list } *CGROUP* [effective]
 53    List all programs attached to the cgroup *CGROUP*.
 54
 55    Output will start with program ID followed by attach type, attach flags and
 56    program name.
 57
 58    If **effective** is specified retrieve effective programs that will execute
 59    for events within a cgroup. This includes inherited along with attached
 60    ones.
 61
 62bpftool cgroup tree [*CGROUP_ROOT*] [effective]
 63    Iterate over all cgroups in *CGROUP_ROOT* and list all attached programs.
 64    If *CGROUP_ROOT* is not specified, bpftool uses cgroup v2 mountpoint.
 65
 66    The output is similar to the output of cgroup show/list commands: it starts
 67    with absolute cgroup path, followed by program ID, attach type, attach
 68    flags and program name.
 69
 70    If **effective** is specified retrieve effective programs that will execute
 71    for events within a cgroup. This includes inherited along with attached
 72    ones.
 73
 74bpftool cgroup attach *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
 75    Attach program *PROG* to the cgroup *CGROUP* with attach type *ATTACH_TYPE*
 76    and optional *ATTACH_FLAGS*.
 77
 78    *ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs some
 79    bpf program, the program in this cgroup yields to sub-cgroup program;
 80    **multi** if a sub-cgroup installs some bpf program, that cgroup program
 81    gets run in addition to the program in this cgroup.
 82
 83    Only one program is allowed to be attached to a cgroup with no attach flags
 84    or the **override** flag. Attaching another program will release old
 85    program and attach the new one.
 86
 87    Multiple programs are allowed to be attached to a cgroup with **multi**.
 88    They are executed in FIFO order (those that were attached first, run
 89    first).
 90
 91    Non-default *ATTACH_FLAGS* are supported by kernel version 4.14 and later.
 92
 93    *ATTACH_TYPE* can be one of:
 94
 95    - **ingress** ingress path of the inet socket (since 4.10)
 96    - **egress** egress path of the inet socket (since 4.10)
 97    - **sock_create** opening of an inet socket (since 4.10)
 98    - **sock_ops** various socket operations (since 4.12)
 99    - **device** device access (since 4.15)
100    - **bind4** call to bind(2) for an inet4 socket (since 4.17)
101    - **bind6** call to bind(2) for an inet6 socket (since 4.17)
102    - **post_bind4** return from bind(2) for an inet4 socket (since 4.17)
103    - **post_bind6** return from bind(2) for an inet6 socket (since 4.17)
104    - **connect4** call to connect(2) for an inet4 socket (since 4.17)
105    - **connect6** call to connect(2) for an inet6 socket (since 4.17)
106    - **connect_unix** call to connect(2) for a unix socket (since 6.7)
107    - **sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected udp4 socket (since 4.18)
108    - **sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected udp6 socket (since 4.18)
109    - **sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected unix socket (since 6.7)
110    - **recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an unconnected udp4 socket (since 5.2)
111    - **recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an unconnected udp6 socket (since 5.2)
112    - **recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an unconnected unix socket (since 6.7)
113    - **sysctl** sysctl access (since 5.2)
114    - **getsockopt** call to getsockopt (since 5.3)
115    - **setsockopt** call to setsockopt (since 5.3)
116    - **getpeername4** call to getpeername(2) for an inet4 socket (since 5.8)
117    - **getpeername6** call to getpeername(2) for an inet6 socket (since 5.8)
118    - **getpeername_unix** call to getpeername(2) for a unix socket (since 6.7)
119    - **getsockname4** call to getsockname(2) for an inet4 socket (since 5.8)
120    - **getsockname6** call to getsockname(2) for an inet6 socket (since 5.8)
121    - **getsockname_unix** call to getsockname(2) for a unix socket (since 6.7)
122    - **sock_release** closing a userspace inet socket (since 5.9)
123
124bpftool cgroup detach *CGROUP* *ATTACH_TYPE* *PROG*
125    Detach *PROG* from the cgroup *CGROUP* and attach type *ATTACH_TYPE*.
126
127bpftool prog help
128    Print short help message.
129
130OPTIONS
131=======
132.. include:: common_options.rst
133
134-f, --bpffs
135    Show file names of pinned programs.
136
137EXAMPLES
138========
139|
140| **# mount -t bpf none /sys/fs/bpf/**
141| **# mkdir /sys/fs/cgroup/test.slice**
142| **# bpftool prog load ./device_cgroup.o /sys/fs/bpf/prog**
143| **# bpftool cgroup attach /sys/fs/cgroup/test.slice/ device id 1 allow_multi**
144
145**# bpftool cgroup list /sys/fs/cgroup/test.slice/**
146
147::
148
149    ID       AttachType      AttachFlags     Name
150    1        device          allow_multi     bpf_prog1
151
152|
153| **# bpftool cgroup detach /sys/fs/cgroup/test.slice/ device id 1**
154| **# bpftool cgroup list /sys/fs/cgroup/test.slice/**
155
156::
157
158    ID       AttachType      AttachFlags     Name