<!--
   $Id: pam_limits.sgml,v 1.1.1.2 2002/09/15 20:08:31 hartmans Exp $
   
   This file was written by Andrew G. Morgan <morgan@kernel.org>
   from information compiled by Cristian Gafton (author of module)
-->

<sect1>The resource limits module

<sect2>Synopsis

<p>
<descrip>

<tag><bf>Module Name:</bf></tag>
<tt/pam_limits/

<tag><bf>Authors:</bf></tag>
Cristian Gafton &lt;gafton@redhat.com&gt; <newline>
Thanks are also due to Elliot Lee &lt;sopwith@redhat.com&gt;
for his comments on improving this module.

<tag><bf>Maintainer:</bf></tag>
Cristian Gafton - 1996/11/20

<tag><bf>Management groups provided:</bf></tag>
session

<tag><bf>Cryptographically sensitive:</bf></tag>
	
<tag><bf>Security rating:</bf></tag>

<tag><bf>Clean code base:</bf></tag>

<tag><bf>System dependencies:</bf></tag>
requires an <tt>/etc/security/limits.conf</tt> file and kernel support
for resource limits. Also uses the library, <tt/libpwdb/.

<tag><bf>Network aware:</bf></tag>

</descrip>

<sect2>Overview of module

<p>
This module, through the <bf/Linux-PAM/ <em/open/-session hook, sets
limits on the system resources that can be obtained in a
user-session. Its actions are dictated more explicitly through the
configuration file discussed below.

<sect2>Session component

<p>
<descrip>

<tag><bf>Recognized arguments:</bf></tag>
<tt/debug/; <tt>conf=/path/to/file.conf</tt>; <tt>change_uid</tt>;
<tt>utmp_early</tt>

<tag><bf>Description:</bf></tag>

Through the contents of the configuration file,
<tt>/etc/security/limits.conf</tt>, resource limits are placed on
users' sessions. Users of <tt/uid=0/ are not affected by this
restriction.

<p>
The behavior of this module can be modified with the following
arguments:
<itemize>

<item><tt/debug/ -
verbose logging to <tt/syslog(3)/.

<item><tt>conf=/path/to/file.conf</tt> -
indicate an alternative <em/limits/ configuration file to the default.

<item><tt/change_uid/ - 
change real uid to the user for who the limits are set up.  Use this
option if you have problems like login not forking a shell for user
who has no processes. Be warned that something else may break when
you do this.

<item><tt/utmp_early/ - 
some broken applications actually allocate a utmp entry for the user
before the user is admitted to the system. If some of the services you
are configuring PAM for do this, you can selectively use this module
argument to compensate for this behavior and at the same time maintain
system-wide consistency with a single limits.conf file.

</itemize>

<tag><bf>Examples/suggested usage:</bf></tag>

In order to use this module the system administrator must first create
a <em/root-only-readable/ file (default is
<tt>/etc/security/limits.conf</tt>).  This file describes the resource
limits the superuser wishes to impose on users and groups. No limits
are imposed on <tt/uid=0/ accounts.

<p>
Each line of the configuration file describes a limit for a user in
the form:
<tscreen>
<verb>
<domain>	<type>	<item>		<value>
</verb>
</tscreen>

