Relevant BUGIDs:

Purpose of commit: new feature/bugfix

Commit summary:
---------------

2006-09-20  Thorsten Kukuk  <kukuk@thkukuk.de>

        * doc/adg/Makefile.am: Add manual pages as dependency.
        * doc/mwg/Makefile.am: Likewise.
        * doc/sag/Makefile.am: Likewise.
        * doc/sag/Linux-PAM_SAG.xml: Include pam_unix.xml.
        * doc/sag/pam_unix.xml: New.
        * modules/pam_unix/Makefile.am: Generate pam_unix.8 manual page.
        * modules/pam_unix/README.xml: New.
        * modules/pam_unix/pam_unix.8.xml: New.
        * modules/pam_unix/README: Regenerate from XML.
        * modules/pam_unix/pam_unix.8: Generated from XML.

1 files changed, 142 insertions, 37 deletions

diff --git a/modules/pam_unix/README b/modules/pam_unix/README
index afeee3da..0caa3131 100644
--- a/modules/pam_unix/README
+++ b/modules/pam_unix/README
@@ -1,37 +1,142 @@
-pam_unix comes as one module pam_unix.so.
-
-The following links are left for compatibility with old versions:
-pam_unix_auth:		authentication module providing
-			pam_authenticate() and pam_setcred() hooks
-pam_unix_sess:		session module, providing session logging
-pam_unix_acct:		account management, providing shadow account
-			managment features, password aging etc..
-pam_unix_passwd:	password updating facilities providing
-			cracklib password strength checking facilities.
-
-The following options are recognized:
-	debug		-	log more debugging info
-	audit		-	a little more extreme than debug
-	use_first_pass	-	don't prompt the user for passwords
-				take them from PAM_ items instead
-	try_first_pass	-	don't prompt the user for the passwords
-				unless PAM_(OLD)AUTHTOK is unset
-	use_authtok	-	like try_first_pass, but * fail * if the new
-				PAM_AUTHTOK has not been previously set.
-				(intended for stacking password modules only)
-	not_set_pass	-	don't set the PAM_ items with the passwords
-				used by this module.
-	shadow		-	try to maintian a shadow based system.
-	md5		-	when a user changes their password next,
-				encrypt it with the md5 algorithm.
-	bigcrypt	-	when a user changes their password next,
-				excrypt it with the DEC C2 - algorithm(0).
-	nodelay		-	used to prevent failed authentication
-				resulting in a delay of about 1 second.
-	nis		-	use NIS RPC for setting new password
-	remember=X	-	remember X old passwords, they are kept in
-				/etc/security/opasswd in MD5 crypted form
-	broken_shadow	-	ignore errors reading shadow information for
-				users in the account management module
-
-	invalid arguments are logged to syslog.
+pam_unix — Module for traditional password authentication
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DESCRIPTION
+
+This is the standard Unix authentication module. It uses standard calls from
+the system's libraries to retrieve and set account information as well as
+authentication. Usually this is obtained from the /etc/passwd and the /etc/
+shadow file as well if shadow is enabled.
+
+The account component performs the task of establishing the status of the
+user's account and password based on the following shadow elements: expire,
+last_change, max_change, min_change, warn_change. In the case of the latter, it
+may offer advice to the user on changing their password or, through the
+PAM_AUTHTOKEN_REQD return, delay giving service to the user until they have
+established a new password. The entries listed above are documented in the
+shadow(5) manual page. Should the user's record not contain one or more of
+these entries, the corresponding shadow check is not performed.
+
+The authentication component performs the task of checking the users
+credentials (password). The default action of this module is to not permit the
+user access to a service if their official password is blank.
+
+A helper binary, unix_chkpwd(8), is provided to check the user's password when
+it is stored in a read protected database. This binary is very simple and will
+only check the password of the user invoking it. It is called transparently on
+behalf of the user by the authenticating component of this module. In this way
+it is possible for applications like xlock to work without being setuid-root.
+The module, by default, will temporarily turn off SIGCHLD handling for the
+duration of execution of the helper binary. This is generally the right thing
+to do, as many applications are not prepared to handle this signal from a child
+they didn't know was fork()d. The noreap module argument can be used to
+suppress this temporary shielding and may be needed for use with certain
+applications.
+
+The password component of this module performs the task of updating the user's
+password.
+
+The session component of this module logs when a user logins or leave the
+system.
+
+Remaining arguments, supported by others functions of this module, are silently
+ignored. Other arguments are logged as errors through syslog(3).
+
+OPTIONS
+
+debug
+
+    Turns on debugging via syslog(3).
+
+audit
+
+    A little more extreme than debug.
+
+nullok
+
+    The default action of this module is to not permit the user access to a
+    service if their official password is blank. The nullok argument overrides
+    this default.
+
+try_first_pass
+
+    Before prompting the user for their password, the module first tries the
+    previous stacked module's password in case that satisfies this module as
+    well.
+
+use_first_pass
+
+    The argument use_first_pass forces the module to use a previous stacked
+    modules password and will never prompt the user - if no password is
+    available or the password is not appropriate, the user will be denied
+    access.
+
+nodelay
+
+    This argument can be used to discourage the authentication component from
+    requesting a delay should the authentication as a whole fail. The default
+    action is for the module to request a delay-on-failure of the order of two
+    second.
+
+use_authtok
+
+    When password changing enforce the module to set the new password to the
+    one provided by a previously stacked password module (this is used in the
+    example of the stacking of the pam_cracklib module documented above).
+
+not_set_pass
+
+    This argument is used to inform the module that it is not to pay attention
+    to/make available the old or new passwords from/to other (stacked) password
+    modules.
+
+nis
+
+    NIS RPC is used for setting new passwords.
+
+remember=n
+
+    The last n passwords for each user are saved in /etc/security/opasswd in
+    order to force password change history and keep the user from alternating
+    between the same password too frequently.
+
+shadow
+
+    Try to maintain a shadow based system.
+
+md5
+
+    When a user changes their password next, encrypt it with the MD5 algorithm.
+
+bigcrypt
+
+    When a user changes their password next, encrypt it with the DEC C2
+    algorithm.
+
+broken_shadow
+
+    Ignore errors reading shadow inforation for users in the account management
+    module.
+
+Invalid arguments are logged with syslog(3).
+
+EXAMPLES
+
+An example usage for /etc/pam.d/login would be:
+
+# Authenticate the user
+auth       required   pam_unix.so
+# Ensure users account and password are still active
+account    required   pam_unix.so
+# Change the users password, but at first check the strength
+# with pam_cracklib(8)
+password   required   pam_cracklib.so retry=3 minlen=6 difok=3
+password   required   pam_unix.so use_authtok nullok md5
+session    required   pam_unix.so
+
+
+AUTHOR
+
+pam_unix was written by various people.
+