Rename README to README.md so that markdown is supported. This will allow for code coverage and continuous integration information to be directly embedded into the readme.
Signed-off-by: Tom Hromatka <tom.hroma...@oracle.com> --- README | 183 -------------------------------------------------------------- README.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+), 183 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 54e0f7b..0000000 --- a/README +++ /dev/null @@ -1,183 +0,0 @@ -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. - -- 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 <list of controllers>:<relative path to cgroup>] 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 <list of pids> - -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. - -- Build pam_cgroup.so - make pam_cgroup.so -- 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 at the end of /etc/pam.d/su file - -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" - -Try similar things with other services like sshd. - -Note: pam_cgroup.so moves the service providing process in the right cgroup - and not the process which will be launched later. Due to parent child - relationship, yet to be forked/execed process will launch in right - group. - -Ex. Lets say user root does "su test1". In this case process "su" is the - one providing service (launching a shell) for user "test1". pam_cgroup.so - will move process "su" to the user "test1"'s cgroup (Decided by the uid - and gid of "test1"). Now once su forks/execs a shell for user test1, - final shell is effectively running in the cgroup it should have been - running based on /etc/cgrules.conf for user 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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..54e0f7b --- /dev/null +++ b/README.md @@ -0,0 +1,183 @@ +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. + +- 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 <list of controllers>:<relative path to cgroup>] 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 <list of pids> + +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. + +- Build pam_cgroup.so + make pam_cgroup.so +- 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 at the end of /etc/pam.d/su file + +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" + +Try similar things with other services like sshd. + +Note: pam_cgroup.so moves the service providing process in the right cgroup + and not the process which will be launched later. Due to parent child + relationship, yet to be forked/execed process will launch in right + group. + +Ex. Lets say user root does "su test1". In this case process "su" is the + one providing service (launching a shell) for user "test1". pam_cgroup.so + will move process "su" to the user "test1"'s cgroup (Decided by the uid + and gid of "test1"). Now once su forks/execs a shell for user test1, + final shell is effectively running in the cgroup it should have been + running based on /etc/cgrules.conf for user 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. -- 1.8.3.1 _______________________________________________ Libcg-devel mailing list Libcg-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/libcg-devel
