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