.TH CGCONFIG.CONF 5
.\"***********************************
.SH NAME
cgconfig.conf \- libcgroup configuration file
.\"***********************************
.SH DESCRIPTION
.B "cgconfig.conf"
is a configuration file used by
.B libcgroup
to define control groups, their parameters and their mount points.
The file consists of
.I mount
,
.I group
and
.I 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.
.LP
.I mount
section has this form:
.RS
.nf
.ft B
.sp
mount {
.RS
.ft B
<controller> = <path>;
.I "..."
.RE
.ft B
}
.ft R
.fi
.RE

.TP
.B controller
Name of the kernel subsystem. The list of subsystems supported by the kernel
can be found in 
.I /proc/cgroups
file. Named hierarchy can be specified as controller
\fB"name=<somename>"\fR. Do not forget to use double quotes around
this controller name (see examples below).

.B Libcgroup
merges all subsystems mounted to the same directory (see
Example 1) and the directory is mounted only once.

.TP
.B 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.
.LP

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

.I group
section has this form:
.RS
.nf
.ft B
.sp
group <name> {
.RS
.ft B
[permissions]
<controller> {
.RS
.ft B
<param name> = <param value>;
.I "..."
.RE
.ft B
}
.I "..."
.RE
.ft B
}
.ft R
.fi
.RE

.TP
.B 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
.B cgconfig.conf
by using '.' as group name. This can be used e.g. to set its permissions,
as shown in Example 6.

When the parent control group of a subgroup is not specified
it is created automatically.

.TP
.B permissions
Permissions of the given control group on mounted filesystem.
.I root
has always permission to do anything with the control group.
Permissions have the following syntax:
.RS 17
.ft B
.nf
perm {
.RS
.ft B
task {
.RS
.ft B
uid = <task user>;
gid = <task group>;
fperm = <file permissions>
.RE
}
admin {
.RS
uid = <admin name>;
gid = <admin group>;
dperm = <directory permissions>
fperm = <file permissions>
.RE
}
.RE
}
.fi
.RE
.ft R

.RS
.TP 17
.B "task user/group"
Name of the user and the group, which own the
.I tasks
file of the control group. Given fperm then specify the file permissions.
Please note that the given value is not used as was specified. Instead,
current file owner permissions are used as a "umask" for group and others
permissions. For example if fperm = 777 then both group and others will get
the same permissions as the file owner.
.TP 17
.B "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 permissions.
.LP
Permissions are only apply to the enclosing control group and are not
inherited by subgroups. If there is no
.B perm
section in the control group definition,
.I root:root
is the owner of all files and default file permissions are preserved if
fperm resp. dperm are not specified.
.RE
.TP
.B controller
Name of the kernel subsystem.
The section can be
empty, default kernel parameters will be used in this case. By
specifying
.B 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 on different directories. Each
control group must be controlled by at least one subsystem, so that
.B libcgroup
knows in which hierarchies the control group should be created.

The parameters of the given controller can be modified in the following
section enclosed in brackets.
.RS
.TP
.B param name
Name of the file to set. Each controller can have zero or more
parameters.
.TP
.B 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.
.RE

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

.I default
section has this form:
.RS
.nf
.ft B
.sp
default {
.RS
.ft B
perm {
.RS
.ft B
task {
.RS
.ft B
uid = <task user>;
gid = <task group>;
fperm = <file permissions>
.RE
}
admin {
.RS
uid = <admin name>;
gid = <admin group>;
dperm = <directory permissions>
fperm = <file permissions>
.RE
}
.RE
}
.RE
}
.ft R
.fi
.RE

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

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

.\"********************************************"
.SH EXAMPLES
.LP
.SS Example 1
.LP
The configuration file:
.LP
.RS
.nf
mount {
.RS
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpu;
.RE
}
.fi
.RE

creates the hierarchy controlled by two subsystems with no groups
inside. It corresponds to the following operations:
.LP
.RS
.nf
mkdir /sys/fs/cgroup/cpu
mount \-t cgroup \-o cpu,cpuacct cpu /sys/fs/cgroup/cpu
.fi
.RE

.SS Example 2
.LP
The configuration file:
.LP
.RS
.nf
mount {
.RS
cpu = /sys/fs/cgroup/cpu;
"name=scheduler" = /sys/fs/cgroup/cpu;
"name=noctrl" = /sys/fs/cgroup/noctrl;
.RE
}

group daemons {
.RS
cpu {
.RS
cpu.shares = "1000";
.RE
}
.RE
}
group test {
.RS
"name=noctrl" {
}
.RE
}
.RE
.fi
creates two hierarchies. One hierarchy named \fBscheduler\fR controlled by cpu
subsystem, with group \fBdaemons\fR inside. Second hierarchy is named
\fBnoctrl\fR without any controller, with group \fBtest\fR. It corresponds to
following operations:
.LP
.RS
.nf
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
.fi
.RE

