1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN">
3 <TITLE>Administration Reference</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3190/auarf000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 5 Nov 1999 at 13:58:29 -->
7 <META HTTP-EQUIV="updated" CONTENT="Fri, 05 Nov 1999 13:58:29">
8 <META HTTP-EQUIV="review" CONTENT="Sun, 05 Nov 2000 13:58:29">
9 <META HTTP-EQUIV="expires" CONTENT="Mon, 05 Nov 2001 13:58:29">
11 <!-- (C) IBM Corporation 2000. All Rights Reserved -->
12 <BODY bgcolor="ffffff">
13 <!-- End Header Records ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>Administration Reference</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf199.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf201.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
18 <H2><A NAME="HDRKLOG" HREF="auarf002.htm#ToC_214">klog</A></H2>
19 <A NAME="IDX5176"></A>
20 <A NAME="IDX5177"></A>
21 <A NAME="IDX5178"></A>
22 <A NAME="IDX5179"></A>
23 <A NAME="IDX5180"></A>
24 <A NAME="IDX5181"></A>
25 <A NAME="IDX5182"></A>
26 <P><STRONG>Purpose</STRONG>
27 <P>Authenticates with the Authentication Server
28 <P><STRONG>Synopsis</STRONG>
29 <PRE><B>klog</B> [<B>-x</B>] [<B>-principal</B> <<VAR>user name</VAR>>] [<B>-password</B> <<VAR>user's password</VAR>>]
30 [<B>-cell</B> <<VAR>cell name</VAR>>] [<B>-servers</B> <<VAR>explicit list of servers</VAR>><SUP>+</SUP>]
31 [<B>-pipe</B>] [<B>-silent</B>] [<B>-lifetime</B> <<VAR>ticket lifetime in hh[:mm[:ss]]</VAR>>]
32 [<B>-setpag</B>] [<B>-tmp</B>] [<B>-help</B>]
34 <B>klog</B> [<B>-x</B>] [<B>-pr</B> <<VAR>user name</VAR>>] [<B>-pa</B> <<VAR>user's password</VAR>>] [<B>-c</B> <<VAR>cell name</VAR>>]
35 [<B>-s</B> <<VAR>explicit list of servers</VAR>><SUP>+</SUP>] [<B>-pi</B>] [<B>-si</B>]
36 [<B>-l</B> <<VAR>ticket lifetime in hh[:mm[:ss]]</VAR>>] [<B>-se</B>] [<B>-t</B>] [<B>-h</B>]
38 <P><STRONG>Description</STRONG>
39 <P>The <B>klog</B> command obtains an AFS token from the Authentication
40 Server. The Cache Manager on the local machine stores the token in a
41 credential structure in kernel memory and uses it when obtaining authenticated
42 access to the AFS filespace. This command does not affect the
43 issuer's identity (UNIX UID) in the local file system.
44 <P>By default, the command interpreter obtains a token for the AFS user name
45 that matches the issuer's identity in the local file system. To
46 specify an alternate user, include the <B>-principal</B> argument.
47 The user named by the <B>-principal</B> argument does not have to appear
48 in the local password file (the <B>/etc/passwd</B> file or
50 <P>By default, the command interpreter obtains a token for the local cell, as
51 defined by the AFSCELL environment variable set in the command shell or by the
52 <B>/usr/vice/etc/ThisCell</B> file on the local machine. To specify
53 an alternate cell, include the <B>-cell</B> argument. The command
54 interpreter contacts an Authentication Server chosen at random from the
55 cell's entry in the local <B>/usr/afs/etc/CellServDB</B> file, unless
56 the <B>-servers</B> argument is used to name one or more database server
58 <P>A user can have tokens in multiple cells simultaneously, but only one token
59 per cell per connection to the client machine. If the user's
60 credential structure already contains a token for the requested cell, the
61 token resulting from this command replaces it.
62 <P>Sites that employ standard Kerberos authentication instead of the AFS
63 Authentication Server must use the Kerberos version of this command,
64 <B>klog.krb</B>, on all client machines. It automatically
65 places the issuer's Kerberos tickets in the file named by the KRBTKFILE
66 environment variable, which the <B>pagsh.krb</B> command defines
67 automatically as <B>/tmp/tktp</B><I>X</I> where <I>X</I> is the
68 number of the user's PAG.
69 <P>The lifetime of the token resulting from this command is the smallest of
72 <P><LI>The lifetime specified by the issuer with the <B>-lifetime</B>
73 argument. If the issuer does not include this argument, the value
74 defaults to 720 hours (30 days).
75 <P><LI>The maximum ticket lifetime recorded for the <B>afs</B> entry in the
76 Authentication Database. The default is 100 hours.
77 <P><LI>The maximum ticket lifetime recorded in the specified user's
78 Authentication Database entry. The default is 25 hours for user entries
79 created by an Authentication Server running AFS 3.1 or later.
80 <P><LI>The maximum ticket lifetime recorded in the
81 <B>krbtgt.</B><VAR>CELLNAME</VAR> entry in the Authentication
82 Database; this entry corresponds to the ticket-granting ticket used
83 internally in generating the token. The default is 720 hours (30
86 <P>The output from the <B>kas examine</B> command displays an
87 Authentication Database entry's maximum ticket lifetime as <TT>Max
88 ticket lifetime</TT>. Administrators can display any entry, and users
89 can display their own entries.
90 <P>If none of the defaults have been changed, the token lifetime is 25 hours
91 for user accounts created by an Authentication Server running AFS 3.1
92 or higher. The maximum lifetime for any token is 720 hours (30 days),
93 and the minimum is 5 minutes.
94 <P>Between the minimum and maximum values, the Authentication Server uses a
95 defined set of values, according to the following rules. Requested
96 lifetimes between 5 minutes and 10 hours 40 minutes are granted at 5 minute
97 intervals, rounding up. For example, if the issuer requests a lifetime
98 of 12 minutes, the token's actual lifetime is 15 minutes.
99 <P>For token lifetimes greater than 10 hours 40 minutes, consult the following
100 table, which presents all the possible times in units of
101 <VAR>hours</VAR><B>:</B><VAR>minutes</VAR><B>:</B><VAR>seconds</VAR>.
102 The number in parentheses is an approximation of the corresponding time in
103 days and hours (as indicated by the <TT>d</TT> and <TT>h</TT>
104 letters). For example, <TT>282:22:17</TT> means 282
105 hours, 22 minutes, and 17 seconds, which translates to approximately 11 days
106 and 18 hours (<TT>11d 18h</TT>). The Authentication Server rounds up
107 a requested lifetime to the next highest possible lifetime.
108 <PRE> 11:24:15 (0d 11h) 46:26:01 (1d 22h) 189:03:38 (7d 21h)
109 12:11:34 (0d 12h) 49:38:40 (2d 01h) 202:08:00 (8d 10h)
110 13:02:09 (0d 13h) 53:04:37 (2d 05h) 216:06:35 (9d 00h)
111 13:56:14 (0d 13h) 56:44:49 (2d 08h) 231:03:09 (9d 15h)
112 14:54:03 (0d 14h) 60:40:15 (2d 12h) 247:01:43 (10d 07h)
113 15:55:52 (0d 15h) 64:51:57 (2d 16h) 264:06:34 (11d 00h)
114 17:01:58 (0d 17h) 69:21:04 (2d 21h) 282:22:17 (11d 18h)
115 18:12:38 (0d 18h) 74:08:46 (3d 02h) 301:53:45 (12d 13h)
116 19:28:11 (0d 19h) 79:16:23 (3d 07h) 322:46:13 (13d 10h)
117 20:48:57 (0d 20h) 84:45:16 (3d 12h) 345:05:18 (14d 09h)
118 22:15:19 (0d 22h) 90:36:53 (3d 18h) 368:56:58 (15d 08h)
119 23:47:38 (0d 23h) 96:52:49 (4d 00h) 394:27:37 (16d 10h)
120 25:26:21 (1d 01h) 103:34:45 (4d 07h) 421:44:07 (17d 13h)
121 27:11:54 (1d 03h) 110:44:28 (4d 14h) 450:53:46 (18d 18h)
122 29:04:44 (1d 05h) 118:23:54 (4d 22h) 482:04:24 (20d 02h)
123 31:05:22 (1d 07h) 126:35:05 (5d 06h) 515:24:22 (21d 11h)
124 33:14:21 (1d 09h) 135:20:15 (5d 15h) 551:02:38 (22d 23h)
125 35:32:15 (1d 11h) 144:41:44 (6d 00h) 589:08:45 (24d 13h)
126 37:59:41 (1d 13h) 154:42:01 (6d 10h) 629:52:56 (26d 05h)
127 40:37:19 (1d 16h) 165:23:50 (6d 21h) 673:26:07 (28d 01h)
128 43:25:50 (1d 19h) 176:50:01 (7d 08h)
131 <P><STRONG>Cautions</STRONG>
132 <P>By default, this command does not create a new process authentication group
133 (PAG); see the description of the <B>pagsh</B> command to learn about
134 PAGs. If a cell does not use an AFS-modified login utility, users must
135 include <B>-setpag</B> option to this command, or issue the
136 <B>pagsh</B> command before this one, to have their tokens stored in a
137 credential structure that is identified by PAG rather than by local
139 <P>When a credential structure is identified by local UID, the potential
140 security exposure is that the local superuser <B>root</B> can use the UNIX
141 <B>su</B> command to assume any other identity and automatically inherit
142 the tokens associated with that UID. Identifying the credential
143 structure by PAG eliminates this exposure.
144 <P>If the <B>-password</B> argument is used, the specified password cannot
145 begin with a hyphen, because it is interpreted as another option name.
146 Use of the <B>-password</B> argument is not recommended in any
148 <P>By default, it is possible to issue this command on a properly configured
149 NFS client machine that is accessing AFS via the NFS/AFS Translator, assuming
150 that the NFS client machine is a supported system type. However, if the
151 translator machine's administrator has enabled UID checking by including
152 the <B>-uidcheck on</B> argument to the <B>fs exportafs</B> command,
153 the command fails with an error message similar to the following:
155 Warning: Remote pioctl to <VAR>translator_machine</VAR> has failed (err=8). . .
156 Unable to authenticate to AFS because a pioctl failed.
158 <P>Enabling UID checking means that the credential structure in which tokens
159 are stored on the translator machine must be identified by a UID that matches
160 the local UID of the process that is placing the tokens in the credential
161 structure. After the <B>klog</B> command interpreter obtains the
162 token on the NFS client, it passes it to the remote executor daemon on the
163 translator machine, which makes the system call that stores the token in a
164 credential structure on the translator machine. The remote executor
165 generally runs as the local superuser <B>root</B>, so in most cases its
166 local UID (normally zero) does not match the local UID of the user who issued
167 the <B>klog</B> command on the NFS client machine.
168 <P>Issuing the <B>klog</B> command on an NFS client machine creates a
169 security exposure: the command interpreter passes the token across the
170 network to the remote executor daemon in clear text mode.
171 <P><STRONG>Options</STRONG>
174 </B><DD>Appears only for backwards compatibility. Its former function is
175 now the default behavior of this command.
177 </B><DD>Specifies the user name to authenticate. If this argument is
178 omitted, the Authentication Server attempts to authenticate the user logged
179 into the local file system.
181 </B><DD>Specifies the issuer's password (or that of the alternate user
182 identified by the <B>-principal</B> argument). Omit this argument
183 to have the command interpreter prompt for the password, in which case it does
184 not echo visibly in the command shell.
186 </B><DD>Specifies the cell for which to obtain a token. The command is
187 directed to that cell's Authentication Servers. During a single
188 login session on a given machine, a user can be authenticated in multiple
189 cells simultaneously, but can have only one token at a time for each of them
190 (that is, can only authenticate under one identity per cell per session on a
191 machine). It is acceptable to abbreviate the cell name to the shortest
192 form that distinguishes it from the other cells listed in the
193 <B>/usr/vice/etc/CellServDB</B> file on the client machine on which the
195 <P>If this argument is omitted, the command is executed in the local cell, as
198 <P><LI>First, by the value of the environment variable AFSCELL
199 <P><LI>Second, in the <B>/usr/vice/etc/ThisCell</B> file on the client
200 machine on which the command is issued
203 </B><DD>Establishes a connection with the Authentication Server running on each
204 specified database server machine. The command interpreter then chooses
205 one of these at random to execute the command. It is best to provide
206 fully-qualified hostnames, but abbreviated forms are possibly acceptable
207 depending on the state of the cell's name server at the time the command
208 is issued. This option is useful for testing specific servers if
209 problems are encountered.
210 <P>If this argument is omitted, the command interpreter establishes a
211 connection with each machine listed for the indicated cell in the local copy
212 of the <B>/usr/vice/etc/CellServDB</B> file, and then chooses one of them
213 at random for command execution.
215 </B><DD>Suppresses all output to the standard output stream, including prompts and
216 error messages. The <B>klog</B> command interpreter expects to
217 receive the password from the standard input stream. Do not use this
218 argument; it is designed for use by application programs rather than
221 </B><DD>Suppresses some of the trace messages that the <B>klog</B> command
222 produces on the standard output stream by default. It still reports on
223 major problems encountered.
225 </B><DD>Requests a specific lifetime for the token. Provide a number of
226 hours and optionally minutes and seconds in the format
227 <VAR>hh</VAR>[<B>:</B><VAR>mm</VAR>[<B>:</B><VAR>ss</VAR>]].
228 The value is used in calculating the token lifetime as described in the
229 <B>Description</B> section.
231 </B><DD>Creates a process authentication group (PAG) prior to requesting
232 authentication. The token is associated with the newly created
235 </B><DD>Creates a Kerberos-style ticket file in the <B>/tmp</B> directory of
236 the local machine. The file is called
237 <B>tkt.</B><VAR>AFS_UID</VAR> where <VAR>AFS_UID</VAR> is the AFS UID
240 </B><DD>Prints the online help for this command. All other valid options
243 <P><STRONG>Cautions</STRONG>
244 <P><STRONG>Output</STRONG>
245 <P>The following message indicates that the limit on consecutive
246 authentication failures has been exceeded. An administrator can use the
247 <B>kas unlock</B> command to unlock the account, or the issuer can wait
248 until the lockout time for the account has passed. (The time is set
249 with the <B>-locktime</B> argument to the <B>kas setfields</B> command
250 and displayed in the output from the <B>kas examine</B> command).
252 Unable to authenticate to AFS because ID is locked - see your system admin
255 <P>If the <B>-tmp</B> flag is included, the following message confirms
256 that a Kerberos-style ticket file was created:
258 Wrote ticket file to /tmp
261 <P><STRONG>Examples</STRONG>
262 <P>Most often, this command is issued without arguments. The
263 appropriate password is for the person currently logged into the local file
264 system. The ticket's lifetime is calculated as described in the
265 <B>Description</B> section (if no defaults have been changed, it is 25
266 hours for a user whose Authentication Database entry was created in AFS
273 <P>The following example authenticates the user as <B>admin</B> in the ABC
274 Corporation's test cell:
276 % <B>klog -principal admin -cell test.abc.com</B>
280 <P>In the following, the issuer requests a ticket lifetime of 104 hours 30
281 minutes (4 days 8 hours 30 minutes). Presuming that this lifetime is
282 allowed by the maximum ticket lifetimes and other factors described in the
283 <B>Description</B> section, the token's lifetime is
284 110:44:28, which is the next largest possible value.
285 <PRE> % <B>klog -lifetime 104:30</B>
289 <P><STRONG>Privilege Required</STRONG>
291 <P><STRONG>Related Information</STRONG>
292 <P><A HREF="auarf139.htm#HDRFS_EXPORTAFS">fs exportafs</A>
293 <P><A HREF="auarf185.htm#HDRKAS_EXAMINE">kas examine</A>
294 <P><A HREF="auarf193.htm#HDRKAS_SETFIELDS">kas setfields</A>
295 <P><A HREF="auarf197.htm#HDRKAS_UNLOCK">kas unlock</A>
296 <P><A HREF="auarf198.htm#HDRKASERVER">kaserver</A>
297 <P><A HREF="auarf208.htm#HDRPAGSH">pagsh</A>
298 <P><A HREF="auarf235.htm#HDRTOKENS">tokens</A>
300 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf199.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf201.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
301 <!-- Begin Footer Records ========================================== -->
303 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
305 <!-- End Footer Records ============================================ -->
306 <A NAME="Bot_Of_Page"></A>
git://git.openafs.org / openafs.git / blob