man > cgconfig.conf(5)

Che Dong

CGCONFIG.CONF(5) File Formats Manual CGCONFIG.CONF(5)

NAME
cgconfig.conf - libcgroup configuration file

DESCRIPTION
cgconfig.conf is a configuration file used by libcgroup to define control groups, their pa‐
rameters and their mount points. The file consists of mount , group and default sections.
These sections can be in arbitrary order and all of them are optional. Any line starting with
'#' is considered a comment line and is ignored.

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. Named hierarchy can be specified as controller
"name=<somename>". Do not forget to use double quotes around this controller name (see
examples below). Apart from named hierarchy, additional mount options may be specified
by putting the controller and the options in quotes. Options supported are nosuid,
noexec and nodev.

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.

If no mount section is specified, no controllers are mounted.

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 di‐
rectory 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 by
using '.' as group name. This can be used e.g. to set its permissions, as shown in Ex‐
ample 6.

When the parent control group of a subgroup is not specified it is created automati‐
cally.

permissions
Permissions of the given control group on mounted filesystem. root has always permis‐
sion to do anything with the control group. Permissions have the following syntax:
perm {
task {
uid = <task user>;
gid = <task group>;
fperm = <file permissions>
}
admin {
uid = <admin name>;
gid = <admin group>;
dperm = <directory permissions>
fperm = <file permissions>
}
}

task user/group Name of the user and the group, which own the tasks file of the con‐
trol group. Given fperm then specify the file permissions. Please
note that the given value is not used as was specified. Instead, cur‐
rent file owner permissions are used as a "umask" for group and oth‐
ers permissions. For example if fperm = 777 then both group and oth‐
ers will get the same permissions as the file owner.

admin user/group Name of the user and the group which own the rest of control group's
files. Given fperm and dperm control file and directory permissions.
Again, the given value is masked by the file/directory owner permis‐
sions.

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 and default file permissions are preserved if fperm resp. dperm
are not specified.

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 par‐
ents are controlled by the specific subsystem. One control group can be controlled by
multiple subsystems, even if the subsystems are mounted on different directories. Each
control group must be controlled by at least one subsystem, so that libcgroup knows in
which hierarchies the control group should be created.

