Debian Codegraph @

doc/pam_cgfs.sgml.in

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