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 2016-05-05 "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
  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
  40 Each cgroup namespace has its own set of cgroup root directories,
  41 which are the base points for the relative locations displayed in
  42 .IR /proc/[pid]/cgroup .
  43 When a process creates a new cgroup namespace using
  44 .BR clone (2)
  45 or
  46 .BR unshare (2)
  47 with the
  48 .BR CLONE_NEWCGROUP
  49 flag, then its current cgroups directories become its cgroup root directories.
  50 (This applies both for the cgroups version 1 hierarchies
  51 and the cgroups version 2 unified hierarchy.)
  52
  53 When viewing
  54 .IR /proc/[pid]/cgroup ,
  55 the pathname shown in the third field of each record will be
  56 relative to the reading process's cgroup root directory.
  57 If the cgroup directory of the target process lies outside
  58 the root directory of the reading process's cgroup namespace,
  59 then the pathname will show
  60 .I ../
  61 entries for each ancestor level in the cgroup hierarchy.
  62
  63 The following shell session demonstrates the effect of creating
  64 a new cgroup namespace.
  65 First, (as superuser) we create a child cgroup in the
  66 .I freezer
  67 hierarchy, and put the shell into that cgroup:
  68
  69 .nf
  70 .in +4n
  71 # \fBmkdir \-p /sys/fs/cgroup/freezer/sub\fP
  72 # \fBecho $$\fP                      # Show PID of this shell
  73 30655
  74 # \fBsh \-c 'echo 30655 > /sys/fs/cgroup/sub'\fP
  75 # \fBcat /proc/self/cgroup | grep freezer\fP
  76 7:freezer:/sub
  77 .in
  78 .fi
  79
  80 Next, we use
  81 .BR unshare (1)
  82 to create a process running a new shell in new cgroup and mount namespaces:
  83
  84 .nf
  85 .in +4n
  86 # \fBunshare \-Cm bash\fP
  87 .in
  88 .fi
  89
  90 We then inspect the
  91 .IR /proc/[pid]/cgroup
  92 files of, respectively, the new shell process started by the
  93 .BR unshare (1)
  94 command, a process that is in the original cgroup namespace
  95 .RI ( init ,
  96 with PID 1), and a process in a sibling cgroup:
  97
  98 .nf
  99 .in +4n
 100 $ \fBcat /proc/self/cgroup | grep freezer\fP
 101 7:freezer:/
 102 $ \fBcat /proc/1/cgroup | grep freezer\fP
 103 7:freezer:/..
 104 $ \fBcat /proc/20124/cgroup | grep freezer\fP
 105 7:freezer:/../sub2
 106 .in
 107 .fi
 108
 109 However, when we look in
 110 .IR /proc/self/mountinfo
 111 we see the following anomaly:
 112
 113 .nf
 114 .in +4n
 115 # \fBcat /proc/self/mountinfo | grep freezer\fP
 116 155 145 0:32 /.. /sys/fs/cgroup/freezer ...
 117 .in
 118 .fi
 119
 120 The fourth field of this file should show the
 121 directory in the cgroup filesystem which forms the root of this mount.
 122 Since by the definition of cgroup namespaces, the process's current
 123 freezer cgroup directory became its root freezer cgroup directory,
 124 we should see \(aq/\(aq in this field.
 125 The problem here is that we are seeing a mount entry for the cgroup
 126 filesystem corresponding to our initial shell process's cgroup namespace
 127 (whose cgroup filesystem is indeed rooted in the parent directory of
 128 .IR sub ).
 129 We need to remount the freezer cgroup filesystem
 130 inside this cgroup namespace, after which we see the expected results:
 131
 132 .nf
 133 .in +4n
 134 # mount \-\-make\-rprivate     # Don't propagate mount events
 135                             # to other namespaces
 136 # umount /sys/fs/cgroup/freezer
 137 # mount \-t cgroup \-o freezer freezer /sys/fs/cgroup/freezer
 138 # cat /proc/self/mountinfo | grep freezer
 139 155 145 0:32 / /sys/fs/cgroup/freezer rw,relatime ...
 140 .in
 141 .fi
 142
 143 Use of cgroup namespaces requires a kernel that is configured with the
 144 .B CONFIG_CGROUPS
 145 option.
 146 .\"
 147 .SH NOTES
 148 Among the purposes served by the
 149 virtualization provided by cgroup namespaces are the following:
 150 .IP * 2
 151 It prevents information leaks whereby cgroup directory paths outside of
 152 a container would otherwise be visible to processes in the container.
 153 Such leakages could, for example,
 154 reveal information about the container framework
 155 to containerized applications.
 156 .IP *
 157 It allows easier and more flexible
 158 confinement of container root tasks, because they can mount
 159 their own cgroup filesystems without gaining access to ancestor
 160 cgroup directories.
 161 Consider, for example, the following scenario:
 162 .RS 4
 163 .IP \(bu 2
 164 We have a cgroup directory,
 165 .IR /cg/1 ,
 166 that is owned by user ID 9000.
 167 .IP \(bu
 168 We have a process,
 169 .IR X ,
 170 also owned by user ID 9000,
 171 that is namespaced under the cgroup
 172 .IR /cg/1/2
 173 (i.e.,
 174 .I X
 175 was placed in a new cgroup namespace via
 176 .BR clone (2)
 177 or
 178 .BR unshare (2)
 179 with the
 180 .BR CLONE_NEWCGROUP
 181 flag).
 182 .RE
 183 .IP
 184 In the absence of cgroup namespacing, because the cgroup directory
 185 .IR /cg/1
 186 is owned (and writable) by UID 9000 and process X is also owned
 187 by user ID 9000, then process X would be able to modify the contents
 188 of cgroups files (i.e., change cgroup settings) not only in
 189 .IR /cg/1/2
 190 but also in the ancestor cgroup directory
 191 .IR /cg/1 .
 192 Namespacing process
 193 .IR X
 194 under the cgroup directory
 195 .IR /cg/1/2
 196 prevents it modifying files in
 197 .IR /cg/1 ,
 198 since it cannot even see the contents of that directory
 199 (or of further removed cgroup ancestor directories).
 200 Combined with correct enforcement of hierarchical limits,
 201 this prevents that process X from escaping the limits imposed
 202 by ancestor cgroups.
 203 .SH CONFORMING TO
 204 Namespaces are a Linux-specific feature.
 205 .SH SEE ALSO
 206 .BR unshare (1),
 207 .BR clone (2),
 208 .BR setns (2),
 209 .BR unshare (2),
 210 .BR proc (5),
 211 .BR cgroups (7),
 212 .BR credentials (7),
 213 .BR user_namespaces (7)