diff options
author | Thorsten Kukuk <kukuk@thkukuk.de> | 2006-06-22 19:44:29 +0000 |
---|---|---|
committer | Thorsten Kukuk <kukuk@thkukuk.de> | 2006-06-22 19:44:29 +0000 |
commit | 1cbeedd65b10f4eee830e3d222519b2701050f77 (patch) | |
tree | 7195310ae8c00f66bd864b990f16d2927bf1d1d3 /doc/man/pam.conf.5.xml | |
parent | 903c285ef795257c6799bfc8b99d7eb9aa182a25 (diff) |
Relevant BUGIDs:
Purpose of commit: bugfix
Commit summary:
---------------
2006-06-23 Thorsten Kukuk <kukuk@thkukuk.de>
* modules/pam_access/access.conf.5.xml: Fix syntax for SAG.
* modules/pam_access/pam_access.8.xml: Likewise.
* modules/pam_deny/pam_deny.8.xml: Likewise.
* modules/pam_echo/pam_echo.8.xml: Likewise.
* modules/pam_env/pam_env.8.xml: Likewise.
* modules/pam_env/pam_env.conf.5.xml: Likewise.
* modules/pam_group/group.conf.5.xml: Likewise.
* modules/pam_group/pam_group.8.xml: Likewise.
* modules/pam_limits/limits.conf.5.xml: Likewise.
* modules/pam_listfile/pam_listfile.8.xml: Likewise.
* modules/pam_succeed_if/pam_succeed_if.8.xml: Likewise.
* modules/pam_time/pam_time.8.xml: Likewise.
* modules/pam_time/time.conf.5.xml: Likewise.
* modules/pam_access/access.conf.5: Regenerate.
* modules/pam_access/pam_access.8: Likewise.
* modules/pam_deny/pam_deny.8: Likewise.
* modules/pam_echo/README: Likewise.
* modules/pam_echo/pam_echo.8: Likewise.
* modules/pam_env/pam_env.8: Likewise.
* modules/pam_env/pam_env.conf.5: Likewise.
* modules/pam_group/README: Likewise.
* modules/pam_group/group.conf.5: Likewise.
* modules/pam_group/pam_group.8: Likewise.
* modules/pam_limits/limits.conf.5: Likewise.
* modules/pam_listfile/README: Likewise.
* modules/pam_listfile/pam_listfile.8: Likewise.
* modules/pam_succeed_if/pam_succeed_if.8: Likewise.
* modules/pam_time/pam_time.8: Likewise.
* modules/pam_time/time.conf.5: Likewise.
* doc/man/Makefile.am: Add pam.conf-desc.xml, pam.conf-dir.xml
and pam.conf-syntax.xml.
* doc/man/pam.conf.5.xml: Split into different pieces for SAG.
* doc/man/pam.conf.5: Regenerated.
* doc/man/pam.conf-desc.xml: New.
* doc/man/pam.conf-dir.xml: New.
* doc/man/pam.conf-syntax.xml: New.
Diffstat (limited to 'doc/man/pam.conf.5.xml')
-rw-r--r-- | doc/man/pam.conf.5.xml | 410 |
1 files changed, 9 insertions, 401 deletions
diff --git a/doc/man/pam.conf.5.xml b/doc/man/pam.conf.5.xml index d744dac0..68f576af 100644 --- a/doc/man/pam.conf.5.xml +++ b/doc/man/pam.conf.5.xml @@ -19,409 +19,17 @@ <refsect1 id='pam.conf-description'> <title>DESCRIPTION</title> - <para> - When a <emphasis>PAM</emphasis> aware privilege granting application - is started, it activates its attachment to the PAM-API. This - activation performs a number of tasks, the most important being the - reading of the configuration file(s): <filename>/etc/pam.conf</filename>. - Alternatively, this may be the contents of the - <filename>/etc/pam.d/</filename> directory. The presence of this - directory will cause Linux-PAM to ignore - <filename>/etc/pam.conf</filename>. - </para> - - <para> - These files list the <emphasis>PAM</emphasis>s that will do the - authentication tasks required by this service, and the appropriate - behavior of the PAM-API in the event that individual - <emphasis>PAM</emphasis>s fail. - </para> - - <para> - The syntax of the <filename>/etc/pam.conf</filename> - configuration file is as follows. The file is made up of a list - of rules, each rule is typically placed on a single line, - but may be extended with an escaped end of line: `\<LF>'. - Comments are preceded with `#' marks and extend to the next end of - line. - </para> - - <para> - The format of each rule is a space separated collection of tokens, - the first three being case-insensitive: - </para> - - <para> - <emphasis remap='B'> service type control module-path module-arguments</emphasis> - </para> - - <para> - The syntax of files contained in the <filename>/etc/pam.d/</filename> - directory, are identical except for the absence of any - <emphasis>service</emphasis> field. In this case, the - <emphasis>service</emphasis> is the name of the file in the - <filename>/etc/pam.d/</filename> directory. This filename must be - in lower case. - </para> - - <para> - An important feature of <emphasis>PAM</emphasis>, is that a - number of rules may be <emphasis>stacked</emphasis> to combine - the services of a number of PAMs for a given authentication task. - </para> - - <para> - The <emphasis>service</emphasis> is typically the familiar name of - the corresponding application: <emphasis>login</emphasis> and - <emphasis>su</emphasis> are good examples. The - <emphasis>service</emphasis>-name, <emphasis>other</emphasis>, - is reserved for giving <emphasis>default</emphasis> rules. - Only lines that mention the current service (or in the absence - of such, the <emphasis>other</emphasis> entries) will be associated - with the given service-application. - </para> - - <para> - The <emphasis>type</emphasis> is the management group that the rule - corresponds to. It is used to specify which of the management groups - the subsequent module is to be associated with. Valid entries are: - </para> - <variablelist> - <varlistentry> - <term>account</term> - <listitem> - <para> - this module type performs non-authentication based account - management. It is typically used to restrict/permit access - to a service based on the time of day, currently available - system resources (maximum number of users) or perhaps the - location of the applicant user -- 'root' login only on the - console. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>auth</term> - <listitem> - <para> - this module type provides two aspects of authenticating - the user. Firstly, it establishes that the user is who they - claim to be, by instructing the application to prompt the user - for a password or other means of identification. Secondly, the - module can grant group membership or other privileges through - its credential granting properties. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>password</term> - <listitem> - <para> - this module type is required for updating the authentication - token associated with the user. Typically, there is one module - for each 'challenge/response' based authentication (auth) type. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>session</term> - <listitem> - <para> - this module type is associated with doing things that need to - be done for the user before/after they can be given service. - Such things include the logging of information concerning the - opening/closing of some data exchange with a user, mounting - directories, etc. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - The third field, <emphasis>control</emphasis>, indicates the - behavior of the PAM-API should the module fail to succeed in its - authentication task. There are two types of syntax for this control - field: the simple one has a single simple keyword; the more - complicated one involves a square-bracketed selection of - <emphasis>value=action</emphasis> pairs. - </para> - - <para> - For the simple (historical) syntax valid <emphasis>control</emphasis> - values are: - </para> - <variablelist> - <varlistentry> - <term>required</term> - <listitem> - <para> - failure of such a PAM will ultimately lead to the PAM-API - returning failure but only after the remaining - <emphasis>stacked</emphasis> modules (for this - <emphasis>service</emphasis> and <emphasis>type</emphasis>) - have been invoked. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>requisite</term> - <listitem> - <para> - like <emphasis>required</emphasis>, however, in the case that - such a module returns a failure, control is directly returned - to the application. The return value is that associated with - the first required or requisite module to fail. Note, this flag - can be used to protect against the possibility of a user getting - the opportunity to enter a password over an unsafe medium. It is - conceivable that such behavior might inform an attacker of valid - accounts on a system. This possibility should be weighed against - the not insignificant concerns of exposing a sensitive password - in a hostile environment. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>sufficient</term> - <listitem> - <para> - success of such a module is enough to satisfy the - authentication requirements of the stack of modules (if a - prior <emphasis>required</emphasis> module has failed the - success of this one is <emphasis>ignored</emphasis>). A failure - of this module is not deemed as fatal to satisfying the - application that this type has succeeded. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>optional</term> - <listitem> - <para> - the success or failure of this module is only important if - it is the only module in the stack associated with this - <emphasis>service</emphasis>+<emphasis>type</emphasis>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>include</term> - <listitem> - <para> - include all lines of given type from the configuration - file specified as an argument to this control. - </para> - </listitem> - </varlistentry> - </variablelist> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam.conf-desc.xml" + xpointer='xpointer(//section[@id = "pam.conf-desc"]/*)' /> - <para> - For the more complicated syntax valid <emphasis>control</emphasis> - values have the following form: - </para> - <programlisting> - [value1=action1 value2=action2 ...] - </programlisting> - - <para> - Where <emphasis>valueN</emphasis> corresponds to the return code - from the function invoked in the module for which the line is - defined. It is selected from one of these: - <emphasis>success</emphasis>, <emphasis>open_err</emphasis>, - <emphasis>symbol_err</emphasis>, <emphasis>service_err</emphasis>, - <emphasis>system_err</emphasis>, <emphasis>buf_err</emphasis>, - <emphasis>perm_denied</emphasis>, <emphasis>auth_err</emphasis>, - <emphasis>cred_insufficient</emphasis>, - <emphasis>authinfo_unavail</emphasis>, - <emphasis>user_unknown</emphasis>, <emphasis>maxtries</emphasis>, - <emphasis>new_authtok_reqd</emphasis>, - <emphasis>acct_expired</emphasis>, <emphasis>session_err</emphasis>, - <emphasis>cred_unavail</emphasis>, <emphasis>cred_expired</emphasis>, - <emphasis>cred_err</emphasis>, <emphasis>no_module_data</emphasis>, - <emphasis>conv_err</emphasis>, <emphasis>authtok_err</emphasis>, - <emphasis>authtok_recover_err</emphasis>, - <emphasis>authtok_lock_busy</emphasis>, - <emphasis>authtok_disable_aging</emphasis>, - <emphasis>try_again</emphasis>, <emphasis>ignore</emphasis>, - <emphasis>abort</emphasis>, <emphasis>authtok_expired</emphasis>, - <emphasis>module_unknown</emphasis>, <emphasis>bad_item</emphasis> - and <emphasis>default</emphasis>. - </para> - <para> - The last of these, <emphasis>default</emphasis>, implies 'all - <emphasis>valueN</emphasis>'s not mentioned explicitly. Note, the - full list of PAM errors is available in - <filename>/usr/include/security/_pam_types.h</filename>. The - <emphasis>actionN</emphasis> can be: an unsigned integer, - <emphasis>n</emphasis>, signifying an action of 'jump over the - next <emphasis>n</emphasis> modules in the stack', or take one - of the following forms: - </para> - <variablelist> - <varlistentry> - <term>ignore</term> - <listitem> - <para> - when used with a stack of modules, the module's return - status will not contribute to the return code the application - obtains. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>bad</term> - <listitem> - <para> - this action indicates that the return code should be thought - of as indicative of the module failing. If this module is the - first in the stack to fail, its status value will be used for - that of the whole stack. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>die</term> - <listitem> - <para> - equivalent to bad with the side effect of terminating the - module stack and PAM immediately returning to the application. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>ok</term> - <listitem> - <para> - this tells PAM that the administrator thinks this return code - should contribute directly to the return code of the full - stack of modules. In other words, if the former state of the - stack would lead to a return of <emphasis>PAM_SUCCESS</emphasis>, - the module's return code will override this value. Note, if - the former state of the stack holds some value that is - indicative of a modules failure, this 'ok' value will not be - used to override that value. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>done</term> - <listitem> - <para> - equivalent to ok with the side effect of terminating the module - stack and PAM immediately returning to the application. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>reset</term> - <listitem> - <para> - clear all memory of the state of the module stack and - start again with the next stacked module. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - Each of the four keywords: required; requisite; sufficient; and - optional, have an equivalent expression in terms of the [...] - syntax. They are as follows: - </para> - <variablelist> - <varlistentry> - <term>required</term> - <listitem> - <para> - [success=ok new_authtok_reqd=ok ignore=ignore default=bad] - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>requisite</term> - <listitem> - <para> - [success=ok new_authtok_reqd=ok ignore=ignore default=die] - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>sufficient</term> - <listitem> - <para> - [success=done new_authtok_reqd=done default=ignore] - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>optional</term> - <listitem> - <para> - [success=ok new_authtok_reqd=ok default=ignore] - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - <emphasis>module-path</emphasis> is either the full filename - of the PAM to be used by the application (it begins with a '/'), - or a relative pathname from the default module location: - <filename>/lib/security/</filename> or - <filename>/lib64/security/</filename>, depending on the architecture. - </para> - - <para> - <emphasis>module-arguments</emphasis> are a space separated list - of tokens that can be used to modify the specific behavior of the - given PAM. Such arguments will be documented for each individual - module. Note, if you wish to include spaces in an argument, you - should surround that argument with square brackets. - </para> - <programlisting> - squid auth required pam_mysql.so user=passwd_query passwd=mada \ - db=eminence [query=select user_name from internet_service \ - where user_name='%u' and password=PASSWORD('%p') and \ - service='web_proxy'] - </programlisting> - <para> - When using this convention, you can include `[' characters - inside the string, and if you wish to include a `]' character - inside the string that will survive the argument parsing, you - should use `\['. In other words: - </para> - <programlisting> - [..[..\]..] --> ..[..].. - </programlisting> - - <para> - Any line in (one of) the configuration file(s), that is not formatted - correctly, will generally tend (erring on the side of caution) to make - the authentication process fail. A corresponding error is written to - the system log files with a call to - <citerefentry> - <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum> - </citerefentry>. - </para> - - <para> - More flexible than the single configuration file is it to - configure libpam via the contents of the - <filename>/etc/pam.d/</filename> directory. In this case the - directory is filled with files each of which has a filename - equal to a service-name (in lower-case): it is the personal - configuration file for the named service. - </para> - - <para> - The syntax of each file in /etc/pam.d/ is similar to that of the - <filename>/etc/pam.conf</filename> file and is made up of lines - of the following form: - </para> - - <para> - <emphasis remap='B'> type control module-path module-arguments</emphasis> - </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam.conf-syntax.xml" + xpointer='xpointer(//section[@id = "pam.conf-syntax"]/*)' /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam.conf-dir.xml" + xpointer='xpointer(//section[@id = "pam.conf-dir"]/*)' /> </refsect1> <refsect1 id='pam.conf-see_also'> |