1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ491">
3 <title>Administering User Accounts</title>
6 <primary>administering</primary>
8 <secondary>user accounts</secondary>
11 <para>This chapter explains how to create and maintain user accounts in your cell.</para>
13 <para>The preferred method for creating user accounts is the <emphasis role="bold">uss</emphasis> program, which enables you to
14 create multiple accounts with a single command. See <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss
15 Command Suite</link>. If you prefer to create each account component individually, follow the instructions in <link
16 linkend="HDRWQ502">Creating AFS User Accounts</link>.</para>
19 <title>Summary of Instructions</title>
21 <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
23 <informaltable frame="none">
25 <colspec colwidth="57*" />
27 <colspec colwidth="43*" />
31 <entry>Create Protection Database entry</entry>
33 <entry><emphasis role="bold">pts createuser</emphasis></entry>
37 <entry>Create Authentication Database entry</entry>
39 <entry><emphasis role="bold">kas create</emphasis></entry>
43 <entry>Create volume</entry>
45 <entry><emphasis role="bold">vos create</emphasis></entry>
49 <entry>Mount volume</entry>
51 <entry><emphasis role="bold">fs mkmount</emphasis></entry>
55 <entry>Create entry on ACL</entry>
57 <entry><emphasis role="bold">fs setacl</emphasis></entry>
61 <entry>Examine Protection Database entry</entry>
63 <entry><emphasis role="bold">pts examine</emphasis></entry>
67 <entry>Change directory ownership</entry>
69 <entry><emphasis role="bold">/etc/chown</emphasis></entry>
73 <entry>Limit failed authentication attempts</entry>
75 <entry><emphasis role="bold">kas setfields</emphasis> with <emphasis role="bold">-attempts</emphasis> and <emphasis
76 role="bold">-locktime</emphasis></entry>
80 <entry>Unlock Authentication Database entry</entry>
82 <entry><emphasis role="bold">kas unlock</emphasis></entry>
86 <entry>Set password lifetime</entry>
88 <entry><emphasis role="bold">kas setfields</emphasis> with <emphasis role="bold">-pwexpires</emphasis></entry>
92 <entry>Prohibit password reuse</entry>
94 <entry><emphasis role="bold">kas setfields</emphasis> with <emphasis role="bold">-reuse</emphasis></entry>
98 <entry>Change AFS password</entry>
100 <entry><emphasis role="bold">kas setpassword</emphasis></entry>
104 <entry>List groups owned by user</entry>
106 <entry><emphasis role="bold">pts listowned</emphasis></entry>
110 <entry>Rename Protection Database entry</entry>
112 <entry><emphasis role="bold">pts rename</emphasis></entry>
116 <entry>Delete Authentication Database entry</entry>
118 <entry><emphasis role="bold">kas delete</emphasis></entry>
122 <entry>Rename volume</entry>
124 <entry><emphasis role="bold">vos rename</emphasis></entry>
128 <entry>Remove mount point</entry>
130 <entry><emphasis role="bold">fs rmmount</emphasis></entry>
134 <entry>Delete Protection Database entry</entry>
136 <entry><emphasis role="bold">pts delete</emphasis></entry>
140 <entry>List volume location</entry>
142 <entry><emphasis role="bold">vos listvldb</emphasis></entry>
146 <entry>Remove volume</entry>
148 <entry><emphasis role="bold">vos remove</emphasis></entry>
155 <primary>local password file</primary>
157 <secondary>creating entry for AFS user</secondary>
159 <tertiary>with manual account creation</tertiary>
163 <sect1 id="HDRWQ494">
164 <title>The Components of an AFS User Account</title>
166 <para>The differences between AFS and the UNIX file system imply that a complete AFS user account is not the same as a UNIX user
167 account. The following list describes the components of an AFS account. The same information appears in a corresponding section
168 of <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>, but is repeated here for your
169 convenience. <itemizedlist>
171 <para>A <emphasis>Protection Database entry</emphasis> defines the username (the name provided when authenticating with
172 AFS), and maps it to an AFS user ID (AFS UID), a number that the AFS servers use internally when referencing users. The
173 Protection Database also tracks the groups to which the user belongs. For details, see <link
174 linkend="HDRWQ531">Administering the Protection Database</link>.</para>
178 <para>An <emphasis>Authentication Database entry</emphasis> records the user's AFS password in a scrambled form suitable
179 for use as an encryption key.</para>
183 <para>A home <emphasis>volume</emphasis> stores all the files in the user's home directory together on a single partition
184 of a file server machine. The volume has an associated quota that limits its size. For a complete discussion of volumes,
185 see <link linkend="HDRWQ174">Managing Volumes</link>.</para>
189 <para>A <emphasis>mount point</emphasis> makes the contents of the user's volume visible and accessible in the AFS
190 filespace, and acts as the user's home directory. For more details about mount points, see <link linkend="HDRWQ183">About
191 Mounting Volumes</link>.</para>
195 <para>Full access permissions on the home directory's <emphasis>access control list (ACL)</emphasis> and ownership of the
196 directory (as displayed by the UNIX <emphasis role="bold">ls -ld</emphasis> command) enable the user to manage his or her
197 files. For details on AFS file protection, see <link linkend="HDRWQ562">Managing Access Control Lists</link>.</para>
201 <para>A <emphasis>local password file entry</emphasis> (in the <emphasis role="bold">/etc/passwd</emphasis> file or
202 equivalent) of each AFS client machine enables the user to log in and access AFS files through the Cache Manager. A
203 subsequent section in this chapter further discusses local password file entries.</para>
207 <para>Other optional <emphasis>configuration files</emphasis> make the account more convenient to use. Such files help the
208 user log in and log out more easily, receive electronic mail, print, and so on.</para>
210 </itemizedlist></para>
213 <primary>AFS UID</primary>
215 <secondary>matching with UNIX UID</secondary>
219 <primary>UNIX UID</primary>
221 <secondary>matching with AFS UID</secondary>
225 <sect1 id="HDRWQ495">
226 <title>Creating Local Password File Entries</title>
228 <para>To obtain authenticated access to a cell's AFS filespace, a user must not only have a valid AFS token, but also an entry
229 in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of the machine whose Cache Manager is
230 representing the user. This section discusses why it is important for the user's AFS UID to match to the UNIX UID listed in the
231 local password file, and describes the appropriate value to put in the file's password field.</para>
233 <para>One reason to use <emphasis role="bold">uss</emphasis> commands is that they enable you to generate local password file
234 entries automatically as part of account creation. See <link linkend="HDRWQ458">Creating a Common Source Password
237 <para>Information similar to the information in this section appears in a corresponding section of <link
238 linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>, but is repeated here for your
241 <sect2 id="HDRWQ496">
242 <title>Assigning AFS and UNIX UIDs that Match</title>
244 <para>A user account is easiest to administer and use if the AFS user ID number (AFS UID) and UNIX UID match. All instructions
245 in the AFS documentation assume that they do.</para>
247 <para>The most basic reason to make AFS and UNIX UIDs the same is so that the owner name reported by the UNIX <emphasis
248 role="bold">ls -l</emphasis> and <emphasis role="bold">ls -ld</emphasis> commands makes sense for AFS files and directories.
249 Following standard UNIX practice, the File Server records a number rather than a username in an AFS file or directory's owner
250 field: the owner's AFS UID. When you issue the <emphasis role="bold">ls -l</emphasis> command, it translates the UID to a
251 username according to the mapping in the local password file, not the AFS Protection Database. If the AFS and UNIX UIDs do not
252 match, the <emphasis role="bold">ls -l</emphasis> command reports an unexpected (and incorrect) owner. The output can even
253 vary on different client machines if their local password files map the same UNIX UID to different names.</para>
255 <para>Follow the recommendations in the indicated sections to make AFS and UNIX UIDs match when creating accounts for various
256 types of users: <itemizedlist>
258 <para>If creating an AFS account for a user who already has a UNIX UID, see <link linkend="HDRWQ499">Making UNIX and AFS
259 UIDs Match</link>.</para>
263 <para>If some users in your cell have existing UNIX accounts but the user for whom you are creating an AFS account does
264 not, then it is best to allow the Protection Server to allocate an AFS UID automatically. To avoid overlap of AFS UIDs
265 with existing UNIX UIDs, set the Protection Database's <computeroutput>max user id</computeroutput> counter higher than
266 the largest UNIX UID, using the instructions in <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID
267 Counters</link>.</para>
271 <para>If none of your users have existing UNIX accounts, allow the Protection Server to allocate AFS UIDs automatically,
272 starting either at its default or at the value you have set for the <computeroutput>max user id</computeroutput>
275 </itemizedlist></para>
278 <primary>password</primary>
280 <secondary>setting in local password file</secondary>
282 <tertiary>with manual account creation</tertiary>
286 <primary>local password file</primary>
288 <secondary>setting password in</secondary>
290 <tertiary>with manual account creation</tertiary>
294 <sect2 id="HDRWQ497">
295 <title>Specifying Passwords in the Local Password File</title>
297 <para>Authenticating with AFS is easiest for your users if you install and configure an AFS-modified login utility, which logs
298 a user into the local file system and obtains an AFS token in one step. In this case, the local password file no longer
299 controls a user's ability to login in most circumstances, because the AFS-modified login utility does not consult the local
300 password file if the user provides the correct AFS password. You can nonetheless use a password file entry's password field
301 (usually, the second field) in the following ways to control login and authentication: <itemizedlist>
303 <para>To prevent both local login and AFS authentication, place an asterisk ( * ) in the field. This is useful mainly in
304 emergencies, when you want to prevent a certain user from logging into the machine.</para>
308 <para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
309 string of any length other than the standard thirteen characters in the field. This is appropriate if you want to allow
310 only people with local AFS accounts to log into to your machines. A single <emphasis role="bold">X</emphasis> or other
311 character is the most easily recognizable way to do this.</para>
315 <para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
316 standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
317 role="bold">passwd</emphasis> or equivalent).</para>
319 </itemizedlist></para>
321 <para>If you do not use an AFS-modified login utility, you must place a standard UNIX password in the local password file of
322 every client machine the user will use. The user logs into the local file system only, and then must issue the <emphasis
323 role="bold">klog</emphasis> command to authenticate with AFS. It is simplest if the passwords in the local password file and
324 the Authentication Database are the same, but this is not required. <indexterm>
325 <primary>converting</primary>
327 <secondary>existing UNIX accounts to AFS accounts</secondary>
329 <tertiary>with manual account creation</tertiary>
330 </indexterm> <indexterm>
331 <primary>user account</primary>
333 <secondary>converting existing UNIX to AFS</secondary>
335 <tertiary>with manual account creation</tertiary>
340 <sect1 id="HDRWQ498">
341 <title>Converting Existing UNIX Accounts</title>
343 <para>This section discusses the three main issues you need to consider if your cell has existing UNIX accounts that you wish to
344 convert to AFS accounts.</para>
346 <sect2 id="HDRWQ499">
347 <title>Making UNIX and AFS UIDs Match</title>
349 <para>As previously mentioned, AFS users must have an entry in the local password file on every client machine from which they
350 access the AFS filespace as an authenticated user. Both administration and use are much simpler if the UNIX UID and AFS UID
351 match. When converting existing UNIX accounts, you have two alternatives: <itemizedlist>
353 <para>Make the AFS UIDs match the existing UNIX UIDs. In this case, you need to assign the AFS UID yourself by including
354 the <emphasis role="bold">-id</emphasis> argument to the <emphasis role="bold">pts createuser</emphasis> command as you
355 create the AFS account.</para>
357 <para>Because you are retaining the user's UNIX UID, you do not need to alter the UID in the local password file entry.
358 However, if you are using an AFS-modified login utility, you possibly need to change the password field in the entry.
359 For a discussion of how the value in the password field affects login with an AFS-modified login utility, see <link
360 linkend="HDRWQ497">Specifying Passwords in the Local Password File</link>.</para>
362 <para>If now or in the future you need to create AFS accounts for users who do not have an existing UNIX UID, then you
363 must guarantee that new AFS UIDs do not conflict with any existing UNIX UIDs. The simplest way is to set the
364 <computeroutput>max user id</computeroutput> counter in the Protection Database to a value higher than the largest
365 existing UNIX UID. See <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID Counters</link>.</para>
369 <para>Change the existing UNIX UIDs to match the new AFS UIDs that the Protection Server assigns automatically.</para>
371 <para>Allow the Protection Server to allocate the AFS UIDs automatically as you create AFS accounts. You must then alter
372 the user's entry in the local password file on every client machine to include the new UID.</para>
374 <para>There is one drawback to changing the UNIX UID: any files and directories that the user owned in the local file
375 system before becoming an AFS user still have the former UID in their owner field. If you want the <emphasis
376 role="bold">ls -l</emphasis> and <emphasis role="bold">ls -ld</emphasis> commands to display the correct owner, you must
377 use the <emphasis role="bold">chown</emphasis> command to change the value to the user's new UID, whether you are
378 leaving the file in the local file system or moving it to AFS. See <link linkend="HDRWQ501">Moving Local Files into
381 </itemizedlist></para>
384 <sect2 id="HDRWQ500">
385 <title>Setting the Password Field Appropriately</title>
387 <para>Existing UNIX accounts already have an entry in the local password file, probably with a (scrambled) password in the
388 password field. You possibly need to change the value in the field, depending on the type of login utility you use:
391 <para>If the login utility is not modified for use with AFS, the actual password must appear (in scrambled form) in the
392 local password file entry.</para>
396 <para>If the login utility is modified for use with AFS, choose one of the values discussed in <link
397 linkend="HDRWQ497">Specifying Passwords in the Local Password File</link>.</para>
399 </itemizedlist></para>
402 <sect2 id="HDRWQ501">
403 <title>Moving Local Files into AFS</title>
405 <para>New AFS users with existing UNIX accounts probably already own files and directories stored in a machine's local file
406 system, and it usually makes sense to transfer them into the new home volume. The easiest method is to move them onto the
407 local disk of an AFS client machine, and then use the UNIX <emphasis role="bold">mv</emphasis> command to transfer them into
408 the user's new AFS home directory.</para>
410 <para>As you move files and directories into AFS, keep in mind that the meaning of their mode bits changes. AFS ignores the
411 second and third sets of mode bits (group and other), and does not use the first set (the owner bits) directly, but only in
412 conjunction with entries on the ACL (for details, see <link linkend="HDRWQ580">How AFS Interprets the UNIX Mode Bits</link>).
413 Be sure that the ACL protects the file or directory at least as securely as the mode bits.</para>
415 <para>If you have chosen to change a user's UNIX UID to match a new AFS UID, you must change the ownership of UNIX files and
416 directories as well. Only members of the <emphasis role="bold">system:administrators</emphasis> group can issue the <emphasis
417 role="bold">chown</emphasis> command on files and directories once they reside in AFS.</para>
421 <sect1 id="HDRWQ502">
422 <title>Creating AFS User Accounts</title>
424 <para>There are two methods for creating user accounts. The preferred method--using the <emphasis role="bold">uss</emphasis>
425 commands--enables you to create multiple accounts with a single command. It uses a template to define standard values for the
426 account components that are the same for each user (such as quota), but provide differing values for more variable components
427 (such as username). See <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>.</para>
429 <para>The second method involves issuing a separate command to create each component of the account. It is best suited to
430 creation of one account at a time, since some of the commands can create only one instance of the relevant component. To review
431 the function of each component, see <link linkend="HDRWQ494">The Components of an AFS User Account</link>.</para>
433 <para>Use the following instructions to create any of the three types of user account, which differ in their levels of
434 functionality. For a description of the types, see <link linkend="HDRWQ57">Configuring AFS User Accounts</link>. <itemizedlist>
436 <para>To create an authentication-only account, perform Step <link linkend="LIWQ504">1</link> through Step <link
437 linkend="LIWQ507">4</link> and also Step <link linkend="LIWQ514">14</link>. This type of account consists only of entries
438 in the Authentication Database and Protection Database.</para>
442 <para>To create a basic account, perform Step <link linkend="LIWQ504">1</link> through Step <link
443 linkend="LIWQ510">8</link> and Step <link linkend="LIWQ512">11</link> through Step <link linkend="LIWQ514">14</link>. In
444 addition to Authentication Database and Protection Database entries, this type of account includes a volume mounted at the
445 home directory with owner and ACL set appropriately.</para>
449 <para>To create a full account, perform all steps in the following instructions. This type of account includes
450 configuration files for basic functions such as logging in, printing, and mail delivery, making it more convenient and
451 useful. For a discussion of some useful types of configuration files, see <link linkend="HDRWQ60">Creating Standard Files
452 in New AFS Accounts</link>.</para>
454 </itemizedlist></para>
457 <primary>creating</primary>
459 <secondary>user account</secondary>
461 <tertiary>with individual commands</tertiary>
465 <primary>user account</primary>
467 <secondary>creating</secondary>
469 <tertiary>with individual commands</tertiary>
473 <primary>creating</primary>
475 <secondary>Protection Database user entry</secondary>
477 <tertiary>with pts createuser command</tertiary>
481 <primary>creating</primary>
483 <secondary>Authentication Database entry</secondary>
485 <tertiary>with kas create command</tertiary>
489 <primary>Protection Database</primary>
491 <secondary>user entry</secondary>
493 <tertiary>creating with pts createuser command</tertiary>
497 <primary>Authentication Database</primary>
499 <secondary>entry</secondary>
501 <tertiary>creating with kas create command</tertiary>
505 <primary>username</primary>
507 <secondary>assigning</secondary>
509 <tertiary>with pts createuser command</tertiary>
513 <primary>AFS UID</primary>
515 <secondary>assigning</secondary>
517 <tertiary>with pts createuser command</tertiary>
521 <primary>user</primary>
523 <secondary>AFS UID, assigning</secondary>
527 <primary>assigning</primary>
529 <secondary>AFS UID to user</secondary>
532 <sect2 id="HDRWQ503">
533 <title>To create one user account with individual commands</title>
537 <para><anchor id="LIWQ504" />Decide on the value to assign to each of the following account components. If you are
538 creating an authentication-only account, you need to pick only a username, AFS UID, and initial password. <itemizedlist>
540 <para>The username. By convention, the names of many components of the user account incorporate this name. For a
541 discussion of restrictions and suggested naming schemes, see <link linkend="HDRWQ58">Choosing Usernames and Naming
542 Other Account Components</link>.</para>
546 <para>The AFS UID, if you want to assign a specific one. It is generally best to have the Protection Server allocate
547 one instead, except when you are creating an AFS account for a user who already has an existing UNIX account. In
548 that case, migrating the user's files into AFS is simplest if you set the AFS UID to match the existing UNIX UID.
549 See <link linkend="HDRWQ498">Converting Existing UNIX Accounts</link>.</para>
553 <para>The initial password. Advise the user to change this at the first login, using the password changing
554 instructions in the <emphasis>OpenAFS User Guide</emphasis>.</para>
558 <para>The name of the user's home volume. The conventional name is <emphasis role="bold">user.</emphasis>username
559 (for example, <emphasis role="bold">user.smith</emphasis>).</para>
563 <para>The volume's site (disk partition on a file server machine). Some cells designate certain machines or
564 partitions for user volumes only, or it possibly makes sense to place the volume on the emptiest partition that
565 meets your other criteria. To display the size and available space on a partition, use the <emphasis role="bold">vos
566 partinfo</emphasis> command, which is fully described in <link linkend="HDRWQ185">Creating Read/write
567 Volumes</link>.</para>
571 <para>The name of the user's home directory (the mount point for the home volume). The conventional location is a
572 directory (or one of a set of directories) directly under the cell directory, such as <emphasis
573 role="bold">/afs/</emphasis>cellname<emphasis role="bold">/usr</emphasis>. For suggestions on how to avoid the
574 slowed directory lookup that can result from having large numbers of user home directories in a single <emphasis
575 role="bold">usr</emphasis> directory, see <link linkend="HDRWQ472">Evenly Distributing User Home Directories with
576 the G Instruction</link>.</para>
580 <para>The volume's space quota. Include the <emphasis role="bold">-maxquota</emphasis> argument to the <emphasis
581 role="bold">vos create</emphasis> command, or accept the default quota of 5000 KB.</para>
585 <para>The ACL on the home directory. By default, the ACL on every new volume grants all seven permissions to the
586 <emphasis role="bold">system:administrators</emphasis> group. After volume creation, use the <emphasis
587 role="bold">fs setacl</emphasis> command to remove the entry if desired, and to grant all seven permissions to the
590 </itemizedlist></para>
594 <para><anchor id="LIWQ505" />Authenticate as an AFS identity with all of the following privileges. In the conventional
595 configuration, the <emphasis role="bold">admin</emphasis> user account has them, or you possibly have a personal
596 administrative account. (To increase cell security, it is best to create special privileged accounts for use only while
597 performing administrative procedures; for further discussion, see <link linkend="HDRWQ584">An Overview of Administrative
598 Privilege</link>.) If necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
599 % <emphasis role="bold">klog</emphasis> admin_user
600 Password: <<replaceable>admin_password</replaceable>>
601 </programlisting></para>
603 <para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>
607 <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
608 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
609 display the members of the system:administrators group</link>. <programlisting>
610 % <emphasis role="bold">pts membership system:administrators</emphasis>
611 </programlisting></para>
615 <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
616 role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
617 users in the UserList file</link>. <programlisting>
618 % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>>
619 </programlisting></para>
623 <para>The <computeroutput>ADMIN</computeroutput> flag on your Authentication Database entry. However, the
624 Authentication Server performs its own authentication, so in Step <link linkend="LIWQ507">4</link> you specify an
625 administrative identity on the <emphasis role="bold">kas</emphasis> command line itself.</para>
629 <para>The <emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) and <emphasis
630 role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where
631 you are mounting the user's volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which
632 is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
633 % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>]
634 </programlisting></para>
636 <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
637 role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
638 role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
639 role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
643 <para>Knowledge of the password for the local superuser <emphasis role="bold">root</emphasis>.</para>
648 <primary>pts commands</primary>
650 <secondary>createuser</secondary>
652 <tertiary>user account</tertiary>
656 <primary>commands</primary>
658 <secondary>pts createuser</secondary>
660 <tertiary>user account</tertiary>
665 <para><anchor id="LIWQ506" />Issue the <emphasis role="bold">pts createuser</emphasis> command to create an entry in the
666 Protection Database. For a discussion of setting AFS UIDs, see <link linkend="HDRWQ496">Assigning AFS and UNIX UIDs that
667 Match</link>. If you are converting an existing UNIX account into an AFS account, also see <link
668 linkend="HDRWQ498">Converting Existing UNIX Accounts</link>. <programlisting>
669 % <emphasis role="bold">pts createuser</emphasis> <<replaceable>user name</replaceable>> [<<replaceable>user id</replaceable>>]
670 </programlisting></para>
676 <term><emphasis role="bold">cu</emphasis></term>
679 <para>Is an acceptable alias for <emphasis role="bold">createuser</emphasis> (and <emphasis
680 role="bold">createu</emphasis> is the shortest acceptable abbreviation).</para>
685 <term><emphasis role="bold">user name</emphasis></term>
688 <para>Specifies the user's username (the character string typed at login). It is best to limit the name to eight or
689 fewer lowercase letters, because many application programs impose that limit. The AFS servers themselves accept
690 names of up to 63 lowercase letters. Also avoid the following characters: colon (<emphasis
691 role="bold">:</emphasis>), semicolon (<emphasis role="bold">;</emphasis>), comma (<emphasis
692 role="bold">,</emphasis>), at sign (<emphasis role="bold">@</emphasis>), space, newline, and the period (<emphasis
693 role="bold">.</emphasis>), which is conventionally used only in special administrative names.</para>
698 <term><emphasis role="bold">user id</emphasis></term>
701 <para>Is optional and appropriate only if the user already has a UNIX UID that the AFS UID must match. If you do not
702 provide this argument, the Protection Server assigns one automatically based on the counter described in <link
703 linkend="HDRWQ560">Displaying and Setting the AFS UID and GID Counters</link>. If the ID you specify is less than
704 <emphasis role="bold">1</emphasis> (one) or is already in use, an error results.</para>
710 <primary>kas commands</primary>
712 <secondary>create</secondary>
716 <primary>commands</primary>
718 <secondary>kas create</secondary>
723 <para><anchor id="LIWQ507" />Issue the <emphasis role="bold">kas create</emphasis> command to create an entry in the
724 Authentication Database. To avoid having the user's temporary initial password echo visibly on the screen, omit the
725 <emphasis role="bold">-initial_password</emphasis> argument; instead enter the password at the prompts that appear when
726 you omit the argument, as shown in the following syntax specification.</para>
728 <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
729 it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
730 Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
731 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
732 issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
733 ADMIN flag is set</link>.</para>
736 % <emphasis role="bold">kas create</emphasis> <<replaceable>name of user</replaceable>> \
737 <emphasis role="bold">-admin</emphasis> <<replaceable>admin principal to use for authentication</replaceable>>
738 Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
739 initial_password: <<replaceable>initial_password</replaceable>>
740 Verifying, please re-enter initial_password: <<replaceable>initial_password</replaceable>>
743 <para>where <variablelist>
745 <term><emphasis role="bold">cr</emphasis></term>
748 <para>Is the shortest acceptable abbreviation for <emphasis role="bold">create</emphasis>.</para>
753 <term><emphasis role="bold">name of user</emphasis></term>
756 <para>Specifies the same username as in Step <link linkend="LIWQ506">3</link>.</para>
761 <term><emphasis role="bold">-admin</emphasis></term>
764 <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
765 Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
766 admin_user. Enter the appropriate password as admin_password.</para>
771 <term><emphasis role="bold">initial_password</emphasis></term>
774 <para>Specifies the initial password as a string of eight characters or less, to comply with the length
775 restriction that some applications impose. Possible choices for an initial password include the username, a string
776 of digits from a personal identification number such as the Social Security number, or a standard string such as
777 <emphasis role="bold">changeme</emphasis>. Instruct the user to change the string to a truly secret password as
778 soon as possible by using the <emphasis role="bold">kpasswd</emphasis> command as described in the <emphasis>IBM
779 AFS User Guide</emphasis>.</para>
782 </variablelist></para>
785 <primary>vos commands</primary>
787 <secondary>create</secondary>
789 <tertiary>when creating user account</tertiary>
793 <primary>commands</primary>
795 <secondary>vos create</secondary>
797 <tertiary>when creating user account</tertiary>
802 <para><anchor id="LIWQ508" />Issue the <emphasis role="bold">vos create</emphasis> command to create the user's volume.
804 % <emphasis role="bold">vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <<replaceable>volume name</replaceable>> \
805 [<emphasis role="bold">-maxquota</emphasis> <<replaceable>initial quota (KB)</replaceable>>]
806 </programlisting></para>
812 <term><emphasis role="bold">cr</emphasis></term>
815 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">create</emphasis>.</para>
820 <term><emphasis role="bold">machine name</emphasis></term>
823 <para>Names the file server machine on which to place the new volume.</para>
828 <term><emphasis role="bold">partition name</emphasis></term>
831 <para>Names the partition on which to place the new volume.</para>
836 <term><emphasis role="bold">volume name</emphasis></term>
839 <para>Names the new volume. The name can include up to 22 characters. By convention, user volume names have the form
840 <emphasis role="bold">user.</emphasis>username, where username is the name assigned in Step <link
841 linkend="LIWQ506">3</link>.</para>
846 <term><emphasis role="bold">-maxquota</emphasis></term>
849 <para>Sets the volume's quota, as a number of kilobyte blocks. If you omit this argument, the default is 5000
856 <primary>fs commands</primary>
858 <secondary>mkmount</secondary>
860 <tertiary>when creating user account</tertiary>
864 <primary>commands</primary>
866 <secondary>fs mkmount</secondary>
868 <tertiary>when creating user account</tertiary>
873 <para><anchor id="LIWQ509" />Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the volume in the
874 filespace and create the user's home directory. <programlisting>
875 % <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>>
876 </programlisting></para>
882 <term><emphasis role="bold">mk</emphasis></term>
885 <para>Is the shortest acceptable abbreviation for <emphasis role="bold">mkmount</emphasis>.</para>
890 <term><emphasis role="bold">directory</emphasis></term>
893 <para>Names the mount point to create. A directory of the same name must not already exist. Partial pathnames are
894 interpreted relative to the current working directory. By convention, user home directories are mounted in a
895 directory called something like <emphasis role="bold">/afs/.</emphasis>cellname<emphasis
896 role="bold">/usr</emphasis>, and the home directory name matches the username assigned in Step <link
897 linkend="LIWQ506">3</link>.</para>
899 <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create
900 the new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period
901 before the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>).
902 For further discussion of the concept of read/write and read-only paths through the filespace, see <link
903 linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para>
908 <term><emphasis role="bold">volume name</emphasis></term>
911 <para>Is the name of the volume created in Step <link linkend="LIWQ508">5</link>.</para>
918 <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs setvol</emphasis> command with the
919 <emphasis role="bold">-offlinemsg</emphasis> argument to record auxiliary information about the volume in its volume
920 header. For example, you can record who owns the volume or where you have mounted it in the filespace. To display the
921 information, use the <emphasis role="bold">fs examine</emphasis> command. <programlisting>
922 % <emphasis role="bold">fs setvol</emphasis> <<replaceable>dir/file path</replaceable>> <emphasis role="bold">-offlinemsg</emphasis> <<replaceable>offline message</replaceable>>
923 </programlisting></para>
929 <term><emphasis role="bold">sv</emphasis></term>
932 <para>Is an acceptable alias for <emphasis role="bold">setvol</emphasis> (and <emphasis role="bold">setv</emphasis>
933 the shortest acceptable abbreviation).</para>
938 <term><emphasis role="bold">dir/file path</emphasis></term>
941 <para>Names the mount point of the volume with which to associate the message. Partial pathnames are interpreted
942 relative to the current working directory.</para>
944 <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to change a
945 read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
946 pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). For further discussion of the
947 concept of read/write and read-only paths through the filespace, see <link linkend="HDRWQ209">The Rules of Mount
948 Point Traversal</link>.</para>
953 <term><emphasis role="bold">-offlinemsg</emphasis></term>
956 <para>Specifies up to 128 characters of auxiliary information to record in the volume header.</para>
963 <para><anchor id="LIWQ510" />Issue the <emphasis role="bold">fs setacl</emphasis> command to set the ACL on the new home
964 directory. At the least, create an entry that grants all permissions to the user, as shown.</para>
966 <para>You can also use the command to edit or remove the entry that the <emphasis role="bold">vos create</emphasis>
967 command automatically places on the ACL for a new volume's root directory, which grants all permissions to the <emphasis
968 role="bold">system:administrators</emphasis> group. Keep in mind that even if you remove the entry, the members of the
969 group by default have implicit <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by
970 default <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions on every ACL, and can
971 grant themselves other permissions as required.</para>
973 <para>For detailed instructions for the <emphasis role="bold">fs setacl</emphasis> command, see <link
974 linkend="HDRWQ573">Setting ACL Entries</link>.</para>
977 % <emphasis role="bold">fs setacl</emphasis> <<replaceable>directory</replaceable>> <emphasis role="bold">-acl</emphasis> <<replaceable>user name</replaceable>> <emphasis
978 role="bold">all</emphasis> \
979 [<emphasis role="bold">system:administrators</emphasis> desired_permissions]
984 <para><anchor id="LIWQ511" /><emphasis role="bold">(Optional)</emphasis> Create configuration files and subdirectories in
985 the new home directory. Possibilities include <emphasis role="bold">.login</emphasis> and <emphasis
986 role="bold">.logout</emphasis> files, a shell-initialization file such as <emphasis role="bold">.cshrc</emphasis>, files
987 to help with printing and mail delivery, and so on.</para>
989 <para>If you are converting an existing UNIX account into an AFS account, you possibly wish to move some files and
990 directories into the user's new AFS home directory. See <link linkend="HDRWQ498">Converting Existing UNIX
991 Accounts</link>.</para>
995 <para><emphasis role="bold">(Optional)</emphasis> In the new <emphasis role="bold">.login</emphasis> or shell
996 initialization file, define the user's $PATH environment variable to include the directories where AFS binaries are kept
997 (for example, the <emphasis role="bold">/usr/afsws/bin</emphasis> and <emphasis role="bold">/usr/afsws/etc</emphasis>
1002 <para><anchor id="LIWQ512" />In Step <link linkend="LIWQ513">12</link> and Step <link linkend="LIWQ514">14</link>, you
1003 must know the user's AFS UID. If you had the Protection Server assign it in Step <link linkend="LIWQ506">3</link>, you
1004 probably do not know it. If necessary, issue the <emphasis role="bold">pts examine</emphasis> command to display it.
1006 % <emphasis role="bold">pts examine</emphasis> <<replaceable>user or group name or id</replaceable>>
1007 </programlisting></para>
1013 <term><emphasis role="bold">e</emphasis></term>
1016 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
1021 <term><emphasis role="bold">user or group name or id</emphasis></term>
1024 <para>Is the username that you assigned in Step <link linkend="LIWQ506">3</link>.</para>
1029 <para>The first line of the output displays the username and AFS UID. For further discussion and an example of the output,
1030 see <link linkend="HDRWQ536">Displaying Information from the Protection Database</link>.</para>
1034 <para><anchor id="LIWQ513" />Designate the user as the owner of the home directory and any files and subdirectories
1035 created or moved in Step <link linkend="LIWQ511">9</link>. Specify the owner by the AFS UID you learned in Step <link
1036 linkend="LIWQ512">11</link> rather than by username. This is necessary for new accounts because the user does not yet have
1037 an entry in your local machine's password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent). If you are
1038 converting an existing UNIX account, an entry possibly already exists, but the UID is possibly incorrect. In that case,
1039 specifying a username means that the corresponding (possibly incorrect) UID is recorded as the owner.</para>
1041 <para>Some operating systems allow only the local superuser <emphasis role="bold">root</emphasis> to issue the <emphasis
1042 role="bold">chown</emphasis> command. If necessary, issuing the <emphasis role="bold">su</emphasis> command before the
1043 <emphasis role="bold">chown</emphasis> command.</para>
1046 % <emphasis role="bold">chown</emphasis> new_owner_ID directory
1049 <para>where <variablelist>
1051 <term><emphasis role="bold">new_owner_ID</emphasis></term>
1054 <para>Is the user's AFS UID, which you learned in Step <link linkend="LIWQ512">11</link>.</para>
1059 <term><emphasis role="bold">directory</emphasis></term>
1062 <para>Names the home directory you created in Step <link linkend="LIWQ509">6</link>, plus each subdirectory or
1063 file you created in Step <link linkend="LIWQ511">9</link>.</para>
1066 </variablelist></para>
1070 <para>If the new user home directory resides in a replicated volume, use the <emphasis role="bold">vos release</emphasis>
1071 command to release the volume, as described in <link linkend="HDRWQ194">To replicate a read/write volume (create a
1072 read-only volume)</link>. <programlisting>
1073 % <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>>
1074 </programlisting></para>
1077 <para>This step can be necessary even if the home directory's parent directory is not itself a mount point for a
1078 replicated volume (and is easier to overlook in that case). Suppose, for example, that the ABC Corporation puts the
1079 mount points for user volumes in the <emphasis role="bold">/afs/abc.com/usr</emphasis> directory. Because that is a
1080 regular directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted
1081 at the <emphasis role="bold">/afs/abc.com</emphasis> directory. That volume is replicated, so after changing it by
1082 creating a new mount point the administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>
1087 <para><anchor id="LIWQ514" />Create or modify an entry for the new user in the local password file (<emphasis
1088 role="bold">/etc/passwd</emphasis> or equivalent) of each machine the user can log onto. Remember to make the UNIX UID the
1089 same as the AFS UID you learned in Step <link linkend="LIWQ512">11</link>, and to fill the password field appropriately
1090 (for instructions, see <link linkend="HDRWQ497">Specifying Passwords in the Local Password File</link>).</para>
1092 <para>If you use the <emphasis role="bold">package</emphasis> utility to distribute a common version of the password file
1093 to all client machines, then you need to make the change only in the common version. See <link
1094 linkend="HDRWQ419">Configuring Client Machines with the package Program</link>.</para>
1099 <primary>password</primary>
1101 <secondary>improving security</secondary>
1105 <primary>authentication</primary>
1107 <secondary>improving security</secondary>
1111 <primary>login</primary>
1113 <secondary>limiting failed attempts</secondary>
1117 <primary>klog command</primary>
1119 <secondary>limiting failed attempts</secondary>
1124 <sect1 id="HDRWQ515">
1125 <title>Improving Password and Authentication Security</title>
1127 <para>AFS provides several optional features than can help to protect your cell's filespace against unauthorized access. The
1128 following list summarizes them, and instructions follow. <itemizedlist>
1130 <para>Limit the number of consecutive failed login attempts.</para>
1132 <para>One of the most common ways for an unauthorized user to access your filespace is to guess an authorized user's
1133 password. This method of attack is most dangerous if the attacker can use many login processes in parallel or use the RPC
1134 interfaces directly.</para>
1136 <para>To protect against this type of attack, use the <emphasis role="bold">-attempts</emphasis> argument to the <emphasis
1137 role="bold">kas setfields</emphasis> command to limit the number of times that a user can consecutively fail to enter the
1138 correct password when using either an AFS-modified login utility or the <emphasis role="bold">klog</emphasis> command.
1139 When the limit is exceeded, the Authentication Server locks the user's Authentication Database entry (disallows
1140 authentication attempts) for a period of time that you define with the <emphasis role="bold">-locktime</emphasis> argument
1141 to the <emphasis role="bold">kas setfields</emphasis> command. If desired, system administrators can use the <emphasis
1142 role="bold">kas unlock</emphasis> command to unlock the entry before the complete lockout time passes.</para>
1144 <para>In certain circumstances, the mechanism used to enforce the number of failed authentication attempts can cause a
1145 lockout even though the number of failed attempts is less than the limit set by the <emphasis
1146 role="bold">-attempts</emphasis> argument. Client-side authentication programs such as <emphasis
1147 role="bold">klog</emphasis> and an AFS-modified login utility normally choose an Authentication Server at random for each
1148 authentication attempt, and in case of a failure are likely to choose a different Authentication Server for the next
1149 attempt. The Authentication Servers running on the various database server machines do not communicate with each other
1150 about how many times a user has failed to provide the correct password to them. Instead, each Authentication Server
1151 maintains its own separate copy of the auxiliary database file <emphasis role="bold">kaserverauxdb</emphasis> (located in
1152 the <emphasis role="bold">/usr/afs/local</emphasis> directory by default), which records the number of consecutive
1153 authentication failures for each user account and the time of the most recent failure. This implementation means that on
1154 average each Authentication Server knows about only a fraction of the total number of failed attempts. The only way to
1155 avoid allowing more than the number of attempts set by the <emphasis role="bold">-attempts</emphasis> argument is to have
1156 each Authentication Server allow only some fraction of the total. More specifically, if the limit on failed attempts is
1157 <emphasis>f</emphasis>, and the number of Authentication Servers is <emphasis>S</emphasis>, then each Authentication
1158 Server can only permit a number of attempts equal to <emphasis>f</emphasis> divided by <emphasis>S</emphasis> (the Ubik
1159 synchronization site for the Authentication Server tracks any remainder, <emphasis>f mod S</emphasis>).</para>
1161 <para>Normally, this implementation does not reduce the number of allowed attempts to less than the configured limit
1162 (<emphasis>f</emphasis>). If one Authentication Server refuses an attempt, the client contacts another instance of the
1163 server, continuing until either it successfully authenticates or has contacted all of the servers. However, if one or more
1164 of the Authentication Server processes is unavailable, the limit is effectively reduced by a percentage equal to the
1165 quantity <emphasis>U</emphasis> divided by <emphasis>S</emphasis>, where <emphasis>U</emphasis> is the number of
1166 unavailable servers and <emphasis>S</emphasis> is the number normally available.</para>
1168 <para>To avoid the undesirable consequences of setting a limit on failed authentication attempts, note the following
1169 recommendations: <itemizedlist>
1171 <para>Do not set the <emphasis role="bold">-attempts</emphasis> argument (the limit on failed authentication
1172 attempts) too low. A limit of nine failed attempts is recommended for regular user accounts, to allow three failed
1173 attempts per Authentication Server in a cell with three database server machines.</para>
1177 <para>Set fairly short lockout times when including the <emphasis role="bold">-locktime</emphasis> argument.
1178 Although guessing passwords is a common method of attack, it is not a very sophisticated one. Setting a lockout time
1179 can help discourage attackers, but excessively long times are likely to be more of a burden to authorized users than
1180 to potential attackers. A lockout time of 25 minutes is recommended for regular user accounts.</para>
1184 <para>Do not assign an infinite lockout time on an account (by setting the <emphasis
1185 role="bold">-locktime</emphasis> argument to <emphasis role="bold">0</emphasis> [zero]) unless there is a highly
1186 compelling reason. Such accounts almost inevitably become locked at some point, because each Authentication Server
1187 never resets the account's failure counter in its copy of the <emphasis role="bold">kaauxdb</emphasis> file (in
1188 contrast, when the lockout time is not infinite, the counter resets after the specified amount of time has passed
1189 since the last failed attempt to that Authentication Server). Furthermore, the only way to unlock an account with an
1190 infinite lockout time is for an administrator to issue the <emphasis role="bold">kas unlock</emphasis> command. It
1191 is especially dangerous to set an infinite lockout time on an administrative account; if all administrative accounts
1192 become locked, the only way to unlock them is to shut down all instances of the Authentication Server and remove the
1193 <emphasis role="bold">kaauxdb</emphasis> file on each.</para>
1195 </itemizedlist></para>
1197 <para>In summary, the recommended limit on authentication attempts is nine and lockout time 25 minutes.</para>
1201 <para>Limit password lifetime.</para>
1203 <para>The longer a password is in use, the more time an attacker has to try to learn it. To protect against this type of
1204 attack, use the <emphasis role="bold">-pwexpires</emphasis> argument to the <emphasis role="bold">kas setfields</emphasis>
1205 command to limit how many days a user's password is valid. The user becomes unable to authenticate with AFS after the
1206 password expires, but has up to 30 days to use the <emphasis role="bold">kpasswd</emphasis> command to set a new password.
1207 After the 30 days pass, only an administrator who has the <computeroutput>ADMIN</computeroutput> flag on the
1208 Authentication Database entry can change the password.</para>
1210 <para>If you set a password lifetime, many AFS-modified login utilities (but not the <emphasis role="bold">klog</emphasis>
1211 command) set the PASSWORD_EXPIRES environment variable to the number of days remaining until the password expires. A
1212 setting of zero means that the password expires today. If desired, you can customize your users' login scripts to display
1213 the number of days remaining before expiration and even prompt for a password change when a small number of days remain
1214 before expiration.</para>
1218 <para>Prohibit reuse of passwords.</para>
1220 <para>Forcing users to select new passwords periodically is not effective if they simply set the new password to the
1221 current value. To prevent a user from setting a new password to a string similar to any of the last 20 passwords, use the
1222 <emphasis role="bold">-reuse</emphasis> argument to the <emphasis role="bold">kas setfields</emphasis> command.</para>
1224 <para>If you prohibit password reuse and the user specifies an excessively similar password, the Authentication Server
1225 generates the following message to reject it:</para>
1228 Password was not changed because it seems like a reused password
1231 <para>A persistent user can try to bypass this restriction by changing the password 20 times in quick succession (or
1232 running a script to do so). If you believe this is likely to be a problem, you can include the <emphasis
1233 role="bold">-minhours</emphasis> argument to the <emphasis role="bold">kaserver</emphasis> initialization command (for
1234 details, see the command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis>. If the user
1235 attempts to change passwords too frequently, the following message appears.</para>
1238 Password was not changed because you changed it too recently; see
1239 your systems administrator
1244 <para>Check the quality of new passwords.</para>
1246 <para>You can impose a minimum quality standard on passwords by writing a script or program called <emphasis
1247 role="bold">kpwvalid</emphasis>. If the <emphasis role="bold">kpwvalid</emphasis> file exists, the <emphasis
1248 role="bold">kpasswd</emphasis> and <emphasis role="bold">kas setpassword</emphasis> command interpreters invoke it to
1249 check a new password. If the password does not comply with the quality standard, the <emphasis
1250 role="bold">kpwvalid</emphasis> program returns an appropriate code and the command interpreter rejects the
1253 <para>The <emphasis role="bold">kpwvalid</emphasis> file must be executable, must reside in the same AFS directory as the
1254 <emphasis role="bold">kpasswd</emphasis> and <emphasis role="bold">kas</emphasis> binaries, and its directory's ACL must
1255 grant the <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) permission only to the <emphasis
1256 role="bold">system:administrators</emphasis> group.</para>
1258 <para>If you choose to write a <emphasis role="bold">kpwvalid</emphasis> program, consider imposing standards such as the
1259 following. <itemizedlist>
1261 <para>A minimum length</para>
1265 <para>Words found in the dictionary are prohibited</para>
1269 <para>Numbers, punctuation, or both must appear along with letters</para>
1271 </itemizedlist></para>
1273 <para>The AFS distribution includes an example <emphasis role="bold">kpwvalid</emphasis> program. See the <emphasis
1274 role="bold">kpwvalid</emphasis> reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
1276 </itemizedlist></para>
1279 <primary>kas commands</primary>
1281 <secondary>setfields</secondary>
1283 <tertiary>limiting failed authentication attempts</tertiary>
1287 <primary>commands</primary>
1289 <secondary>kas setfields</secondary>
1291 <tertiary>limiting failed authentication attempts</tertiary>
1294 <sect2 id="Header_585">
1295 <title>To limit the number of consecutive failed authentication attempts</title>
1299 <para>Issue the <emphasis role="bold">kas setfields</emphasis> command with the <emphasis role="bold">-attempts</emphasis>
1300 and <emphasis role="bold">-locktime</emphasis> arguments.</para>
1302 <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
1303 it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
1304 Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
1305 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
1306 issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
1307 ADMIN flag is set</link>.</para>
1310 % <emphasis role="bold">kas setfields</emphasis> <<replaceable>name of user</replaceable>> \
1311 <emphasis role="bold">-admin</emphasis> <<replaceable>admin principal to use for authentication</replaceable>> \
1312 <emphasis role="bold">-attempts</emphasis> <<replaceable>maximum successive failed login tries ([0..254])</replaceable>> \
1313 <emphasis role="bold">-locktime</emphasis> <<replaceable>failure penalty [hh:mm or minutes]</replaceable>>
1314 Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
1317 <para>where <variablelist>
1319 <term><emphasis role="bold">name of user</emphasis></term>
1322 <para>Names the Authentication Database entry to edit.</para>
1327 <term><emphasis role="bold">-admin</emphasis></term>
1330 <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
1331 Authentication Database entry, such as the <emphasis role="bold">admin</emphasis> account. The password prompt
1332 echoes it as admin_user. Enter the appropriate password as admin_password.</para>
1337 <term><emphasis role="bold">-attempts</emphasis></term>
1340 <para>Specifies the maximum consecutive number of times that a user can fail to provide the correct password
1341 during authentication (via the <emphasis role="bold">klog</emphasis> command or an AFS-modified login utility)
1342 before the Authentication Server refuses further attempts for the amount of time specified by the <emphasis
1343 role="bold">-locktime</emphasis> argument. The range of valid values is <emphasis role="bold">0</emphasis> (zero)
1344 through <emphasis role="bold">254</emphasis>. If you omit this argument or specify <emphasis
1345 role="bold">0</emphasis>, the Authentication Server allows an unlimited number of failures.</para>
1350 <term><emphasis role="bold">-locktime</emphasis></term>
1353 <para>Specifies how long the Authentication Server refuses authentication attempts after the user exceeds the
1354 failure limit specified by the <emphasis role="bold">-attempts</emphasis> argument.</para>
1356 <para>Specify a time in either hours and minutes (hh:mm) or minutes only (mm), from the range <emphasis
1357 role="bold">01</emphasis> (one minute) through <emphasis role="bold">36:00</emphasis> (36 hours). The <emphasis
1358 role="bold">kas</emphasis> command interpreter automatically reduces any larger value to 36:00 and also rounds up
1359 each nonzero value to the next-higher multiple of 8.5 minutes.</para>
1361 <para>It is best not to provide a value of <emphasis role="bold">0</emphasis> (zero), especially on administrative
1362 accounts, because it sets an infinite lockout time. An administrator must always issue the <emphasis
1363 role="bold">kas unlock</emphasis> command to unlock such an account.</para>
1366 </variablelist></para>
1371 <sect2 id="Header_586">
1372 <title>To unlock a locked user account</title>
1376 <para>Issue the <emphasis role="bold">kas</emphasis> command to enter interactive mode.</para>
1378 <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
1379 it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
1380 Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
1381 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
1382 issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
1383 ADMIN flag is set</link>.</para>
1386 % <emphasis role="bold">kas -admin</emphasis> <<replaceable>admin principal to use for authentication</replaceable>>
1387 Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
1391 <para>where <emphasis role="bold">-admin</emphasis> names an administrative account that has the
1392 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry, such as <emphasis
1393 role="bold">admin</emphasis>. The password prompt echoes it as admin_user. Enter the appropriate password as
1394 admin_password.</para>
1398 <para>Issue the <emphasis role="bold">(kas) examine</emphasis> command to verify that the user's account is in fact
1399 locked, as indicated by the message shown: <programlisting>
1400 ka> <emphasis role="bold">examine</emphasis> <<replaceable>name of user</replaceable>>
1401 User is locked until time
1402 </programlisting> <indexterm>
1403 <primary>kas commands</primary>
1405 <secondary>unlock</secondary>
1406 </indexterm> <indexterm>
1407 <primary>commands</primary>
1409 <secondary>kas unlock</secondary>
1414 <para>Issue the <emphasis role="bold">(kas) unlock</emphasis> command to unlock the account. <programlisting>
1415 ka> <emphasis role="bold">unlock</emphasis> <<replaceable>authentication ID</replaceable>>
1416 </programlisting></para>
1422 <term><emphasis role="bold">u</emphasis></term>
1425 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">unlock</emphasis>.</para>
1430 <term><emphasis role="bold">authentication ID</emphasis></term>
1433 <para>Names the Authentication Database entry to unlock.</para>
1441 <primary>kas commands</primary>
1443 <secondary>setfields</secondary>
1445 <tertiary>setting password lifetime</tertiary>
1449 <primary>commands</primary>
1451 <secondary>kas setfields</secondary>
1453 <tertiary>setting password lifetime</tertiary>
1457 <primary>Authentication Database</primary>
1459 <secondary>password lifetime, setting</secondary>
1463 <sect2 id="Header_587">
1464 <title>To set password lifetime</title>
1468 <para>Issue the <emphasis role="bold">kas setfields</emphasis> command with the <emphasis
1469 role="bold">-pwexpires</emphasis> argument.</para>
1471 <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
1472 it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
1473 Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
1474 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
1475 issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
1476 ADMIN flag is set</link>.</para>
1479 % <emphasis role="bold">kas setfields</emphasis> <<replaceable>name of user</replaceable>> \
1480 <emphasis role="bold">-pwexpires</emphasis> <<replaceable>number days password is valid [0..254])</replaceable>> \
1481 <emphasis role="bold">-admin</emphasis> <<replaceable>admin principal to use for authentication</replaceable>>
1482 Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
1485 <para>where <variablelist>
1487 <term><emphasis role="bold">name of user</emphasis></term>
1490 <para>Specifies the Authentication Database entry on which to impose a password expiration.</para>
1495 <term><emphasis role="bold">-pwexpires</emphasis></term>
1498 <para>Sets the number of days after the user's password was last changed that it remains valid. Provide an integer
1499 from the range <emphasis role="bold">1</emphasis> through <emphasis role="bold">254</emphasis> to specify the
1500 number of days until expiration.</para>
1502 <para>When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in
1503 which to issue the <emphasis role="bold">kpasswd</emphasis> or <emphasis role="bold">kas setpassword</emphasis>
1504 command to change the password (after that, only an administrator can change it). Note that the clock starts at
1505 the time the password was last changed, not when the <emphasis role="bold">kas setfields</emphasis> command is
1506 issued. To avoid retroactive expiration, have the user change the password just before issuing the command.</para>
1511 <term><emphasis role="bold">-admin</emphasis></term>
1514 <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
1515 Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
1516 admin_user. Enter the appropriate password as admin_password.</para>
1519 </variablelist></para>
1524 <primary>kas commands</primary>
1526 <secondary>setfields</secondary>
1528 <tertiary>prohibiting password reuse</tertiary>
1532 <primary>commands</primary>
1534 <secondary>kas setfields</secondary>
1536 <tertiary>prohibiting password reuse</tertiary>
1540 <sect2 id="Header_588">
1541 <title>To prohibit reuse of passwords</title>
1545 <para>Issue the <emphasis role="bold">kas setfields</emphasis> command with the <emphasis role="bold">-reuse</emphasis>
1548 <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
1549 it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
1550 Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
1551 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
1552 issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
1553 ADMIN flag is set</link>.</para>
1556 % <emphasis role="bold">kas setfields</emphasis> <<replaceable>name of user</replaceable>> <emphasis role="bold">-reuse</emphasis> <<replaceable> permit password reuse (yes/no)</replaceable>> \
1557 <emphasis role="bold">-admin</emphasis> <<replaceable>admin principal to use for authentication</replaceable>>
1558 Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
1561 <para>where <variablelist>
1563 <term><emphasis role="bold">name of user</emphasis></term>
1566 <para>Names the Authentication Database entry for which to set the password reuse policy.</para>
1571 <term><emphasis role="bold">-reuse</emphasis></term>
1574 <para>Specifies whether the Authentication Server allows reuse of passwords similar to any of the user's last 20
1575 passwords. Specify the value <emphasis role="bold">no</emphasis> to prohibit reuse, or the value <emphasis
1576 role="bold">yes</emphasis> to reinstate the default of allowing password reuse.</para>
1581 <term><emphasis role="bold">-admin</emphasis></term>
1584 <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
1585 Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
1586 admin_user. Enter the appropriate password as admin_password.</para>
1589 </variablelist></para>
1594 <primary>password</primary>
1596 <secondary>setting in Authentication Database</secondary>
1600 <primary>setting</primary>
1602 <secondary>password</secondary>
1604 <tertiary>in Authentication Database</tertiary>
1608 <primary>Authentication Database</primary>
1610 <secondary>password</secondary>
1612 <tertiary>setting</tertiary>
1617 <sect1 id="HDRWQ516">
1618 <title>Changing AFS Passwords</title>
1620 <para>After setting an initial password during account creation, you normally do not need to change user passwords, since they
1621 can use the <emphasis role="bold">kpasswd</emphasis> command themselves by following the instructions in the <emphasis>OpenAFS
1622 User Guide</emphasis>. In the rare event that a user forgets the password or otherwise cannot log in, you can use the <emphasis
1623 role="bold">kas setpassword</emphasis> command to set a new password.</para>
1625 <para>If entries in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) have actual scrambled
1626 passwords in their password field, remember to change the password there also. For further discussion, see <link
1627 linkend="HDRWQ497">Specifying Passwords in the Local Password File</link>. <indexterm>
1628 <primary>kas commands</primary>
1630 <secondary>setpassword</secondary>
1631 </indexterm> <indexterm>
1632 <primary>commands</primary>
1634 <secondary>kas setpassword</secondary>
1637 <sect2 id="Header_590">
1638 <title>To change an AFS password</title>
1642 <para>Issue the <emphasis role="bold">kas setpassword</emphasis> command to change the password. To avoid having the new
1643 password echo visibly on the screen, omit the <emphasis role="bold">-new_password</emphasis> argument; instead enter the
1644 password at the prompts that appear when you omit the argument, as shown.</para>
1646 <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
1647 it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
1648 Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
1649 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
1650 issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
1651 ADMIN flag is set</link>.</para>
1654 % <emphasis role="bold">kas setpassword</emphasis> <<replaceable>name of user</replaceable>> \
1655 <emphasis role="bold">-admin</emphasis> <<replaceable>admin principal to use for authentication</replaceable>>
1656 Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
1657 new_password: <<replaceable>new_password</replaceable>>
1658 Verifying, please re-enter new_password: <<replaceable>new_password</replaceable>>
1661 <para>where <variablelist>
1663 <term><emphasis role="bold">sp</emphasis></term>
1666 <para>Is an acceptable alias for <emphasis role="bold">setpassword</emphasis> (<emphasis
1667 role="bold">setp</emphasis> is the shortest acceptable abbreviation).</para>
1672 <term><emphasis role="bold">name of user</emphasis></term>
1675 <para>Names the Authentication Database entry for which to set the password.</para>
1680 <term><emphasis role="bold">-admin</emphasis></term>
1683 <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
1684 Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
1685 admin_user. Enter the appropriate password as admin_password.</para>
1690 <term><emphasis role="bold">new_password</emphasis></term>
1693 <para>Specifies the user's new password. It is subject to the restrictions imposed by the <emphasis
1694 role="bold">kpwvalid</emphasis> program, if you use it.</para>
1697 </variablelist></para>
1703 <sect1 id="HDRWQ517">
1704 <title>Displaying and Setting the Quota on User Volumes</title>
1706 <para>User volumes are like all other volumes with respect to quota. Each new AFS volume has a default quota of 5000 KB, unless
1707 you use the <emphasis role="bold">-maxquota</emphasis> argument to the <emphasis role="bold">vos create</emphasis> command to
1708 set a different quota. You can also use either of the following commands to change quota at any time: <itemizedlist>
1710 <para><emphasis role="bold">fs setquota</emphasis></para>
1714 <para><emphasis role="bold">fs setvol</emphasis></para>
1716 </itemizedlist></para>
1718 <para>You can use any of the three following commands to display a volume's quota: <itemizedlist>
1720 <para><emphasis role="bold">fs quota</emphasis></para>
1724 <para><emphasis role="bold">fs listquota</emphasis></para>
1728 <para><emphasis role="bold">fs examine</emphasis></para>
1730 </itemizedlist></para>
1732 <para>For instructions, see <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current Size</link>. <indexterm>
1733 <primary>username</primary>
1735 <secondary>changing</secondary>
1736 </indexterm> <indexterm>
1737 <primary>changing</primary>
1739 <secondary>username</secondary>
1740 </indexterm> <indexterm>
1741 <primary>renaming</primary>
1743 <secondary>user account components</secondary>
1744 </indexterm> <indexterm>
1745 <primary>Protection Database</primary>
1747 <secondary>changing username</secondary>
1748 </indexterm> <indexterm>
1749 <primary>Authentication Database</primary>
1751 <secondary>changing username</secondary>
1755 <sect1 id="HDRWQ518">
1756 <title>Changing Usernames</title>
1758 <para>By convention, many components of a user account incorporate the username, including the Protection and Authentication
1759 Database entries, the volume name and the home directory name. When changing a username, it is best to maintain consistency by
1760 changing the names of all components, so the procedure for changing a username has almost as many steps as the procedure for
1761 creating a new user account.</para>
1763 <sect2 id="Header_593">
1764 <title>To change a username</title>
1768 <primary>pts commands</primary>
1770 <secondary>rename</secondary>
1772 <tertiary>username</tertiary>
1776 <primary>commands</primary>
1778 <secondary>pts rename</secondary>
1780 <tertiary>username</tertiary>
1784 <para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
1785 <emphasis role="bold">admin</emphasis> user account has them, or you possibly have a personal administrative account. (To
1786 increase cell security, it is best to create special privileged accounts for use only while performing administrative
1787 procedures; for further discussion, see <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
1788 necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
1789 % <emphasis role="bold">klog</emphasis> admin_user
1790 Password: <<replaceable>admin_password</replaceable>>
1791 </programlisting></para>
1793 <para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>
1797 <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
1798 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
1799 display the members of the system:administrators group</link>. <programlisting>
1800 % <emphasis role="bold">pts membership system:administrators</emphasis>
1801 </programlisting></para>
1805 <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
1806 role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
1807 users in the UserList file</link>. <programlisting>
1808 % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>>
1809 </programlisting></para>
1813 <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. However, the
1814 Authentication Server performs its own authentication, so the following instructions direct you to specify an
1815 administrative identity on the <emphasis role="bold">kas</emphasis> command line itself.</para>
1819 <para>The <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>), <emphasis
1820 role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>), and <emphasis role="bold">i</emphasis> (<emphasis
1821 role="bold">insert</emphasis>) permissions on the ACL of the directory where you are removing the current mount point
1822 and creating a new one. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully
1823 described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
1824 % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>]
1825 </programlisting></para>
1827 <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
1828 role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
1829 role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
1830 role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
1836 <para><anchor id="LIWQ519" />Issue the <emphasis role="bold">pts listowned</emphasis> command to display the names of the
1837 groups the user owns. After you change the username in the Protection Database in Step <link linkend="LIWQ520">3</link>,
1838 you must issue the <emphasis role="bold">pts rename</emphasis> command to change each group's owner prefix to match the
1839 new name, because the Protection Server does not automatically make this change. For a complete description of the
1840 <emphasis role="bold">pts listowned</emphasis> command, see <link linkend="HDRWQ536">Displaying Information from the
1841 Protection Database</link>. <programlisting>
1842 % <emphasis role="bold">pts listowned</emphasis> <<replaceable>user or group name or id</replaceable>>
1843 </programlisting></para>
1847 <para><anchor id="LIWQ520" />Issue the <emphasis role="bold">pts rename</emphasis> command to change the user's name in
1848 the Protection Database. <programlisting>
1849 % <emphasis role="bold">pts rename</emphasis> <<replaceable>old name</replaceable>> <<replaceable>new name</replaceable>>
1850 </programlisting></para>
1854 <para>Issue the <emphasis role="bold">pts rename</emphasis> command to change the group names you noted in Step <link
1855 linkend="LIWQ519">2</link>, so that their owner prefix (the part of the group name before the colon) accurately reflects
1856 the owner's new name.</para>
1858 <para>Repeat the command for each group. Step <link linkend="LIWQ520">3</link> details its syntax.</para>
1861 % <emphasis role="bold">pts rename</emphasis> <<replaceable>old name</replaceable>> <<replaceable>new name</replaceable>>
1866 <para>Issue the <emphasis role="bold">kas</emphasis> command to enter interactive mode.</para>
1868 <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
1869 it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
1870 Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
1871 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
1872 issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
1873 ADMIN flag is set</link>.</para>
1876 % <emphasis role="bold">kas -admin</emphasis> <<replaceable>admin principal to use for authentication</replaceable>>
1877 Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
1881 <para>where <emphasis role="bold">-admin</emphasis> names an administrative account that has the
1882 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry, such as <emphasis
1883 role="bold">admin</emphasis>. The password prompt echoes it as admin_user. Enter the appropriate password as
1884 admin_password. <indexterm>
1885 <primary>kas commands</primary>
1887 <secondary>delete</secondary>
1889 <tertiary>when changing username</tertiary>
1890 </indexterm> <indexterm>
1891 <primary>commands</primary>
1893 <secondary>kas delete</secondary>
1895 <tertiary>when changing username</tertiary>
1900 <para>Issue the <emphasis role="bold">(kas) delete</emphasis> command to delete the user's existing Authentication
1901 Database entry. <programlisting>
1902 ka> <emphasis role="bold">delete</emphasis> <<replaceable>name of user</replaceable>>
1903 </programlisting></para>
1909 <term><emphasis role="bold">del</emphasis></term>
1912 <para>Is the shortest acceptable abbreviation for <emphasis role="bold">delete</emphasis>, or you can use the alias
1913 <emphasis role="bold">rm</emphasis>.</para>
1918 <term><emphasis role="bold">name of user</emphasis></term>
1921 <para>Names the Authentication Database entry to delete.</para>
1927 <primary>kas commands</primary>
1929 <secondary>create</secondary>
1931 <tertiary>when changing username</tertiary>
1935 <primary>commands</primary>
1937 <secondary>kas create</secondary>
1939 <tertiary>when changing username</tertiary>
1944 <para>Issue the <emphasis role="bold">(kas) create</emphasis> command to create an Authentication Database entry for the
1945 new username. To avoid having the user's password echo visibly on the screen, do not include the <emphasis
1946 role="bold">-initial_password</emphasis> argument; instead enter the password at the prompts that appear in that case, as
1947 shown in the following syntax specification. <programlisting>
1948 ka> <emphasis role="bold">create</emphasis> <<replaceable>name of user</replaceable>>
1949 initial_password: <<replaceable>password</replaceable>>
1950 Verifying, please re-enter initial_password: <<replaceable>password</replaceable>>
1951 </programlisting></para>
1957 <term><emphasis role="bold">cr</emphasis></term>
1960 <para>Is the shortest acceptable abbreviation for <emphasis role="bold">create</emphasis>.</para>
1965 <term><emphasis role="bold">name of user</emphasis></term>
1968 <para>Specifies the new username.</para>
1973 <term><emphasis role="bold">password</emphasis></term>
1976 <para>Specifies the password for the new user account. If the user is willing to tell you his or her current
1977 password, you can retain it. Otherwise, provide a string of eight characters or less to comply with the length
1978 restriction that some applications impose. Possible choices for an initial password include the username, a string
1979 of digits from a personal identification number such as the Social Security number, or a standard string such as
1980 <emphasis role="bold">changeme</emphasis>. Instruct the user to change the string to a truly secret password as soon
1981 as possible by using the <emphasis role="bold">kpasswd</emphasis> command as instructed in the <emphasis>OpenAFS
1982 User Guide</emphasis>.</para>
1989 <para>Issue the <emphasis role="bold">quit</emphasis> command to leave interactive mode. <programlisting>
1990 ka> <emphasis role="bold">quit</emphasis>
1991 </programlisting> <indexterm>
1992 <primary>vos commands</primary>
1994 <secondary>rename</secondary>
1996 <tertiary>when changing username</tertiary>
1997 </indexterm> <indexterm>
1998 <primary>commands</primary>
2000 <secondary>vos rename</secondary>
2002 <tertiary>when changing username</tertiary>
2003 </indexterm> <indexterm>
2004 <primary>volume name</primary>
2006 <secondary>changing</secondary>
2008 <tertiary>when renaming user</tertiary>
2009 </indexterm> <indexterm>
2010 <primary>renaming</primary>
2012 <secondary>volume when changing username</secondary>
2013 </indexterm> <indexterm>
2014 <primary>changing</primary>
2016 <secondary>volume name when renaming user</secondary>
2021 <para><anchor id="LIWQ521" />Issue the <emphasis role="bold">vos rename</emphasis> command to change the name of the
2022 user's volume. For complete syntax, see <link linkend="HDRWQ246">To rename a volume</link>. <programlisting>
2023 % <emphasis role="bold">vos rename</emphasis> <<replaceable>old volume name</replaceable>> <<replaceable>new volume name</replaceable>>
2024 </programlisting><indexterm>
2025 <primary>fs commands</primary>
2027 <secondary>rmmount</secondary>
2029 <tertiary>when changing username</tertiary>
2030 </indexterm><indexterm>
2031 <primary>commands</primary>
2033 <secondary>fs rmmount</secondary>
2034 </indexterm><indexterm>
2035 <primary>mount point</primary>
2037 <secondary>changing when renaming user</secondary>
2038 </indexterm><indexterm>
2039 <primary>removing</primary>
2041 <secondary>mount point</secondary>
2043 <tertiary>when changing username</tertiary>
2044 </indexterm><indexterm>
2045 <primary>changing</primary>
2047 <secondary>mount point when renaming user</secondary>
2052 <para><anchor id="LIWQ522" />Issue the <emphasis role="bold">fs rmmount</emphasis> command to remove the existing mount
2053 point. For the directory argument, specify the read/write path to the mount point, to avoid the failure that results when
2054 you attempt to delete a mount point from a read-only volume. <programlisting>
2055 % <emphasis role="bold">fs rmmount</emphasis> <<replaceable>directory</replaceable>>
2056 </programlisting><indexterm>
2057 <primary>fs commands</primary>
2059 <secondary>mkmount</secondary>
2061 <tertiary>when changing username</tertiary>
2062 </indexterm><indexterm>
2063 <primary>commands</primary>
2065 <secondary>fs mkmount</secondary>
2067 <tertiary>when changing username</tertiary>
2068 </indexterm><indexterm>
2069 <primary>creating</primary>
2071 <secondary>mount point when changing username</secondary>
2076 <para><anchor id="LIWQ523" />Issue the <emphasis role="bold">fs mkmount</emphasis> command to create a mount point for the
2077 volume's new name. Specify the read/write path to the mount point for the directory argument, as in the previous step. For
2078 complete syntax, see Step <link linkend="LIWQ509">6</link> in <link linkend="HDRWQ503">To create one user account with
2079 individual commands</link>. <programlisting>
2080 % <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>>
2081 </programlisting></para>
2085 <para>If the changes you made in Step <link linkend="LIWQ522">10</link> and Step <link linkend="LIWQ523">11</link> are to
2086 a mount point that resides in a replicated volume, use the <emphasis role="bold">vos release</emphasis> command to release
2087 the volume, as described in <link linkend="HDRWQ194">To replicate a read/write volume (create a read-only volume)</link>.
2089 % <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>>
2090 </programlisting></para>
2093 <para>This step can be necessary even if the home directory's parent directory is not itself a mount point for a
2094 replicated volume (and is easier to overlook in that case). For example, the ABC Corporation template puts the mount
2095 points for user volumes in the <emphasis role="bold">/afs/abc.com/usr</emphasis> directory. Because that is a regular
2096 directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted at the
2097 <emphasis role="bold">/afs/abc.com</emphasis> directory. That volume is replicated, so after changing it the
2098 administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>
2105 <sect1 id="HDRWQ524">
2106 <title>Removing a User Account</title>
2109 <primary>removing</primary>
2111 <secondary>user account components</secondary>
2115 <primary>user account</primary>
2117 <secondary>removing from system</secondary>
2120 <para>Before removing an account, it is best to make a backup copy of the user's home volume on a permanent storage medium such
2121 as tape. If you need to remove several accounts, it is probably more efficient to use the <emphasis role="bold">uss
2122 delete</emphasis> command instead; see <link linkend="HDRWQ486">Deleting Individual Accounts with the uss delete
2123 Command</link>.</para>
2125 <sect2 id="Header_595">
2126 <title>To remove a user account</title>
2130 <para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
2131 <emphasis role="bold">admin</emphasis> user account has them, or you possibly have a personal administrative account. (To
2132 increase cell security, it is best to create special privileged accounts for use only while performing administrative
2133 procedures; for further discussion, see <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
2134 necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
2135 % <emphasis role="bold">klog</emphasis> admin_user
2136 Password: <<replaceable>admin_password</replaceable>>
2137 </programlisting></para>
2139 <para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>
2143 <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
2144 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
2145 display the members of the system:administrators group</link>. <programlisting>
2146 % <emphasis role="bold">pts membership system:administrators</emphasis>
2147 </programlisting></para>
2151 <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
2152 role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
2153 users in the UserList file</link>. <programlisting>
2154 % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>>
2155 </programlisting></para>
2159 <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. However, the
2160 Authentication Server performs its own authentication, so the following instructions direct you to specify an
2161 administrative identity on the <emphasis role="bold">kas</emphasis> command line itself.</para>
2165 <para>The <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>) permission on the ACL of the
2166 directory where you are removing the user volume's mount point. If necessary, issue the <emphasis role="bold">fs
2167 listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>.
2169 % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>]
2170 </programlisting></para>
2172 <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
2173 role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
2174 role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
2175 role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
2181 <para><emphasis role="bold">(Optional)</emphasis> If it is possible you need to restore the user's account someday, note
2182 the username and AFS UID, possibly in a file designated for that purpose. You can later restore the account with its
2183 original AFS UID.</para>
2187 <para><emphasis role="bold">(Optional)</emphasis> Copy the contents of the user's volume to tape. You can use the
2188 <emphasis role="bold">vos dump</emphasis> command as described in <link linkend="HDRWQ240">Dumping and Restoring
2189 Volumes</link> or the AFS Backup System as described in <link linkend="HDRWQ296">Backing Up Data</link>.</para>
2193 <para><anchor id="LIWQ525" /><emphasis role="bold">(Optional)</emphasis> If you intend to remove groups that the user owns
2194 from the Protection Database after removing the user's entry, issue the <emphasis role="bold">pts listowned</emphasis>
2195 command to display them. For complete instructions, see <link linkend="HDRWQ536">Displaying Information from the
2196 Protection Database</link>. <programlisting>
2197 % <emphasis role="bold">pts listowned</emphasis> <<replaceable>user or group name or id</replaceable>>
2198 </programlisting></para>
2202 <para><anchor id="LIWQ526" />(<emphasis role="bold">Optional)</emphasis> Issue the <emphasis role="bold">pts
2203 delete</emphasis> command to remove the groups the user owns. However, if it is likely that other users have placed the
2204 groups on the ACLs of directories they own, it is best not to remove them. <programlisting>
2205 % <emphasis role="bold">pts delete</emphasis> <<replaceable>user or group name or id</replaceable>>+
2206 </programlisting></para>
2212 <term><emphasis role="bold">del</emphasis></term>
2215 <para>Is the shortest acceptable abbreviation for <emphasis role="bold">delete</emphasis>.</para>
2220 <term><emphasis role="bold">user or group name or id</emphasis></term>
2223 <para>Specifies the name or AFS UID of each group displayed in the output from Step <link
2224 linkend="LIWQ525">4</link>.</para>
2230 <primary>kas commands</primary>
2232 <secondary>delete</secondary>
2234 <tertiary>when removing user account</tertiary>
2238 <primary>commands</primary>
2240 <secondary>kas delete</secondary>
2244 <primary>Authentication Database</primary>
2246 <secondary>entry</secondary>
2248 <tertiary>removing</tertiary>
2253 <para>Issue the <emphasis role="bold">kas delete</emphasis> command to remove the user's Authentication Database
2256 <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
2257 it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
2258 Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
2259 <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
2260 issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
2261 ADMIN flag is set</link>.</para>
2264 % <emphasis role="bold">kas delete</emphasis> <<replaceable>name of user</replaceable>> \
2265 <emphasis role="bold">-admin</emphasis> <<replaceable>admin principal to use for authentication</replaceable>>
2266 Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
2269 <para>where <variablelist>
2271 <term><emphasis role="bold">d</emphasis></term>
2274 <para>Is the shortest acceptable abbreviation for <emphasis role="bold">delete</emphasis>.</para>
2279 <term><emphasis role="bold">name of user</emphasis></term>
2282 <para>Names the Authentication Database entry to delete.</para>
2287 <term><emphasis role="bold">-admin</emphasis></term>
2290 <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
2291 Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
2292 admin_user. Enter the appropriate password as admin_password.</para>
2295 </variablelist></para>
2299 <para><anchor id="LIWQ527" />Issue the <emphasis role="bold">vos listvldb</emphasis> command to display the site of the
2300 user's home volume in preparation for removing it. By convention, user volumes are named <emphasis
2301 role="bold">user</emphasis>.username. <programlisting>
2302 % <emphasis role="bold">vos listvldb</emphasis> <<replaceable>volume name or ID</replaceable>>
2303 </programlisting></para>
2309 <term><emphasis role="bold">listvl</emphasis></term>
2312 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvldb</emphasis>.</para>
2317 <term><emphasis role="bold">volume name or ID</emphasis></term>
2320 <para>Specifies the volume's name or volume ID number.</para>
2326 <primary>vos commands</primary>
2328 <secondary>remove</secondary>
2330 <tertiary>when removing user account</tertiary>
2334 <primary>commands</primary>
2336 <secondary>vos remove</secondary>
2340 <primary>volume</primary>
2342 <secondary>removing</secondary>
2344 <tertiary>when removing user account</tertiary>
2348 <primary>removing</primary>
2350 <secondary>volume when removing user account</secondary>
2355 <para><anchor id="LIWQ528" />Issue the <emphasis role="bold">vos remove</emphasis> command to remove the user's volume. It
2356 automatically removes the backup version of the volume, if it exists. It is not conventional to replicate user volumes, so
2357 the command usually also completely removes the volume's entry from the Volume Location Database (VLDB). If there are
2358 ReadOnly replicas of the volume, you must repeat the <emphasis role="bold">vos remove</emphasis> command to remove each
2359 one individually. <programlisting>
2360 % <emphasis role="bold">vos remove</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <<replaceable>volume name or ID</replaceable>>
2361 </programlisting></para>
2367 <term><emphasis role="bold">remo</emphasis></term>
2370 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">remove</emphasis>.</para>
2375 <term><emphasis role="bold">machine name</emphasis></term>
2378 <para>Names the file server machine that houses the volume, as specified in the output from Step <link
2379 linkend="LIWQ527">7</link>.</para>
2384 <term><emphasis role="bold">partition name</emphasis></term>
2387 <para>Names the partition that houses the volume, as specified in the output from Step <link
2388 linkend="LIWQ527">7</link>.</para>
2393 <term><emphasis role="bold">volume name or ID</emphasis></term>
2396 <para>Specifies the volume's name or ID number.</para>
2402 <primary>fs commands</primary>
2404 <secondary>rmmount</secondary>
2406 <tertiary>when removing user account</tertiary>
2410 <primary>commands</primary>
2412 <secondary>fs rmmount</secondary>
2416 <primary>mount point</primary>
2418 <secondary>removing when removing user account</secondary>
2422 <primary>removing</primary>
2424 <secondary>mount point when removing user account</secondary>
2429 <para><anchor id="LIWQ529" />Issue the <emphasis role="bold">fs rmmount</emphasis> command to remove the volume's mount
2432 <para>If you mounted the user's backup volume as a subdirectory of the home directory, then this command is sufficient to
2433 unmount the backup version as well. If you mounted the backup version at an unrelated location in the filespace, repeat
2434 the <emphasis role="bold">fs rmmount</emphasis> command for it.</para>
2437 % <emphasis role="bold">fs rmmount</emphasis> <<replaceable>directory</replaceable>>
2440 <para>where <variablelist>
2442 <term><emphasis role="bold">rmm</emphasis></term>
2445 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">rmmount</emphasis>.</para>
2450 <term><emphasis role="bold">directory</emphasis></term>
2453 <para>Names the mount point for the volume's previous name (the former home directory). Partial pathnames are
2454 interpreted relative to the current working directory.</para>
2456 <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete
2457 a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before
2458 the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). For
2459 further discussion of the concept of read/write and read-only paths through the filespace, see <link
2460 linkend="HDRWQ208">Mounting Volumes</link>.</para>
2463 </variablelist></para>
2466 <primary>pts commands</primary>
2468 <secondary>delete</secondary>
2470 <tertiary>when removing user account</tertiary>
2474 <primary>commands</primary>
2476 <secondary>pts delete</secondary>
2480 <primary>Protection Database</primary>
2482 <secondary>user entry</secondary>
2484 <tertiary>deleting</tertiary>
2488 <primary>removing</primary>
2490 <secondary>Protection Database entry</secondary>
2495 <para><anchor id="LIWQ530" />Issue the <emphasis role="bold">pts delete</emphasis> command to remove the user's Protection
2496 Database entry. A complete description of this command appears in Step <link linkend="LIWQ526">5</link>. <programlisting>
2497 % <emphasis role="bold">pts delete</emphasis> <<replaceable>user or group name or id</replaceable>>
2498 </programlisting></para>
2502 <para>If the deleted user home directory resided in a replicated volume, use the <emphasis role="bold">vos
2503 release</emphasis> command to release the volume, as described in <link linkend="HDRWQ194">To replicate a read/write
2504 volume (create a read-only volume)</link>. <programlisting>
2505 % <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>>
2506 </programlisting></para>
2509 <para>This step can be necessary even if the home directory's parent directory is not itself a mount point for a
2510 replicated volume (and is easier to overlook in that case). For example, the ABC Corporation template puts the mount
2511 points for user volumes in the <emphasis role="bold">/afs/abc.com/usr</emphasis> directory. Because that is a regular
2512 directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted at the
2513 <emphasis role="bold">/afs/abc.com</emphasis> directory. That volume is replicated, so after changing it by deleting a
2514 mount point the administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>