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 /etc/cgconfig.d/ directory can be used for additional configuration
163 files. cgrulesengd searches this directory for additional templates.
164
167 Example 1
168 The configuration file:
169 mount {
171 cpu = /mnt/cgroups/cpu;
172 cpuacct = /mnt/cgroups/cpu;
173 }
174 creates the hierarchy controlled by two subsystems with no groups
176 inside. It corresponds to the following operations:
177 mkdir /mnt/cgroups/cpu
179 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
180 Example 2
183 The configuration file:
184 mount {
186 cpu = /mnt/cgroups/cpu;
187 "name=scheduler" = /mnt/cgroups/cpu;
188 "name=noctrl" = /mnt/cgroups/noctrl;
189 }
190 group daemons {
192 cpu {
193 cpu.shares = "1000";
194 }
195 }
196 group test {
197 "name=noctrl" {
198 }
199 }
200 creates two hierarchies. One hierarchy named scheduler controlled by
201 cpu subsystem, with group daemons inside. Second hierarchy is named
202 noctrl without any controller, with group test. It corresponds to fol‐
203 lowing operations:
204 mkdir /mnt/cgroups/cpu
206 mount -t cgroup -o cpu,name=scheduler cpu /mnt/cgroups/cpu
207 mount -t cgroup -o none,name=noctrl none /mnt/cgroups/noctrl
208 mkdir /mnt/cgroups/cpu/daemons
210 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
211 mkdir /mnt/cgroups/noctrl/tests
213 The daemons group is created automatically when its first subgroup is
215 created. All its parameters have the default value and only root can
216 access group's files.
217 Since both cpuacct and cpu subsystems are mounted to the same direc‐
219 tory, all groups are implicitly controlled also by cpuacct subsystem,
220 even if there is no cpuacct section in any of the groups.
221 Example 3
224 The configuration file:
225 mount {
227 cpu = /mnt/cgroups/cpu;
228 cpuacct = /mnt/cgroups/cpu;
229 }
230 group daemons/www {
232 perm {
233 task {
234 uid = root;
235 gid = webmaster;
236 fperm = 770;
237 }
238 admin {
239 uid = root;
240 gid = root;
241 dperm = 775;
242 fperm = 744;
243 }
244 }
245 cpu {
246 cpu.shares = "1000";
247 }
248 }
249 group daemons/ftp {
251 perm {
252 task {
253 uid = root;
254 gid = ftpmaster;
255 fperm = 774;
256 }
257 admin {
258 uid = root;
259 gid = root;
260 dperm = 755;
261 fperm = 700;
262 }
263 }
264 cpu {
265 cpu.shares = "500";
266 }
267 }
268 creates the hierarchy controlled by two subsystems with one group and
269 two subgroups inside, setting one parameter. It corresponds to the
270 following operations (except for file permissions which are little bit
271 trickier to emulate via chmod):
272 mkdir /mnt/cgroups/cpu
275 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
276 mkdir /mnt/cgroups/cpu/daemons
278 mkdir /mnt/cgroups/cpu/daemons/www
280 chown root:root /mnt/cgroups/cpu/daemons/www/*
281 chown root:webmaster /mnt/cgroups/cpu/daemons/www/tasks
282 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
283 # + chmod the files so the result looks like:
285 # ls -la /mnt/cgroups/cpu/daemons/www/
286 # admin.dperm = 755:
287 # drwxr-xr-x. 2 root webmaster 0 Jun 16 11:51 .
288 #
289 # admin.fperm = 744:
290 # --w-------. 1 root webmaster 0 Jun 16 11:51 cgroup.event_control
291 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cgroup.procs
292 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.stat
293 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage
294 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage_percpu
295 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_period_us
296 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_runtime_us
297 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.shares
298 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 notify_on_release
299 #
300 # tasks.fperm = 770
301 # -rw-rw----. 1 root webmaster 0 Jun 16 11:51 tasks
302 mkdir /mnt/cgroups/cpu/daemons/ftp
305 chown root:root /mnt/cgroups/cpu/daemons/ftp/*
306 chown root:ftpmaster /mnt/cgroups/cpu/daemons/ftp/tasks
307 echo 500 > /mnt/cgroups/cpu/daemons/ftp/cpu.shares
308 # + chmod the files so the result looks like:
310 # ls -la /mnt/cgroups/cpu/daemons/ftp/
311 # admin.dperm = 755:
312 # drwxr-xr-x. 2 root ftpmaster 0 Jun 16 11:51 .
313 #
314 # admin.fperm = 700:
315 # --w-------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.event_control
316 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.procs
317 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.stat
318 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage
319 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage_percpu
320 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_period_us
321 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_runtime_us
322 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.shares
323 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 notify_on_release
324 #
325 # tasks.fperm = 774:
326 # -rw-rw-r--. 1 root ftpmaster 0 Jun 16 11:51 tasks
327 The daemons group is created automatically when its first subgroup is
330 created. All its parameters have the default value and only root can
331 access the group's files.
332 Since both cpuacct and cpu subsystems are mounted to the same direc‐
334 tory, all groups are implicitly also controlled by the cpuacct subsys‐
335 tem, even if there is no cpuacct section in any of the groups.
336 Example 4
339 The configuration file:
340 mount {
343 cpu = /mnt/cgroups/cpu;
344 cpuacct = /mnt/cgroups/cpuacct;
345 }
346 group daemons {
348 cpuacct{
349 }
350 cpu {
351 }
352 }
353 creates two hierarchies and one common group in both of them. It cor‐
354 responds to the following operations:
355 mkdir /mnt/cgroups/cpu
357 mkdir /mnt/cgroups/cpuacct
358 mount -t cgroup -o cpu cpu /mnt/cgroups/cpu
359 mount -t cgroup -o cpuacct cpuacct /mnt/cgroups/cpuacct
360 mkdir /mnt/cgroups/cpu/daemons
362 mkdir /mnt/cgroups/cpuacct/daemons
363 In fact there are two groups created. One in the cpuacct hierarchy, the
365 second in the cpu hierarchy. These two groups have nothing in common
366 and can contain different subgroups and different tasks.
367 Example 5
370 The configuration file:
371 mount {
374 cpu = /mnt/cgroups/cpu;
375 cpuacct = /mnt/cgroups/cpuacct;
376 }
377 group daemons {
379 cpuacct{
380 }
381 }
382 group daemons/www {
384 cpu {
385 cpu.shares = "1000";
386 }
387 }
388 group daemons/ftp {
390 cpu {
391 cpu.shares = "500";
392 }
393 }
394 creates two hierarchies with few groups inside. One of the groups is
395 created in both hierarchies.
396 It corresponds to the following operations:
398 mkdir /mnt/cgroups/cpu
400 mkdir /mnt/cgroups/cpuacct
401 mount -t cgroup -o cpu cpu /mnt/cgroups/cpu
402 mount -t cgroup -o cpuacct cpuacct /mnt/cgroups/cpuacct
403 mkdir /mnt/cgroups/cpuacct/daemons
405 mkdir /mnt/cgroups/cpu/daemons
406 mkdir /mnt/cgroups/cpu/daemons/www
407 echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
408 mkdir /mnt/cgroups/cpu/daemons/ftp
409 echo 500 > /mnt/cgroups/cpu/daemons/ftp/cpu.shares
410 Group daemons is created in both hierarchies. In the cpuacct hierarchy
411 the group is explicitly mentioned in the configuration file. In the cpu
412 hierarchy the group is created implicitly when www is created there.
413 These two groups have nothing in common, for example they do not share
414 processes and subgroups. Groups www and ftp are created only in the cpu
415 hierarchy and are not controlled by the cpuacct subsystem.
416 Example 6
419 The configuration file:
420 mount {
422 cpu = /mnt/cgroups/cpu;
423 cpuacct = /mnt/cgroups/cpu;
424 }
425 group . {
427 perm {
428 task {
429 uid = root;
430 gid = operator;
431 }
432 admin {
433 uid = root;
434 gid = operator;
435 }
436 }
437 cpu {
438 }
439 }
440 group daemons {
442 perm {
443 task {
444 uid = root;
445 gid = daemonmaster;
446 }
447 admin {
448 uid = root;
449 gid = operator;
450 }
451 }
452 cpu {
453 }
454 }
455 creates the hierarchy controlled by two subsystems with one group hav‐
456 ing some special permissions. It corresponds to the following opera‐
457 tions:
458 mkdir /mnt/cgroups/cpu
460 mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
461 chown root:operator /mnt/cgroups/cpu/*
463 chown root:operator /mnt/cgroups/cpu/tasks
464 mkdir /mnt/cgroups/cpu/daemons
466 chown root:operator /mnt/cgroups/cpu/daemons/*
467 chown root:daemonmaster /mnt/cgroups/cpu/daemons/tasks
468 Users which are members of the operator group are allowed to administer
470 the control groups, i.e. create new control groups and move processes
471 between these groups without having root privileges.
472 Members of the daemonmaster group can move processes to the daemons
474 control group, but they can not move the process out of the group. Only
475 the operator or root can do that.
476 Example 7
479 The configuration file:
480 mount {
483 cpu = /mnt/cgroups/cpu;
484 cpuacct = /mnt/cgroups/cpuacct;
485 }
486 group students {
488 cpuacct{
489 }
490 cpu {
491 }
492 }
493 template students/%u {
495 cpuacct{
496 }
497 cpu {
498 }
499 }
500 mkdir /mnt/cgroups/cpu/daemons
502 mkdir /mnt/cgroups/cpuacct/daemons
503 The situation is the similar as in Example 4. The only difference is
505 template, which is used if some rule uses "/students/%u" as a destina‐
506 tion.
507
512 Keep hierarchies separated
513 Having multiple hierarchies is perfectly valid and can be useful in
514 various scenarios. To keeps things clean, do not create one group in
515 multiple hierarchies. Examples 4 and 5 show how unreadable and confus‐
516 ing it can be, especially when reading somebody elses configuration
517 file.
518 Explicit is better than implicit
521 libcgroup can implicitly create groups which are needed for the cre‐
522 ation of configured subgroups. This may be useful and save some typing
523 in simple scenarios. When it comes to multiple hierarchies, it's better
524 to explicitly specify all groups and all controllers related to them.
525
528 /etc/cgconfig.conf
529 default libcgroup configuration file
530 /etc/cgconfig.d/
531 default libcgroup configuration files directory
532
535 cgconfigparser (8)
536
539 Parameter values must be single strings without spaces. Parsing of
540 quoted strings is not implemented.
541 CGCONFIG.CONF(5)