1CGCONFIG.CONF(5)              File Formats Manual             CGCONFIG.CONF(5)
2
3
4

NAME

6       cgconfig.conf - libcgroup configuration file
7

DESCRIPTION

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
15       mount section has this form:
16
17              mount {
18                     <controller> = <path>;
19                     ...
20              }
21
22
23       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
33              Libcgroup merges all subsystems mounted to  the  same  directory
34              (see Example 1) and the directory is mounted only once.
35
36
37       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
42       If no mount section is specified, no controllers are mounted.
43
44       group section has this form:
45
46              group <name> {
47                     [permissions]
48                     <controller> {
49                            <param name> = <param value>;
50                            ...
51                     }
52                     ...
53              }
54
55
56       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
61              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
67              When  the parent control group of a subgroup is not specified it
68              is created automatically.
69
70
71       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
89
90              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
100              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
106              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
112       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
122              The  parameters  of  the given controller can be modified in the
123              following section enclosed in brackets.
124
125              param name
126                     Name of the file to set. Each controller can have zero or
127                     more parameters.
128
129              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
134       If no group section is specified, no groups are created.
135
136       default section has this form:
137
138              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
154       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
159       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  (5) with the same destination
163       name.  Templates does not use default section settings.
164
165       /etc/cgconfig.d/ directory can be  used  for  additional  configuration
166       files. cgrulesengd searches this directory for additional templates.
167
168

EXAMPLES

170   Example 1
171       The configuration file:
172
173              mount {
174                     cpu = /mnt/cgroups/cpu;
175                     cpuacct = /mnt/cgroups/cpu;
176              }
177
178       creates  the  hierarchy  controlled  by  two  subsystems with no groups
179       inside. It corresponds to the following operations:
180
181              mkdir /mnt/cgroups/cpu
182              mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
183
184
185   Example 2
186       The configuration file:
187
188              mount {
189                     cpu = /mnt/cgroups/cpu;
190                     "name=scheduler" = /mnt/cgroups/cpu;
191                     "name=noctrl" = /mnt/cgroups/noctrl;
192              }
193
194              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
208              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
212              mkdir /mnt/cgroups/cpu/daemons
213              echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
214
215              mkdir /mnt/cgroups/noctrl/tests
216
217       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
221       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
225
226   Example 3
227       The configuration file:
228
229              mount {
230                     cpu = /mnt/cgroups/cpu;
231                     cpuacct = /mnt/cgroups/cpu;
232              }
233
234              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
253              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
276
277              mkdir /mnt/cgroups/cpu
278              mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
279
280              mkdir /mnt/cgroups/cpu/daemons
281
282              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
287               # + 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
306
307              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
312               # + 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
331
332       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
336       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
340
341   Example 4
342       The configuration file:
343
344
345              mount {
346                     cpu = /mnt/cgroups/cpu;
347                     cpuacct = /mnt/cgroups/cpuacct;
348              }
349
350              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
359              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
364              mkdir /mnt/cgroups/cpu/daemons
365              mkdir /mnt/cgroups/cpuacct/daemons
366
367       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
371
372   Example 5
373       The configuration file:
374
375
376              mount {
377                     cpu = /mnt/cgroups/cpu;
378                     cpuacct = /mnt/cgroups/cpuacct;
379              }
380
381              group daemons {
382                     cpuacct{
383                     }
384              }
385
386              group daemons/www {
387                     cpu {
388                            cpu.shares = "1000";
389                     }
390              }
391
392              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
400       It corresponds to the following operations:
401
402              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
407              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
420
421   Example 6
422       The configuration file:
423
424              mount {
425                     cpu = /mnt/cgroups/cpu;
426                     cpuacct = /mnt/cgroups/cpu;
427              }
428
429              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
444              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
462              mkdir /mnt/cgroups/cpu
463              mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
464
465              chown root:operator /mnt/cgroups/cpu/*
466              chown root:operator /mnt/cgroups/cpu/tasks
467
468              mkdir /mnt/cgroups/cpu/daemons
469              chown root:operator /mnt/cgroups/cpu/daemons/*
470              chown root:daemonmaster /mnt/cgroups/cpu/daemons/tasks
471
472       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
476       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
480
481   Example 7
482       The configuration file:
483
484
485              mount {
486                     cpu = /mnt/cgroups/cpu;
487                     cpuacct = /mnt/cgroups/cpuacct;
488              }
489
490              group students {
491                     cpuacct{
492                     }
493                     cpu {
494                     }
495              }
496
497              template students/%u {
498                     cpuacct{
499                     }
500                     cpu {
501                     }
502              }
503
504              mkdir /mnt/cgroups/cpu/daemons
505              mkdir /mnt/cgroups/cpuacct/daemons
506
507       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
511
512   Example 8
513       The configuration file:
514
515
516              mount {
517                     "cpu,nodev,nosuid,noexec" = /mnt/cgroups/cpu;
518              }
519
520
521       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
525
526

RECOMMENDATIONS

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
535
536   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
542

FILES

544       /etc/cgconfig.conf
545              default libcgroup configuration file
546
547       /etc/cgconfig.d/
548              default libcgroup configuration files directory
549
550

SEE ALSO

552       cgconfigparser (8)
553
554

BUGS

556       Parameter values must be single strings  without  spaces.   Parsing  of
557       quoted strings is not implemented.
558
559
560
561
562
563
564
565                                                              CGCONFIG.CONF(5)
Impressum