]>
Commit | Line | Data |
---|---|---|
014cb63b | 1 | .\" Copyright (C) 2015 Serge Hallyn <serge@hallyn.com> |
43df1ab3 | 2 | .\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> |
014cb63b MK |
3 | .\" |
4 | .\" %%%LICENSE_START(VERBATIM) | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
3df541c0 | 26 | .TH CGROUPS 7 2016-07-17 "Linux" "Linux Programmer's Manual" |
21f0d132 MK |
27 | .SH NAME |
28 | cgroups \- Linux control groups | |
29 | .SH DESCRIPTION | |
30 | Control cgroups, usually referred to as cgroups, | |
8bff7140 MK |
31 | are a Linux kernel feature which which allow processes to |
32 | be organized into hierarchical groups whose usage of | |
33 | various types of resources can then be limited and monitored. | |
34 | The kernel's cgroup interface is provided through | |
21f0d132 | 35 | a pseudo-filesystem called cgroupfs. |
6398ca15 | 36 | Grouping is implemented in the core cgroup kernel code, |
21f0d132 | 37 | while resource tracking and limits are implemented in |
8bff7140 | 38 | a set of per-resource-type subsystems (memory, CPU, and so on). |
21f0d132 | 39 | .\" |
176a4211 MK |
40 | .SS Terminology |
41 | A | |
42 | .I cgroup | |
43 | is a collection of processes that are bound to a set of | |
44 | limits or parameters defined via the cgroup filesystem. | |
45 | ||
46 | A | |
47 | .I subsystem | |
48 | is a kernel component that modifies the behavior of | |
49 | the processes in a cgroup. | |
50 | Various subsystems have been implemented, making it possible to do things | |
51 | such as limiting the amount of CPU time and memory available to a cgroup, | |
52 | accounting for the CPU time used by a cgroup, | |
53 | and freezing and resuming execution of the processes in a cgroup. | |
54 | Subsystems are sometimes also known as | |
55 | .IR "resource controllers" | |
56 | (or simply, controllers). | |
57 | ||
55f52de8 | 58 | The cgroups for a controller are arranged in a |
176a4211 MK |
59 | .IR hierarchy . |
60 | This hierarchy is defined by creating, removing, and | |
61 | renaming subdirectories within the cgroup filesystem. | |
8fc9db1e MK |
62 | At each level of the hierarchy, attributes (e.g., limits) can be defined. |
63 | The limits, control, and accounting provided by cgroups generally have | |
64 | effect throughout the subhierarchy underneath the cgroup where the | |
65 | attributes are defined. | |
8bff7140 MK |
66 | Thus, for example, the limits placed on |
67 | a cgroup at a higher level in the hierarchy cannot be exceeded | |
68 | by descendant cgroups. | |
176a4211 | 69 | .\" |
43df1ab3 MK |
70 | .SS Cgroups version 1 and version 2 |
71 | The initial release of the cgroups implementation was in Linux 2.6.24. | |
55f52de8 | 72 | Over time, various cgroup controllers have been added |
43df1ab3 | 73 | to allow the management of various types of resources. |
55f52de8 MK |
74 | However, the development of these controllers was largely uncoordinated, |
75 | with the result that many inconsistencies arose between controllers | |
43df1ab3 MK |
76 | and management of the cgroup hierarchies became rather complex. |
77 | (A longer description of these problems can be found in | |
78 | the kernel source file | |
0a837899 | 79 | .IR Documentation/cgroup\-v2.txt .) |
43df1ab3 | 80 | |
813d9220 MK |
81 | Because of the problems with the initial cgroups implementation |
82 | (cgroups version 1), | |
43df1ab3 MK |
83 | starting in Linux 3.10, work began on a new, |
84 | orthogonal implementation to remedy these problems. | |
85 | Initially marked experimental, and hidden behind the | |
86 | .I "\-o\ __DEVEL__sane_behavior" | |
87 | mount option, the new version (cgroups version 2) | |
88 | was eventually made official with the release of Linux 4.5. | |
89 | Differences between the two versions are described in the text below. | |
90 | ||
91 | Although cgroups v2 is intended as a replacement for cgroups v1, | |
92 | the older system continues to exist | |
93 | (and for compatibility reasons is unlikely to be removed). | |
94 | Currently, cgroups v2 implements only a subset of the controllers | |
95 | available in cgroups v1. | |
96 | The two systems are implemented so that both v1 controllers and | |
97 | v2 controllers can be mounted on the same system. | |
98 | Thus, for example, it is possible to use those controllers | |
99 | that are supported under version 2, | |
100 | while also using version 1 controllers | |
101 | where version 2 does not yet support those controllers. | |
1a90a85e MK |
102 | The only restriction here is that a controller can't be simultaneously |
103 | employed in both a cgroups v1 hierarchy and in the cgroups v2 hierarchy. | |
43df1ab3 | 104 | .\" |
8bff7140 MK |
105 | .SS Cgroups version 1 |
106 | Under cgroups v1, each controller may be mounted against a separate | |
107 | cgroup filesystem that provides its own hierarchical organization of the | |
108 | processes on the system. | |
109 | It is also possible comount multiple (or even all) cgroups v1 controllers | |
110 | against the same cgroup filesystem, meaning that the comounted controllers | |
111 | manage the same hierarchical organization of processes. | |
112 | ||
113 | For each mounted hierarchy, | |
114 | the directory tree mirrors the control group hierarchy. | |
115 | Each control group is represented by a directory, with each of its child | |
116 | control cgroups represented as a child directory. | |
117 | For instance, | |
118 | .IR /user/joe/1.session | |
119 | represents control group | |
120 | .IR 1.session , | |
121 | which is a child of cgroup | |
122 | .IR joe , | |
123 | which is a child of | |
124 | .IR /user . | |
125 | Under each cgroup directory is a set of files which can be read or | |
126 | written to, reflecting resource limits and a few general cgroup | |
127 | properties. | |
128 | ||
129 | In addition, in cgroups v1, | |
55f52de8 | 130 | cgroups can be mounted with no bound controller, in which case |
8bff7140 | 131 | they serve only to track processes. |
59dabd75 | 132 | (See the discussion of release notification below.) |
8bff7140 MK |
133 | An example of this is the |
134 | .I name=systemd | |
135 | cgroup which is used by | |
136 | .BR systemd (1) | |
137 | to track services and user sessions. | |
138 | .\" | |
6398ca15 | 139 | .SS Tasks (threads) versus processes |
c775bca2 MK |
140 | In cgroups v1, a distinction is drawn between |
141 | .I processes | |
142 | and | |
143 | .IR tasks . | |
144 | In this view, a process can consist of multiple tasks | |
6398ca15 MK |
145 | (more commonly called threads, from a user-space perspective, |
146 | and called such in the remainder of this man page). | |
0ec74e08 | 147 | In cgroups v1, it is possible to independently manipulate |
6398ca15 | 148 | the cgroup memberships of the threads in a process. |
c775bca2 MK |
149 | Because this ability caused certain problems, |
150 | .\" FIXME Add some text describing why this was a problem. | |
151 | the ability to independently manipulate the cgroup memberships | |
6398ca15 | 152 | of the threads in a process has been removed in cgroups v2. |
c775bca2 MK |
153 | Cgroups v2 allows manipulation of cgroup membership only for processes |
154 | (which has the effect of changing the cgroup membership of | |
6398ca15 | 155 | all threads in the process). |
c775bca2 | 156 | .\" |
77e0a626 MK |
157 | .SS Mounting v1 controllers |
158 | The use of cgroups requires a kernel built with the | |
159 | .BR CONFIG_CGROUP\option. | |
160 | In addition, each of the v1 controllers has an associated | |
161 | configuration option that must be set in order to employ that controller. | |
effa83ce | 162 | |
77e0a626 MK |
163 | In order to use a v1 controller, |
164 | it must be mounted against a cgroup filesystem. | |
165 | The usual place for such mounts is under a tmpfs filesystem mounted at | |
166 | .IR /sys/fs/cgroup . | |
167 | Thus, one might mount the | |
168 | .I cpu | |
169 | controller as follows: | |
34d725f6 | 170 | |
77e0a626 MK |
171 | .nf |
172 | .in +4n | |
173 | mount \-t cgroup \-o cpu none /sys/fs/cgroup/cpu | |
174 | .in | |
175 | .fi | |
effa83ce | 176 | |
77e0a626 MK |
177 | It is possible to comount multiple controllers against the same hierarchy. |
178 | For example, here the | |
179 | .IR cpu | |
21f0d132 | 180 | and |
77e0a626 MK |
181 | .IR cpuacct |
182 | controllers are comounted against a single hierarchy: | |
21f0d132 MK |
183 | |
184 | .nf | |
185 | .in +4n | |
77e0a626 | 186 | mount \-t cgroup \-o cpu,cpuacct none /sys/fs/cgroup/cpu,cpuacct |
21f0d132 MK |
187 | .in |
188 | .fi | |
effa83ce | 189 | |
55f52de8 | 190 | Comounting controllers has the effect that a process is in the same cgroup for |
77e0a626 | 191 | all of the comounted controllers. |
55f52de8 | 192 | Separately mounting controllers allows a process to |
21f0d132 MK |
193 | be in cgroup |
194 | .I /foo1 | |
55f52de8 | 195 | for one controller while being in |
21f0d132 MK |
196 | .I /foo2/foo3 |
197 | for another. | |
77e0a626 MK |
198 | |
199 | It is possible to comount all v1 controllers against the same hierarchy: | |
200 | ||
201 | .nf | |
202 | .in +4n | |
203 | mount \-t cgroup \-o all cgroup /sys/fs/cgroup | |
204 | .in | |
205 | .fi | |
206 | ||
207 | (One can achieve the same result by omitting | |
208 | .IR "\-o all" , | |
209 | since it is the default if no controllers are explicitly specified.) | |
210 | ||
211 | Note that on many systems, the v1 controllers are automatically mounted under | |
212 | .IR /sys/fs/cgroup ; | |
213 | in particular, | |
214 | .BR systemd (1) | |
215 | automatically creates such mount points. | |
21f0d132 | 216 | .\" |
6398ca15 | 217 | .SS Creating cgroups and moving processes |
9ed582ac | 218 | A cgroup filesystem initially contains a single root cgroup, '/', |
6398ca15 | 219 | which all processes belong to. |
21f0d132 MK |
220 | A new cgroup is created by creating a directory in the cgroup filesystem: |
221 | ||
222 | mkdir /sys/fs/cgroup/cpu/cg1 | |
223 | ||
224 | This creates a new empty cgroup. | |
87402a2e MK |
225 | Processes may be moved to this cgroup by writing |
226 | their PIDs into the cgroup's | |
21f0d132 | 227 | .I cgroup.procs |
21f0d132 MK |
228 | file: |
229 | ||
230 | echo $$ > /sys/fs/cgroup/cpu/cg1/cgroup.procs | |
231 | ||
87402a2e | 232 | The same file can be read to obtain a list of the processes |
6398ca15 | 233 | that are currently in |
21f0d132 | 234 | .IR cg1 . |
6398ca15 MK |
235 | When writing a PID into the |
236 | .IR cgroup.procs , | |
87402a2e MK |
237 | all threads in the process are moved into the new cgroup at once. |
238 | ||
239 | In cgroups v1 (but not cgroups v2), an individual thread can be moved to | |
240 | another cgroup by writing its thread ID | |
241 | (i.e., the kernel thread ID returned by | |
242 | .BR clone (2) | |
243 | and | |
244 | .BR gettid (2)) | |
245 | to the | |
246 | .IR tasks | |
247 | file in a cgroup directory. | |
248 | This file can be read to discover the set of threads | |
249 | that are members of the cgroup. | |
250 | This file is not present in cgroup v2 directories. | |
21f0d132 | 251 | |
81833969 MK |
252 | A child process created via |
253 | .BR fork (2) | |
254 | inherits its parent's cgroup memberships. | |
255 | A process's cgroup memberships are preserved across | |
256 | .BR execve (2). | |
b43be47e MK |
257 | .\" |
258 | .SS Removing cgroups | |
259 | To remove a cgroup, | |
260 | it must first have no child cgroups and contain no (nonzombie) processes. | |
261 | So long as that is the case, one can simply | |
262 | remove the corresponding directory pathname. | |
263 | Note that files in a cgroup directory cannot and need not be | |
264 | removed. | |
265 | .\" | |
266 | .SS Cgroups version 2 | |
267 | In cgroups v2, | |
268 | all mounted controllers reside in a single unified hierarchy. | |
269 | While (different) controllers may be simultaneously | |
270 | mounted under the v1 and v2 hierarchies, | |
271 | it is not possible to mount the same controller simultaneously | |
272 | under both the v1 and the v2 hierarchies. | |
273 | ||
274 | The new behaviors in cgroups v2 are summarized below: | |
275 | .TP 3 | |
276 | 1. Processes only in leaf nodes | |
277 | With the exception of the root cgroup, processes may reside only in leaf nodes. | |
278 | This avoids the need to decide how to partition resources between | |
279 | processes which are members of cgroup A and processes in child cgroups of A. | |
effa83ce | 280 | |
21f0d132 MK |
281 | For instance, if cgroup |
282 | .I /cg1/cg2 | |
6398ca15 | 283 | exists, then a process may reside in |
21f0d132 MK |
284 | .IR /cg1/cg2 , |
285 | but not in | |
286 | .IR /cg1 . | |
3ddb25ac MK |
287 | This is to avoid an ambiguity cgroups v1 |
288 | with respect to the delegation of resources between processes in | |
21f0d132 MK |
289 | .I /cg1 |
290 | and its child cgroups. | |
3ddb25ac | 291 | The recommended approach in cgroups v2 is to create a subdirectory called |
21f0d132 | 292 | .I leaf |
3ddb25ac MK |
293 | for any nonleaf cgroup which should contain processes, but no child cgroups. |
294 | Thus, processes which previously would have gone into | |
21f0d132 MK |
295 | .I /cg1 |
296 | would now go into | |
297 | .IR /cg1/leaf . | |
3ddb25ac MK |
298 | This has the advantage of making explicit |
299 | the relationship between processes in | |
21f0d132 MK |
300 | .I /cg1/leaf |
301 | and | |
302 | .IR /cg1 's | |
303 | other children. | |
21f0d132 | 304 | .TP |
effa83ce | 305 | 2. Active cgroups must be specified |
21f0d132 MK |
306 | The unified hierarchy presents two new files, |
307 | .IR cgroup.controllers | |
308 | and | |
309 | .IR cgroup.subtree_control . | |
310 | When a cgroup | |
311 | .I A/b | |
312 | is created, its | |
313 | .IR cgroup.controllers | |
effa83ce | 314 | file contains the list of controllers which were active in its parent, A. |
21f0d132 MK |
315 | This is the list of controllers which are available to this cgroup. |
316 | No controllers are active until they are enabled through the | |
317 | .IR cgroup.subtree_control | |
df6f53cc | 318 | file, by writing the list of space-delimited names of the controllers, |
0a837899 | 319 | each preceded by '+' (to enable) or '\-' (to disable). |
21f0d132 MK |
320 | If the |
321 | .I freezer | |
322 | controller is not enabled in | |
323 | .IR /A/B , | |
324 | then it cannot be enabled in | |
325 | .IR /A/B/C . | |
326 | .TP | |
effa83ce | 327 | 3. No "tasks" or "cgroup.clone_children" files |
21f0d132 | 328 | .TP |
effa83ce | 329 | 4. Empty cgroup notification |
21f0d132 MK |
330 | A new file, |
331 | .IR cgroup.populated , | |
332 | under each cgroup contains '0' when the | |
333 | cgroup is empty, and 1 when it is populated. | |
334 | It therefore may be watched to detect when a cgroup becomes (non-)empty. | |
335 | This replaces the original notify-on-release mechanism. | |
56daf0c4 | 336 | .PP |
e466137a | 337 | For more changes, see the |
2a8ef76b | 338 | .I Documentation/cgroup-v2.txt |
effa83ce | 339 | file in the kernel source. |
21f0d132 | 340 | .\" |
55f52de8 MK |
341 | .SS Cgroups version 1 controllers |
342 | Each of the cgroups version 1 controllers is governed | |
96c55745 MK |
343 | by a kernel configuration option (listed below). |
344 | Additionally, the availability of the cgroups feature is governed by the | |
345 | .BR CONFIG_CGROUPS | |
346 | kernel configuration option. | |
21f0d132 | 347 | .TP |
96c55745 | 348 | .IR cpu " (since Linux 2.6.24; " \fBCONFIG_CGROUP_SCHED\fP ) |
94eeedfd | 349 | Cgroups can be guaranteed a minimum number of "CPU shares" |
f0d27655 MK |
350 | when a system is busy. |
351 | This does not limit a cgroup's CPU usage if the CPUs are not busy. | |
cfb51917 MK |
352 | |
353 | Further information can be found in the kernel source file | |
354 | .IR Documentation/scheduler/sched\-bwc.txt . | |
f0d27655 | 355 | .TP |
96c55745 | 356 | .IR cpuacct " (since Linux 2.6.24; " \fBCONFIG_CGROUP_CPUACCT\fP ) |
6398ca15 | 357 | This provides accounting for CPU usage by groups of processes. |
cfb51917 MK |
358 | |
359 | Further information can be found in the kernel source file | |
360 | .IR Documentation/cgroup\-v1/cpuacct.txt . | |
f0d27655 | 361 | .TP |
96c55745 | 362 | .IR cpuset " (since Linux 2.6.24; " \fBCONFIG_CPUSETS\fP ) |
6398ca15 | 363 | This cgroup can be used to bind the processes in a cgroup to |
21f0d132 | 364 | a specified set of CPUs and NUMA nodes. |
cfb51917 MK |
365 | |
366 | Further information can be found in the kernel source file | |
367 | .IR Documentation/cgroup\-v1/cpusets.txt . | |
21f0d132 | 368 | .TP |
96c55745 | 369 | .IR memory " (since Linux 2.6.25; " \fBCONFIG_MEMCG\fP ) |
f0d27655 MK |
370 | The memory controller supports reporting and limiting of process memory, kernel |
371 | memory, and swap used by cgroups. | |
cfb51917 MK |
372 | |
373 | Further information can be found in the kernel source file | |
374 | .IR Documentation/cgroup\-v1/memory.txt . | |
21f0d132 | 375 | .TP |
96c55745 | 376 | .IR devices " (since Linux 2.6.26; " \fBCONFIG_CGROUP_DEVICE\fP ) |
6398ca15 | 377 | This supports controlling which processes may create (mknod) devices as |
21f0d132 MK |
378 | well as open them for reading or writing. |
379 | The policies may be specified as whitelists and blacklists. | |
380 | Hierarchy is enforced, so new rules must not | |
effa83ce | 381 | violate existing rules for the target or ancestor cgroups. |
cfb51917 MK |
382 | |
383 | Further information can be found in the kernel source file | |
384 | .IR Documentation/cgroup-v1/devices.txt . | |
21f0d132 | 385 | .TP |
96c55745 | 386 | .IR freezer " (since Linux 2.6.28; " \fBCONFIG_CGROUP_FREEZER\fP ) |
21f0d132 | 387 | The |
96c55745 | 388 | .IR freezer |
6398ca15 | 389 | cgroup can suspend and restore (resume) all processes in a cgroup. |
21f0d132 MK |
390 | Freezing a cgroup |
391 | .I /A | |
6398ca15 | 392 | also causes its children, for example, processes in |
21f0d132 | 393 | .IR /A/B , |
effa83ce | 394 | to be frozen. |
cfb51917 MK |
395 | |
396 | Further information can be found in the kernel source file | |
397 | .IR Documentation/cgroup-v1/freezer-subsystem.txt . | |
21f0d132 | 398 | .TP |
96c55745 | 399 | .IR net_cls " (since Linux 2.6.29; " \fBCONFIG_CGROUP_NET_CLASSID\fP ) |
effa83ce | 400 | This places a classid, specified for the cgroup, on network packets |
21f0d132 MK |
401 | created by a cgroup. |
402 | These classids can then be used in firewall rules, | |
403 | as well as used to shape traffic using | |
404 | .BR tc (8). | |
813d9220 | 405 | This applies only to packets |
effa83ce | 406 | leaving the cgroup, not to traffic arriving at the cgroup. |
cfb51917 MK |
407 | |
408 | Further information can be found in the kernel source file | |
e39fcffa | 409 | .IR Documentation/cgroup-v1/net_cls.txt . |
21f0d132 | 410 | .TP |
96c55745 | 411 | .IR blkio " (since Linux 2.6.33; " \fBCONFIG_BLK_CGROUP\fP ) |
f0d27655 MK |
412 | The |
413 | .I blkio | |
9e48d04d | 414 | cgroup controls and limits access to specified block devices by |
f0d27655 MK |
415 | applying IO control in the form of throttling and upper limits against leaf |
416 | nodes and intermediate nodes in the storage hierarchy. | |
417 | ||
418 | Two policies are available. | |
419 | The first is a proportional-weight time-based division | |
420 | of disk implemented with CFQ. | |
421 | This is in effect for leaf nodes using CFQ. | |
422 | The second is a throttling policy which specifies | |
423 | upper I/O rate limits on a device. | |
cfb51917 MK |
424 | |
425 | Further information can be found in the kernel source file | |
426 | .IR Documentation/cgroup-v1/blkio-controller.txt . | |
f0d27655 | 427 | .TP |
96c55745 | 428 | .IR perf_event " (since Linux 2.6.39; " \fBCONFIG_CGROUP_PERF\fP ) |
43df1ab3 MK |
429 | This controller allows |
430 | .I perf | |
431 | monitoring of the set of processes grouped in a cgroup. | |
cfb51917 MK |
432 | |
433 | Further information can be found in the kernel source file | |
434 | .IR Documentation/perf-record.txt . | |
f0d27655 | 435 | .TP |
96c55745 | 436 | .IR net_prio " (since Linux 3.3; " \fBCONFIG_CGROUP_NET_PRIO\fP ) |
21f0d132 | 437 | This allows priorities to be specified, per network interface, for cgroups. |
cfb51917 MK |
438 | |
439 | Further information can be found in the kernel source file | |
440 | .IR Documentation/cgroup-v1/net_prio.txt . | |
21f0d132 | 441 | .TP |
96c55745 | 442 | .IR hugetlb " (since Linux 3.5; " \fBCONFIG_CGROUP_HUGETLB\fP ) |
f0d27655 | 443 | This supports limiting the use of huge pages by cgroups. |
cfb51917 MK |
444 | |
445 | Further information can be found in the kernel source file | |
446 | .IR Documentation/cgroup-v1/hugetlb.txt . | |
0d293858 | 447 | .TP |
96c55745 | 448 | .IR pids " (since Linux 4.3; " \fBCONFIG_CGROUP_PIDS\fP ) |
0d293858 MK |
449 | This controller permits limiting the number of process that may be created |
450 | in a cgroup (and its descendants). | |
cfb51917 MK |
451 | |
452 | Further information can be found in the kernel source file | |
453 | .IR Documentation/cgroup-v1/pids.txt . | |
1a4f7d59 | 454 | .\" |
c91a9f8a MK |
455 | .SS Release notification |
456 | A special file in each cgroup hierarchy, | |
457 | .IR release_agent , | |
458 | can be used to register a program to handle cgroups which become newly empty. | |
459 | The program will be called each time a cgroup marked for | |
460 | autoremove becomes empty and childless. | |
461 | The cgroup path will be provided as the first command-line argument. | |
462 | The cgroup must be marked as eligible for autoremove by writing '1' into its | |
463 | .IR notify_on_release | |
464 | file; | |
465 | this value is inherited by newly created child cgroups. | |
466 | ||
467 | A new feature in cgroups v2 is the | |
468 | .I cgroup.populated | |
469 | file. | |
470 | This reads 0 if there are no processes in the cgroup or its descendants, | |
471 | and 1 otherwise. | |
472 | It can be watched for changes using | |
473 | .BR inotify (7). | |
474 | This allows user-space applications to efficiently watch cgroups | |
475 | for autoremove conditions. | |
476 | .\" | |
5c2181ad MK |
477 | .SS /proc files |
478 | .TP | |
34eb3340 | 479 | .IR /proc/cgroups " (since Linux 2.6.24)" |
92bb6d36 | 480 | This file contains information about the controllers |
1a4f7d59 | 481 | that are compiled into the kernel. |
34eb3340 MK |
482 | An example of the contents of this file (reformatted for readability) |
483 | is the following: | |
484 | ||
485 | .nf | |
486 | .in +4n | |
487 | #subsys_name hierarchy num_cgroups enabled | |
488 | cpuset 4 1 1 | |
489 | cpu 8 1 1 | |
490 | cpuacct 8 1 1 | |
491 | blkio 6 1 1 | |
492 | memory 3 1 1 | |
493 | devices 10 84 1 | |
494 | freezer 7 1 1 | |
495 | net_cls 9 1 1 | |
496 | perf_event 5 1 1 | |
497 | net_prio 9 1 1 | |
498 | hugetlb 0 1 0 | |
499 | pids 2 1 1 | |
500 | .in | |
501 | .fi | |
502 | ||
503 | The fields in this file are, from left to right: | |
504 | .RS | |
505 | .IP 1. 3 | |
506 | The name of the controller. | |
507 | .IP 2. | |
92bb6d36 | 508 | The unique ID of the cgroup hierarchy on which this controller is mounted. |
11c0797f | 509 | If multiple cgroups v1 controllers are bound to the same hierarchy, |
34eb3340 | 510 | then each will show the same hierarchy ID in this field. |
92bb6d36 MK |
511 | The value in this field will be 0 if: |
512 | .RS 5 | |
513 | .IP a) 3 | |
514 | the controller is not mounted on a cgroups v1 hierarchy; | |
515 | .IP b) | |
516 | the controller is bound to the cgroups v2 single unified hierarchy; or | |
517 | .IP c) | |
518 | the controller is disabled (see below). | |
519 | .RE | |
34eb3340 MK |
520 | .IP 3. |
521 | The number of control groups in this hierarchy using this controller. | |
522 | .IP 4. | |
523 | This field contains the value 1 if this controller is enabled, | |
524 | or 0 if it has been disabled (via the | |
525 | .IR cgroup_disable | |
526 | kernel command-line boot parameter). | |
527 | .RE | |
528 | .TP | |
5c2181ad | 529 | .IR /proc/[pid]/cgroup " (since Linux 2.6.24)" |
f5faa016 MK |
530 | This file describes control groups to which the process |
531 | with the corresponding PID belongs. | |
5f8a7eb2 | 532 | The displayed information differs for |
2c4fbe35 | 533 | cgroups version 1 and version 2 hierarchies. |
5f8a7eb2 MK |
534 | |
535 | For each cgroup hierarchy of which the process is a member, | |
536 | there is one entry containing three | |
5c2181ad | 537 | colon-separated fields of the form: |
5f8a7eb2 | 538 | |
55f52de8 | 539 | hierarchy-ID:controller-list:cgroup-path |
5f8a7eb2 MK |
540 | |
541 | For example: | |
5c2181ad MK |
542 | .nf |
543 | .ft CW | |
544 | ||
545 | 5:cpuacct,cpu,cpuset:/daemons | |
546 | .ft | |
547 | .fi | |
548 | .IP | |
549 | The colon-separated fields are, from left to right: | |
5f8a7eb2 | 550 | .RS |
5c2181ad | 551 | .IP 1. 3 |
5f8a7eb2 MK |
552 | For cgroups version 1 hierarchies, |
553 | this field contains a unique hierarchy ID number | |
554 | that can be matched to a hierarchy ID in | |
555 | .IR /proc/cgroups . | |
556 | For the cgroups version 2 hierarchy, this field contains the value 0. | |
5c2181ad | 557 | .IP 2. |
5f8a7eb2 | 558 | For cgroups version 1 hierarchies, |
55f52de8 | 559 | this field contains a comma-separated list of the controllers |
5f8a7eb2 MK |
560 | bound to the hierarchy. |
561 | For the cgroups version 2 hierarchy, this field is empty. | |
5c2181ad | 562 | .IP 3. |
5f8a7eb2 MK |
563 | This field contains the pathname of the control group in the hierarchy |
564 | to which the process belongs. | |
565 | This pathname is relative to the mount point of the hierarchy. | |
5c2181ad | 566 | .RE |
2e23a9b2 MK |
567 | .SH ERRORS |
568 | The following errors can occur for | |
569 | .BR mount (2): | |
570 | .TP | |
571 | .B EBUSY | |
572 | An attempt to mount a cgroup version 1 filesystem specified neither the | |
573 | .I name= | |
574 | option (to mount a named hierarchy) nor a controller name (or | |
28bcfee9 | 575 | .IR all ). |
bbfdf727 | 576 | .SH SEE ALSO |
ebbc83be | 577 | .BR prlimit (1), |
f60a5da2 | 578 | .BR systemd (1), |
325b7eb0 | 579 | .BR clone (2), |
ebbc83be MK |
580 | .BR ioprio_set (2), |
581 | .BR perf_event_open (2), | |
582 | .BR setrlimit (2), | |
cff6de30 | 583 | .BR cgroup_namespaces (7), |
69c47536 | 584 | .BR cpuset (7), |
ebbc83be MK |
585 | .BR namespaces (7), |
586 | .BR sched (7), | |
587 | .BR user_namespaces (7) |