Bug 201047 - cgroup_namespace(7) - example walkthrough has missing step for child PID
Summary: cgroup_namespace(7) - example walkthrough has missing step for child PID
Status: RESOLVED CODE_FIX
Alias: None
Product: Documentation
Classification: Unclassified
Component: man-pages (show other bugs)
Hardware: All Linux
: P1 normal
Assignee: documentation_man-pages@kernel-bugs.osdl.org
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2018-09-08 13:48 UTC by Troy Engel
Modified: 2018-10-14 12:02 UTC (History)
1 user (show)

See Also:
Kernel Version:
Subsystem:
Regression: No
Bisected commit-id:


Attachments

Description Troy Engel 2018-09-08 13:48:17 UTC
Hello, while walking through the manpage example, learning how cgroup namespaces are constructed:

  http://man7.org/linux/man-pages/man7/cgroup_namespaces.7.html

...there is an example step that has a "sibling cgroup PID" appear out of nowhere, making reference to it but not describing how to recreate that scenario. The part right here:

       We then inspect the /proc/[pid]/cgroup files of, respectively, the
       new shell process started by the unshare(1) command, a process that
       is in the original cgroup namespace (init, with PID 1), and a process
       in a sibling cgroup (sub2):

           $ cat /proc/self/cgroup | grep freezer
           7:freezer:/
           $ cat /proc/1/cgroup | grep freezer
           7:freezer:/..
           $ cat /proc/20124/cgroup | grep freezer
           7:freezer:/../sub2

The problem is "and a process in a sibling cgroup (sub2)" (shown as PID 20124 here) - how did this get here? How do I recreate this? Following this example, there's no mention of how, it's out of place when following the instructions. There is nothing in any of the cgroup files which contain this (# grep freezer /proc/*/cgroup) while at this stage.

The intent is understood, however the man page seems to skip a step to create this in the teaching example. We should add whatever simple steps are needed to create the "process in a sibling cgroup" as outlined so it makes sense - as written, I have no clue where "sibling cgroup (sub2)" came from, it just appeared out of the blue in that step. Thanks!
Comment 1 Michael Kerrisk 2018-10-14 12:02:08 UTC
Actually, the text was intended to be as is when I wrote it. I tried to hint that the reader should simply assume that there is a sibling cgroup with a member process. But perhaps my hint was not strong enough, which I agree could be problematic for new users who are following along with the teaching example. 

So, as you suggest, I have made things more explicit, by showing the creation of 'sub2' and its member process:

       First, (as superuser) we create a  child  cgroup  in  the  freezer
       hierarchy,  and place a process in that cgroup that we will use as
       part of the demonstration below:

           # mkdir -p /sys/fs/cgroup/freezer/sub2
           # sleep 10000 &     # Create a process that lives for a while
           [1] 20124
           # echo 20124 > /sys/fs/cgroup/freezer/sub2/cgroup.procs

       We then create another child cgroup in the freezer  hierarchy  and
       put the shell into that cgroup:

           # mkdir -p /sys/fs/cgroup/freezer/sub
           # echo $$                      # Show PID of this shell
           30655
           # echo 30655 > /sys/fs/cgroup/freezer/sub/cgroup.procs
           # cat /proc/self/cgroup | grep freezer
           7:freezer:/sub

Thanks for the report!

Note You need to log in before you can comment on or make changes to this bug.