man7/cgroup_namespaces.7

   1 .\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\"
  26 .TH CGROUP_NAMESPACES 7 2019-08-02 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 cgroup_namespaces \- overview of Linux cgroup namespaces
  29 .SH DESCRIPTION
  30 For an overview of namespaces, see
  31 .BR namespaces (7).
  32 .PP
  33 Cgroup namespaces virtualize the view of a process's cgroups (see
  34 .BR cgroups (7))
  35 as seen via
  36 .IR /proc/[pid]/cgroup
  37 and
  38 .IR /proc/[pid]/mountinfo .
  39 .PP
  40 Each cgroup namespace has its own set of cgroup root directories.
  41 These root directories are the base points for the relative
  42 locations displayed in the corresponding records in the
  43 .IR /proc/[pid]/cgroup
  44 file.
  45 When a process creates a new cgroup namespace using
  46 .BR clone (2)
  47 or
  48 .BR unshare (2)
  49 with the
  50 .BR CLONE_NEWCGROUP
  51 flag, its current
  52 cgroups directories become the cgroup root directories
  53 of the new namespace.
  54 (This applies both for the cgroups version 1 hierarchies
  55 and the cgroups version 2 unified hierarchy.)
  56 .PP
  57 When reading the cgroup memberships of a "target" process from
  58 .IR /proc/[pid]/cgroup ,
  59 the pathname shown in the third field of each record will be
  60 relative to the reading process's root directory
  61 for the corresponding cgroup hierarchy.
  62 If the cgroup directory of the target process lies outside
  63 the root directory of the reading process's cgroup namespace,
  64 then the pathname will show
  65 .I ../
  66 entries for each ancestor level in the cgroup hierarchy.
  67 .PP
  68 The following shell session demonstrates the effect of creating
  69 a new cgroup namespace.
  70 .PP
  71 First, (as superuser) in a shell in the initial cgroup namespace,
  72 we create a child cgroup in the
  73 .I freezer
  74 hierarchy, and place a process in that cgroup that we will
  75 use as part of the demonstration below:
  76 .PP
  77 .in +4n
  78 .EX
  79 # \fBmkdir \-p /sys/fs/cgroup/freezer/sub2\fP
  80 # \fBsleep 10000 &\fP     # Create a process that lives for a while
  81 [1] 20124
  82 # \fBecho 20124 > /sys/fs/cgroup/freezer/sub2/cgroup.procs\fP
  83 .EE
  84 .in
  85 .PP
  86 We then create another child cgroup in the
  87 .I freezer
  88 hierarchy and put the shell into that cgroup:
  89 .PP
  90 .in +4n
  91 .EX
  92 # \fBmkdir \-p /sys/fs/cgroup/freezer/sub\fP
  93 # \fBecho $$\fP                      # Show PID of this shell
  94 30655
  95 # \fBecho 30655 > /sys/fs/cgroup/freezer/sub/cgroup.procs\fP
  96 # \fBcat /proc/self/cgroup | grep freezer\fP
  97 7:freezer:/sub
  98 .EE
  99 .in
 100 .PP
 101 Next, we use
 102 .BR unshare (1)
 103 to create a process running a new shell in new cgroup and mount namespaces:
 104 .PP
 105 .EX
 106 .in +4n
 107 # \fBPS1="sh2# " unshare \-Cm bash\fP
 108 .in
 109 .EE
 110 .PP
 111 From the new shell started by
 112 .BR unshare (1),
 113 we then inspect the
 114 .IR /proc/[pid]/cgroup
 115 files of, respectively, the new shell,
 116 a process that is in the initial cgroup namespace
 117 .RI ( init ,
 118 with PID 1), and the process in the sibling cgroup
 119 .RI ( sub2 ):
 120 .PP
 121 .EX
 122 .in +4n
 123 sh2# \fBcat /proc/self/cgroup | grep freezer\fP
 124 7:freezer:/
 125 sh2# \fBcat /proc/1/cgroup | grep freezer\fP
 126 7:freezer:/..
 127 sh2# \fBcat /proc/20124/cgroup | grep freezer\fP
 128 7:freezer:/../sub2
 129 .in
 130 .EE
 131 .PP
 132 From the output of the first command,
 133 we see that the freezer cgroup membership of the new shell
 134 (which is in the same cgroup as the initial shell)
 135 is shown defined relative to the freezer cgroup root directory
 136 that was established when the new cgroup namespace was created.
 137 (In absolute terms,
 138 the new shell is in the
 139 .I /sub
 140 freezer cgroup,
 141 and the root directory of the freezer cgroup hierarchy
 142 in the new cgroup namespace is also
 143 .IR /sub .
 144 Thus, the new shell's cgroup membership is displayed as \(aq/\(aq.)
 145 .PP
 146 However, when we look in
 147 .IR /proc/self/mountinfo
 148 we see the following anomaly:
 149 .PP
 150 .EX
 151 .in +4n
 152 sh2# \fBcat /proc/self/mountinfo | grep freezer\fP
 153 155 145 0:32 /.. /sys/fs/cgroup/freezer ...
 154 .in
 155 .EE
 156 .PP
 157 The fourth field of this line
 158 .RI ( /.. )
 159 should show the
 160 directory in the cgroup filesystem which forms the root of this mount.
 161 Since by the definition of cgroup namespaces, the process's current
 162 freezer cgroup directory became its root freezer cgroup directory,
 163 we should see \(aq/\(aq in this field.
 164 The problem here is that we are seeing a mount entry for the cgroup
 165 filesystem corresponding to the initial cgroup namespace
 166 (whose cgroup filesystem is indeed rooted at the parent directory of
 167 .IR sub ).
 168 To fix this problem, we must remount the freezer cgroup filesystem
 169 from the new shell (i.e., perform the mount from a process that is in the
 170 new cgroup namespace), after which we see the expected results:
 171 .PP
 172 .EX
 173 .in +4n
 174 sh2# \fBmount \-\-make\-rslave /\fP     # Don't propagate mount events
 175                                # to other namespaces
 176 sh2# \fBumount /sys/fs/cgroup/freezer\fP
 177 sh2# \fBmount \-t cgroup \-o freezer freezer /sys/fs/cgroup/freezer\fP
 178 sh2# \fBcat /proc/self/mountinfo | grep freezer\fP
 179 155 145 0:32 / /sys/fs/cgroup/freezer rw,relatime ...
 180 .in
 181 .EE
 182 .\"
 183 .SH CONFORMING TO
 184 Namespaces are a Linux-specific feature.
 185 .SH NOTES
 186 Use of cgroup namespaces requires a kernel that is configured with the
 187 .B CONFIG_CGROUPS
 188 option.
 189 .PP
 190 The virtualization provided by cgroup namespaces serves a number of purposes:
 191 .IP * 2
 192 It prevents information leaks whereby cgroup directory paths outside of
 193 a container would otherwise be visible to processes in the container.
 194 Such leakages could, for example,
 195 reveal information about the container framework
 196 to containerized applications.
 197 .IP *
 198 It eases tasks such as container migration.
 199 The virtualization provided by cgroup namespaces
 200 allows containers to be isolated from knowledge of
 201 the pathnames of ancestor cgroups.
 202 Without such isolation, the full cgroup pathnames (displayed in
 203 .IR /proc/self/cgroups )
 204 would need to be replicated on the target system when migrating a container;
 205 those pathnames would also need to be unique,
 206 so that they don't conflict with other pathnames on the target system.
 207 .IP *
 208 It allows better confinement of containerized processes,
 209 because it is possible to mount the container's cgroup filesystems such that
 210 the container processes can't gain access to ancestor cgroup directories.
 211 Consider, for example, the following scenario:
 212 .RS 4
 213 .IP \(bu 2
 214 We have a cgroup directory,
 215 .IR /cg/1 ,
 216 that is owned by user ID 9000.
 217 .IP \(bu
 218 We have a process,
 219 .IR X ,
 220 also owned by user ID 9000,
 221 that is namespaced under the cgroup
 222 .IR /cg/1/2
 223 (i.e.,
 224 .I X
 225 was placed in a new cgroup namespace via
 226 .BR clone (2)
 227 or
 228 .BR unshare (2)
 229 with the
 230 .BR CLONE_NEWCGROUP
 231 flag).
 232 .RE
 233 .IP
 234 In the absence of cgroup namespacing, because the cgroup directory
 235 .IR /cg/1
 236 is owned (and writable) by UID 9000 and process
 237 .I X
 238 is also owned by user ID 9000, then process
 239 .I X
 240 would be able to modify the contents of cgroups files
 241 (i.e., change cgroup settings) not only in
 242 .IR /cg/1/2
 243 but also in the ancestor cgroup directory
 244 .IR /cg/1 .
 245 Namespacing process
 246 .IR X
 247 under the cgroup directory
 248 .IR /cg/1/2 ,
 249 in combination with suitable mount operations
 250 for the cgroup filesystem (as shown above),
 251 prevents it modifying files in
 252 .IR /cg/1 ,
 253 since it cannot even see the contents of that directory
 254 (or of further removed cgroup ancestor directories).
 255 Combined with correct enforcement of hierarchical limits,
 256 this prevents process
 257 .I X
 258 from escaping the limits imposed by ancestor cgroups.
 259 .SH SEE ALSO
 260 .BR unshare (1),
 261 .BR clone (2),
 262 .BR setns (2),
 263 .BR unshare (2),
 264 .BR proc (5),
 265 .BR cgroups (7),
 266 .BR credentials (7),
 267 .BR namespaces (7),
 268 .BR user_namespaces (7)