Commit | Line | Data |
---|---|---|
805e021f CE |
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 |