From 0ea80fd83c57c4d25729f4bba6ce0a357a6df9f7 Mon Sep 17 00:00:00 2001 From: Balbir Singh Date: Tue, 3 Feb 2009 09:43:57 +0000 Subject: 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 Reviewed-by: Ivana Varekova git-svn-id: https://libcg.svn.sourceforge.net/svnroot/libcg/trunk@315 4f4bb910-9a46-0410-90c8-c897d4f1cd53 --- doc/man/cgconfig.conf.5 | 463 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 463 insertions(+) create mode 100644 doc/man/cgconfig.conf.5 (limited to 'doc') 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 + = ; +.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 { +.RS +.ft B +[permissions] + { +.RS +.ft B + = ; +.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 = ; +gid = ; +.RE +} +admin { +.RS +uid = ; +gid = ; +.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 + -- cgit