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