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="auarf192.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="auarf194.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="HDRKAS_SETFIELDS" HREF="auarf002.htm#ToC_207">kas setfields</A></H2>
19 <A NAME="IDX5130"></A>
20 <A NAME="IDX5131"></A>
21 <A NAME="IDX5132"></A>
22 <A NAME="IDX5133"></A>
23 <A NAME="IDX5134"></A>
24 <A NAME="IDX5135"></A>
25 <A NAME="IDX5136"></A>
26 <A NAME="IDX5137"></A>
27 <A NAME="IDX5138"></A>
28 <A NAME="IDX5139"></A>
29 <A NAME="IDX5140"></A>
30 <A NAME="IDX5141"></A>
31 <A NAME="IDX5142"></A>
32 <P><STRONG>Purpose</STRONG>
33 <P>Sets optional characteristics in an Authentication Database entry
34 <P><STRONG>Synopsis</STRONG>
35 <PRE><B>kas setfields -name</B> <<VAR>name of user</VAR>>
36 [<B>-flags</B> <<VAR>hex flag value or flag name expression</VAR>>]
37 [<B>-expiration</B> <<VAR>date of account expiration</VAR>>]
38 [<B>-lifetime</B> <<VAR>maximum ticket lifetime</VAR>>]
39 [<B>-pwexpires</B> <<VAR>number days password is valid ([0..254])</VAR>>]
40 [<B>-reuse</B> <<VAR>permit password reuse (yes/no)</VAR>>]
41 [<B>-attempts</B> <<VAR>maximum successive failed login tries ([0..254])</VAR>>]
42 [<B>-locktime</B> <<VAR>failure penalty [hh:mm or minutes]</VAR>>]
43 [<B>-admin_username</B> <<VAR>admin principal to use for authentication</VAR>>]
44 [<B>-password_for_admin</B> <<VAR>admin password</VAR>>] [<B>-cell</B> <<VAR>cell name</VAR>>]
45 [<B>-servers</B> <<VAR>explicit list of authentication servers</VAR>><SUP>+</SUP>]
46 [<B>-noauth</B>] [<B>-help</B>]
48 <B>kas setf -na</B> <<VAR>name of user</VAR>> [<B>-f</B> <<VAR>hex flag value or flag name expression</VAR>>]
49 [<B>-e</B> <<VAR>date of account expiration</VAR>>] [<B>-li</B> <<VAR>maximum ticket lifetime</VAR>>]
50 [<B>-pw</B> <<VAR>number days password is valid ([0..254])</VAR>>]
51 [<B>-r</B> <<VAR>permit password reuse (yes/no)</VAR>>]
52 [<B>-at</B> <<VAR>maximum successive failed login tries ([0..254])</VAR>>]
53 [<B>-lo</B> <<VAR>failure penalty [hh:mm or minutes]</VAR>>]
54 [<B>-ad</B> <<VAR>admin principal to use for authentication</VAR>>]
55 [<B>-pa</B> <<VAR>admin password</VAR>>] [<B>-c</B> <<VAR>cell name</VAR>>]
56 [<B>-s</B> <<VAR>explicit list of authentication servers</VAR>><SUP>+</SUP>] [<B>-no</B>] [<B>-h</B>]
58 <B>kas sf -na</B> <<VAR>name of user</VAR>> [<B>-f</B> <<VAR>hex flag value or flag name expression</VAR>>]
59 [<B>-e</B> <<VAR>date of account expiration</VAR>>] [<B>-li</B> <<VAR>maximum ticket lifetime</VAR>>]
60 [<B>-pw</B> <<VAR>number days password is valid ([0..254])</VAR>>]
61 [<B>-r</B> <<VAR>permit password reuse (yes/no)</VAR>>]
62 [<B>-at</B> <<VAR>maximum successive failed login tries ([0..254])</VAR>>]
63 [<B>-lo</B> <<VAR>failure penalty [hh:mm or minutes]</VAR>>]
64 [<B>-ad</B> <<VAR>admin principal to use for authentication</VAR>>]
65 [<B>-pa</B> <<VAR>admin password</VAR>>] [<B>-c</B> <<VAR>cell name</VAR>>]
66 [<B>-s</B> <<VAR>explicit list of authentication servers</VAR>><SUP>+</SUP>] [<B>-no</B>] [<B>-h</B>]
68 <P><STRONG>Description</STRONG>
69 <P>The <B>kas setfields</B> command changes the Authentication Database
70 entry for the user named by the <B>-name</B> argument in the manner
71 specified by the various optional arguments, which can occur singly or in
74 <P><LI>To set the flags that determine whether the user has administrative
75 privileges to the Authentication Server, can obtain a ticket, can change his
76 or her password, and so on, include the <B>-flags</B> argument.
77 <P><LI>To set when the Authentication Database entry expires, include the
78 <B>-expiration</B> argument.
79 <P><LI>To set the maximum ticket lifetime associated with the entry, include the
80 <B>-lifetime</B> argument. The reference page for the
81 <B>klog</B> command explains how this value interacts with others to
82 determine the actual lifetime of a token.
83 <P><LI>To set when the user's password expires, include the
84 <B>-pwexpires</B> argument.
85 <P><LI>To set whether the user can reuse any of the previous twenty passwords
86 when creating a new one, include the <B>-reuse</B> argument.
87 <P><LI>To set the maximum number of times the user can provide an incorrect
88 password before the Authentication Server refuses to accept any more attempts
89 (locks the issuer out), include the <B>-attempts</B> argument.
90 After the sixth failed authentication attempt, the Authentication Server logs
91 a message in the UNIX system log file (the <B>syslog</B> file or
92 equivalent, for which the standard location varies depending on the operating
94 <P><LI>To set how long the Authentication Server refuses to process
95 authentication attempts for a locked-out user, set the <B>-locktime</B>
98 <P>The <B>kas examine</B> command displays the settings made with this
100 <P><STRONG>Cautions</STRONG>
101 <P>The password lifetime set with the <B>-pwexpires</B> argument begins at
102 the time the user's password was last changed, rather than when this
103 command is issued. It can therefore be retroactive. If, for
104 example, a user changed her password 100 days ago and the password lifetime is
105 set to 100 days or less, the password effectively expires immediately.
106 To avoid retroactive expiration, instruct the user to change the password just
107 before setting a password lifetime.
108 <P>Administrators whose authentication accounts have the <TT>ADMIN</TT> flag
109 enjoy complete access to the sensitive information in the Authentication
110 Database. To prevent access by unauthorized users, use the
111 <B>-attempts</B> argument to impose a fairly strict limit on the number of
112 times that a user obtaining administrative tokens can provide an incorrect
113 password. Note, however, that there must be more than one account in
114 the cell with the <TT>ADMIN</TT> flag. The <B>kas unlock</B>
115 command requires the <TT>ADMIN</TT> privilege, so it is important that the
116 locked-out administrator (or a colleague) can access another
117 <TT>ADMIN</TT>-privileged account to unlock the current account.
118 <P>In certain circumstances, the mechanism used to enforce the number of
119 failed authentication attempts can cause a lockout even though the number of
120 failed attempts is less than the limit set by the <B>-attempts</B>
121 argument. Client-side authentication programs such as <B>klog</B>
122 and an AFS-modified login utility normally choose an Authentication Server at
123 random for each authentication attempt, and in case of a failure are likely to
124 choose a different Authentication Server for the next attempt. The
125 Authentication Servers running on the various database server machines do not
126 communicate with each other about how many times a user has failed to provide
127 the correct password to them. Instead, each Authentication Server
128 maintains its own separate copy of the auxiliary database file
129 <B>kaserverauxdb</B> (located in the <B>/usr/afs/local</B> directory
130 by default), which records the number of consecutive authentication failures
131 for each user account and the time of the most recent failure. This
132 implementation means that on average each Authentication Server knows about
133 only a fraction of the total number of failed attempts. The only way to
134 avoid allowing more than the number of attempts set by the
135 <B>-attempts</B> argument is to have each Authentication Server allow only
136 some fraction of the total. More specifically, if the limit on failed
137 attempts is <I>f</I>, and the number of Authentication Servers is
138 <I>S</I>, then each Authentication Server can only permit a number of
139 attempts equal to <I>f</I> divided by <I>S</I> (the Ubik
140 synchronization site for the Authentication Server tracks any remainder,
142 <P>Normally, this implementation does not reduce the number of allowed
143 attempts to less than the configured limit (<I>f</I>). If one
144 Authentication Server refuses an attempt, the client contacts another instance
145 of the server, continuing until either it successfully authenticates or has
146 contacted all of the servers. However, if one or more of the
147 Authentication Server processes is unavailable, the limit is effectively
148 reduced by a percentage equal to the quantity <I>U</I> divided by
149 <I>S</I>, where <I>U</I> is the number of unavailable servers and
150 <I>S</I> is the number normally available.
151 <P>To avoid the undesirable consequences of setting a limit on failed
152 authentication attempts, note the following recommendations:
154 <P><LI>Do not set the <B>-attempts</B> argument (the limit on failed
155 authentication attempts) too low. A limit of nine failed attempts is
156 recommended for regular user accounts, to allow three failed attempts per
157 Authentication Server in a cell with three database server machines.
158 <P><LI>Set fairly short lockout times when including the <B>-locktime</B>
159 argument. Although guessing passwords is a common method of attack, it
160 is not a very sophisticated one. Setting a lockout time can help
161 discourage attackers, but excessively long times are likely to be more of a
162 burden to authorized users than to potential attackers. A lockout time
163 of 25 minutes is recommended for regular user accounts.
164 <P><LI>Do not assign an infinite lockout time on an account (by setting the
165 <B>-locktime</B> argument to <B>0</B> [zero]) unless there is a highly
166 compelling reason. Such accounts almost inevitably become locked at
167 some point, because each Authentication Server never resets the account's
168 failure counter in its copy of the <B>kaauxdb</B> file (in contrast, when
169 the lockout time is not infinite, the counter resets after the specified
170 amount of time has passed since the last failed attempt to that Authentication
171 Server). Furthermore, the only way to unlock an account with an
172 infinite lockout time is for an administrator to issue the <B>kas
173 unlock</B> command. It is especially dangerous to set an infinite
174 lockout time on an administrative account; if all administrative accounts
175 become locked, the only way to unlock them is to shut down all instances of
176 the Authentication Server and remove the <B>kaauxdb</B> file on
179 <P><STRONG>Options</STRONG>
182 </B><DD>Names the Authentication Database account for which to change
185 </B><DD>Sets one or more of four toggling flags, adding them to any flags
186 currently set. Either specify one or more of the following strings, or
187 specify a hexidecimal number that combines the indicated values. To
188 return all four flags to their defaults, provide a value of <B>0</B>
189 (zero). To set more than one flag at once using the strings, connect
190 them with plus signs (example: <B>NOTGS+ADMIN+CPW</B>). To
191 remove all the current flag settings before setting new ones, precede the list
192 with an equal sign (example: <B>=NOTGS+ADMIN+CPW</B>).
195 </B><DD>The user is allowed to issue privileged <B>kas</B> commands
196 (hexadecimal equivalent is <B>0x004</B>, default is
198 <A NAME="IDX5143"></A>
200 </B><DD>The Authentication Server's Ticket Granting Service (TGS) refuses to
201 issue tickets to the user (hexadecimal equivalent is <B>0x008</B>, default
203 <A NAME="IDX5144"></A>
205 </B><DD>The Ticket Granting Service cannot use the contents of this entry's
206 key field as an encryption key (hexadecimal equivalent is <B>0x020</B>,
207 default is <B>SEAL</B>).
208 <A NAME="IDX5145"></A>
210 </B><DD>The user cannot change his or her own password or key (hexadecimal
211 equivalent is <B>0x040</B>, default is <B>CPW</B>).
212 <A NAME="IDX5146"></A>
214 <P><DT><B>-expiration
215 </B><DD>Determines when the entry itself expires. When a user entry
216 expires, the user becomes unable to log in; when a server entry such as
217 <B>afs</B> expires, all server processes that use the associated key
218 become inaccessible. Provide one of the three acceptable values:
221 </B><DD>The account never expires (the default).
222 <P><DT><B><VAR>mm/dd/yyyy</VAR>
223 </B><DD>Sets the expiration date to 12:00 a.m. on the
224 indicated date (month/day/year). Examples: <B>01/23/1999</B>,
226 <P><DT><B>"<VAR>mm/dd/yyyy hh:MM</VAR>"
227 </B><DD>Sets the expiration date to the indicated time (hours:minutes) on
228 the indicated date (month/day/year). Specify the time in 24-hour format
229 (for example, <B>20:30</B> is 8:30 p.m.) Date
230 format is the same as for a date alone. Surround the entire instance
231 with quotes because it contains a space. Examples:
232 <B>"01/23/1999 22:30"</B>, <B>"10/07/2000
236 <P>Acceptable values for the year range from <B>1970</B> (1 January 1970
237 is time 0 in the standard UNIX date representation) through <B>2037</B>
238 (2037 is the maximum because the UNIX representation cannot accommodate dates
239 later than a value in February 2038).
241 </B><DD>Specifies the maximum lifetime that the Authentication Server's
242 Ticket Granting Service (TGS) can assign to a ticket. If the account
243 belongs to a user, this value is the maximum lifetime of a token issued to the
244 user. If the account corresponds to a server such as <B>afs</B>,
245 this value is the maximum lifetime of a ticket that the TGS issues to clients
246 for presentation to the server during mutual authentication.
247 <P>Specify an integer that represents a number of seconds (<B>3600</B>
248 equals one hour), or include a colon in the number to indicate a number of
249 hours and minutes (<B>10:00</B> equals 10 hours). If this
250 argument is omitted, the default setting is 100:00 hours (360000
253 </B><DD>Sets the number of days after the user's password was last changed
254 that it remains valid. Provide an integer from the range <B>1</B>
255 through <B>254</B> to specify the number of days until expiration, or the
256 value <B>0</B> to indicate that the password never expires (the
258 <P>When the password expires, the user is unable to authenticate, but has 30
259 days after the expiration date in which to use the <B>kpasswd</B> command
260 to change the password (after that, only an administrator can change it by
261 using the <B>kas setpassword</B> command). Note that the clock
262 starts at the time the password was last changed, not when the <B>kas
263 setfields</B> command is issued. To avoid retroactive expiration,
264 have the user change the password just before issuing a command that includes
267 </B><DD>Specifies whether or not the user can reuse any of his or her last 20
268 passwords. The acceptable values are <B>yes</B> to allow reuse of
269 old passwords (the default) and <B>no</B> to prohibit reuse of a password
270 that is similar to one of the previous 20 passwords.
272 </B><DD>Sets the number of consecutive times the user can provide an incorrect
273 password during authentication (using the <B>klog</B> command or a login
274 utility that grants AFS tokens). When the user exceeds the limit, the
275 Authentication Server rejects further attempts (locks the user out) for the
276 amount of time specified by the <B>-locktime</B> argument. Provide
277 an integer from the range <B>1</B> through <B>254</B> to specify the
278 number of failures allowed, or <B>0</B> to indicate that there is no limit
279 on authentication attempts (the default value).
281 </B><DD>Specifies how long the Authentication Server refuses authentication
282 attempts from a user who has exceeded the failure limit set by the
283 <B>-attempts</B> argument.
284 <P>Specify a number of hours and minutes (<VAR>hh</VAR>:<VAR>mm</VAR>) or
285 minutes only (<VAR>mm</VAR>), from the range <B>01</B> (one minute) through
286 <B>36:00</B> (36 hours). The <B>kas</B> command
287 interpreter automatically reduces any larger value to <B>36:00</B>
288 and also rounds up any non-zero value to the next higher multiple of
289 8.5 minutes. A value of <B>0</B> (zero) sets an infinite
290 lockout time; an administrator must issue the <B>kas unlock</B>
291 command to unlock the account.
292 <P><DT><B>-admin_username
293 </B><DD>Specifies the user identity under which to authenticate with the
294 Authentication Server for execution of the command. For more details,
295 see the introductory <B>kas</B> reference page.
296 <P><DT><B>-password_for_admin
297 </B><DD>Specifies the password of the command's issuer. If it is
298 omitted (as recommended), the <B>kas</B> command interpreter prompts for
299 it and does not echo it visibly. For more details, see the introductory
300 <B>kas</B> reference page.
302 </B><DD>Names the cell in which to run the command. For more details, see
303 the introductory <B>kas</B> reference page.
305 </B><DD>Names each machine running an Authentication Server with which to
306 establish a connection. For more details, see the introductory
307 <B>kas</B> reference page.
309 </B><DD>Assigns the unprivileged identity <B>anonymous</B> to the
310 issuer. For more details, see the introductory <B>kas</B> reference
313 </B><DD>Prints the online help for this command. All other valid options
316 <P><STRONG>Examples</STRONG>
317 <P>In the following example, an administrator using the <B>admin</B>
318 account grants administrative privilege to the user <B>smith</B>, and sets
319 the Authentication Database entry to expire at midnight on 31 December
321 <PRE> %<B> kas setfields -name smith -flags ADMIN -expiration 12/31/2000</B>
322 Password for admin:
325 <P>In the following example, an administrator using the <B>admin</B>
326 account sets the user <B>pat</B>'s password to expire in 60 days from
327 when it last changed, and prohibits reuse of passwords.
328 <PRE> %<B> kas setfields -name pat -pwexpires 60 -reuse no</B>
329 Password for admin:
332 <P><STRONG>Privilege Required</STRONG>
333 <P>The issuer must have the <TT>ADMIN</TT> flag set on his or her
334 Authentication Database entry.
335 <P><STRONG>Related Information</STRONG>
336 <P><A HREF="auarf046.htm#HDRKASERVERAUXDB">kaserverauxdb</A>
337 <P><A HREF="auarf181.htm#HDRKAS_INTRO">kas</A>
338 <P><A HREF="auarf185.htm#HDRKAS_EXAMINE">kas examine</A>
339 <P><A HREF="auarf194.htm#HDRKAS_SETPASSWORD">kas setpassword</A>
340 <P><A HREF="auarf197.htm#HDRKAS_UNLOCK">kas unlock</A>
341 <P><A HREF="auarf200.htm#HDRKLOG">klog</A>
342 <P><A HREF="auarf202.htm#HDRKPASSWD">kpasswd</A>
344 <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="auarf192.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="auarf194.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>
345 <!-- Begin Footer Records ========================================== -->
347 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
349 <!-- End Footer Records ============================================ -->
350 <A NAME="Bot_Of_Page"></A>
git://git.openafs.org / openafs.git / blob