aklog-heimdal-integration-20050630
[openafs.git] / src / aklog / aklog.1
1 .\" 
2 .\" $Id$
3 .\"
4 .\" Copyright 1990,1991 by the Massachusetts Institute of Technology
5 .\" For distribution and copying rights, see the file "mit-copyright.h"
6 .\"
7 .TH AKLOG 1 "August 1, 1990"
8 .UC 4
9 .SH NAME
10 aklog \- Obtain tokens for authentication to AFS
11
12 .SH SYNOPSIS
13 .B aklog 
14
15 .B \-d 
16 ] [ 
17 .B \-hosts
18 ] [ 
19 .B \-zsubs 
20 ] [ 
21 .B \-noprdb 
22 ] [ [
23 .B \-cell | \-c 
24 ] cell [
25 .B \-k 
26 kerberos-realm
27 ] ] [ [ 
28 .B \-path | \-p 
29 ] pathname ]
30
31 .SH DESCRIPTION
32 The 
33 .I aklog
34 program is used to authenticate to a cell or directory in 
35 .I AFS,
36 the Andrew Filesystem, by obtaining AFS 
37 .I tokens.  
38 Ordinarily, aklog is not used directly but called by
39 .IR attach (1).
40
41 If 
42 .I aklog
43 is invoked with no command line arguments, it will obtain tokens 
44 for the workstation's local cell.  It is possible to invoke
45 .I aklog
46 with arbitrarily many cells and pathnames
47 specified on the command line.  
48 .I aklog 
49 knows how to expand cell name abbreviations, so short
50 forms of cell names can be use used.  In addition, 
51 .I aklog
52 understands the following command line options:
53
54 .TP 4 
55 .B  \-cell | \-c \fRcell
56 This flag is not ordinarily necessary since 
57 .I aklog
58 can usually figure out when an argument is a cell.  It can be
59 used to introduce a cell name that would ordinarily be mistaken
60 for a path name if this should be required.  If this flag is
61 omitted, an argument will be treated as a cell name if it
62 contains no slashes (/) and is neither "." nor ".." .
63
64 .TP
65 .B \-k \fRkerberos-realm
66 This flag is valid only when immediately following the name of a
67 cell.  It is used to tell 
68 .I aklog
69 what kerberos realm should be used while authenticating to the
70 preceding cell.  This argument is unnecessary except when the
71 workstation is not properly configured.  Ordinarily, 
72 .I aklog
73 can determine this information on its own.
74
75 .TP
76 .B \-path | \-p \fRpathname
77 Like the \-cell flag, this flag is usually unnecessary.  When it
78 appears, the next command line argument is always treated as a
79 path name.  Ordinarily, an argument is treated as a path name
80 if it is "." or ".." or if it contains a slash (/).  
81
82 .TP
83 .B \-hosts
84 Prints all the server addresses which may act as a single point of
85 failure in accessing the specified directory path.  Each element of the
86 path is examined, and as new volumes are traversed, if they are not
87 replicated, the server's IP address containing the volume will be
88 displayed.
89 .IR Attach (1)
90 invokes 
91 .I aklog
92 with this option.  The output is of the form
93
94 host: 
95 .I IP address
96
97 .TP
98 .B \-zsubs
99 Causes the printing of the zephyr subscription information that a
100 person using a given path or cell would want.  
101 .IR Attach (1)
102 invokes 
103 .I aklog
104 with this option.  The output is of the form
105
106 zsub: 
107 .I instance
108
109 where 
110 .I instance
111 is the instance of a class filsrv zephyr subscription.
112
113 .TP
114 .B \-noprdb
115 Ordinarily, aklog looks up the AFS ID corresponding to the name
116 of the person invoking the command.  Specifying this flag turns
117 off this functionality.  This may be desirable if the protection
118 database is unavailable for some reason and tokens are desired
119 anyway.  
120
121 .TP
122 .B \-d
123 Turns on printing of debugging information.  This option is not
124 intended for general users.
125
126 .SH EXIT CODES
127 The exit status of
128 .I aklog
129 will be one of the following:
130 .TP 5
131 0
132 Success -- No error occurred.
133 .TP 5
134 1
135 Usage -- Bad command syntax; accompanied by a usage message.
136 .TP 5
137 2
138 Something failed -- More than one cell or pathname was given on
139 the command line and at least one failure occurred.
140 A more specific error status is returned when only one directive
141 is given.
142 .TP 5
143 3
144 AFS -- Unable to get AFS configuration or unable to get
145 information about a specific cell.
146 .TP 5
147 4
148 Kerberos -- Unable to get tickets for authentication.
149 .TP 5
150 5
151 Token -- Unable to get tokens.
152 .TP 5
153 6
154 Bad pathname -- The path given was not a directory or 
155 .I lstat(2)
156 failed on some component of the pathname.
157 .TP 5
158 7
159 Miscellaneous -- An internal failure occurred.  For example, 
160 .I aklog
161 returns this if it runs out of memory.
162
163 .SH EXAMPLES
164 .br
165 To get tokens for the local cell:
166 .br
167 % aklog
168
169 To get tokens for the athena.mit.edu cell:
170 .br
171 % aklog athena.mit.edu
172 .br
173 or
174 .br
175 % aklog athena
176
177 To get tokens adequate to read /afs/athena.mit.edu/user/p/potato:
178 .br
179 % aklog /afs/athena.mit.edu/user/p/potato
180
181 To get tokens for a test cell that is in a test Kerberos realm:
182 .br
183 % aklog testcell.mit.edu -k TESTREALM.MIT.EDU
184
185 .SH SEE ALSO
186 attach(1), tokens(1), unlog(1)
187
188 .SH AUTHOR
189 Emanuel Jay Berkenbilt (MIT-Project Athena)