aklog-man-page-20060731
[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.  If B<aklog> is invoked with no command-line arguments, it will
24 obtain tokens for the workstation's local cell.  It may be invoked with an
25 arbitrary number of cells and pathnames to obtain tokens for multiple
26 cells.  B<aklog> knows how to expand cell name abbreviations, so cells can
27 be referred to by enough letters to make the cell name unique among the
28 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 upcase 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 =head1 OPTIONS
37
38 =over 4
39
40 =item B<-524>
41
42 Normally, B<aklog> generates native K5 tokens.  This flag tells B<aklog>
43 to instead use the krb524 translation service to generate K4 or rxkad2b
44 tokens, which may be necessary for AFS cells that don't support native K5
45 tokens.  Support for native K5 tokens were added in OpenAFS 1.2.8.
46
47 =item B<-cell> <I<cell>>, B<-c> <I<cell>>
48
49 This flag tells B<aklog> that the next argument is the name of a cell to
50 authenticate to.  It normally isn't necessary; B<aklog> normally
51 determines whether an argument is a cell or a path name based on whether
52 it contains C</> or is C<.> or C<..>.  The cell may be followed by B<-k>
53 to specify the corresponding Kerberos realm.
54
55 =item B<-d>
56
57 Turns on printing of debugging information.  This option is not intended
58 for general users.
59
60 =item B<-force>
61
62 Normally, aklog will not replace tokens with new tokens that appear to be
63 identical.  If this flag is given, it will skip that check.
64
65 =item B<-hosts>
66
67 Prints all the server addresses which may act as a single point of
68 failure in accessing the specified directory path.  Each element of the
69 path is examined, and as new volumes are traversed, if they are not
70 replicated, the server's IP address containing the volume will be
71 displayed.  The output is of the form:
72
73     host: <ip-address>
74
75 This option is only useful in combination with paths as arguments rather
76 than cells.
77
78 =item B<-k> <I<Kerberos realm>>
79
80 This flag is valid only immediately after the name of the cell.  It tells
81 B<aklog> to use that Kerberos realm when authenticating to the preceding
82 cell.  By default, B<aklog> will use the realm (per the local Kerberos
83 configuration) of the first database server in the cell, so this flag
84 normally won't be necessary.
85
86 =item B<-linked>
87
88 If the AFS cell is linked to a DCE cell, get tokens for both.
89
90 =item B<-noauth>
91
92 Don't actually authenticate, just do everything else B<aklog> does up to
93 setting tokens.
94
95 =item B<-noprdb>
96
97 Ordinarily, B<aklog> looks up the AFS ID corresponding to the name of the
98 person invoking the command, and if the user doesn't exist and the cell is
99 a foreign one, attempts automatic registration of the user with the remote
100 cell.  Specifying this flag turns off this functionality.  This may be
101 desirable if the protection database is unavailable for some reason and
102 tokens are desired anyway, or if one wants to disable user registration.
103
104 =item B<-path> <I<pathname>>, B<-p> <I<pathname>>
105
106 This flag tells B<aklog> that the next argument is a path in AFS.
107 B<aklog> will walk that path and obtain tokens for every cell needed to
108 access all of the directories.  Normally, this flag isn't necessary;
109 B<aklog> assumes an argument is a path if it contains C</> or is C<.> or
110 C<..>.
111
112 =item B<-setpag>
113
114 When setting tokens, attempt to put the parent process in a new PAG.  This
115 is usually used as part of the login process but can be used any time to
116 create a new AFS authentication context.
117
118 =item B<-zsubs>
119
120 Prints out the Zephyr subscription information to get alerts regarding all
121 of the file servers required to access a particular path.  The output is
122 of the form:
123
124     zsub: <instance>
125
126 where <instance> is the instance of a class C<filsrv> Zephyr subscription.
127
128 =back
129
130 =head1 FILES
131
132 =over 4
133
134 =item F<~/.xlog>
135
136 If this file exists in the user's home directory, it should contain a list
137 of AFS cells to which to authenticate, one per line.  If B<aklog> is
138 invoked without any options, it will attempt to obtain tokens in every
139 cell listed in this file if it exists, rather than only obtaining tokens
140 for the local cell.
141
142 =back
143
144 =head1 EXIT CODES
145
146 The exit status of B<aklog> will be one of the following:
147
148 =over 3
149
150 =item 0
151
152 Success -- No error occurred.
153
154 =item 1
155
156 Usage -- Bad command syntax; accompanied by a usage message.
157
158 =item 2
159
160 Something failed -- More than one cell or pathname was given on the
161 command line and at least one failure occurred.  A more specific error
162 status is returned when only one directive is given.
163
164 =item 3
165
166 AFS -- Unable to get AFS configuration or unable to get information about
167 a specific cell.
168
169 =item 4
170
171 Kerberos -- Unable to get tickets for authentication.
172
173 =item 5
174
175 Token -- Unable to get tokens.
176
177 =item 6
178
179 Bad pathname -- The path given was not a directory or lstat(2) failed on
180 some component of the pathname.
181
182 =item 7
183
184 Miscellaneous -- An internal failure occurred.  For example, B<aklog>
185 returns this if it runs out of memory.
186
187 =back
188
189 =head1 EXAMPLES
190
191 To get tokens for the local cell:
192
193     % aklog
194
195 To get tokens for the C<athena.mit.edu> cell:
196
197     % aklog athena.mit.edu
198
199 or
200
201     % aklog athena
202
203 The latter will work if you local cache manager already knows about the
204 C<athena> cell.
205
206 To get tokens adequate to read F</afs/athena.mit.edu/user/p/potato>:
207
208     % aklog /afs/athena.mit.edu/user/p/potato
209
210 To get tokens for C<testcell.mit.edu> that is in a test Kerberos realm:
211
212     % aklog testcell.mit.edu -k TESTREALM.MIT.EDU
213
214 =head1 SEE ALSO
215
216 kinit(1), tokens(1), unlog(1)
217
218 =head1 AUTHOR
219
220 Manpage originally written by Emanuel Jay Berkenbilt (MIT-Project
221 Athena).  Extensively modified by Russ Allbery <rra@stanford.edu>.
222
223 =head1 COPYRIGHT
224
225 Original manpage is copyright 1990, 1991 Massachusetts Institute of
226 Technology.  All rights reserved.
227
228 Copyright 2006 Russ Allbery <rra@stanford.edu>.
229
230 Export of this software from the United States of America may require
231 a specific license from the United States Government.  It is the
232 responsibility of any person or organization contemplating export to
233 obtain such a license before exporting.
234
235 WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute
236 this software and its documentation for any purpose and without fee is
237 hereby granted, provided that the above copyright notice appear in all
238 copies and that both that copyright notice and this permission notice
239 appear in supporting documentation, and that the name of M.I.T. not be
240 used in advertising or publicity pertaining to distribution of the
241 software without specific, written prior permission.  Furthermore if you
242 modify this software you must label your software as modified software and
243 not distribute it in such a fashion that it might be confused with the
244 original MIT software.  M.I.T. makes no representations about the
245 suitability of this software for any purpose.  It is provided "as is"
246 without express or implied warranty.
247
248 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
249 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
250 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
251
252 =cut