CGCONFIG.CONF(5)CGCONFIG.CONF(5)NAMEcgconfig.conf - libcgroup configuration file
DESCRIPTIONcgconfig.conf is a configuration file used by libcgroup to define con‐
trol groups, their parameters and also their mount points. The file
consists of mount and group sections. These sections can be in arbi‐
trary order. Any line starting with
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. 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.
group section has this form:
group <name> {
[permissions]
<controller> {
<param name> = <param value>;
...
}
...
}
name Name of the control group. It may only contain 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 the '/' 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 the group
name. This can be used to e.g. set its permissions as shown in
Example 5.
If 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>;
}
admin {
uid = <admin name>;
gid = <admin group>;
}
}
task user/group Name of the user and the group, which own the
tasks file of the control group. I.e. this user
and members of this group have write access to
the file.
admin user/group Name of the user and the group which own the
rest of control group's files. These users are
allowed to set subsystem parameters and create
subgroups.
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.
controller
Name of the kernel subsystem. The section can be empty, default
kernel parameters will be used in this case. By specifying con‐
troller 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 dif‐
ferent directories. Each control group must be controlled by at
least one subsystem, so that libcgroup knows in which hierar‐
chies 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
The 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.
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 the 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 the
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 the group's files.
Since both cpuacct and cpu subsystems are mounted to the same direc‐
tory, all groups are implicitly also controlled by the cpuacct subsys‐
tem, 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 cor‐
responds to the 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 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 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 the groups is
created in both hierarchies.
It corresponds to the 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 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 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 hav‐
ing some special permissions. It corresponds to the following opera‐
tions:
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 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.
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 confus‐
ing 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 cre‐
ation of the 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)