The parameters of the given controller can be modified in the following section en‐
closed 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. If
it is enclosed in double quotes `"', it can contain spaces and other special
characters.

If no group section is specified, no groups are created.

default section has this form:

default {
perm {
task {
uid = <task user>;
gid = <task group>;
fperm = <file permissions>
}
admin {
uid = <admin name>;
gid = <admin group>;
dperm = <directory permissions>
fperm = <file permissions>
}
}
}

Content of the perm section has the same form as in group section. The permissions defined
here specify owner and permissions of groups and files of all groups, which do not have ex‐
plicitly specified their permissions in their group section.

template section has the same structure as group section. Template name uses the same tem‐
plates string as cgrules.conf destination tag (see (cgrules.conf (5)). Template definition
is used as a control group definition for rules in cgrules.conf (5) with the same destination
name. Templates does not use default section settings.

/etc/cgconfig.d/ directory can be used for additional configuration files. cgrulesengd
searches this directory for additional templates.

EXAMPLES
Example 1
The configuration file:

mount {
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpu;
}

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

mkdir /sys/fs/cgroup/cpu
mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

Example 2
The configuration file:

mount {
cpu = /sys/fs/cgroup/cpu;
"name=scheduler" = /sys/fs/cgroup/cpu;
"name=noctrl" = /sys/fs/cgroup/noctrl;
}

group daemons {
cpu {
cpu.shares = "1000";
}
}
group test {
"name=noctrl" {
}
}
creates two hierarchies. One hierarchy named scheduler controlled by cpu subsystem, with
group daemons inside. Second hierarchy is named noctrl without any controller, with group
test. It corresponds to following operations:

mkdir /sys/fs/cgroup/cpu
mount -t cgroup -o cpu,name=scheduler cpu /sys/fs/cgroup/cpu
mount -t cgroup -o none,name=noctrl none /sys/fs/cgroup/noctrl

mkdir /sys/fs/cgroup/cpu/daemons
echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares

mkdir /sys/fs/cgroup/noctrl/tests

The daemons group is created automatically when its first subgroup is created. All its param‐
eters 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 im‐
plicitly controlled also by cpuacct subsystem, even if there is no cpuacct section in any of
the groups.

Example 3
The configuration file:

mount {
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpu;
}

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

group daemons/ftp {
perm {
task {
uid = root;
gid = ftpmaster;
fperm = 774;
}
admin {
uid = root;
gid = root;
dperm = 755;
fperm = 700;
}
}
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 (except for file permis‐
sions which are little bit trickier to emulate via chmod):

mkdir /sys/fs/cgroup/cpu
mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

mkdir /sys/fs/cgroup/cpu/daemons

mkdir /sys/fs/cgroup/cpu/daemons/www
chown root:root /sys/fs/cgroup/cpu/daemons/www/*
chown root:webmaster /sys/fs/cgroup/cpu/daemons/www/tasks
echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares

# + chmod the files so the result looks like:
# ls -la /sys/fs/cgroup/cpu/daemons/www/
# admin.dperm = 755:
# drwxr-xr-x. 2 root webmaster 0 Jun 16 11:51 .
#
# admin.fperm = 744:
# --w-------. 1 root webmaster 0 Jun 16 11:51 cgroup.event_control
# -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cgroup.procs
# -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.stat
# -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage
# -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage_percpu
# -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_period_us
# -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_runtime_us
# -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.shares
# -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 notify_on_release
#
# tasks.fperm = 770
# -rw-rw----. 1 root webmaster 0 Jun 16 11:51 tasks

mkdir /sys/fs/cgroup/cpu/daemons/ftp
chown root:root /sys/fs/cgroup/cpu/daemons/ftp/*
chown root:ftpmaster /sys/fs/cgroup/cpu/daemons/ftp/tasks
echo 500 > /sys/fs/cgroup/cpu/daemons/ftp/cpu.shares

# + chmod the files so the result looks like:
# ls -la /sys/fs/cgroup/cpu/daemons/ftp/
# admin.dperm = 755:
# drwxr-xr-x. 2 root ftpmaster 0 Jun 16 11:51 .
#
# admin.fperm = 700:
# --w-------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.event_control
# -r--------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.procs
# -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.stat
# -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage
# -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage_percpu
# -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_period_us
# -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_runtime_us
# -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.shares
# -rw-------. 1 root ftpmaster 0 Jun 16 11:51 notify_on_release
#
# tasks.fperm = 774:
# -rw-rw-r--. 1 root ftpmaster 0 Jun 16 11:51 tasks

The daemons group is created automatically when its first subgroup is created. All its param‐
eters have the default value and only root can access the group's files.

Since both cpuacct and cpu subsystems are mounted to the same directory, all groups are im‐
plicitly also controlled by the cpuacct subsystem, even if there is no cpuacct section in any
of the groups.

Example 4
The configuration file:

mount {
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpuacct;
}

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

mkdir /sys/fs/cgroup/cpu
mkdir /sys/fs/cgroup/cpuacct
mount -t cgroup -o cpu cpu /sys/fs/cgroup/cpu
mount -t cgroup -o cpuacct cpuacct /sys/fs/cgroup/cpuacct

mkdir /sys/fs/cgroup/cpu/daemons
mkdir /sys/fs/cgroup/cpuacct/daemons

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

Example 5
The configuration file:

mount {
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/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 hierar‐
chies.

It corresponds to the following operations:

mkdir /sys/fs/cgroup/cpu
mkdir /sys/fs/cgroup/cpuacct
mount -t cgroup -o cpu cpu /sys/fs/cgroup/cpu
mount -t cgroup -o cpuacct cpuacct /sys/fs/cgroup/cpuacct

mkdir /sys/fs/cgroup/cpuacct/daemons
mkdir /sys/fs/cgroup/cpu/daemons
mkdir /sys/fs/cgroup/cpu/daemons/www
echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares
mkdir /sys/fs/cgroup/cpu/daemons/ftp
echo 500 > /sys/fs/cgroup/cpu/daemons/ftp/cpu.shares
Group daemons is created in both hierarchies. In the cpuacct hierarchy the group is explic‐
itly mentioned in the configuration file. In the cpu hierarchy the group is created implic‐
itly 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 6
The configuration file:

mount {
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/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 having some special permis‐
sions. It corresponds to the following operations:

mkdir /sys/fs/cgroup/cpu
mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

chown root:operator /sys/fs/cgroup/cpu/*
chown root:operator /sys/fs/cgroup/cpu/tasks

mkdir /sys/fs/cgroup/cpu/daemons
chown root:operator /sys/fs/cgroup/cpu/daemons/*
chown root:daemonmaster /sys/fs/cgroup/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.

Example 7
The configuration file:

mount {
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpuacct;
}

group students {
cpuacct{
}
cpu {
}
}

template students/%u {
cpuacct{
}
cpu {
}
}

mkdir /sys/fs/cgroup/cpu/daemons
mkdir /sys/fs/cgroup/cpuacct/daemons

The situation is the similar as in Example 4. The only difference is template, which is used
if some rule uses "/students/%u" as a destination.

Example 8
The configuration file:

mount {
"cpu,nodev,nosuid,noexec" = /mnt/cgroups/cpu;
}

This is the same as mount -t cgroup cgroup -o nodev,nosuid,noexec,cpu /mnt/cgroups/cpu It
mounts the cpu controller with MS_NODEV, MS_NOSUID and MS_NOEXEC options passed.

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 4 and 5 show
how unreadable and confusing 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 creation of configured sub‐
groups. This may be useful and save some typing in simple scenarios. When it comes to multi‐
ple hierarchies, it's better to explicitly specify all groups and all controllers related to
them.

FILES
/etc/cgconfig.conf
default libcgroup configuration file

/etc/cgconfig.d/
default libcgroup configuration files directory