.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PAM_AFS_SESSION 5"
.TH PAM_AFS_SESSION 5 "2015-09-19" "2.6" "pam-afs-session"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
pam_afs_session \- AFS PAG and token PAM module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  auth          optional        pam_afs_session.so
\&  session       required        pam_afs_session.so
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \s-1AFS\s0 session service module for \s-1PAM,\s0 typically installed at
\&\fI/lib/security/pam_afs_session.so\fR, establishes new \s-1AFS\s0 sessions and
obtains \s-1AFS\s0 tokens when a new session is opened for a user.  It is a
shared object that is dynamically loaded by the \s-1PAM\s0 subsystem as
necessary, based on the system \s-1PAM\s0 configuration.  \s-1PAM\s0 is a system for
plugging in external authentication and session management modules so that
each application doesn't have to know the best way to check user
authentication or create a user session on that system.  For details on
how to configure \s-1PAM\s0 on your system, see the \s-1PAM\s0 man page, often \fIpam\fR\|(7).
.PP
This module provides pam_setcred, pam_open_session, and pam_close_session
implementations for \s-1AFS. \s0 Because pam_setcred is part of the auth \s-1PAM\s0
group, it also implements a dummy pam_authenticate that always succeeds
(otherwise, it can't provide a pam_setcred).
.PP
Make sure that this module is \s-1NEVER\s0 listed as \f(CW\*(C`sufficient\*(C'\fR or as the only
\&\f(CW\*(C`required\*(C'\fR module in the auth group.  Doing so will potentially allow
users to log on without any password.  There unfortunately isn't a way to
work around this and still provide pam_setcred without running afoul of a
bug in (at least) Linux \s-1PAM 0.99.7.1\s0 and probably earlier that causes
authentication to fail when the final module in the auth group returns
\&\s-1PAM_IGNORE\s0 and \f(CW\*(C`[default=done]\*(C'\fR was given as the action.
.PP
Here are the actions of this module:
.IP "pam_open_session" 4
.IX Item "pam_open_session"
When a new session is opened, this module will first check to see if \s-1AFS\s0
is running on the system.  If not, it will log a message and exit
successfully.  If \s-1AFS\s0 is running, it will place the user's session in a
new \s-1PAG \s0(Process Authentication Group, often implemented as supplemental
groups, which limits user tokens to only processes in that \s-1PAG\s0).  It will
then attempt to obtain tokens, either directly if built with the Heimdal
libkafs library and Kerberos support or by running an external \fBaklog\fR
program.  If \s-1PAG\s0 creation fails, the module will fail; if obtaining tokens
fails, the module will log a warning but still return success.
.Sp
The module will only attempt to obtain tokens if the environment variable
\&\s-1KRB5CCNAME\s0 is set in the environment, unless otherwise configured (see the
always_aklog option).  It will always create a new \s-1PAG,\s0 however.
.IP "pam_close_session" 4
.IX Item "pam_close_session"
If and only if pam_open_session successfully obtained \s-1AFS\s0 tokens and \s-1AFS\s0
is still running on the system, pam_close_session will delete the tokens
in the current \s-1PAG \s0(equivalent to running \fBunlog\fR).  To leave the tokens
after session close, set the retain_after_close option.
.IP "pam_setcred" 4
.IX Item "pam_setcred"
When pam_setcred is called with the \s-1PAM_ESTABLISH_CRED\s0 flag, it will do
the same as if pam_open_session was called.  When pam_setcred is called
with the \s-1PAM_DELETE_CRED\s0 flag, it will do the same as if pam_close_session
was called.  When called with the \s-1PAM_REINITIALIZE_CRED\s0 flag or the
\&\s-1PAM_REFRESH_CRED\s0 flag, it won't create a new \s-1PAG\s0 but instead will only
attempt to get new tokens (still skipping this unless \s-1KRB5CCNAME\s0 is set in
the environment or always_aklog is set).
.PP
This module is primarily intended for use with a Kerberos authentication
module.  It does not itself do any user authentication; it cannot, for
instance, be used to authenticate users to a \fBkaserver\fR.  While it is
intended for use with an \fBaklog\fR that uses Kerberos ticket caches to
obtain tokens, it can be used with any \fBaklog\fR implementation
(always_aklog may have to be set if no Kerberos ticket cache will be
present).
.PP
This module performs no authorization checks and does not hook into
password changes; it only implements the session functions and
pam_setcred.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The \s-1AFS\s0 session \s-1PAM\s0 module supports the following configuration options,
which may be set in the \s-1PAM\s0 configuration as arguments listed after
\&\f(CW\*(C`pam_afs_session.so\*(C'\fR or in the system \fIkrb5.conf\fR.
.PP
Some of them take arguments, in which case the argument will be given
after \f(CW\*(C`=\*(C'\fR.  The rest are boolean options.  To set a boolean option in the
\&\s-1PAM\s0 configuration, just give the name of the option in the arguments.  To
set an option that takes an argument, follow the option name with an equal
sign (\f(CW\*(C`=\*(C'\fR) and the value, with no separating whitespace.  Whitespace in
option arguments is not supported in the \s-1PAM\s0 configuration files of most
\&\s-1PAM\s0 implementations.
.PP
To set an option for the \s-1PAM\s0 module in the system \fIkrb5.conf\fR file, put
that option in the [appdefaults] section.  The \s-1AFS\s0 session \s-1PAM\s0 module will
look for options either at the top level of the [appdefaults] section or
in a subsection named \f(CW\*(C`pam\-afs\-session\*(C'\fR (currently, realm-specific
configuration is not checked).  For example, the following fragment of a
\&\fIkrb5.conf\fR file would set \fIaklog_homedir\fR to true and \fIminimum_uid\fR to
100.
.PP
.Vb 5
\&    [appdefaults]
\&        aklog_homedir = true
\&        pam\-afs\-session = {
\&            minimum_uid = 100
\&        }
.Ve
.PP
There is no difference to the \s-1PAM\s0 module whether options are specified at
the top level or in a \f(CW\*(C`pam\-afs\-session\*(C'\fR section; the \f(CW\*(C`pam\-afs\-session\*(C'\fR
section is supported in case there are options that should be set for the
\&\s-1PAM\s0 module but not for other applications.  For more information on the
syntax of \fIkrb5.conf\fR, see \fIkrb5.conf\fR\|(5).
.PP
If the same option is set in \fIkrb5.conf\fR and in the \s-1PAM\s0 configuration,
the latter takes precedent.  Note, however, that due to the configuration
syntax, there's no way to turn off a boolean option in the \s-1PAM\s0
configuration that was turned on in \fIkrb5.conf\fR.
.IP "afs_cells=\fIcell\fR[,\fIcell\fR...]" 4
.IX Item "afs_cells=cell[,cell...]"
Obtain tokens for the listed cells instead of the default local cell.  If
more than one cell is listed, try to obtain tokens for each cell.  If
specified in \fIkrb5.conf\fR, the cells can be separated by any combination
of spaces and commas; if specified in the \s-1PAM\s0 configuration, they must be
separated by commas.
.Sp
If the \s-1AFS\s0 session \s-1PAM\s0 module is running an external program, this option
is implemented by passing a \fB\-c\fR flag with the cell as its argument for
each listed cell to that program.  If aklog_homedir is also set, the \fB\-c\fR
flags and the \fB\-p\fR flag will all be passed to the external program.
.IP "aklog_homedir" 4
.IX Item "aklog_homedir"
Try to obtain the necessary tokens to access the user's home directory.
If the libkafs token-obtaining \s-1API\s0 is used, setting this will cause the
\&\s-1AFS\s0 session \s-1PAM\s0 module to pass the user's home directory into that \s-1API\s0 and
request that the appropriate tokens be obtained.  If running an external
\&\fBaklog\fR program, \fBaklog\fR will be called with \fB\-p\fR \fIhome-directory\fR
where \fIhome-directory\fR is the home directory of the local user for which
the session is being opened or refreshed.  This generally will tell
\&\fBaklog\fR to check that path, find all \s-1AFS\s0 cells involved in access to that
path, and attempt to obtain tokens for each one.  Note that this means
that if the user's home directory is not in \s-1AFS,\s0 no tokens will be
obtained.
.Sp
In either case, the user's home directory is obtained via \fIgetpwnam()\fR based
on the username \s-1PAM\s0 says we are authenticating.
.IP "always_aklog" 4
.IX Item "always_aklog"
Normally, the \s-1AFS\s0 session \s-1PAM\s0 module only tries to obtain tokens if
\&\s-1KRB5CCNAME\s0 is set in the \s-1PAM\s0 environment.  If this option is set, it will
always attempt to obtain tokens.  This is only useful if it is configured
to run an external \fBaklog\fR program.
.Sp
This can be used if your environment doesn't correctly set \s-1KRB5CCNAME\s0 in
the environment for some reason, or if your \fBaklog\fR doesn't rely on a
Kerberos ticket cache to obtain tokens (or can find the cache on its own
via some other means).
.IP "debug" 4
.IX Item "debug"
If this option is set, additional trace information will be logged to
syslog with priority \s-1LOG_DEBUG.\s0
.IP "ignore_root" 4
.IX Item "ignore_root"
If this option is set, the \s-1AFS\s0 session \s-1PAM\s0 module won't take any action
(and will exit successfully) if the account for which the session is being
established is named \f(CW\*(C`root\*(C'\fR.
.IP "kdestroy" 4
.IX Item "kdestroy"
If this option is set and the \s-1AFS\s0 session \s-1PAM\s0 module was built with
Kerberos support, the user's ticket cache will be destroyed after tokens
are obtained successfully.  If tokens are not obtained successfully, the
ticket cache will be left intact.  Please note that this is not properly a
security feature, since the ticket cache will still be written to disk
between the time the Kerberos \s-1PAM\s0 module authenticates the user and the
time the \s-1AFS\s0 session \s-1PAM\s0 module is run.  It can, however, be used to
reduce the window during which Kerberos ticket caches are lying about if
the only use one has for ticket caches is to obtain \s-1AFS\s0 tokens.
.IP "minimum_uid=\fIuid\fR" 4
.IX Item "minimum_uid=uid"
If this option is set, the \s-1AFS\s0 session \s-1PAM\s0 module won't take any action
(and will exit successfully) if the account for which the session is being
established has a \s-1UID\s0 lower than \fIuid\fR.
.IP "nopag" 4
.IX Item "nopag"
If this option is set, no \s-1PAG\s0 will be created.  Be careful when using this
option, since it means that the user will inherit a \s-1PAG\s0 from the process
managing the login.  If \fBsshd\fR, for instance, is started in a \s-1PAG,\s0 every
user who logs in via ssh will be put in the same \s-1PAG\s0 and will share tokens
if this option is used.
.Sp
This is the default on Mac \s-1OS X,\s0 where PAGs are not supported.
.IP "notokens" 4
.IX Item "notokens"
If this option is set, the \s-1AFS\s0 session \s-1PAM\s0 module will only create a \s-1PAG\s0
and not attempt to obtain tokens.  Setting this option overrides all other
settings related to acquiring tokens, including always_aklog.  If both
nopag and notokens are set, the module essentially does nothing.
.Sp
Setting notokens also implies retain_after_close, meaning that the \s-1AFS\s0
session \s-1PAM\s0 module will also not attempt to delete tokens when the user's
session ends.
.IP "program=\fIpath\fR" 4
.IX Item "program=path"
The path to the \fBaklog\fR program to run.  Setting this option tells the
\&\s-1AFS\s0 session \s-1PAM\s0 module to always run an external program to obtain tokens
and never use the libkafs interface, even if the latter is available.
.Sp
You may pass options to this program by separating them with commas (or
spaces or tabs in \fIkrb5.conf\fR or if the configuration syntax of your \s-1PAM\s0
configuration allows this).  For example, the setting:
.Sp
.Vb 1
\&    program=/usr/bin/aklog,\-noprdb,\-524
.Ve
.Sp
will run \f(CW\*(C`/usr/bin/aklog \-noprdb \-524\*(C'\fR as the program to obtain tokens.
The arguments are passed directly, not parsed by the shell.
.Sp
If this option is not set, the default behavior is to call the libkafs
function to obtain tokens, if available, and otherwise to use a default
path to \fBaklog\fR determined at compile time (the first \fBaklog\fR found on
the compiler's path by default).  If no \fBaklog\fR could be found at compile
time and libkafs isn't used, this option must be set.
.IP "retain_after_close" 4
.IX Item "retain_after_close"
If this option is set, pam_close_session will do nothing (successfully)
rather than deleting tokens.  This will allow programs started in the
user's \s-1PAG\s0 that are still running when the log out to continue to use the
user's tokens until they expire.  Normally, the \s-1AFS\s0 kernel module will
automatically clean up tokens once every process in that \s-1PAG\s0 has
terminated.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1KRB5CCNAME\s0" 4
.IX Item "KRB5CCNAME"
This module looks for \s-1KRB5CCNAME\s0 in the \s-1PAM\s0 environment and by default
does not run \fBaklog\fR if it is not set.
.PP
The entire \s-1PAM\s0 environment is passed to \fBaklog\fR as its environment
(rather than the environment of the process running the \s-1PAM\s0 functions).
.SH "WARNINGS"
.IX Header "WARNINGS"
As mentioned above, this module implements a dummy pam_authenticate
function so that it can provide a pam_setcred function.  Never list this
module as \f(CW\*(C`sufficient\*(C'\fR or as the only \f(CW\*(C`required\*(C'\fR module or you may allow
users to log on without a password.
.PP
While spawning an external \fBaklog\fR program, the \s-1AFS\s0 session \s-1PAM\s0 module
resets the \s-1SIGCHLD\s0 signal handler to the default handler while the program
runs and then restores it afterward.  This is done to avoid having aklog
interfere with process handling in the calling application, but it means
that there's a race condition that can cause children to be incorrectly
handled if they exit while aklog is running.  There is unfortunately no
good solution to this other than building against Heimdal and using the
libkafs interface to obtain tokens instead of an external program.
.PP
To detect whether \s-1AFS\s0 is running on the system, the \s-1AFS\s0 session \s-1PAM\s0 module
temporarily sets a \s-1SIGSYS\s0 handler before attempting an \s-1AFS\s0 system call.
That handler may also modify a static variable.  Neither of these should
ideally be done in a \s-1PAM\s0 module, but there is no other good way of
checking for the non-existence of a system call that doesn't crash the
application on some operating systems.  The \s-1PAM\s0 module will attempt to
restore the previous \s-1SIGSYS\s0 handler, if any, after the test is done, and
the static variable is used in such a way that running it from multiple
threads shouldn't be an issue, but be aware that the \s-1PAM\s0 module is doing
this behind the back of the application and may interfere with unusual
\&\s-1SIGSYS\s0 handlers or similar application actions.
.SH "NOTES"
.IX Header "NOTES"
When using the libkafs interface to obtain tokens, be sure that it is
configured properly for the type of \s-1AFS\s0 tokens expected at your site.  As
of Heimdal 0.7, the default behavior is to contact the krb524 service to
translate Kerberos v5 tickets into Kerberos v4 tickets to use as tokens.
\&\s-1AFS\s0 cells running current server software no longer need this, and if your
site doesn't run the krb524 service, this may break token acquisition.
.PP
Sites running \s-1AFS\s0 servers that understand Kerberos\-v5\-derived tokens
should add configuration like:
.PP
.Vb 5
\&    libkafs = {
\&        EXAMPLE.ORG = {
\&            afs\-use\-524 = no
\&        }
\&    }
.Ve
.PP
to the [appdefaults] section of their \fIkrb5.conf\fR files to disable use of
the krb524 service.  See the Heimdal \fIkafs\fR\|(3) man page for more
information.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2015 Russ Allbery <eagle@eyrie.org>
.PP
Copyright 2005, 2006, 2007, 2008, 2009, 2010, 2011 The Board of Trustees
of the Leland Stanford Junior University
.PP
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and
this notice are preserved.  This file is offered as-is, without any
warranty.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIaklog\fR\|(1), \fIkafs\fR\|(3), \fIpam\fR\|(7), \fIsyslog\fR\|(3), \fIunlog\fR\|(1)