1CGROUP_NAMESPACES(7)       Linux Programmer's Manual      CGROUP_NAMESPACES(7)
2
3
4

NAME

6       cgroup_namespaces - overview of Linux cgroup namespaces
7

DESCRIPTION

9       For an overview of namespaces, see namespaces(7).
10
11       Cgroup  namespaces  virtualize  the  view  of  a process's cgroups (see
12       cgroups(7)) as seen via /proc/[pid]/cgroup and /proc/[pid]/mountinfo.
13
14       Each cgroup namespace has its  own  set  of  cgroup  root  directories.
15       These  root  directories are the base points for the relative locations
16       displayed in the corresponding records in the /proc/[pid]/cgroup  file.
17       When  a  process  creates  a  new  cgroup  namespace  using clone(2) or
18       unshare(2) with the CLONE_NEWCGROUP flag, it enters a new cgroup names‐
19       pace  in  which  its current cgroups directories become the cgroup root
20       directories of the new namespace.  (This applies both for  the  cgroups
21       version 1 hierarchies and the cgroups version 2 unified hierarchy.)
22
23       When  viewing /proc/[pid]/cgroup, the pathname shown in the third field
24       of each record will be relative to the reading process's root directory
25       for the corresponding cgroup hierarchy.  If the cgroup directory of the
26       target process lies outside the root directory of the reading process's
27       cgroup  namespace,  then  the  pathname  will show ../ entries for each
28       ancestor level in the cgroup hierarchy.
29
30       The following shell session demonstrates the effect of creating  a  new
31       cgroup  namespace.   First,  (as superuser) we create a child cgroup in
32       the freezer hierarchy, and put the shell into that cgroup:
33
34           # mkdir -p /sys/fs/cgroup/freezer/sub
35           # echo $$                      # Show PID of this shell
36           30655
37           # sh -c 'echo 30655 > /sys/fs/cgroup/freezer/sub/cgroup.procs'
38           # cat /proc/self/cgroup | grep freezer
39           7:freezer:/sub
40
41       Next, we use unshare(1) to create a process running a new shell in  new
42       cgroup and mount namespaces:
43
44           # unshare -Cm bash
45
46       We  then inspect the /proc/[pid]/cgroup files of, respectively, the new
47       shell process started by the unshare(1) command, a process that  is  in
48       the  original  cgroup  namespace (init, with PID 1), and a process in a
49       sibling cgroup (sub2):
50
51           $ cat /proc/self/cgroup | grep freezer
52           7:freezer:/
53           $ cat /proc/1/cgroup | grep freezer
54           7:freezer:/..
55           $ cat /proc/20124/cgroup | grep freezer
56           7:freezer:/../sub2
57
58       From the output of the first command, we see that  the  freezer  cgroup
59       membership of the new shell (which is in the same cgroup as the initial
60       shell) is shown defined relative to the freezer cgroup  root  directory
61       that  was  established  when the new cgroup namespace was created.  (In
62       absolute terms, the new shell is in the /sub freezer  cgroup,  and  the
63       root directory of the freezer cgroup hierarchy in the new cgroup names‐
64       pace is also /sub.  Thus, the new shell's  cgroup  membership  is  dis‐
65       played as '/'.)
66
67       However,  when  we  look  in  /proc/self/mountinfo we see the following
68       anomaly:
69
70           # cat /proc/self/mountinfo | grep freezer
71           155 145 0:32 /.. /sys/fs/cgroup/freezer ...
72
73       The fourth field of this line (/..)  should show the directory  in  the
74       cgroup  filesystem  which  forms  the root of this mount.  Since by the
75       definition of cgroup namespaces, the process's current  freezer  cgroup
76       directory  became  its root freezer cgroup directory, we should see '/'
77       in this field.  The problem here is that we are seeing  a  mount  entry
78       for  the cgroup filesystem corresponding to our initial shell process's
79       cgroup namespace (whose cgroup filesystem is indeed rooted in the  par‐
80       ent  directory of sub).  We need to remount the freezer cgroup filesys‐
81       tem inside this cgroup namespace,  after  which  we  see  the  expected
82       results:
83
84           # mount --make-rslave /     # Don't propagate mount events
85                                       # to other namespaces
86           # umount /sys/fs/cgroup/freezer
87           # mount -t cgroup -o freezer freezer /sys/fs/cgroup/freezer
88           # cat /proc/self/mountinfo | grep freezer
89           155 145 0:32 / /sys/fs/cgroup/freezer rw,relatime ...
90
91       Use  of cgroup namespaces requires a kernel that is configured with the
92       CONFIG_CGROUPS option.
93

CONFORMING TO

95       Namespaces are a Linux-specific feature.
96

NOTES

98       Among the purposes served by  the  virtualization  provided  by  cgroup
99       namespaces are the following:
100
101       * It  prevents information leaks whereby cgroup directory paths outside
102         of a container would otherwise be visible to processes  in  the  con‐
103         tainer.   Such  leakages could, for example, reveal information about
104         the container framework to containerized applications.
105
106       * It eases tasks such as container migration.  The virtualization  pro‐
107         vided  by  cgroup  namespaces  allows  containers to be isolated from
108         knowledge of the pathnames of ancestor cgroups.  Without such  isola‐
109         tion,  the  full  cgroup  pathnames (displayed in /proc/self/cgroups)
110         would need to be replicated on the target  system  when  migrating  a
111         container; those pathnames would also need to be unique, so that they
112         don't conflict with other pathnames on the target system.
113
114       * It allows better confinement of containerized processes,  because  it
115         is possible to mount the container's cgroup filesystems such that the
116         container processes can't gain access to ancestor cgroup directories.
117         Consider, for example, the following scenario:
118
119           · We have a cgroup directory, /cg/1, that is owned by user ID 9000.
120
121           · We  have a process, X, also owned by user ID 9000, that is names‐
122             paced under the cgroup /cg/1/2 (i.e.,  X  was  placed  in  a  new
123             cgroup  namespace via clone(2) or unshare(2) with the CLONE_NEWC‐
124             GROUP flag).
125
126         In the absence of cgroup namespacing, because  the  cgroup  directory
127         /cg/1 is owned (and writable) by UID 9000 and process X is also owned
128         by user ID 9000, then process X would be able to modify the  contents
129         of  cgroups  files (i.e., change cgroup settings) not only in /cg/1/2
130         but also in the ancestor cgroup directory /cg/1.  Namespacing process
131         X  under  the  cgroup directory /cg/1/2, in combination with suitable
132         mount operations for the cgroup filesystem (as shown above), prevents
133         it modifying files in /cg/1, since it cannot even see the contents of
134         that directory (or of further removed cgroup  ancestor  directories).
135         Combined  with  correct enforcement of hierarchical limits, this pre‐
136         vents process X from escaping the limits imposed by ancestor cgroups.
137

SEE ALSO

139       unshare(1), clone(2), setns(2), unshare(2), proc(5),  cgroups(7),  cre‐
140       dentials(7), namespaces(7), user_namespaces(7)
141

COLOPHON

143       This  page  is  part of release 4.16 of the Linux man-pages project.  A
144       description of the project, information about reporting bugs,  and  the
145       latest     version     of     this    page,    can    be    found    at
146       https://www.kernel.org/doc/man-pages/.
147
148
149
150Linux                             2017-09-15              CGROUP_NAMESPACES(7)
Impressum