ion can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth group.
+.IP force_pwchange 4
+.IX Item "force_pwchange"
+[3.11] If this option is set and authentication fails with a Kerberos
+error indicating the user's password is expired, attempt to immediately
+change their password during the authenticate step.  Under normal
+circumstances, this is unnecessary.  Most Kerberos libraries will do this
+for you, and setting this option will prompt the user twice to change
+their password if the first attempt (done by the Kerberos library) fails.
+However, some system Kerberos libraries (such as Solaris's) have password
+change prompting disabled in the Kerberos library; on those systems, you
+can set this option to simulate the normal library behavior.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth group.
+.IP no_update_user 4
+.IX Item "no_update_user"
+[4.7] Normally, if pam\-krb5 is able to canonicalize the principal to a
+local name using \fBkrb5_aname_to_localname()\fR or similar calls, it changes
+the PAM_USER variable for this PAM session to the canonicalized local
+name.  Setting this option disables this behavior and leaves PAM_USER set
+to the initial authentication identity.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth group.
+.IP silent 4
+.IX Item "silent"
+[1.0] Don't show messages and errors from Kerberos, such as warnings of
+expiring passwords, to the user via the prompter.  This is equivalent to
+the behavior when the application passes in PAM_SILENT, but can be set in
+the PAM configuration.
+.Sp
+This option is only applicable to the auth and password groups.
+.IP trace=<log\-file> 4
+.IX Item "trace=<log-file>"
+[4.6] Enables Kerberos library trace logging to the specified log file if
+it is supported by the Kerberos library.  This is intended for temporary
+debugging.  The specified file will be appended to without further
+security checks, so do not specify a file in a publicly writable directory
+like \fI/tmp\fR.
+.SS PKINIT
+.IX Subsection "PKINIT"
+.IP pkinit_anchors=<anchors> 4
+.IX Item "pkinit_anchors=<anchors>"
+[3.0] When doing PKINIT authentication, use <anchors> as the client trust
+anchors.  This is normally a reference to a file containing the trusted
+certificate authorities.  This option is only used if \fItry_pkinit\fR or
+\&\fIuse_pkinit\fR are set.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and password groups.
+.IP pkinit_prompt 4
+.IX Item "pkinit_prompt"
+[3.0] Before attempting PKINIT authentication, prompt the user to insert a
+smart card.  You may want to set this option for programs such as
+\&\fBgnome-screensaver\fR that call PAM as soon as the mouse is touched and
+don't give the user an opportunity to enter the smart card first.  Any
+information entered at the first prompt is ignored.  If \fItry_pkinit\fR is
+set, a user who wishes to use a password instead can just press Enter and
+then enter their password as normal.  This option is only used if
+\&\fItry_pkinit\fR or \fIuse_pkinit\fR are set.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and password groups.
+.IP pkinit_user=<userid> 4
+.IX Item "pkinit_user=<userid>"
+[3.0] When doing PKINIT authentication, use <userid> as the user ID.  The
+value of this string is highly dependent on the type of PKINIT
+implementation you're using, but will generally be something like:
+.Sp
+.Vb 1
+\&    PKCS11:/usr/lib/pkcs11/lib/soft\-pkcs11.so
+.Ve
+.Sp
+to specify the module to use with a smart card.  It may also point to a
+user certificate or to other types of user IDs.  See the Kerberos library
+documentation for more details.  This option is only used if \fItry_pkinit\fR
+or \fIuse_pkinit\fR are set.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and password groups.
+.IP preauth_opt=<option> 4
+.IX Item "preauth_opt=<option>"
+[3.3] Sets a preauth option (currently only applicable when built with MIT
+Kerberos).  <option> is either a key/value pair with the key separated
+from the value by \f(CW\*(C`=\*(C'\fR or a boolean option (in which case it's turned on).
+In \fIkrb5.conf\fR, multiple options should be separated by whitespace.  In
+the PAM configuration, this option can be given multiple times to set
+multiple options.  In either case, <option> may not contain whitespace.
+.Sp
+The primary use of this option, at least in the near future, will be to
+set options for the MIT Kerberos PKINIT support.  For the full list of
+possible options, see the PKINIT plugin documentation.  At the time of
+this writing, \f(CW\*(C`X509_user_identity\*(C'\fR is equivalent to \fIpkinit_user\fR and
+\&\f(CW\*(C`X509_anchors\*(C'\fR is equivalent to \fIpkinit_anchors\fR.  \f(CW\*(C`flag_DSA_PROTOCOL\*(C'\fR
+can only be set via this option.
+.Sp
+Any settings made with this option are applied after the \fIpkinit_anchors\fR
+and \fIpkinit_user\fR options, so if an equivalent setting is made via
+\&\fIpreauth_opt\fR, it will probably override the other setting.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and password groups.  Note that there is no way to
+remove a setting made in \fIkrb5.conf\fR using the PAM configuration, but
+options set in the PAM configuration are applied after options set in
+\&\fIkrb5.conf\fR and therefore may override earlier settings.
+.IP try_pkinit 4
+.IX Item "try_pkinit"
+[3.0] Attempt PKINIT authentication before trying a regular password.  You
+will probably also need to set the \fIpkinit_user\fR configuration option.
+If PKINIT fails, the PAM module will fall back on regular password
+authentication.  This option is currently only supported if pam\-krb5 was
+built against Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later.
+.Sp
+If this option is set and pam\-krb5 is built against MIT Kerberos, and
+PKINIT fails and the module falls back to password authentication, the
+user's password will not be stored in the PAM stack for subsequent
+modules.  This is a bug in the interaction between the module and MIT
+Kerberos that requires some reworking of the PKINIT authentication method
+to fix.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and password groups.
+.IP use_pkinit 4
+.IX Item "use_pkinit"
+[3.0, 4.9 for MIT Kerberos] Require PKINIT authentication.  You will
+probably also need to set the \fIpkinit_user\fR configuration option.  If
+PKINIT fails, authentication will fail.  This option is only supported if
+pam\-krb5 was built against Heimdal 0.8rc1 or later or MIT Kerberos 1.12 or
+later.
+.Sp
+Be aware that, with MIT Kerberos, this option is implemented by using a
+responder without a prompter, and thus any informational messages from the
+Kerberos libraries or KDC during authentication will not be displayed.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and password groups.
+.SS Prompting
+.IX Subsection "Prompting"
+.IP banner=<banner> 4
+.IX Item "banner=<banner>"
+[3.0] By default, the prompts when a user changes their password are:
+.Sp
+.Vb 3
+\&    Current Kerberos password:
+\&    Enter new Kerberos password:
+\&    Retype new Kerberos password:
+.Ve
+.Sp
+The string "Kerberos" is inserted so that users aren't confused about
+which password they're changing.  Setting this option replaces the word
+"Kerberos" with whatever this option is set to.  Setting this option to
+the empty string removes the word before "password:" entirely.
+.Sp
+If set in the PAM configuration, <banner> may not contain whitespace.  If
+you want a value containing whitespace, set it in \fIkrb5.conf\fR.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the password group.
+.IP expose_account 4
+.IX Item "expose_account"
+[3.0] By default, the Kerberos PAM module password prompt is simply
+"Password:".  This avoids leaking any information about the system realm
+or account to principal conversions.  If this option is set, the string
+"for <principal>" is added before the colon, where <principal> is the
+user's principal.  This string is also added before the colon on prompts
+when changing the user's password.
+.Sp
+Enabling this option with ChallengeResponseAuthentication enabled in
+OpenSSH may cause problems for some ssh clients that only recognize
+"Password:" as a prompt.  This option is automatically disabled if
+\&\fIsearch_k5login\fR is enabled since the principal displayed would be
+inaccurate.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and password groups.
+.IP force_first_pass 4
+.IX Item "force_first_pass"
+[4.0] Use the password obtained by a previous authentication or password
+module to authenticate the user without prompting the user again.  If no
+previous module obtained the user's password, fail without prompting the
+user.  Also see \fItry_first_pass\fR and \fIuse_first_pass\fR for weaker
+versions of this option.
+.Sp
+This option is only applicable to the auth and password groups.  For the
+password group, it applies only to the old password.  See \fIuse_authtok\fR
+for a similar setting for the new password.
+.IP no_prompt 4
+.IX Item "no_prompt"
+[4.6] Never prompt for the current password.  Instead, pass in a NULL
+password to the Kerberos library and let the Kerberos library do the
+prompting.  This may be needed if, for example, the Kerberos library is
+configured to use other authentication mechanisms than passwords and needs
+full control over the prompting process.
+.Sp
+The major disadvantage of this option is that it means the PAM module will
+never see the user's password and therefore cannot save it in the PAM
+module data for any subsequent modules.  In other words, this option
+cannot be used if another module is in the stack behind the Kerberos PAM
+module and wants to use \fIuse_first_pass\fR.  The Kerberos library also
+usually includes the principal in the prompt, and therefore this option
+implies behavior similar to \fIexpose_account\fR.  Similar to
+\&\fIexpose_account\fR, this can cause problems with OpenSSH if
+ChallengeResponseAuthentication is enabled, since clients may not
+recognize password prompts other than "Password:".
+.Sp
+Using this option with \fIsearch_k5login\fR would result in a password prompt
+for every principal listed in the user's \fI.k5login\fR file.  This is
+probably not desired behavior, although it's not prohibited by the module.
+.Sp
+This option is only applicable to the auth and password groups.  For the
+password group, it applies only to the authentication process; the user
+will still be prompted for a new password.
+.IP prompt_principal 4
+.IX Item "prompt_principal"
+[3.6] Before prompting for the user's password (or using the previously
+entered password, if \fItry_first_pass\fR, \fIuse_first_pass\fR, or
+\&\fIforce_first_pass\fR are set), prompt the user for the Kerberos principal
+to use for authentication.  This allows the user to authenticate with a
+different principal than the one corresponding to the local username,
+provided that either a \fI.k5login\fR file or local Kerberos principal to
+account mapping authorize that principal to access the local account.
+.Sp
+Be cautious when using this configuration option and don't use it with
+OpenSSH PasswordAuthentication, only ChallengeResponseAuthentication.
+Some PAM-enabled applications expect PAM modules to only prompt for
+passwords and may even blindly give the password to the first prompt, no
+matter what it is.  Such applications, in combination with this option,
+may expose the user's password in log messages and Kerberos requests.
+.IP try_first_pass 4
+.IX Item "try_first_pass"
+[1.0] If the authentication module isn't the first on the stack, and a
+previous module obtained the user's password, use that password to
+authenticate the user without prompting them again.  If that
+authentication fails, fall back on prompting the user for their password.
+This option has no effect if the authentication module is first in the
+stack or if no previous module obtained the user's password.  Also see
+\&\fIuse_first_pass\fR and \fIforce_first_pass\fR for stronger versions of this
+option.
+.Sp
+This option is only applicable to the auth and password groups.  For the
+password group, it applies only to the old password.
+.IP use_authtok 4
+.IX Item "use_authtok"
+[4.0] Use the new password obtained by a previous password module when
+changing passwords rather than prompting for the new password.  If the new
+password isn't available, fail.  This can be used to require passwords be
+checked by another, prior module, such as \fBpam_cracklib\fR.
+.Sp
+This option is only applicable to the password group.
+.IP use_first_pass 4
+.IX Item "use_first_pass"
+[1.0] Use the password obtained by a previous authentication module to
+authenticate the user without prompting the user again.  If no previous
+module obtained the user's password for either an authentication or
+password change, fall back on prompting the user.  If a previous module
+did obtain the user's password but authentication with that password
+fails, fail without further prompting the user.  Also see
+\&\fItry_first_pass\fR and \fIforce_first_pass\fR for other versions of this
+option.
+.Sp
+This option is only applicable to the auth and password groups.  For the
+password group, it applies only to the old password.  See \fIuse_authtok\fR
+for a similar setting for the new password.
+.SS "Ticket Caches"
+.IX Subsection "Ticket Caches"
+.IP ccache=<pattern> 4
+.IX Item "ccache=<pattern>"
+[2.0] Use <pattern> as the pattern for creating credential cache names.
+<pattern> must be in the form <type>:<residual> where <type> and the
+following colon are optional if a file cache should be used.  The special
+token \f(CW%u\fR, anywhere in <pattern>, is replaced with the user's numeric
+UID.  The special token \f(CW%p\fR, anywhere in <pattern>, is replaced with the
+current process ID.
+.Sp
+If <pattern> ends in the literal string \f(CW\*(C`XXXXXX\*(C'\fR (six X's), that string
+will be replaced by randomly generated characters and the ticket cache
+will be created using \fBmkstemp\fR\|(3).  This is strongly recommended if
+<pattern> points to a world-writable directory.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and session groups.
+.IP ccache_dir=<directory> 4
+.IX Item "ccache_dir=<directory>"
+[1.2] Store both the temporary ticket cache used during authentication and
+user ticket caches in <directory> instead of in \fI/tmp\fR.  The algorithm
+for generating the ticket cache name is otherwise unchanged.  <directory>
+may be prefixed with \f(CW\*(C`FILE:\*(C'\fR to make the cache type unambiguous (and this
+may be required on systems that use a cache type other than file as the
+default).
+.Sp
+Be aware that pam_krb5 creates and stores a temporary ticket cache file
+owned by root during the login process.  If you set \fIccache\fR above to
+avoid using the system \fI/tmp\fR directory for user ticket caches, you may
+also want to set \fIccache_dir\fR to move those temporary caches to some
+other location.  This will allow pam_krb5 to continue working even if the
+system \fI/tmp\fR directory is full.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and session groups.
+.IP no_ccache 4
+.IX Item "no_ccache"
+[1.0] Do not create a ticket cache after authentication.  This option
+shouldn't be set in general, but is useful as part of the PAM
+configuration for a particular service that uses PAM for authentication
+but isn't creating user sessions and doesn't want the overhead of ever
+writing the user credentials to disk.  When using this option, the
+application should only call \fBpam_authenticate()\fR; other functions like
+\&\fBpam_setcred()\fR, \fBpam_start_session()\fR, and \fBpam_acct_mgmt()\fR don't make sense
+with this option.  Don't use this option if the application needs PAM
+account and session management calls.
+.Sp
+This option is only applicable to the auth group.
+.IP retain_after_close 4
+.IX Item "retain_after_close"
+[2.3] Normally, the user's ticket cache is destroyed when either \fBpam_end()\fR
+or \fBpam_close_session()\fR is called by the authenticating application so that
+ticket caches aren't left behind after the user logs out.  In some cases,
+however, this isn't desirable.  (On Solaris 8, for instance, the default
+behavior means login will destroy the ticket cache before running the
+user's shell.)  If this option is set, the PAM module will never destroy
+the user's ticket cache.  If you set this, you may want to call
+\&\fBkdestroy\fR in the shell's logout configuration or run a temporary file
+removal program to avoid accumulating hundreds of ticket caches in
+\&\fI/tmp\fR.
+.Sp
+This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only
+applicable to the auth and session groups.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+.IP KRB5CCNAME 4
+.IX Item "KRB5CCNAME"
+Set by \fBpam_setcred()\fR with the PAM_ESTABLISH_CRED option, and therefore
+also by \fBpam_open_session()\fR, to point to the new credential cache for the
+user.  See the \fIccache\fR and \fIccache_dir\fR options.  By default, the cache
+name will be prefixed with \f(CW\*(C`FILE:\*(C'\fR to make the cache type unambiguous.
+.IP PAM_KRB5CCNAME 4
+.IX Item "PAM_KRB5CCNAME"
+Set by \fBpam_authenticate()\fR to point to the temporary ticket cache used for
+authentication (unless the \fIno_ccache\fR option was given).  \fBpam_setcred()\fR
+then uses that environment variable to locate the temporary cache even if
+it was not called in the same PAM session as \fBpam_authenticate()\fR (a problem
+with \fBsshd\fR running in some modes).  This environment variable is only
+used internal to the PAM module.
+.SH FILES
+.IX Header "FILES"
+.IP \fI/tmp/krb5cc_UID_RANDOM\fR 4
+.IX Item "/tmp/krb5cc_UID_RANDOM"
+The default credential cache name.  UID is the decimal UID of the local
+user and RANDOM is a random six-character string.  The pattern may be
+changed with the \fIccache\fR option and the directory with the \fIccache_dir\fR
+option.
+.IP \fI/tmp/krb5cc_pam_RANDOM\fR 4
+.IX Item "/tmp/krb5cc_pam_RANDOM"
+The credential cache name used for the temporary credential cache created
+by \fBpam_authenticate()\fR.  This cache is removed again when the PAM session
+is ended or when \fBpam_setcred()\fR is called and will normally not be
+user-visible.  RANDOM is a random six-character string.
+.IP \fI~/.k5login\fR 4
+.IX Item "~/.k5login"
+File containing Kerberos principals that are allowed access to that
+account.
+.SH BUGS
+.IX Header "BUGS"
*** 77 LINES SKIPPED ***