Here is my proposal for a man page describing content of /etc/cgconfig.conf.

I did not find any realistic example of configuration file, I just thought
of something mounting groups to /mnt/cgroups. Is it suitable location of
such mount points? Or is /container mentioned on libcg web the right place
for such mounts?

Feel free to rephrase and reformat anything, especially RECOMMENDATIONS
section would appreciate some 'official' content - I wrote there just my
experiences. I'm not native speaker, please look for grammar errors too.

Signed-off-by: Jan Safranek <jsafrane@redhat.com>
Reviewed-by: Ivana Varekova <varekova@redhat.com>

git-svn-id: https://libcg.svn.sourceforge.net/svnroot/libcg/trunk@315 4f4bb910-9a46-0410-90c8-c897d4f1cd53

1 files changed, 463 insertions, 0 deletions

diff --git a/doc/man/cgconfig.conf.5 b/doc/man/cgconfig.conf.5
new file mode 100644
index 0000000..6ea149a
--- /dev/null
+++ b/doc/man/cgconfig.conf.5
@@ -0,0 +1,463 @@
+.TH CGCONFIG.CONF 5
+.\"***********************************
+.SH NAME
+cgconfig.conf \- libcgroup configuration file
+.\"***********************************
+.SH DESCRIPTION
+.B "cgconfig.conf"
+is the configuration file used by
+.B libcgroup
+to define control groups, their parameters and also mount points.
+The file consists of
+.I mount
+and
+.I group
+sections.
+These sections can be in arbitrary order.
+Any line starting with '#' is considered as comment line and is
+ignored.
+.LP
+.I mount
+section has the 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 kernel subsystem. List of subsystems supported by kernel
+can be found in 
+.I /proc/cgroups
+file.
+.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 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.
+.LP
+.I group
+section has the 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. 
+When the parent control group of a subgroup is not specified,
+then 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>;
+.RE
+}
+admin {
+.RS
+uid = <admin name>;
+gid = <admin group>;
+.RE
+}
+.RE
+}
+.fi
+.RE
+.ft R
+
+.RS
+.TP 17
+.B "task user/group"
+Name of the user and the group, which owns
+.I tasks
+file of the control group. I.e. this user and members of this
+group has write access to the file.
+.TP 17
+.B "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.
+.LP
+Permissions are related only to enclosing control group and are not
+inherited by subgroups. If there is no
+.B perm
+section in control group definition,
+.I root:root
+is owner of all files.
+.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 to different directories. Each
+control group must be controlled by at least one subsystem, so
+.B 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.
+.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.
+.RE
+
+.\"********************************************"
+.SH EXAMPLES
+.LP
+.SS Example 1
+.LP
+The configuration file:
+.LP
+.RS
+.nf
+mount {
+.RS
+cpu = /mnt/cgroups/cpu;
+cpuacct = /mnt/cgroups/cpu;
+.RE
+}
+.fi
+.RE
+
+creates the hierarchy controlled by two subsystems, with no groups
+inside. It corresponds to following operations:
+.LP
+.RS
+.nf
+mkdir /mnt/cgroups/cpu
+mount -t cgroup -o cpu,cpuacct cpu /mnt/cgroups/cpu
+.fi
+.RE
+
+.SS Example 2
+.LP
+The configuration file:
+.LP
+.RS
+.nf
+mount {
+.RS
+cpu = /mnt/cgroups/cpu;
+cpuacct = /mnt/cgroups/cpu;
+.RE
+}
+
+group daemons/www {
+.RS
+perm {
+.RS
+task {
+.RS
+uid = root;
+gid = webmaster;
+.RE
+}
+admin {
+.RS
+uid = root;
+gid = root;
+.RE
+}
+.RE
+}
+cpu {
+.RS
+cpu.shares = 1000;
+.RE
+}
+.RE
+}
+
+group daemons/ftp {
+.RS
+perm {
+.RS
+task {
+.RS
+uid = root;
+gid = ftpmaster;
+.RE
+}
+admin {
+.RS
+uid = root;
+gid = root;
+.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 following operations:
+.LP
+.RS
+.nf
+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
+.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 implicilty 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 = /mnt/cgroups/cpu;
+cpuacct = /mnt/cgroups/cpuacct;
+.RE
+}
+
+group daemons {
+.RS
+cpuacct{
+}
+cpu {
+}
+.RE
+}
+.fi
+.RE
+creates two hierarchies and one common group in both of them.
+It corresponds to following operations:
+.LP
+.RS
+.nf
+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
+.fi
+.RE
+
+In fact there are two groups created. One in
+.I cpuacct
+hierarchy, the second in
+.I cpu
+hierarchy. These two groups have nothing in common and can
+contain different subgroups and different tasks.
+
+.SS Example 4
+.LP
+
+The configuration file:
+
+.LP
+.RS
+.nf
+mount {
+.RS
+cpu = /mnt/cgroups/cpu;
+cpuacct = /mnt/cgroups/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 groups
+is created in both hierarchies.
+
+It corresponds to following operations:
+.LP
+.RS
+.nf
+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
+mkdir /mnt/cgroups/cpu/daemons/ftp
+.fi
+.RE
+
+Group
+.I daemons
+is created in both hierarchies. In
+.I cpuacct
+hierarchy the groupis explicitly mentioned in the configuration
+file. In 
+.I cpu
+hierarchy is the group 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
+.I cpu
+hierarchy and are not controlled by
+.I cpuacct
+subsystem.
+
+.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 3 and 4 shows,
+how unreadable and confusing it can be, especially when reading
+somebody other's configuration file.
+
+.SS Explicit is better than implicit
+.B 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.
+
+.SH FILES
+.LP
+.PD .1v
+.TP 20
+.B /etc/cgconfig.conf
+.TP
+default libcgroup configuration file
+.PD 
+
+.SH SEE ALSO
+To be defined...
+
+.SH BUGS
+Parameter values can be only single string without spaces.
+Parsing of quoted strings is not implemented.
+
+.SH
+