doc/pam_cgfs.sgml.in

   1 <!--
   2
   3 lxc: linux Container library
   4
   5 (C) Copyright Canonical Inc. 2019
   6
   7 Authors:
   8 Venkata Harshavardhan Reddy Allu <venkataharshavardhan_ven@srmuniv.edu.in>
   9
  10 This library is free software; you can redistribute it and/or
  11 modify it under the terms of the GNU Lesser General Public
  12 License as published by the Free Software Foundation; either
  13 version 2.1 of the License, or (at your option) any later version.
  14
  15 This library is distributed in the hope that it will be useful,
  16 but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18 Lesser General Public License for more details.
  19
  20 You should have received a copy of the GNU Lesser General Public
  21 License along with this library; if not, write to the Free Software
  22 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  23
  24 -->
  25
  26 <!DOCTYPE refentry PUBLIC @docdtd@ [
  27
  28 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
  29 ]>
  30
  31 <refentry>
  32
  33   <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
  34
  35   <refmeta>
  36     <refentrytitle>pam_cgfs</refentrytitle>
  37     <manvolnum>8</manvolnum>
  38   </refmeta>
  39
  40   <refnamediv>
  41     <refname>pam_cgfs</refname>
  42
  43     <refpurpose>
  44       cgroup management for unprivileged LXC containers.
  45     </refpurpose>
  46   </refnamediv>
  47
  48   <refsynopsisdiv>
  49     <cmdsynopsis>
  50       <command>pam_cgfs.so</command>
  51       <arg choice="req">-c <replaceable>kernel_controller,name=named_controller</replaceable></arg>
  52     </cmdsynopsis>
  53   </refsynopsisdiv>
  54
  55   <refsect1>
  56     <title>Description</title>
  57
  58     <para>
  59       LXC has supported fully unprivileged containers since LXC 1.0.
  60       Fully unprivileged containers are the safest containers and are run by
  61       normal (non-root) users.  This is achieved by using user namespaces by
  62       mapping between a range of UIDs and GIDs on the host to a different
  63       (unprivileged) range of UIDs and GIDs in the container. That means the uid
  64       0 (root) in the container is mapped to an unprivileged user id (something
  65       like 1000000) outside of the container and only has rights on resources
  66       that it owns itself.
  67     </para>
  68     <para>
  69       Cgroup management of fully unprivileged containers means restricting the
  70       resources used by these containers like limiting the CPU usage of a
  71       container, or the number of processes it is allowed to spawn, or the
  72       memory it is allowed to consume. It is clear that the fully
  73       unprivileged containers are run by normal users and there is a need to
  74       limit and manage resource consumption among the containers.
  75       But unprivileged cgroup management is not easy with most init systems.
  76       So, the pam_cgfs.so came into existence.
  77     </para>
  78
  79     <para>
  80       The <command>pam_cgfs.so</command> module can handle both pure cgroupfs v1
  81       (<filename>/sys/fs/cgroup/$controller</filename>) and pure cgroupfs
  82       v2 (<filename>/sys/fs/cgroup</filename>), as well as mixed mounts,
  83       where some controllers are mounted in a standard cgroupfs v1 hierarchy
  84       (<filename>/sys/fs/cgroup/$controller</filename>) and others in
  85       cgroupfs v2 hierarchy (<filename>/sys/fs/cgroup/unified</filename>).
  86       Writeable cgroups are either created for all controllers or, if specified,
  87       for only controllers listed as arguments on the command line.
  88     </para>
  89
  90     <para>
  91       The cgroup created <filename>user/$user/n</filename> will be for the nth
  92       session under cgroup kernel controller hierarchy.
  93     </para>
  94
  95     <para>
  96       Systems with a systemd init system are treated specifically, both with
  97       respect to cgroupfs v1 and cgroupfs v2. For  both, cgroupfs v1 and
  98       cgroupfs v2, the module checks whether systemd already placed the user in
  99       a cgroup it created <filename>user.slice/user-$uid/session-n.scope
 100       </filename> by checking whether $uid == login uid. If so, the login
 101       user chown the <filename>session-n.scope</filename>, else a cgroup is
 102       created as outlined above (<filename>user/$user/n</filename>) and chown it
 103       to login uid. If the init system has already placed the login user inside
 104       a session specific group, the <command>pam_cgfs.so</command> module is
 105       smart enough to detect it and re-use the cgroup.
 106     </para>
 107
 108     <para>
 109       In essence,  the <command>pam_cgfs.so</command> module takes care of
 110       placing unprivileged (non-root) users into writable cgroups at login
 111       and also cleaning up these cgroup hierarchies on logout, so they are free
 112       to delegate resources to containers as needed that have been provided to
 113       them.
 114     </para>
 115
 116   </refsect1>
 117
 118   <refsect1>
 119
 120     <title>Options</title>
 121
 122     <variablelist>
 123
 124           <varlistentry>
 125             <term> <option>-c <replaceable>controller-list</replaceable></option> </term>
 126            <listitem>
 127             <para>
 128         Takes a string argument which sets the list of kernel controllers and
 129         named controllers delimited by commas in-between “,”. Named controllers
 130         need to be specified in the form “name=$namedcontroller”. Can use “all”
 131         enable all cgroup resource controller hierarchies. Specifying “all” and
 132         other controllers explicitly returns PAM_SESSION_ERR.
 133       </para>
 134            </listitem>
 135           </varlistentry>
 136
 137     </variablelist>
 138
 139   </refsect1>
 140
 141   <refsect1>
 142     <title>Module types provided</title>
 143     <para>
 144       Only <option>session</option> module type is provided (and needed).
 145     </para>
 146   </refsect1>
 147
 148   <refsect1>
 149
 150     <title>Return Values</title>
 151
 152     <variablelist>
 153
 154       <varlistentry>
 155         <term>PAM_SUCCESS</term>
 156         <listitem>
 157           <para>
 158             Writeable cgroups have been created for the user.
 159           </para>
 160         </listitem>
 161       </varlistentry>
 162
 163       <varlistentry>
 164         <term>PAM_SESSION_ERR</term>
 165         <listitem>
 166           <para>
 167             Failed to create writable cgroups for the user.
 168           </para>
 169         </listitem>
 170       </varlistentry>
 171
 172     </variablelist>
 173
 174   </refsect1>
 175
 176   <refsect1>
 177
 178     <title>Files</title>
 179
 180     <variablelist>
 181
 182       <varlistentry>
 183         <term>/etc/pam.d/common-session{,-noninteractive}</term>
 184         <listitem>
 185           <para>
 186             Default configuration is added at the end of these files.
 187           </para>
 188         </listitem>
 189       </varlistentry>
 190
 191     </variablelist>
 192
 193   </refsect1>
 194
 195   <refsect1>
 196     <title>EXAMPLE</title>
 197     <programlisting>
 198 session optional        pam_cgfs.so -c freezer,memory,named=systemd
 199 # default configuration
 200 # user writable cgroups are created under freezer, memory and named cgroup systemd hierarchies.
 201 # /sys/fs/cgroup/$controller/user/$user/n for freezer,memory.
 202 # /sys/fs/cgroup/systemd/user.slice/user-$uid/session-n.scope for systemd.
 203
 204 session optional        pam_cgfs.so -c all
 205 # user writable cgroups are created under all cgroup controllers.
 206
 207 session optional        pam_cgfs.so -c all,memory,freezer
 208 # invalid argument and returns PAM_SESSION_ERR
 209     </programlisting>
 210   </refsect1>
 211
 212   <refsect1>
 213     <title>See Also</title>
 214
 215     <simpara>
 216       <citerefentry>
 217       <refentrytitle><command>lxc-cgroup</command></refentrytitle>
 218       <manvolnum>1</manvolnum>
 219       </citerefentry>,
 220
 221       <citerefentry>
 222       <refentrytitle><command>cgroups</command></refentrytitle>
 223       <manvolnum>7</manvolnum>
 224       </citerefentry>,
 225
 226       <citerefentry>
 227       <refentrytitle><command>user_namespaces</command></refentrytitle>
 228       <manvolnum>7</manvolnum>
 229       </citerefentry>,
 230
 231       <citerefentry>
 232       <refentrytitle><command>namespaces</command></refentrytitle>
 233       <manvolnum>7</manvolnum>
 234       </citerefentry>,
 235
 236       <citerefentry>
 237       <refentrytitle><command>pam</command></refentrytitle>
 238       <manvolnum>8</manvolnum>
 239       </citerefentry>
 240     </simpara>
 241
 242
 243   </refsect1>
 244
 245
 246   <refsect1>
 247     <title>Author</title>
 248     <para>Venkata Harshavardhan Reddy Allu <email>venkataharshavardhan_ven@srmuniv.edu.in</email></para>
 249   </refsect1>
 250
 251 </refentry>
 252
 253 <!-- Keep this comment at the end of the file
 254 Local variables:
 255 mode: sgml
 256 sgml-omittag:t
 257 sgml-shorttag:t
 258 sgml-minimize-attributes:nil
 259 sgml-always-quote-attributes:t
 260 sgml-indent-step:2
 261 sgml-indent-data:t
 262 sgml-parent-document:nil
 263 sgml-default-dtd-file:nil
 264 sgml-exposed-tags:nil
 265 sgml-local-catalogs:nil
 266 sgml-local-ecat-files:nil
 267 End:
 268 -->