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