Provided by: cgroup-tools_0.41-7ubuntu1_amd64 bug

NAME

       cgconfig.conf - libcgroup configuration file

DESCRIPTION

       cgconfig.conf  is  a  configuration file used by libcgroup to define control groups, their
       parameters and their mount points.  The  file  consists  of  mount  ,  group  and  default
       sections.  These sections can be in arbitrary order and all of them are optional. Any line
       starting with '#' is considered a comment line and is ignored.

       mount section has this form:

              mount {
                     <controller> = <path>;
                     ...
              }

       controller
              Name of the kernel subsystem. The list of subsystems supported by the kernel can be
              found  in  /proc/cgroups  file.  Named  hierarchy  can  be  specified as controller
              "name=<somename>". Do not forget to use double quotes around this  controller  name
              (see examples below).

              Libcgroup  merges  all subsystems mounted to the same directory (see Example 1) and
              the directory is mounted only once.

       path   The directory path where the group hierarchy associated to a given controller shall
              be  mounted.  The directory is created automatically on cgconfig service startup if
              it does not exist and is deleted on service shutdown.

       If no mount section is specified, no controllers are mounted.

       group section has this form:

              group <name> {
                     [permissions]
                     <controller> {
                            <param name> = <param value>;
                            ...
                     }
                     ...
              }

       name   Name of the control group. It can contain only characters, which  are  allowed  for
              directory  names.  The groups form a tree, i.e. a control group can contain zero or
              more subgroups. Subgroups can be specified using '/' delimiter.

              The root control group is always created automatically in all hierarchies and it is
              the base of the group hierarchy. It can be explicitly specified in cgconfig.conf by
              using '.' as group name. This can be used e.g. to set its permissions, as shown  in
              Example 6.

              When  the  parent  control  group  of  a  subgroup  is  not specified it is created
              automatically.

       permissions
              Permissions of the given control group on  mounted  filesystem.   root  has  always
              permission  to  do anything with the control group.  Permissions have the following
              syntax:
                        perm {
                               task {
                                      uid = <task user>;
                                      gid = <task group>;
                                      fperm = <file permissions>
                               }
                               admin {
                                      uid = <admin name>;
                                      gid = <admin group>;
                                      dperm = <directory permissions>
                                      fperm = <file permissions>
                               }
                        }

              task user/group  Name of the user and the group, which own the tasks  file  of  the
                               control  group.  Given  fperm  then  specify the file permissions.
                               Please note that the given value is not  used  as  was  specified.
                               Instead,  current file owner permissions are used as a "umask" for
                               group and others permissions. For example if fperm = 777 then both
                               group and others will get the same permissions as the file owner.

              admin user/group Name  of  the  user  and  the  group which own the rest of control
                               group's files. Given fperm and dperm control  file  and  directory
                               permissions.    Again,   the   given   value   is  masked  by  the
                               file/directory owner permissions.

              Permissions are only apply to the enclosing control group and are not inherited  by
              subgroups.  If  there is no perm section in the control group definition, root:root
              is the owner of all files and default file permissions are preserved if fperm resp.
              dperm are not specified.

       controller
              Name  of the kernel subsystem.  The section can be empty, default kernel parameters
              will be used in this case. By specifying controller the control group and  all  its
              parents  are  controlled  by  the  specific  subsystem.  One  control  group can be
              controlled by multiple subsystems, even if the subsystems are mounted on  different
              directories.  Each  control  group must be controlled by at least one subsystem, so
              that libcgroup knows in which hierarchies the control group should be created.

              The parameters of the given controller can be modified  in  the  following  section
              enclosed in brackets.

              param name
                     Name of the file to set. Each controller can have zero or more parameters.

              param value
                     Value which should be written to the file when the control group is created.
                     If it is enclosed in double quotes `"', it  can  contain  spaces  and  other
                     special characters.

       If no group section is specified, no groups are created.

       default section has this form:

              default {
                     perm {
                            task {
                                   uid = <task user>;
                                   gid = <task group>;
                                   fperm = <file permissions>
                            }
                            admin {
                                   uid = <admin name>;
                                   gid = <admin group>;
                                   dperm = <directory permissions>
                                   fperm = <file permissions>
                            }
                     }
              }

       Content of the perm section has the same form as in group section. The permissions defined
       here specify owner and permissions of groups and files of all groups, which  do  not  have
       explicitly specified their permissions in their group section.

       template  section  has  the  same  structure as group section. Template name uses the same
       templates string as  cgrules.conf  destination  tag  (see  (cgrules.conf  (5)).   Template
       definition  is  used  as a control group definition for rules in cgrules.conf (5) with the
       same destination name.  Templates does not use default section settings.

EXAMPLES

   Example 1
       The configuration file:

              mount {
                     cpu = /sys/fs/cgroup/cpu;
                     cpuacct = /sys/fs/cgroup/cpu;
              }

       creates the hierarchy controlled by two subsystems with no groups inside.  It  corresponds
       to the following operations:

              mkdir /sys/fs/cgroup/cpu
              mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

   Example 2
       The configuration file:

              mount {
                     cpu = /sys/fs/cgroup/cpu;
                     "name=scheduler" = /sys/fs/cgroup/cpu;
                     "name=noctrl" = /sys/fs/cgroup/noctrl;
              }

              group daemons {
                     cpu {
                            cpu.shares = "1000";
                     }
              }
              group test {
                     "name=noctrl" {
                     }
              }
       creates  two  hierarchies. One hierarchy named scheduler controlled by cpu subsystem, with
       group daemons inside. Second hierarchy is named noctrl without any controller, with  group
       test. It corresponds to following operations:

              mkdir /sys/fs/cgroup/cpu
              mount -t cgroup -o cpu,name=scheduler cpu /sys/fs/cgroup/cpu
              mount -t cgroup -o none,name=noctrl none /sys/fs/cgroup/noctrl

              mkdir /sys/fs/cgroup/cpu/daemons
              echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares

              mkdir /sys/fs/cgroup/noctrl/tests

       The  daemons  group  is  created automatically when its first subgroup is created. All its
       parameters have the default value and only root can access group's files.

       Since both cpuacct and cpu subsystems are mounted to the same directory,  all  groups  are
       implicitly  controlled  also  by cpuacct subsystem, even if there is no cpuacct section in
       any of the groups.

   Example 3
       The configuration file:

              mount {
                     cpu = /sys/fs/cgroup/cpu;
                     cpuacct = /sys/fs/cgroup/cpu;
              }

              group daemons/www {
                     perm {
                            task {
                                   uid = root;
                                   gid = webmaster;
                                   fperm = 770;
                            }
                            admin {
                                   uid = root;
                                   gid = root;
                                   dperm = 775;
                                   fperm = 744;
                            }
                     }
                     cpu {
                            cpu.shares = "1000";
                     }
              }

              group daemons/ftp {
                     perm {
                            task {
                                   uid = root;
                                   gid = ftpmaster;
                                   fperm = 774;
                            }
                            admin {
                                   uid = root;
                                   gid = root;
                                   dperm = 755;
                                   fperm = 700;
                            }
                     }
                     cpu {
                            cpu.shares = "500";
                     }
              }
       creates the hierarchy controlled by two  subsystems  with  one  group  and  two  subgroups
       inside,  setting  one  parameter.   It corresponds to the following operations (except for
       file permissions which are little bit trickier to emulate via chmod):

              mkdir /sys/fs/cgroup/cpu
              mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

              mkdir /sys/fs/cgroup/cpu/daemons

              mkdir /sys/fs/cgroup/cpu/daemons/www
              chown root:root /sys/fs/cgroup/cpu/daemons/www/*
              chown root:webmaster /sys/fs/cgroup/cpu/daemons/www/tasks
              echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares

               # + chmod the files so the result looks like:
               # ls -la /sys/fs/cgroup/cpu/daemons/www/
               # admin.dperm = 755:
               # drwxr-xr-x. 2 root webmaster 0 Jun 16 11:51 .
               #
               # admin.fperm = 744:
               # --w-------. 1 root webmaster 0 Jun 16 11:51 cgroup.event_control
               # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cgroup.procs
               # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.stat
               # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage
               # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage_percpu
               # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_period_us
               # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_runtime_us
               # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.shares
               # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 notify_on_release
               #
               # tasks.fperm = 770
               # -rw-rw----. 1 root webmaster 0 Jun 16 11:51 tasks

              mkdir /sys/fs/cgroup/cpu/daemons/ftp
              chown root:root /sys/fs/cgroup/cpu/daemons/ftp/*
              chown root:ftpmaster /sys/fs/cgroup/cpu/daemons/ftp/tasks
              echo 500 > /sys/fs/cgroup/cpu/daemons/ftp/cpu.shares

               # + chmod the files so the result looks like:
               # ls -la /sys/fs/cgroup/cpu/daemons/ftp/
               # admin.dperm = 755:
               # drwxr-xr-x. 2 root ftpmaster 0 Jun 16 11:51 .
               #
               # admin.fperm = 700:
               # --w-------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.event_control
               # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.procs
               # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.stat
               # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage
               # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage_percpu
               # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_period_us
               # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_runtime_us
               # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.shares
               # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 notify_on_release
               #
               # tasks.fperm = 774:
               # -rw-rw-r--. 1 root ftpmaster 0 Jun 16 11:51 tasks

       The daemons group is created automatically when its first subgroup  is  created.  All  its
       parameters have the default value and only root can access the group's files.

       Since  both  cpuacct  and cpu subsystems are mounted to the same directory, all groups are
       implicitly also controlled by the cpuacct subsystem, even if there is no  cpuacct  section
       in any of the groups.

   Example 4
       The configuration file:

              mount {
                     cpu = /sys/fs/cgroup/cpu;
                     cpuacct = /sys/fs/cgroup/cpuacct;
              }

              group daemons {
                     cpuacct{
                     }
                     cpu {
                     }
              }
       creates  two  hierarchies  and  one  common  group in both of them.  It corresponds to the
       following operations:

              mkdir /sys/fs/cgroup/cpu
              mkdir /sys/fs/cgroup/cpuacct
              mount -t cgroup -o cpu cpu /sys/fs/cgroup/cpu
              mount -t cgroup -o cpuacct cpuacct /sys/fs/cgroup/cpuacct

              mkdir /sys/fs/cgroup/cpu/daemons
              mkdir /sys/fs/cgroup/cpuacct/daemons

       In fact there are two groups created. One in the cpuacct hierarchy, the second in the  cpu
       hierarchy. These two groups have nothing in common and can contain different subgroups and
       different tasks.

   Example 5
       The configuration file:

              mount {
                     cpu = /sys/fs/cgroup/cpu;
                     cpuacct = /sys/fs/cgroup/cpuacct;
              }

              group daemons {
                     cpuacct{
                     }
              }

              group daemons/www {
                     cpu {
                            cpu.shares = "1000";
                     }
              }

              group daemons/ftp {
                     cpu {
                            cpu.shares = "500";
                     }
              }
       creates two hierarchies with few groups inside. One of  the  groups  is  created  in  both
       hierarchies.

       It corresponds to the following operations:

              mkdir /sys/fs/cgroup/cpu
              mkdir /sys/fs/cgroup/cpuacct
              mount -t cgroup -o cpu cpu /sys/fs/cgroup/cpu
              mount -t cgroup -o cpuacct cpuacct /sys/fs/cgroup/cpuacct

              mkdir /sys/fs/cgroup/cpuacct/daemons
              mkdir /sys/fs/cgroup/cpu/daemons
              mkdir /sys/fs/cgroup/cpu/daemons/www
              echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares
              mkdir /sys/fs/cgroup/cpu/daemons/ftp
              echo 500 > /sys/fs/cgroup/cpu/daemons/ftp/cpu.shares
       Group  daemons  is  created  in  both  hierarchies.  In the cpuacct hierarchy the group is
       explicitly mentioned in the configuration file. In the cpu hierarchy the group is  created
       implicitly when www is created there. These two groups have nothing in common, for example
       they do not share processes and subgroups. Groups www and ftp are created only in the  cpu
       hierarchy and are not controlled by the cpuacct subsystem.

   Example 6
       The configuration file:

              mount {
                     cpu = /sys/fs/cgroup/cpu;
                     cpuacct = /sys/fs/cgroup/cpu;
              }

              group . {
                     perm {
                            task {
                                   uid = root;
                                   gid = operator;
                            }
                            admin {
                                   uid = root;
                                   gid = operator;
                            }
                     }
                     cpu {
                     }
              }

              group daemons {
                     perm {
                            task {
                                   uid = root;
                                   gid = daemonmaster;
                            }
                            admin {
                                   uid = root;
                                   gid = operator;
                            }
                     }
                     cpu {
                     }
              }
       creates  the  hierarchy  controlled  by  two subsystems with one group having some special
       permissions.  It corresponds to the following operations:

              mkdir /sys/fs/cgroup/cpu
              mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

              chown root:operator /sys/fs/cgroup/cpu/*
              chown root:operator /sys/fs/cgroup/cpu/tasks

              mkdir /sys/fs/cgroup/cpu/daemons
              chown root:operator /sys/fs/cgroup/cpu/daemons/*
              chown root:daemonmaster /sys/fs/cgroup/cpu/daemons/tasks

       Users which are members of the operator  group  are  allowed  to  administer  the  control
       groups,  i.e.  create  new  control groups and move processes between these groups without
       having root privileges.

       Members of the daemonmaster group can move processes to the  daemons  control  group,  but
       they can not move the process out of the group. Only the operator or root can do that.

   Example 7
       The configuration file:

              mount {
                     cpu = /sys/fs/cgroup/cpu;
                     cpuacct = /sys/fs/cgroup/cpuacct;
              }

              group students {
                     cpuacct{
                     }
                     cpu {
                     }
              }

              template students/%u {
                     cpuacct{
                     }
                     cpu {
                     }
              }

              mkdir /sys/fs/cgroup/cpu/daemons
              mkdir /sys/fs/cgroup/cpuacct/daemons

       The  situation  is  the similar as in Example 4. The only difference is template, which is
       used if some rule uses "/students/%u" as a destination.

RECOMMENDATIONS

   Keep hierarchies separated
       Having multiple hierarchies is perfectly valid and can be useful in various scenarios.  To
       keeps things clean, do not create one group in multiple hierarchies. Examples 4 and 5 show
       how  unreadable  and  confusing  it  can  be,  especially  when  reading  somebody   elses
       configuration file.

   Explicit is better than implicit
       libcgroup  can  implicitly  create  groups which are needed for the creation of configured
       subgroups. This may be useful and save some typing in simple scenarios. When it  comes  to
       multiple  hierarchies,  it's  better  to explicitly specify all groups and all controllers
       related to them.

FILES

       /etc/cgconfig.conf
       default libcgroup configuration file

SEE ALSO

       cgconfigparser (8)

BUGS

       Parameter values must be single strings without spaces.  Parsing of quoted strings is  not
       implemented.

                                                                                 CGCONFIG.CONF(5)