From 2fa28d8f1be10453f31deb1504ad6b5e017db5b9 Mon Sep 17 00:00:00 2001 From: Dhaval Giani Date: Wed, 13 Aug 2008 19:53:35 +0000 Subject: libcgroup: documentation Signed-off-by: Vivek Goyal Signed-off-by: Dhaval Giani git-svn-id: https://libcg.svn.sourceforge.net/svnroot/libcg/trunk@135 4f4bb910-9a46-0410-90c8-c897d4f1cd53 --- README | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) diff --git a/README b/README index b9cedca..0835004 100644 --- a/README +++ b/README @@ -13,3 +13,171 @@ Please follow the following steps (TODO: Automate these steps) b. copy tarball and spec file to correct place in the RPMBUILD c. Build an rpm of the spec file + +Design +======== + +After cgroup system has taken shape, its time to have some basic tools +in user space which can enable a user to use the resource management +functionality effictively. + +One of the needed functionality is rule based placement of a task. In general, +there can be either uid or gid or exec based rules. Admin/root will +control/enforce uid/gid based rules and exec based rules can be defined by +user in a config file residing in user's home dir and fully controlled by user. + +uid/gid based rules will be defined in /etc/cgrules.conf config file and +this file will be managed by root. + +Basic idea is that to begin with provide facility to implement rules +based on uid and gid. So a hierarchy might look like as follows. + + /mnt/cgroup + | | + gid1 gid2 + | | + uid1 uid2 + | | + proj1 proj2 + + +Admin will write rules to control the resources among users. Then users +can manage their own cgroup at their own (proj1 and proj2) and control +the resources as they want. + +Following are the few methods using which tasks can be placed in right +cgroups. + +- Use pam_cgroup PAM plugin which will make sure users are placed in right + cgroup at login time and any tasks launch after login, will continue to run + in user's cgroup. (PAM module is still on TODO list) + +- Use command line tool "cgexec" to launch the task in right cgroup. + +- Modify the program and use libcgroup provided APIs for placing a task + in right cgroup before doing exec(). + +- Use "cgclassify" tool to classify a already running task. + +- May be, a user space daemon can also be implemented which will listen to + kernel events and place the task in right group based on the rules. + This method involves few concerns. + + - Reliability of netlink socket. Messages can be dropped. + - Change the netlink with a cgroup controller which exports the + events. + + - Delay incurred since the event took place and task was actually placed + in right cgroup. + + - daemon will interfere with container's tasks which is not desired. + +HOWTO +===== + +Section 1: +---------- +To use "cgexec" to place the task in right cgroup. + +- make cgexec +- Run a task using cgexec. Following is the cgexec syntax. + + cgexec [-g :] command [arguments] + + Note: Cgroup controllers and path are optional. If user does not know the + right cgroup, cgexec will automatically place the task in right + cgroup based on /etc/cgrules.conf + +Example: + cgexec -g *:test1 ls + cgexec -g cpu,memory:test1 ls -l + cgexec -g cpu,memory:test1 -g swap:test2 ls -l + +Section 2 +--------- +To use "cgclassify" to place task in right cgroup. + +- make cgclassify +- Pick a task's pid to be classified, and run + cgclassify + +Example: +-------- + cgclassify 2140 4325 + + Note: After classification check out whether tasks 2140 and 4325 + are in the right cgroup or not (Based on rules in /etc/cgrules.conf) + +Section 3: +---------- +To use a pam plugin which will automatically place the task in right +cgroup upon login. + +- Download pam source tree and apply the patch for pam_cgroup module. +- Build pam_cgroup.so + ./configure; make +- Copy pam_cgroup.so to /lib/security/ +- Edit /etc/pam.d/su to make use of pam_cgroup.so session module upon + execution of su. + +example: Add following line to the end. +session optional pam_cgroup.so + +- Now launch a shell for a user "xyz" using su and the resulting shell + should be running in the cgroup designated for the user as specified + by cgrules.conf + + ex. "su test1" + +Section 4: +---------- +To use cgrulesengd which will move a task to right cgroup based on +rules in /etc/cgrules.conf do following. + +- build and install latest libcgroup.so +- build cgrulesengd + make cgrulesengd +- specify some uid/gid based rules in /etc/cgrules.conf +- Mount some controllers and create an hierarchy of cgroups (matching + your rules). +- Run cgrulesengd. + - ./cgrulesengd +- Launch some task or login as a user to the sytem. Daemon should automatically + place the task in right cgroup. + +FAQ +=== +Q. Why admin should not control "exec" based rules. +A. Unix file system provides access control only based on uid/gid. So + even if admin starts putting tasks based on uid/gid, it can't enforce + it. For example, consider following scenario. + + Lets say an admin creates following cgroup hierarchy. + + /container + | | + database browser + | | | | + user1 user2 user1 user2 + + Now admin wants to run all the database jobs under /container/database/ + and all the firefox jobs under /container/browser/. Based on which user + launched it, jobs should go in either user1 or user2 dir. + + Now assume that database subdir has to more cpu resources as compared to + browser subdir. Then a user, say user2, can always move his browser job + also to /container/database/user2 dir to get more cpu resources and + admin will not be able to control that. + + [Note: user2 will control what tasks can be added in /container/database/user2 + and will contol what further subdirs can be created under user2 dir. Root + should not restrict the control to root only for practical purposes. Its + something like that till /container/databse, admin controls the resources + and below that how resources are further subdivided among various projects + should be controlled by respective user]. + +In the light of above, it seems to make more sense that admin should enforce +rules only based on uid and gid. Probably later we can have a per user exec +based rules config file (~/.cgrules.conf), which can be parsed by cgrulesd +and then jobs launched by user will be placed in right cgroup based on +combination of rules in /etc/cgrules.conf and ~/cgrules.conf. -- cgit