The
.I 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.
.LP
Since both
.I cpuacct
and
.I cpu
subsystems are mounted to the same directory, all
groups are implicitly controlled also by
.I cpuacct
subsystem, even if there is no
.I cpuacct
section in any of the groups.
.RE

.SS Example 3
.LP
The configuration file:
.LP
.RS
.nf
mount {
.RS
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpu;
.RE
}

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

group daemons/ftp {
.RS
perm {
.RS
task {
.RS
uid = root;
gid = ftpmaster;
fperm = 774;
.RE
}
admin {
.RS
uid = root;
gid = root;
dperm = 755;
fperm = 700;
.RE
}
.RE
}
cpu {
.RS
cpu.shares = "500";
.RE
}
.RE
}
.RE
.fi
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 permissions
which are little bit trickier to emulate via chmod):

.LP
.RS
.nf
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

.fi
.RE

The
.I 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.
.LP
Since both
.I cpuacct
and
.I cpu
subsystems are mounted to the same directory, all
groups are implicitly also controlled by the
.I cpuacct
subsystem, even if there is no
.I cpuacct
section in any of the groups.
.RE

.SS Example 4
.LP
The configuration file:

.LP
.RS
.nf
mount {
.RS
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpuacct;
.RE
}

group daemons {
.RS
cpuacct{
}
cpu {
}
.RE
}
.fi
.RE
creates two hierarchies and one common group in both of them.
It corresponds to the following operations:
.LP
.RS
.nf
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
.fi
.RE

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

.SS Example 5
.LP

The configuration file:

.LP
.RS
.nf
mount {
.RS
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpuacct;
.RE
}

group daemons {
.RS
cpuacct{
}
.RE
}

group daemons/www {
.RS
cpu {
.RS
cpu.shares = "1000";
.RE
}
.RE
}

group daemons/ftp {
.RS
cpu {
.RS
cpu.shares = "500";
.RE
}
.RE
}
.fi
.RE
creates two hierarchies with few groups inside. One of the groups
is created in both hierarchies.

It corresponds to the following operations:
.LP
.RS
.nf
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
.fi
.RE
Group
.I daemons
is created in both hierarchies. In the
.I cpuacct
hierarchy the group is explicitly mentioned in the configuration
file. In the
.I cpu
hierarchy the group is created implicitly when
.I www
is created there. These two groups have nothing in common, for example
they do not share processes and subgroups. Groups
.I www
and
.I ftp
are created only in the
.I cpu
hierarchy and are not controlled by the
.I cpuacct
subsystem.

.SS Example 6
.LP
The configuration file:
.LP
.RS
.nf
mount {
.RS
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpu;
.RE
}

group . {
.RS
perm {
.RS
task {
.RS
uid = root;
gid = operator;
.RE
}
admin {
.RS
uid = root;
gid = operator;
.RE
}
.RE
}
cpu {
}
.RE
}

group daemons {
.RS
perm {
.RS
task {
.RS
uid = root;
gid = daemonmaster;
.RE
}
admin {
.RS
uid = root;
gid = operator;
.RE
}
.RE
}
cpu {
}
.RE
}
.RE
.fi
creates the hierarchy controlled by two subsystems with one group having some
special permissions.
It corresponds to the following operations:
.LP
.RS
.nf
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
.fi
.RE

Users which are members of the
.I 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
.I daemonmaster
group can move processes to the
.I daemons
control group, but they can not move the process out of the group. Only the
.I operator
or root can do that.

.SS Example 7
.LP
The configuration file:

.LP
.RS
.nf
mount {
.RS
cpu = /sys/fs/cgroup/cpu;
cpuacct = /sys/fs/cgroup/cpuacct;
.RE
}

group students {
.RS
cpuacct{
}
cpu {
}
.RE
}

template students/%u {
.RS
cpuacct{
}
cpu {
}
.RE
}

mkdir /sys/fs/cgroup/cpu/daemons
mkdir /sys/fs/cgroup/cpuacct/daemons
.fi
.RE

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.



.SH RECOMMENDATIONS
.SS 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.

.SS Explicit is better than implicit
.B libcgroup
can implicitly create groups which are needed for the 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.

.SH FILES
.LP
.PD .1v
.TP 20
.B /etc/cgconfig.conf
.TP
default libcgroup configuration file
.PD 

.SH SEE ALSO
cgconfigparser (8)

.SH BUGS
Parameter values must be single strings without spaces.
Parsing of quoted strings is not implemented.

.SH