doc: Add aklog_dynamic_auth manpage
[openafs.git] / doc / man-pages / pod8 / aklog_dynamic_auth.pod
1 =head1 NAME
2
3 aklog_dynamic_auth - LAM module to obtain AFS tokens from Kerberos tickets
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10   K5AFS:
11     program = /usr/lib/security/aklog_dynamic_auth
12     options = authonly
13
14 =for html
15 </div>
16
17 =head1 DESCRIPTION
18
19 B<aklog_dynamic_auth> is an AIX LAM (Loadable Authentication Modules)
20 module that can create new AFS sessions and acquire AFS tokens from
21 Kerberos 5 tickets. It is similar in function to the L<aklog(1)> program,
22 and various PAM modules such as L<pam_afs_session(8)>.
23
24 B<aklog_dynamic_auth> does not obtain any credentials on its own, nor does
25 it deal with passwords of any kind. You must have another way of obtaining
26 Kerberos 5 tickets before invoking B<aklog_dynamic_auth> in order for it
27 to do anything useful. AIX comes with a B<KRB5> LAM module that can do
28 this.
29
30 =head1 OPTIONS
31
32 Beyond the normal LAM options, B<aklog_dynamic_auth> understands the
33 following options.
34
35 =over 4
36
37 =item B<uidpag>
38
39 If this is specified, B<aklog_dynamic_auth> will try to only utilize
40 UID-based PAGs. This means that when acquiring credentials,
41 B<aklog_dynamic_auth> will not try to create a new PAG, and instead will
42 set tokens for the current UID. If the current UID is root,
43 B<aklog_dynamic_auth> will look up the UID of the user we are
44 authenticating for, and will set tokens for that UID instead.
45
46 Specifying this option is necessary for AFS tokens to be refreshed with
47 the CDE screen locking program, and possibly other LAM users.
48
49 Note that if B<aklog_dynamic_auth> is run from a context that has a real
50 PAG, it is impossible for it to set the tokens for a particular UID. If
51 B<uidpag> is set and this situation is detected, B<aklog_dynamic_auth>
52 will log an error, but will attempt to continue and will just create a new
53 PAG, as if B<uidpag> were not set.
54
55 =item B<localuid>
56
57 Normally, B<aklog_dynamic_auth> will look up the AFS ID of the username
58 for which it is acquiring credentials by looking the in AFS Protection
59 Database. Specifying the B<localuid> option instead causes
60 B<aklog_dynamic_auth> to look up the relevant user via L<getpwnam(3)>, and
61 to use the returned UID for the AFS ID.
62
63 This will only work correctly if the IDs of local users and their AFS IDs
64 in the AFS Protection Database are synchronized, and will only work for
65 users of the local cell.
66
67 Specifying B<localuid> makes B<aklog_dynamic_auth> avoid calling AFS pt
68 routines, which can crash certain long-running daemons that call into LAM.
69
70 =back
71
72 =head1 EXAMPLES
73
74 The following example allows the user C<userid> to login with Kerberos 5
75 credentials and obtain AFS tokens on success. If Kerberos 5 authentication
76 fails, we fall back to using local authentication. The
77 B<aklog_dynamic_aklog> options for B<uidpag> and B<localuid>
78
79 In C</usr/lib/security/methods.cfg>:
80
81   KRB5:
82     program = /usr/lib/security/KRB5
83     program_64 = /usr/lib/security/KRB5_64
84     options = authonly,kadmind=no
85
86   K5AFS:
87     program = /usr/lib/security/aklog_dynamic_auth
88     options = uidpag,localuid,authonly
89
90 In C</etc/security/user>:
91
92   userid:
93     SYSTEM = "(KRB5[SUCCESS] and K5AFS) OR compat"
94
95 =head1 SEE ALSO
96
97 L<aklog(1)>
98
99 =head1 COPYRIGHT
100
101 Copyright Sine Nomine Associates 2011
102
103 This documentation is covered by the BSD License as written in the
104 doc/LICENSE file. This man page was written by Andrew Deason for OpenAFS.