1CGCONFIG.CONF(5) File Formats Manual CGCONFIG.CONF(5)
2
6 cgconfig.conf - libcgroup configuration file
7
9 cgconfig.conf is a configuration file used by libcgroup to define con‐
10 trol groups, their parameters and their mount points. The file con‐
11 sists of mount , group and default sections. These sections can be in
12 arbitrary order and all of them are optional. Any line starting with
13 '#' is considered a comment line and is ignored.
14 mount section has this form:
16 mount {
18 <controller> = <path>;
19 ...
20 }
21 controller
24 Name of the kernel subsystem. The list of subsystems supported
25 by the kernel can be found in /proc/cgroups file. Named hierar‐
26 chy can be specified as controller "name=<somename>". Do not
27 forget to use double quotes around this controller name (see
28 examples below).
29 Libcgroup merges all subsystems mounted to the same directory
31 (see Example 1) and the directory is mounted only once.
32 path The directory path where the group hierarchy associated to a
35 given controller shall be mounted. The directory is created
36 automatically on cgconfig service startup if it does not exist
37 and is deleted on service shutdown.
38 If no mount section is specified, no controllers are mounted.
40 group section has this form:
42 group <name> {
44 [permissions]
45 <controller> {
46 <param name> = <param value>;
47 ...
48 }
49 ...
50 }
51 name Name of the control group. It can contain only characters, which
54 are allowed for directory names. The groups form a tree, i.e. a
55 control group can contain zero or more subgroups. Subgroups can
56 be specified using '/' delimiter.
57 The root control group is always created automatically in all
59 hierarchies and it is the base of the group hierarchy. It can be
60 explicitly specified in cgconfig.conf by using '.' as group
61 name. This can be used e.g. to set its permissions, as shown in
62 Example 6.
63 When the parent control group of a subgroup is not specified it
65 is created automatically.
66 permissions
69 Permissions of the given control group on mounted filesystem.
70 root has always permission to do anything with the control
71 group. Permissions have the following syntax:
72 perm {
73 task {
74 uid = <task user>;
75 gid = <task group>;
76 fperm = <file permissions>
77 }
78 admin {
79 uid = <admin name>;
80 gid = <admin group>;
81 dperm = <directory permissions>
82 fperm = <file permissions>
83 }
84 }
85 task user/group Name of the user and the group, which own the
88 tasks file of the control group. Given fperm
89 then specify the file permissions. Please note
90 that the given value is not used as was speci‐
91 fied. Instead, current file owner permissions
92 are used as a "umask" for group and others per‐
93 missions. For example if fperm = 777 then both
94 group and others will get the same permissions
95 as the file owner.
96 admin user/group Name of the user and the group which own the
98 rest of control group's files. Given fperm and
99 dperm control file and directory permissions.
100 Again, the given value is masked by the
101 file/directory owner permissions.
102 Permissions are only apply to the enclosing control group and
104 are not inherited by subgroups. If there is no perm section in
105 the control group definition, root:root is the owner of all
106 files and default file permissions are preserved if fperm resp.
107 dperm are not specified.
108 controller
110 Name of the kernel subsystem. The section can be empty, default
111 kernel parameters will be used in this case. By specifying con‐
112 troller the control group and all its parents are controlled by
113 the specific subsystem. One control group can be controlled by
114 multiple subsystems, even if the subsystems are mounted on dif‐
115 ferent directories. Each control group must be controlled by at
116 least one subsystem, so that libcgroup knows in which hierar‐
117 chies the control group should be created.
118 The parameters of the given controller can be modified in the
120 following section enclosed in brackets.
121 param name
123 Name of the file to set. Each controller can have zero or
124 more parameters.
125 param value
127 Value which should be written to the file when the con‐
128 trol group is created. If it is enclosed in double quotes
129 `"', it can contain spaces and other special characters.
130 If no group section is specified, no groups are created.
132 default section has this form:
134 default {
136 perm {
137 task {
138 uid = <task user>;
139 gid = <task group>;
140 fperm = <file permissions>
141 }
142 admin {
143 uid = <admin name>;
144 gid = <admin group>;
145 dperm = <directory permissions>
146 fperm = <file permissions>
147 }
148 }
149 }
150 Content of the perm section has the same form as in group section. The
152 permissions defined here specify owner and permissions of groups and
153 files of all groups, which do not have explicitly specified their per‐
154 missions in their group section.
155 template section has the same structure as group section. Template name
157 uses the same templates string as cgrules.conf destination tag (see
158 (cgrules.conf [22m(5)). Template definition is used as a control group
159 definition for rules in cgrules.conf [22m(5) with the same destination
160 name. Templates does not use default section settings.
161
164 Example 1
165 The configuration file:
166 mount {
168 cpu = /mnt/cgroups/cpu;
169 cpuacct = /mnt/cgroups/cpu;
170 }
171 creates the hierarchy controlled by two subsystems with no groups
173 inside. It corresponds to the following operations:
174 mkdir /mnt/cgroups/cpu
176 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
177 Example 2
180 The configuration file:
181 mount {
183 cpu = /mnt/cgroups/cpu;
184 "name=scheduler" = /mnt/cgroups/cpu;
185 "name=noctrl" = /mnt/cgroups/noctrl;
186 }
187 group daemons {
189 cpu {
190 cpu.shares = "1000";
191 }
192 }
193 group test {
194 "name=noctrl" {
195 }
196 }
197 creates two hierarchies. One hierarchy named scheduler controlled by
198 cpu subsystem, with group daemons inside. Second hierarchy is named
199 noctrl without any controller, with group test. It corresponds to fol‐
200 lowing operations:
201 mkdir /mnt/cgroups/cpu
203 mount -t cgroup -o cpu,name=scheduler cpu /mnt/cgroups/cpu
204 mount -t cgroup -o none,name=noctrl none /mnt/cgroups/noctrl
205 mkdir /mnt/cgroups/cpu/daemons
207 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
208 mkdir /mnt/cgroups/noctrl/tests
210 The daemons group is created automatically when its first subgroup is
212 created. All its parameters have the default value and only root can
213 access group's files.
214 Since both cpuacct and cpu subsystems are mounted to the same direc‐
216 tory, all groups are implicitly controlled also by cpuacct subsystem,
217 even if there is no cpuacct section in any of the groups.
218 Example 3
221 The configuration file:
222 mount {
224 cpu = /mnt/cgroups/cpu;
225 cpuacct = /mnt/cgroups/cpu;
226 }
227 group daemons/www {
229 perm {
230 task {
231 uid = root;
232 gid = webmaster;
233 fperm = 770;
234 }
235 admin {
236 uid = root;
237 gid = root;
238 dperm = 775;
239 fperm = 744;
240 }
241 }
242 cpu {
243 cpu.shares = "1000";
244 }
245 }
246 group daemons/ftp {
248 perm {
249 task {
250 uid = root;
251 gid = ftpmaster;
252 fperm = 774;
253 }
254 admin {
255 uid = root;
256 gid = root;
257 dperm = 755;
258 fperm = 700;
259 }
260 }
261 cpu {
262 cpu.shares = "500";
263 }
264 }
265 creates the hierarchy controlled by two subsystems with one group and
266 two subgroups inside, setting one parameter. It corresponds to the
267 following operations (except for file permissions which are little bit
268 trickier to emulate via chmod):
269 mkdir /mnt/cgroups/cpu
272 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
273 mkdir /mnt/cgroups/cpu/daemons
275 mkdir /mnt/cgroups/cpu/daemons/www
277 chown root:root /mnt/cgroups/cpu/daemons/www/*
278 chown root:webmaster /mnt/cgroups/cpu/daemons/www/tasks
279 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
280 # + chmod the files so the result looks like:
282 # ls -la /mnt/cgroups/cpu/daemons/www/
283 # admin.dperm = 755:
284 # drwxr-xr-x. 2 root webmaster 0 Jun 16 11:51 .
285 #
286 # admin.fperm = 744:
287 # --w-------. 1 root webmaster 0 Jun 16 11:51 cgroup.event_control
288 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cgroup.procs
289 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.stat
290 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage
291 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage_percpu
292 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_period_us
293 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_runtime_us
294 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.shares
295 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 notify_on_release
296 #
297 # tasks.fperm = 770
298 # -rw-rw----. 1 root webmaster 0 Jun 16 11:51 tasks
299 mkdir /mnt/cgroups/cpu/daemons/ftp
302 chown root:root /mnt/cgroups/cpu/daemons/ftp/*
303 chown root:ftpmaster /mnt/cgroups/cpu/daemons/ftp/tasks
304 echo 500 > /mnt/cgroups/cpu/daemons/ftp/cpu.shares
305 # + chmod the files so the result looks like:
307 # ls -la /mnt/cgroups/cpu/daemons/ftp/
308 # admin.dperm = 755:
309 # drwxr-xr-x. 2 root ftpmaster 0 Jun 16 11:51 .
310 #
311 # admin.fperm = 700:
312 # --w-------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.event_control
313 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.procs
314 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.stat
315 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage
316 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage_percpu
317 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_period_us
318 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_runtime_us
319 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.shares
320 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 notify_on_release
321 #
322 # tasks.fperm = 774:
323 # -rw-rw-r--. 1 root ftpmaster 0 Jun 16 11:51 tasks
324 The daemons group is created automatically when its first subgroup is
327 created. All its parameters have the default value and only root can
328 access the group's files.
329 Since both cpuacct and cpu subsystems are mounted to the same direc‐
331 tory, all groups are implicitly also controlled by the cpuacct subsys‐
332 tem, even if there is no cpuacct section in any of the groups.
333 Example 4
336 The configuration file:
337 mount {
340 cpu = /mnt/cgroups/cpu;
341 cpuacct = /mnt/cgroups/cpuacct;
342 }
343 group daemons {
345 cpuacct{
346 }
347 cpu {
348 }
349 }
350 creates two hierarchies and one common group in both of them. It cor‐
351 responds to the following operations:
352 mkdir /mnt/cgroups/cpu
354 mkdir /mnt/cgroups/cpuacct
355 mount -t cgroup -o cpu cpu /mnt/cgroups/cpu
356 mount -t cgroup -o cpuacct cpuacct /mnt/cgroups/cpuacct
357 mkdir /mnt/cgroups/cpu/daemons
359 mkdir /mnt/cgroups/cpuacct/daemons
360 In fact there are two groups created. One in the cpuacct hierarchy, the
362 second in the cpu hierarchy. These two groups have nothing in common
363 and can contain different subgroups and different tasks.
364 Example 5
367 The configuration file:
368 mount {
371 cpu = /mnt/cgroups/cpu;
372 cpuacct = /mnt/cgroups/cpuacct;
373 }
374 group daemons {
376 cpuacct{
377 }
378 }
379 group daemons/www {
381 cpu {
382 cpu.shares = "1000";
383 }
384 }
385 group daemons/ftp {
387 cpu {
388 cpu.shares = "500";
389 }
390 }
391 creates two hierarchies with few groups inside. One of the groups is
392 created in both hierarchies.
393 It corresponds to the following operations:
395 mkdir /mnt/cgroups/cpu
397 mkdir /mnt/cgroups/cpuacct
398 mount -t cgroup -o cpu cpu /mnt/cgroups/cpu
399 mount -t cgroup -o cpuacct cpuacct /mnt/cgroups/cpuacct
400 mkdir /mnt/cgroups/cpuacct/daemons
402 mkdir /mnt/cgroups/cpu/daemons
403 mkdir /mnt/cgroups/cpu/daemons/www
404 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
405 mkdir /mnt/cgroups/cpu/daemons/ftp
406 echo 500 > /mnt/cgroups/cpu/daemons/ftp/cpu.shares
407 Group daemons is created in both hierarchies. In the cpuacct hierarchy
408 the group is explicitly mentioned in the configuration file. In the cpu
409 hierarchy the group is created implicitly when www is created there.
410 These two groups have nothing in common, for example they do not share
411 processes and subgroups. Groups www and ftp are created only in the cpu
412 hierarchy and are not controlled by the cpuacct subsystem.
413 Example 6
416 The configuration file:
417 mount {
419 cpu = /mnt/cgroups/cpu;
420 cpuacct = /mnt/cgroups/cpu;
421 }
422 group . {
424 perm {
425 task {
426 uid = root;
427 gid = operator;
428 }
429 admin {
430 uid = root;
431 gid = operator;
432 }
433 }
434 cpu {
435 }
436 }
437 group daemons {
439 perm {
440 task {
441 uid = root;
442 gid = daemonmaster;
443 }
444 admin {
445 uid = root;
446 gid = operator;
447 }
448 }
449 cpu {
450 }
451 }
452 creates the hierarchy controlled by two subsystems with one group hav‐
453 ing some special permissions. It corresponds to the following opera‐
454 tions:
455 mkdir /mnt/cgroups/cpu
457 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
458 chown root:operator /mnt/cgroups/cpu/*
460 chown root:operator /mnt/cgroups/cpu/tasks
461 mkdir /mnt/cgroups/cpu/daemons
463 chown root:operator /mnt/cgroups/cpu/daemons/*
464 chown root:daemonmaster /mnt/cgroups/cpu/daemons/tasks
465 Users which are members of the operator group are allowed to administer
467 the control groups, i.e. create new control groups and move processes
468 between these groups without having root privileges.
469 Members of the daemonmaster group can move processes to the daemons
471 control group, but they can not move the process out of the group. Only
472 the operator or root can do that.
473 Example 7
476 The configuration file:
477 mount {
480 cpu = /mnt/cgroups/cpu;
481 cpuacct = /mnt/cgroups/cpuacct;
482 }
483 group students {
485 cpuacct{
486 }
487 cpu {
488 }
489 }
490 template students/%u {
492 cpuacct{
493 }
494 cpu {
495 }
496 }
497 mkdir /mnt/cgroups/cpu/daemons
499 mkdir /mnt/cgroups/cpuacct/daemons
500 The situation is the similar as in Example 4. The only difference is
502 template, which is used if some rule uses "/students/%u" as a destina‐
503 tion.
504
509 Keep hierarchies separated
510 Having multiple hierarchies is perfectly valid and can be useful in
511 various scenarios. To keeps things clean, do not create one group in
512 multiple hierarchies. Examples 4 and 5 show how unreadable and confus‐
513 ing it can be, especially when reading somebody elses configuration
514 file.
515 Explicit is better than implicit
518 libcgroup can implicitly create groups which are needed for the cre‐
519 ation of configured subgroups. This may be useful and save some typing
520 in simple scenarios. When it comes to multiple hierarchies, it's better
521 to explicitly specify all groups and all controllers related to them.
522
525 /etc/cgconfig.conf
526 default libcgroup configuration file
527
530 cgconfigparser (8)
531
534 Parameter values must be single strings without spaces. Parsing of
535 quoted strings is not implemented.
536 CGCONFIG.CONF(5)