CGCONFIG.CONF(5)

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

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.