Provided by: cgroup-bin_0.37.1-1ubuntu10_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 also mount points.  The file consists of mount and  group  sections.  These
       sections  can be in arbitrary order. Any line starting with '#' is considered as a comment
       line and is ignored.

       mount section has this form:

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

       controller
              Name of kernel subsystem. List of subsystems supported by kernel can  be  found  in
              /proc/cgroups  file.  Libcgroup merges all subsystems mounted to the same directory
              (see Example 1) and the directory is mounted only once.

       path   The directory path, where group hierarchy associated to 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.

       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
              file by using '.' as group name. This can be used e.g. to set its  permissions,  as
              shown in Example 5.

              When  the  parent  control group of a subgroup is not specified, then 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>;
                               }
                               admin {
                                      uid = <admin name>;
                                      gid = <admin group>;
                               }
                        }

              task user/group  Name of the user and the group,  which  owns  tasks  file  of  the
                               control  group. I.e. this user and members of this group has write
                               access to the file.

              admin user/group Name of the user and the group, which owns  the  rest  of  control
                               group's files. These users are allowed to set subsystem parameters
                               and create subgroups.

              Permissions are related only to enclosing control group and are  not  inherited  by
              subgroups.  If  there  is no perm section in control group definition, root:root is
              owner of all files.

       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 to different
              directories. Each control group must be controlled by at least  one  subsystem,  so
              libcgroup knows, in which hierarchies the control group should be created.

              The parameters of given controller can be modified in 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.  Optionally it can be enclosed in double quotes `"', it can contain
                     spaces then.

EXAMPLES

   Example 1
       The configuration file:

              mount {
                     cpu = /mnt/cgroups/cpu;
                     cpuacct = /mnt/cgroups/cpu;
              }

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

              mkdir /mnt/cgroups/cpu
              mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu

   Example 2
       The configuration file:

              mount {
                     cpu = /mnt/cgroups/cpu;
                     cpuacct = /mnt/cgroups/cpu;
              }

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

              group daemons/ftp {
                     perm {
                            task {
                                   uid = root;
                                   gid = ftpmaster;
                            }
                            admin {
                                   uid = root;
                                   gid = root;
                            }
                     }
                     cpu {
                            cpu.shares = "500";
                     }
              }
       creates  the  hierarchy  controlled  by  two  subsystems  with one group and two subgroups
       inside, setting one parameter.  It corresponds to following operations:

              mkdir /mnt/cgroups/cpu
              mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu

              mkdir /mnt/cgroups/cpu/daemons

              mkdir /mnt/cgroups/cpu/daemons/www
              chown root:root /mnt/cgroups/cpu/daemons/www/*
              chown root:webmaster /mnt/cgroups/cpu/daemons/www/tasks
              echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares

              mkdir /mnt/cgroups/cpu/daemons/ftp
              chown root:root /mnt/cgroups/cpu/daemons/ftp/*
              chown root:ftpmaster /mnt/cgroups/cpu/daemons/ftp/tasks
              echo 500 > /mnt/cgroups/cpu/daemons/ftp/cpu.shares

       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 = /mnt/cgroups/cpu;
                     cpuacct = /mnt/cgroups/cpuacct;
              }

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

              mkdir /mnt/cgroups/cpu
              mkdir /mnt/cgroups/cpuacct
              mount -t cgroup -o cpu cpu /mnt/cgroups/cpu
              mount -t cgroup -o cpuacct cpuacct /mnt/cgroups/cpuacct

              mkdir /mnt/cgroups/cpu/daemons
              mkdir /mnt/cgroups/cpuacct/daemons

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

   Example 4
       The configuration file:

              mount {
                     cpu = /mnt/cgroups/cpu;
                     cpuacct = /mnt/cgroups/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  groups  is  created  in  both
       hierarchies.

       It corresponds to following operations:

              mkdir /mnt/cgroups/cpu
              mkdir /mnt/cgroups/cpuacct
              mount -t cgroup -o cpu cpu /mnt/cgroups/cpu
              mount -t cgroup -o cpuacct cpuacct /mnt/cgroups/cpuacct

              mkdir /mnt/cgroups/cpuacct/daemons
              mkdir /mnt/cgroups/cpu/daemons
              mkdir /mnt/cgroups/cpu/daemons/www
              echo 1000 > /mnt/cgroups/cpu/daemons/www/cpu.shares
              mkdir /mnt/cgroups/cpu/daemons/ftp
              echo 500 > /mnt/cgroups/cpu/daemons/ftp/cpu.shares
       Group daemons is created in both hierarchies. In cpuacct hierarchy the group is explicitly
       mentioned in the configuration file. In cpu hierarchy is the group 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  cpu  hierarchy  and
       are not controlled by cpuacct subsystem.

   Example 5
       The configuration file:

              mount {
                     cpu = /mnt/cgroups/cpu;
                     cpuacct = /mnt/cgroups/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 with some special
       permissions.  It corresponds to following operations:

              mkdir /mnt/cgroups/cpu
              mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu

              chown root:operator /mnt/cgroups/cpu/*
              chown root:operator /mnt/cgroups/cpu/tasks

              mkdir /mnt/cgroups/cpu/daemons
              chown root:operator /mnt/cgroups/cpu/daemons/*
              chown root:daemonmaster /mnt/cgroups/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 can move processes between these groups without
       having root privileges.

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

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  3  and  4
       shows,  how  unreadable  and  confusing it can be, especially when reading somebody others
       configuration file.

   Explicit is better than implicit
       libcgroup can implicitly create  groups  which  are  needed  for  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  can be only single string without spaces.  Parsing of quoted strings is
       not implemented.

                                                                                 CGCONFIG.CONF(5)