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 ex‐
28 amples below). Apart from named hierarchy, additional mount op‐
29 tions may be specified by putting the controller and the options
30 in quotes. Options supported are nosuid, noexec and nodev.
31 Libcgroup merges all subsystems mounted to the same directory
33 (see Example 1) and the directory is mounted only once.
34 path The directory path where the group hierarchy associated to a
37 given controller shall be mounted. The directory is created au‐
38 tomatically on cgconfig service startup if it does not exist and
39 is deleted on service shutdown.
40 If no mount section is specified, no controllers are mounted.
42 group section has this form:
44 group <name> {
46 [permissions]
47 <controller> {
48 <param name> = <param value>;
49 ...
50 }
51 ...
52 }
53 name Name of the control group. It can contain only characters, which
56 are allowed for directory names. The groups form a tree, i.e. a
57 control group can contain zero or more subgroups. Subgroups can
58 be specified using '/' delimiter.
59 The root control group is always created automatically in all
61 hierarchies and it is the base of the group hierarchy. It can be
62 explicitly specified in cgconfig.conf by using '.' as group
63 name. This can be used e.g. to set its permissions, as shown in
64 Example 6.
65 When the parent control group of a subgroup is not specified it
67 is created automatically.
68 permissions
71 Permissions of the given control group on mounted filesystem.
72 root has always permission to do anything with the control
73 group. Permissions have the following syntax:
74 perm {
75 task {
76 uid = <task user>;
77 gid = <task group>;
78 fperm = <file permissions>
79 }
80 admin {
81 uid = <admin name>;
82 gid = <admin group>;
83 dperm = <directory permissions>
84 fperm = <file permissions>
85 }
86 }
87 task user/group Name of the user and the group, which own the
90 tasks file of the control group. Given fperm
91 then specify the file permissions. Please note
92 that the given value is not used as was speci‐
93 fied. Instead, current file owner permissions
94 are used as a "umask" for group and others per‐
95 missions. For example if fperm = 777 then both
96 group and others will get the same permissions
97 as the file owner.
98 admin user/group Name of the user and the group which own the
100 rest of control group's files. Given fperm and
101 dperm control file and directory permissions.
102 Again, the given value is masked by the
103 file/directory owner permissions.
104 Permissions are only apply to the enclosing control group and
106 are not inherited by subgroups. If there is no perm section in
107 the control group definition, root:root is the owner of all
108 files and default file permissions are preserved if fperm resp.
109 dperm are not specified.
110 controller
112 Name of the kernel subsystem. The section can be empty, default
113 kernel parameters will be used in this case. By specifying con‐
114 troller the control group and all its parents are controlled by
115 the specific subsystem. One control group can be controlled by
116 multiple subsystems, even if the subsystems are mounted on dif‐
117 ferent directories. Each control group must be controlled by at
118 least one subsystem, so that libcgroup knows in which hierar‐
119 chies the control group should be created.
120 The parameters of the given controller can be modified in the
122 following section enclosed in brackets.
123 param name
125 Name of the file to set. Each controller can have zero or
126 more parameters.
127 param value
129 Value which should be written to the file when the con‐
130 trol group is created. If it is enclosed in double quotes
131 `"', it can contain spaces and other special characters.
132 If no group section is specified, no groups are created.
134 default section has this form:
136 default {
138 perm {
139 task {
140 uid = <task user>;
141 gid = <task group>;
142 fperm = <file permissions>
143 }
144 admin {
145 uid = <admin name>;
146 gid = <admin group>;
147 dperm = <directory permissions>
148 fperm = <file permissions>
149 }
150 }
151 }
152 Content of the perm section has the same form as in group section. The
154 permissions defined here specify owner and permissions of groups and
155 files of all groups, which do not have explicitly specified their per‐
156 missions in their group section.
157 template section has the same structure as group section. Template name
159 uses the same templates string as cgrules.conf destination tag (see
160 (cgrules.conf [22m(5)). Template definition is used as a control group
161 definition for rules in cgrules.conf [22m(5) with the same destination
162 name. Templates does not use default section settings.
163 /etc/cgconfig.d/ directory can be used for additional configuration
165 files. cgrulesengd searches this directory for additional templates.
166
169 Example 1
170 The configuration file:
171 mount {
173 cpu = /mnt/cgroups/cpu;
174 cpuacct = /mnt/cgroups/cpu;
175 }
176 creates the hierarchy controlled by two subsystems with no groups in‐
178 side. It corresponds to the following operations:
179 mkdir /mnt/cgroups/cpu
181 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
182 Example 2
185 The configuration file:
186 mount {
188 cpu = /mnt/cgroups/cpu;
189 "name=scheduler" = /mnt/cgroups/cpu;
190 "name=noctrl" = /mnt/cgroups/noctrl;
191 }
192 group daemons {
194 cpu {
195 cpu.shares = "1000";
196 }
197 }
198 group test {
199 "name=noctrl" {
200 }
201 }
202 creates two hierarchies. One hierarchy named scheduler controlled by
203 cpu subsystem, with group daemons inside. Second hierarchy is named
204 noctrl without any controller, with group test. It corresponds to fol‐
205 lowing operations:
206 mkdir /mnt/cgroups/cpu
208 mount -t cgroup -o cpu,name=scheduler cpu /mnt/cgroups/cpu
209 mount -t cgroup -o none,name=noctrl none /mnt/cgroups/noctrl
210 mkdir /mnt/cgroups/cpu/daemons
212 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
213 mkdir /mnt/cgroups/noctrl/tests
215 The daemons group is created automatically when its first subgroup is
217 created. All its parameters have the default value and only root can
218 access group's files.
219 Since both cpuacct and cpu subsystems are mounted to the same direc‐
221 tory, all groups are implicitly controlled also by cpuacct subsystem,
222 even if there is no cpuacct section in any of the groups.
223 Example 3
226 The configuration file:
227 mount {
229 cpu = /mnt/cgroups/cpu;
230 cpuacct = /mnt/cgroups/cpu;
231 }
232 group daemons/www {
234 perm {
235 task {
236 uid = root;
237 gid = webmaster;
238 fperm = 770;
239 }
240 admin {
241 uid = root;
242 gid = root;
243 dperm = 775;
244 fperm = 744;
245 }
246 }
247 cpu {
248 cpu.shares = "1000";
249 }
250 }
251 group daemons/ftp {
253 perm {
254 task {
255 uid = root;
256 gid = ftpmaster;
257 fperm = 774;
258 }
259 admin {
260 uid = root;
261 gid = root;
262 dperm = 755;
263 fperm = 700;
264 }
265 }
266 cpu {
267 cpu.shares = "500";
268 }
269 }
270 creates the hierarchy controlled by two subsystems with one group and
271 two subgroups inside, setting one parameter. It corresponds to the
272 following operations (except for file permissions which are little bit
273 trickier to emulate via chmod):
274 mkdir /mnt/cgroups/cpu
277 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
278 mkdir /mnt/cgroups/cpu/daemons
280 mkdir /mnt/cgroups/cpu/daemons/www
282 chown root:root /mnt/cgroups/cpu/daemons/www/*
283 chown root:webmaster /mnt/cgroups/cpu/daemons/www/tasks
284 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
285 # + chmod the files so the result looks like:
287 # ls -la /mnt/cgroups/cpu/daemons/www/
288 # admin.dperm = 755:
289 # drwxr-xr-x. 2 root webmaster 0 Jun 16 11:51 .
290 #
291 # admin.fperm = 744:
292 # --w-------. 1 root webmaster 0 Jun 16 11:51 cgroup.event_control
293 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cgroup.procs
294 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.stat
295 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage
296 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage_percpu
297 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_period_us
298 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_runtime_us
299 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.shares
300 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 notify_on_release
301 #
302 # tasks.fperm = 770
303 # -rw-rw----. 1 root webmaster 0 Jun 16 11:51 tasks
304 mkdir /mnt/cgroups/cpu/daemons/ftp
307 chown root:root /mnt/cgroups/cpu/daemons/ftp/*
308 chown root:ftpmaster /mnt/cgroups/cpu/daemons/ftp/tasks
309 echo 500 > /mnt/cgroups/cpu/daemons/ftp/cpu.shares
310 # + chmod the files so the result looks like:
312 # ls -la /mnt/cgroups/cpu/daemons/ftp/
313 # admin.dperm = 755:
314 # drwxr-xr-x. 2 root ftpmaster 0 Jun 16 11:51 .
315 #
316 # admin.fperm = 700:
317 # --w-------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.event_control
318 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.procs
319 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.stat
320 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage
321 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage_percpu
322 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_period_us
323 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_runtime_us
324 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.shares
325 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 notify_on_release
326 #
327 # tasks.fperm = 774:
328 # -rw-rw-r--. 1 root ftpmaster 0 Jun 16 11:51 tasks
329 The daemons group is created automatically when its first subgroup is
332 created. All its parameters have the default value and only root can
333 access the group's files.
334 Since both cpuacct and cpu subsystems are mounted to the same direc‐
336 tory, all groups are implicitly also controlled by the cpuacct subsys‐
337 tem, even if there is no cpuacct section in any of the groups.
338 Example 4
341 The configuration file:
342 mount {
345 cpu = /mnt/cgroups/cpu;
346 cpuacct = /mnt/cgroups/cpuacct;
347 }
348 group daemons {
350 cpuacct{
351 }
352 cpu {
353 }
354 }
355 creates two hierarchies and one common group in both of them. It cor‐
356 responds to the following operations:
357 mkdir /mnt/cgroups/cpu
359 mkdir /mnt/cgroups/cpuacct
360 mount -t cgroup -o cpu cpu /mnt/cgroups/cpu
361 mount -t cgroup -o cpuacct cpuacct /mnt/cgroups/cpuacct
362 mkdir /mnt/cgroups/cpu/daemons
364 mkdir /mnt/cgroups/cpuacct/daemons
365 In fact there are two groups created. One in the cpuacct hierarchy, the
367 second in the cpu hierarchy. These two groups have nothing in common
368 and can contain different subgroups and different tasks.
369 Example 5
372 The configuration file:
373 mount {
376 cpu = /mnt/cgroups/cpu;
377 cpuacct = /mnt/cgroups/cpuacct;
378 }
379 group daemons {
381 cpuacct{
382 }
383 }
384 group daemons/www {
386 cpu {
387 cpu.shares = "1000";
388 }
389 }
390 group daemons/ftp {
392 cpu {
393 cpu.shares = "500";
394 }
395 }
396 creates two hierarchies with few groups inside. One of the groups is
397 created in both hierarchies.
398 It corresponds to the following operations:
400 mkdir /mnt/cgroups/cpu
402 mkdir /mnt/cgroups/cpuacct
403 mount -t cgroup -o cpu cpu /mnt/cgroups/cpu
404 mount -t cgroup -o cpuacct cpuacct /mnt/cgroups/cpuacct
405 mkdir /mnt/cgroups/cpuacct/daemons
407 mkdir /mnt/cgroups/cpu/daemons
408 mkdir /mnt/cgroups/cpu/daemons/www
409 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
410 mkdir /mnt/cgroups/cpu/daemons/ftp
411 echo 500 > /mnt/cgroups/cpu/daemons/ftp/cpu.shares
412 Group daemons is created in both hierarchies. In the cpuacct hierarchy
413 the group is explicitly mentioned in the configuration file. In the cpu
414 hierarchy the group is created implicitly when www is created there.
415 These two groups have nothing in common, for example they do not share
416 processes and subgroups. Groups www and ftp are created only in the cpu
417 hierarchy and are not controlled by the cpuacct subsystem.
418 Example 6
421 The configuration file:
422 mount {
424 cpu = /mnt/cgroups/cpu;
425 cpuacct = /mnt/cgroups/cpu;
426 }
427 group . {
429 perm {
430 task {
431 uid = root;
432 gid = operator;
433 }
434 admin {
435 uid = root;
436 gid = operator;
437 }
438 }
439 cpu {
440 }
441 }
442 group daemons {
444 perm {
445 task {
446 uid = root;
447 gid = daemonmaster;
448 }
449 admin {
450 uid = root;
451 gid = operator;
452 }
453 }
454 cpu {
455 }
456 }
457 creates the hierarchy controlled by two subsystems with one group hav‐
458 ing some special permissions. It corresponds to the following opera‐
459 tions:
460 mkdir /mnt/cgroups/cpu
462 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
463 chown root:operator /mnt/cgroups/cpu/*
465 chown root:operator /mnt/cgroups/cpu/tasks
466 mkdir /mnt/cgroups/cpu/daemons
468 chown root:operator /mnt/cgroups/cpu/daemons/*
469 chown root:daemonmaster /mnt/cgroups/cpu/daemons/tasks
470 Users which are members of the operator group are allowed to administer
472 the control groups, i.e. create new control groups and move processes
473 between these groups without having root privileges.
474 Members of the daemonmaster group can move processes to the daemons
476 control group, but they can not move the process out of the group. Only
477 the operator or root can do that.
478 Example 7
481 The configuration file:
482 mount {
485 cpu = /mnt/cgroups/cpu;
486 cpuacct = /mnt/cgroups/cpuacct;
487 }
488 group students {
490 cpuacct{
491 }
492 cpu {
493 }
494 }
495 template students/%u {
497 cpuacct{
498 }
499 cpu {
500 }
501 }
502 mkdir /mnt/cgroups/cpu/daemons
504 mkdir /mnt/cgroups/cpuacct/daemons
505 The situation is the similar as in Example 4. The only difference is
507 template, which is used if some rule uses "/students/%u" as a destina‐
508 tion.
509 Example 8
512 The configuration file:
513 mount {
516 "cpu,nodev,nosuid,noexec" = /mnt/cgroups/cpu;
517 }
518 This is the same as mount -t cgroup cgroup -o nodev,nosuid,noexec,cpu
521 /mnt/cgroups/cpu It mounts the cpu controller with MS_NODEV, MS_NOSUID
522 and MS_NOEXEC options passed.
523
527 Keep hierarchies separated
528 Having multiple hierarchies is perfectly valid and can be useful in
529 various scenarios. To keeps things clean, do not create one group in
530 multiple hierarchies. Examples 4 and 5 show how unreadable and confus‐
531 ing it can be, especially when reading somebody elses configuration
532 file.
533 Explicit is better than implicit
536 libcgroup can implicitly create groups which are needed for the cre‐
537 ation of configured subgroups. This may be useful and save some typing
538 in simple scenarios. When it comes to multiple hierarchies, it's better
539 to explicitly specify all groups and all controllers related to them.
540
543 /etc/cgconfig.conf
544 default libcgroup configuration file
545 /etc/cgconfig.d/
547 default libcgroup configuration files directory
548
551 cgconfigparser (8)
552
555 Parameter values must be single strings without spaces. Parsing of
556 quoted strings is not implemented.
557 CGCONFIG.CONF(5)