Provided by: cgroup-bin_0.37.1-1ubuntu7_i386 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)