STABLE12-pam-afs-man-page-20020806

our first real man page. now, we just need a few hundred others.

(cherry picked from commit f4d6cdd26c8b3a4db9ff2c13588c7c9c6ebd2f5b)

diff --git a/src/pam/pam_afs.5 b/src/pam/pam_afs.5
new file mode 100644 (file)
index 0000000..a50b332
--- /dev/null
+++ b/src/pam/pam_afs.5
@@ -0,0 +1,158 @@
+.TH pam_afs 5 "5 August 2002"\r
+\r
+.SH NAME\r
+pam_afs, pam_afs.so \- pluggable authentication modules for OpenAFS\r
+\r
+.SH SYNOPSIS\r
+.B pam_afs.so.1, pam_afs.krb.so.1\r
+\r
+.SH DESCRIPTION\r
+The OpenAFS pluggable authentication module provides module support\r
+for authentication, session management, and password management, which\r
+coorespond to the auth, session, and  password directives in a PAM \r
+configuration file, respectively.\r
+\r
+The\r
+.B pam_afs.krb.so\r
+module additionally keeps users' Kerberos 4 TGT available for users\r
+to use in other applications.  The \r
+.B pam_afs.so\r
+module does not do this.\r
+\r
+The\r
+.B pam_afs.krb.so\r
+module has nothing to do with Kerberos 5 authentication.  Users\r
+with a Kerberos 5 integrated AFS environment should not use\r
+either of these modules, but instead use\r
+.B pam_krb5.so\r
+directly.\r
+\r
+.SH OPTIONS\r
+The following arguments are supported.  In parenthesis next to\r
+each option are the environments in which it works.\r
+\r
+.IP "cell cell_name"\r
+(auth) Specify a \r
+.I cell_name \r
+to authenticate to other than the local cell.\r
+.IP debug\r
+(all) Provide extra debugging information to syslog.\r
+.IP dont_fork\r
+(auth) Do not use a fork() when authenticating.  Forking is a good idea,\r
+because sockets and memory used by the authentication function get\r
+cleaned up automatically.  This option should only be used if a\r
+PAM application fails when a fork() is issued.  This option cannot \r
+be used with \r
+.B use_klog.\r
+.IP ignore_root\r
+(auth, password) If user root is authenticating, simply return PAM_SUCCESS without\r
+any AFS authentication attempt.  Presumably, authentication would fall through\r
+to a secondary mechanism.\r
+.IP "ignore_uid uid"\r
+(auth) Similar to ignore_root but it allows you to specify a \r
+.I uid\r
+such that any user authenticating with uid less than or equal to\r
+.I uid\r
+will not have AFS authentication performed.\r
+.IP no_unlog\r
+(session) Does not destroy a token during logout.  This is useful if\r
+users have background jobs still running under their PAG that\r
+need access to AFS after they log out.\r
+.IP nowarn\r
+(auth, password) Prevents warning from being written to syslog.\r
+.IP refresh_token\r
+(auth) Obtains a token without first obtaining a PAG.  This is useful for\r
+screensavers to update the lifetime of a user's token.\r
+.IP remain\r
+(session) Causes AFS tokens to remain for 5 minutes after logout.\r
+.IP "remainlifetime lifetime"\r
+(session) Specify, in seconds, how long tokens should remain after\r
+logout.\r
+.IP set_token\r
+(auth) If set_token is specified, the token obtained in the authentication\r
+phase is not destroyed.  Ordinarily, tokens are obtained in the\r
+setcred() phase of authentication.  For PAM applications which do not\r
+call setcred(), the\r
+.B set_token\r
+directive should be used.\r
+.IP setenv_password_expires\r
+(auth) Sets the PASSWORD_EXPIRES environment variable to the time when your\r
+AFS token will expire.\r
+.IP try_first_pass\r
+(auth, password) This will first try a password entered to a previous module and if it\r
+fails, prompt for the user's AFS password.\r
+If\r
+.B pam_afs.so\r
+is the first module called, it will generate a failed login attempt\r
+with a NULL password for every user logging in.\r
+.IP use_first_pass\r
+(auth, password) This option is similar to\r
+.B try_first_pass\r
+except that it will not prompt for the user's AFS password if the first\r
+password fails.  If this option is specified and \r
+.B pam_afs.so\r
+is the first module listed in the PAM configuration, authentication\r
+will fail.\r
+.IP use_klog\r
+(auth) This directs\r
+.B pam_afs.so\r
+to exec klog for authentication instead of calling the authentication\r
+functions in the AFS libraries directly.\r
+\r
+.SH FILES\r
+.I /etc/pam.conf\r
+.RS\r
+This is the PAM configuration file on Solaris systems.\r
+.RE\r
+\r
+.I /etc/pam.d/*\r
+.RS\r
+These are the PAM configuration files on Linux systems.\r
+.RE\r
+\r
+.I /etc/pam.d/system-auth\r
+.RS\r
+This file controls all system authentication on many\r
+Linux distributions.\r
+.RE\r
+.SH EXAMPLE\r
+\r
+Standard \r
+.I auth\r
+settings for\r
+.I /etc/pam.d/system-auth\r
+on Linux using OpenAFS:\r
+.RS\r
+auth required /lib/security/pam_env.so\r
+.br\r
+auth sufficient /lib/security/pam_afs.so.1 \\\r
+.br\r
+     setenv_password_expires ignore_root\r
+.br\r
+auth sufficient /lib/security/pam_unix.so likeauth \\\r
+.br\r
+     nullok try_first_pass\r
+.br\r
+auth required /lib/security/pam_deny.so\r
+.RE\r
+\r
+Suggested settings for\r
+.I auth\r
+in\r
+.I /etc/pam.d/xscreensaver\r
+.RS\r
+auth sufficient /lib/security/pam_afs.so.1 \\\r
+.br\r
+     refresh_token ignore_root\r
+.br\r
+auth required /lib/security/pam_stack.so \\\r
+.br\r
+     service=system-auth\r
+.RE\r
+\r
+.SH AUTHOR\r
+Charles Clancy <tcc@xauth.net>\r
+.SH "SEE ALSO"\r
+.BR klog (1),\r
+.BR klog.krb (1),\r
+.BR pagsh (1)\r