eb1727b42d7f60384c1e280dcb0c1bbbdfa44789
[openafs.git] / doc / man-pages / pod1 / aklog.pod
1 =head1 NAME
2
3 aklog - Obtain tokens for authentication to AFS
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<aklog> [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>]
11     [B<-force>] [B<-524>] [B<-setpag>]
12     S<<< [[B<-cell> | B<-c>] <I<cell>> [B<-k> <I<Kerberos realm>>]]+ >>>
13
14 B<aklog> [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>]
15     [B<-force>] [B<-524>] [B<-setpag>] [B<-path> | B<-p>] <I<path>>+
16
17 =for html
18 </div>
19
20 =head1 DESCRIPTION
21
22 The B<aklog> program authenticates to a cell in AFS by obtaining AFS
23 tokens using a Kerberos 5 ticket. If B<aklog> is invoked with no
24 command-line arguments, it will obtain tokens for the workstation's local
25 cell.  It may be invoked with an arbitrary number of cells and pathnames
26 to obtain tokens for multiple cells.  B<aklog> knows how to expand cell
27 name abbreviations, so cells can be referred to by enough letters to make
28 the cell name unique among the cells the workstation knows about.
29
30 B<aklog> obtains tokens by obtaining a Kerberos service ticket for the AFS
31 service and then storing it as a token.  By default, it obtains that
32 ticket from the realm corresponding to that cell (the uppercase version of
33 the cell name), but a different realm for a particular cell can be
34 specified with B<-k>.  B<-k> cannot be used in B<-path> mode (see below).
35
36 When a Kerberos 5 cross-realm trust is used, B<aklog> looks up the AFS ID
37 corresponding to the name (Kerberos principal) of the person invoking the
38 command, and if the user doesn't exist and the
39 C<system:authuser@FOREIGN.REALM> PTS group exists, then it attempts automatic
40 registration of the user with the foreign cell.  The user is then added to
41 the C<system:authuser@FOREIGN.REALM> PTS group if registration is successful.
42 Automatic registration in the foreign cell will fail if the group quota
43 for the C<system:authuser@FOREIGN.REALM> group is less than one.  Each
44 automatic registration decrements the group quota by one.
45
46 =head1 CAUTIONS
47
48 When using B<aklog>, be aware that AFS uses the Kerberos v4 principal
49 naming format, not the Kerberos v5 format, when referring to principals in
50 PTS ACLs, F<UserList>, and similar locations.  AFS will internally map
51 Kerberos v5 principal names to the Kerberos v4 syntax by removing any
52 portion of the instance after the first period (generally the domain name
53 of a host principal), changing any C</> to C<.>, and changing an initial
54 principal part of C<host> to C<rcmd>.  In other words, to create a PTS
55 entry for the Kerberos v5 principal C<user/admin>, refer to it as
56 C<user.admin>, and for the principal C<host/shell.example.com>, refer to
57 it as C<rcmd.shell>.
58
59 The B<aklog> mapping of Kerberos v5 principal to Kerberos v4 principal and
60 the determination that a Kerberos realm is foreign is performed in the
61 absence of the actual AFS server configuration.  If the B<aklog> mapping
62 of Kerberos v5 principal to Kerberos v4 principal or the foreign realm
63 determination is wrong, the PTS name-to-id lookup will produce the wrong
64 AFS ID for the user.  The AFS ID is only used for display purposes and
65 should not be trusted.  Use the B<-noprdb> switch to disable the PTS
66 name-to-id lookup.
67
68 =head1 OPTIONS
69
70 =over 4
71
72 =item B<-524>
73
74 Normally, B<aklog> generates native K5 tokens.  This flag tells B<aklog>
75 to instead use the krb524 translation service to generate K4 or rxkad2b
76 tokens, which may be necessary for AFS cells that don't support native K5
77 tokens.  Support for native K5 tokens were added in OpenAFS 1.2.8.
78
79 =item B<-cell> <I<cell>>, B<-c> <I<cell>>
80
81 This flag tells B<aklog> that the next argument is the name of a cell to
82 authenticate to.  It normally isn't necessary; B<aklog> normally
83 determines whether an argument is a cell or a path name based on whether
84 it contains C</> or is C<.> or C<..>.  The cell may be followed by B<-k>
85 to specify the corresponding Kerberos realm.
86
87 =item B<-d>
88
89 Turns on printing of debugging information.  This option is not intended
90 for general users.
91
92 =item B<-force>
93
94 Normally, aklog will not replace tokens with new tokens that appear to be
95 identical.  If this flag is given, it will skip that check.
96
97 =item B<-hosts>
98
99 Prints all the server addresses which may act as a single point of failure
100 in accessing the specified directory path.  Each element of the path is
101 examined, and as new volumes are traversed, if they are not replicated,
102 the server's IP address containing the volume will be displayed.  The
103 output is of the form:
104
105     host: <ip-address>
106
107 This option is only useful in combination with paths as arguments rather
108 than cells.
109
110 =item B<-k> <I<Kerberos realm>>
111
112 This flag is valid only immediately after the name of the cell.  It tells
113 B<aklog> to use that Kerberos realm when authenticating to the preceding
114 cell.  By default, B<aklog> will use the realm (per the local Kerberos
115 configuration) of the first database server in the cell, so this flag
116 normally won't be necessary.
117
118 =item B<-linked>
119
120 If the AFS cell is linked to another AFS cell, get tokens for both.
121
122 =item B<-noauth>
123
124 Don't actually authenticate, just do everything else B<aklog> does up to
125 setting tokens.
126
127 =item B<-noprdb>
128
129 Ordinarily, B<aklog> looks up the AFS ID corresponding to the name of the
130 person invoking the command, and if the user doesn't exist, the cell is a
131 foreign one, the system:authuser@FOREIGN.REALM PTS group exists, and has a
132 positive group quota, then it attempts automatic registration of the user
133 with the foreign cell.  Specifying this flag turns off this functionality.
134 This may be desirable if the protection database is unavailable for some
135 reason and tokens are desired anyway, or if one wants to disable user
136 registration.
137
138 =item B<-path> <I<pathname>>, B<-p> <I<pathname>>
139
140 This flag tells B<aklog> that the next argument is a path in AFS.
141 B<aklog> will walk that path and obtain tokens for every cell needed to
142 access all of the directories.  Normally, this flag isn't necessary;
143 B<aklog> assumes an argument is a path if it contains C</> or is C<.> or
144 C<..>.
145
146 =item B<-setpag>
147
148 When setting tokens, attempt to put the parent process in a new PAG.  This
149 is usually used as part of the login process but can be used any time to
150 create a new AFS authentication context.  Note that this in some cases
151 relies on dangerous and tricky manipulations of kernel records and will
152 not work on all platforms or with all Linux kernels.
153
154 =item B<-zsubs>
155
156 Prints out the Zephyr subscription information to get alerts regarding all
157 of the file servers required to access a particular path.  The output is
158 of the form:
159
160     zsub: <instance>
161
162 where <instance> is the instance of a class C<filsrv> Zephyr subscription.
163
164 =back
165
166 =head1 ENVIRONMENT
167
168 =over 4
169
170 =item KRB5CCNAME
171
172 As with most programs that use an existing Kerberos ticket cache, B<aklog>
173 can be told to use a cache other than the default by setting the
174 environment variable KRB5CCNAME.  On UNIX and Linux systems, this variable
175 is normally set to a file name, but may point to other types of caches.
176 See the documentation of your Kerberos implementation for more details.
177
178 =back
179
180 =head1 FILES
181
182 =over 4
183
184 =item F<~/.xlog>
185
186 If this file exists in the user's home directory, it should contain a list
187 of AFS cells to which to authenticate, one per line.  If B<aklog> is
188 invoked without any options, it will attempt to obtain tokens in every
189 cell listed in this file if it exists, rather than only obtaining tokens
190 for the local cell.
191
192 =back
193
194 =head1 EXIT CODES
195
196 The exit status of B<aklog> will be one of the following:
197
198 =over 3
199
200 =item C<0>
201
202 Success -- No error occurred.
203
204 =item C<1>
205
206 Usage -- Bad command syntax; accompanied by a usage message.
207
208 =item C<2>
209
210 Something failed -- More than one cell or pathname was given on the
211 command line and at least one failure occurred.  A more specific error
212 status is returned when only one directive is given.
213
214 =item C<3>
215
216 AFS -- Unable to get AFS configuration or unable to get information about
217 a specific cell.
218
219 =item C<4>
220
221 Kerberos -- Unable to get tickets for authentication.
222
223 =item C<5>
224
225 Token -- Unable to get tokens.
226
227 =item C<6>
228
229 Bad pathname -- The path given was not a directory or lstat(2) failed on
230 some component of the pathname.
231
232 =item C<7>
233
234 Miscellaneous -- An internal failure occurred.  For example, B<aklog>
235 returns this if it runs out of memory.
236
237 =back
238
239 =head1 EXAMPLES
240
241 To get tokens for the local cell:
242
243     % aklog
244
245 To get tokens for the C<prod.example.org> cell:
246
247     % aklog prod.example.org
248
249 or
250
251     % aklog prod
252
253 The latter will work if you local cache manager already knows about the
254 C<prod> cell.
255
256 To get tokens adequate to read F</afs/prod.example.org/user/p/potato>:
257
258     % aklog /afs/prod.example.org/user/p/potato
259
260 To get tokens for C<testcell.example.org> that is in a test Kerberos realm:
261
262     % aklog testcell.example.org -k TESTREALM.EXAMPLE.ORG
263
264 =head1 SEE ALSO
265
266 kinit(1), tokens(1), unlog(1)
267
268 =head1 AUTHOR
269
270 Manpage originally written by Emanuel Jay Berkenbilt (MIT-Project
271 Athena).  Extensively modified by Russ Allbery <rra@stanford.edu>.
272
273 =head1 COPYRIGHT
274
275 Original manpage is copyright 1990, 1991 Massachusetts Institute of
276 Technology.  All rights reserved.
277
278 Copyright 2006 Russ Allbery <rra@stanford.edu>.
279
280 Export of this software from the United States of America may require
281 a specific license from the United States Government.  It is the
282 responsibility of any person or organization contemplating export to
283 obtain such a license before exporting.
284
285 WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute
286 this software and its documentation for any purpose and without fee is
287 hereby granted, provided that the above copyright notice appear in all
288 copies and that both that copyright notice and this permission notice
289 appear in supporting documentation, and that the name of M.I.T. not be
290 used in advertising or publicity pertaining to distribution of the
291 software without specific, written prior permission.  Furthermore if you
292 modify this software you must label your software as modified software and
293 not distribute it in such a fashion that it might be confused with the
294 original MIT software.  M.I.T. makes no representations about the
295 suitability of this software for any purpose.  It is provided "as is"
296 without express or implied warranty.
297
298 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
299 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
300 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
301
302 =cut