<p>
The fields listed above should be filled as follows...<newline>
<tt>&lt;domain&gt;</tt> can be:
<itemize>
<item> a username
<item> a groupname, with <tt>@group</tt> syntax
<item> the wild-card <tt/*/, for default entry
<item> the wild-card <tt/%/, for maxlogins limit only,
can also be used with <tt>%group</tt> syntax
</itemize>

<p>
<tt>&lt;type&gt;</tt> can have the three values:
<itemize>

<item> <tt/hard/ for enforcing <em/hard/ resource limits. These limits
are set by the superuser and enforced by the Linux Kernel. The user
cannot raise his requirement of system resources above such values.

<item> <tt/soft/ for enforcing <em/soft/ resource limits. These limits
are ones that the user can move up or down within the permitted range
by any pre-exisiting <em/hard/ limits. The values specified with this
token can be thought of as <em/default/ values, for normal system
usage.

<item> <tt/-/ for enforcing both <em/soft/ and <em/hard/ limits
together.

</itemize>

<p>
<tt>&lt;item&gt;</tt> can be one of the following:
<itemize>
<item><tt/core/ - limits the core file size (KB)
<item><tt/data/ - max data size (KB)
<item><tt/fsize/ - maximum filesize (KB)
<item><tt/memlock/ - max locked-in-memory address space (KB)
<item><tt/nofile/ - max number of open files
<item><tt/rss/ - max resident set size (KB)
<item><tt/stack/ - max stack size (KB)
<item><tt/cpu/ - max CPU time (MIN)
<item><tt/nproc/ - max number of processes
<item><tt/as/ - address space limit
<item><tt/maxlogins/ - max number of logins for this user
<item><tt/maxsyslogins/ - max number of logins on system
<item><tt/priority/ - the priority to run user process with (negative
values boost process priority)
<item><tt/locks/ - max locked files (Linux 2.4 and higher)
</itemize>

<p>
Note, if you specify a type of ``-'' but neglect to supply the
<tt/item/ and <tt/value/ fields then the module will never enforce any
limits on the corresponding user/group-members etc. . Note, the first
entry of the form which applies to the authenticating user will
override all other entries in the limits configuration file. In such
cases, the <tt/pam_limits/ module will always return <tt/PAM_SUCCESS/.

<p>
In general, individual limits have priority over group limits, so if
you impose no limits for <tt/admin/ group, but one of the members in
this group have a limits line, the user will have its limits set
according to this line.

<p>
Also, please note that all limit settings are set <em/per login/.
They are not global, nor are they permanent; existing only for the
duration of the session.

<p>
In the <em/limits/ configuration file, the ``<tt/#/'' character
introduces a comment - after which the rest of the line is ignored.

<p>
The <tt/pam_limits/ module does its best to report configuration
problems found in its configuration file via <tt/syslog(3)/.

<p>
The following is an example configuration file:
<tscreen>
<verb>
# EXAMPLE /etc/security/limits.conf file:
# =======================================
# <domain>	<type>	<item>		<value>
*               soft    core            0
*               hard    rss             10000
@student        hard    nproc           20
@faculty        soft    nproc           20
@faculty        hard    nproc           50
ftp             hard    nproc           0
@student        -       maxlogins       4
</verb>
</tscreen>
Note, the use of <tt/soft/ and <tt/hard/ limits for the same resource
(see <tt/@faculty/) -- this establishes the <em/default/ and permitted
<em/extreme/ level of resources that the user can obtain in a given
service-session.

<p>
Note, that wild-cards <tt/*/ and <tt/%/ have the following meaning when
used for maxlogins limit
<itemize>
<item> <tt/*/ every user
<item> <tt/%/ all users, or entire group when <tt>%group</tt> is specified 
</itemize>
See the following examples:
<tscreen>
<verb>
# EXAMPLE /etc/security/limits.conf file:
# <domain>	<type>	<item>		<value>
*               -       maxlogins       2
@faculty        -       maxlogins       4
%               -       maxlogins       30
%student        -       maxlogins       10
</verb>
</tscreen>
Explanation: every user can login 2 times, members of the <tt/faculty/
group can login 4 times, there can be only 30 logins, only 10 from
<tt/students/ group.

<p>
For the services that need resources limits (login for example) put
the following line in <tt>/etc/pam.conf</tt> as the last line for that
service (usually after the pam_unix session line:
<tscreen>
<verb>
#
# Resource limits imposed on login sessions via pam_limits
#
login   session    required     pam_limits.so
</verb>
</tscreen>

</descrip>

<!--
End of sgml insert for this module.
-->
