Provided by: cgroup-bin_0.36.2-3_i386 bug

NAME

       cgconfig.conf - libcgroup configuration file

DESCRIPTION

       cgconfig.conf  is  the  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  comment
       line and is ignored.

       mount section has the 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 the 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.

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
              mkdir /mnt/cgroups/cpu/daemons/ftp
       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

       To be defined...

BUGS

       Parameter  values can be only single string without spaces.  Parsing of
       quoted strings is not implemented.

                                                              CGCONFIG.CONF(5)