# Administering User Accounts

This chapter explains how to create and maintain user accounts in your cell.

The preferred method for creating user accounts is the uss program, which enables you to create multiple accounts with a single command. See Creating and Deleting User Accounts with the uss Command Suite. If you prefer to create each account component individually, follow the instructions in Creating AFS User Accounts.

## Summary of Instructions

This chapter explains how to perform the following tasks by using the indicated commands:

Create Protection Database entry | pts createuser
Create Authentication Database entry | kas create
Create volume | vos create
Mount volume | fs mkmount
Create entry on ACL | fs setacl
Examine Protection Database entry | pts examine
Change directory ownership | /etc/chown
Limit failed authentication attempts | kas setfields with -attempts and -locktime
Unlock Authentication Database entry | kas unlock
Set password lifetime | kas setfields with -pwexpires
Prohibit password reuse | kas setfields with -reuse
Change AFS password | kas setpassword
List groups owned by user | pts listowned
Rename Protection Database entry | pts rename
Delete Authentication Database entry | kas delete
Rename volume | vos rename
Remove mount point | fs rmmount
Delete Protection Database entry | pts delete
List volume location | vos listvldb
Remove volume | vos remove

## The Components of an AFS User Account

The differences between AFS and the UNIX file system imply that a complete AFS user account is not the same as a UNIX user account. The following list describes the components of an AFS account. The same information appears in a corresponding section of Creating and Deleting User Accounts with the uss Command Suite, but is repeated here for your convenience.

- A Protection Database entry defines the username (the name provided when authenticating with AFS), and maps it to an AFS user ID (AFS UID), a number that the AFS servers use internally when referencing users. The Protection Database also tracks the groups to which the user belongs. For details, see Administering the Protection Database.

- An Authentication Database entry records the user's AFS password in a scrambled form suitable for use as an encryption key.

- A home volume stores all the files in the user's home directory together on a single partition of a file server machine. The volume has an associated quota that limits its size. For a complete discussion of volumes, see Managing Volumes.

- A mount point makes the contents of the user's volume visible and accessible in the AFS filespace, and acts as the user's home directory. For more details about mount points, see About Mounting Volumes.

- Full access permissions on the home directory's access control list (ACL) and ownership of the directory (as displayed by the UNIX ls -ld command) enable the user to manage his or her files. For details on AFS file protection, see Managing Access Control Lists.

- A local password file entry (in the /etc/passwd file or equivalent) of each AFS client machine enables the user to log in and access AFS files through the Cache Manager. A subsequent section in this chapter further discusses local password file entries.

- Other optional configuration files make the account more convenient to use. Such files help the user log in and log out more easily, receive electronic mail, print, and so on.

## Creating Local Password File Entries

To obtain authenticated access to a cell's AFS filespace, a user must not only have a valid AFS token, but also an entry in the local password file (/etc/passwd or equivalent) of the machine whose Cache Manager is 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 local password file, and describes the appropriate value to put in the file's password field.

One reason to use uss commands is that they enable you to generate local password file entries automatically as part of account creation. See Creating a Common Source Password File.

Information similar to the information in this section appears in a corresponding section of Creating and Deleting User Accounts with the uss Command Suite, but is repeated here for your convenience

### Assigning AFS and UNIX UIDs that Match

A user account is easiest to administer and use if the AFS user ID number (AFS UID) and UNIX UID match. All instructions in the AFS documentation assume that they do.

The most basic reason to make AFS and UNIX UIDs the same is so that the owner name reported by the UNIX ls -l and ls -ld commands makes sense for AFS files and directories. Following standard UNIX practice, the File Server records a number rather than a username in an AFS file or directory's owner field: the owner's AFS UID. When you issue the ls -l command, it translates the UID to a username according to the mapping in the local password file, not the AFS Protection Database. If the AFS and UNIX UIDs do not match, the ls -l command reports an unexpected (and incorrect) owner. The output can even vary on different client machines if their local password files map the same UNIX UID to different names.

Follow the recommendations in the indicated sections to make AFS and UNIX UIDs match when creating accounts for various types of users:

- If creating an AFS account for a user who already has a UNIX UID, see Making UNIX and AFS UIDs Match.

- If some users in your cell have existing UNIX accounts but the user for whom you are creating an AFS account does not, then it is best to allow the Protection Server to allocate an AFS UID automatically. To avoid overlap of AFS UIDs with existing UNIX UIDs, set the Protection Database's `max user id` counter higher than the largest UNIX UID, using the instructions in Displaying and Setting the AFS UID and GID Counters.

- If none of your users have existing UNIX accounts, allow the Protection Server to allocate AFS UIDs automatically, starting either at its default or at the value you have set for the `max user id` counter.

### Specifying Passwords in the Local Password File

Authenticating with AFS is easiest for your users if you install and configure an AFS-modified login utility, which logs a user into the local file system and obtains an AFS token in one step. In this case, the local password file no longer controls a user's ability to login in most circumstances, because the AFS-modified login utility does not consult the local password file if the user provides the correct AFS password. You can nonetheless use a password file entry's password field (usually, the second field) in the following ways to control login and authentication:

- To prevent both local login and AFS authentication, place an asterisk ( * ) in the field. This is useful mainly in emergencies, when you want to prevent a certain user from logging into the machine.

- To prevent login to the local file system if the user does not provide the correct AFS password, place a character string of any length other than the standard thirteen characters in the field. This is appropriate if you want to allow only people with local AFS accounts to log into to your machines. A single X or other character is the most easily recognizable way to do this.

- To enable a user to log into the local file system even after providing an incorrect AFS password, record a standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (passwd or equivalent).

If you do not use an AFS-modified login utility, you must place a standard UNIX password in the local password file of every client machine the user will use. The user logs into the local file system only, and then must issue the klog command to authenticate with AFS. It is simplest if the passwords in the local password file and the Authentication Database are the same, but this is not required.

## Converting Existing UNIX Accounts

This section discusses the three main issues you need to consider if your cell has existing UNIX accounts that you wish to convert to AFS accounts.

### Making UNIX and AFS UIDs Match

As previously mentioned, AFS users must have an entry in the local password file on every client machine from which they access the AFS filespace as an authenticated user. Both administration and use are much simpler if the UNIX UID and AFS UID match. When converting existing UNIX accounts, you have two alternatives:

- Make the AFS UIDs match the existing UNIX UIDs. In this case, you need to assign the AFS UID yourself by including the -id argument to the pts createuser command as you create the AFS account.

  Because you are retaining the user's UNIX UID, you do not need to alter the UID in the local password file entry. However, if you are using an AFS-modified login utility, you possibly need to change the password field in the entry. For a discussion of how the value in the password field affects login with an AFS-modified login utility, see Specifying Passwords in the Local Password File.

  If now or in the future you need to create AFS accounts for users who do not have an existing UNIX UID, then you must guarantee that new AFS UIDs do not conflict with any existing UNIX UIDs. The simplest way is to set the `max user id` counter in the Protection Database to a value higher than the largest existing UNIX UID. See Displaying and Setting the AFS UID and GID Counters.

- Change the existing UNIX UIDs to match the new AFS UIDs that the Protection Server assigns automatically.

  Allow the Protection Server to allocate the AFS UIDs automatically as you create AFS accounts. You must then alter the user's entry in the local password file on every client machine to include the new UID.

  There is one drawback to changing the UNIX UID: any files and directories that the user owned in the local file system before becoming an AFS user still have the former UID in their owner field. If you want the ls -l and ls -ld commands to display the correct owner, you must use the chown command to change the value to the user's new UID, whether you are leaving the file in the local file system or moving it to AFS. See Moving Local Files into AFS.

### Setting the Password Field Appropriately

Existing UNIX accounts already have an entry in the local password file, probably with a (scrambled) password in the password field. You possibly need to change the value in the field, depending on the type of login utility you use:

- If the login utility is not modified for use with AFS, the actual password must appear (in scrambled form) in the local password file entry.

- If the login utility is modified for use with AFS, choose one of the values discussed in Specifying Passwords in the Local Password File.

### Moving Local Files into AFS

New AFS users with existing UNIX accounts probably already own files and directories stored in a machine's local file system, and it usually makes sense to transfer them into the new home volume. The easiest method is to move them onto the local disk of an AFS client machine, and then use the UNIX mv command to transfer them into the user's new AFS home directory.

As you move files and directories into AFS, keep in mind that the meaning of their mode bits changes. AFS ignores the second and third sets of mode bits (group and other), and does not use the first set (the owner bits) directly, but only in conjunction with entries on the ACL (for details, see How AFS Interprets the UNIX Mode Bits). Be sure that the ACL protects the file or directory at least as securely as the mode bits.

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 directories as well. Only members of the system:administrators group can issue the chown command on files and directories once they reside in AFS.

## Creating AFS User Accounts

There are two methods for creating user accounts. The preferred method--using the uss commands--enables you to create multiple accounts with a single command. It uses a template to define standard values for the account components that are the same for each user (such as quota), but provide differing values for more variable components (such as username). See Creating and Deleting User Accounts with the uss Command Suite.

The second method involves issuing a separate command to create each component of the account. It is best suited to creation of one account at a time, since some of the commands can create only one instance of the relevant component. To review the function of each component, see The Components of an AFS User Account.

Use the following instructions to create any of the three types of user account, which differ in their levels of functionality. For a description of the types, see Configuring AFS User Accounts.

- To create an authentication-only account, perform Step 1 through Step 4 and also Step 14. This type of account consists only of entries in the Authentication Database and Protection Database.

- To create a basic account, perform Step 1 through Step 8 and Step 11 through Step 14. In addition to Authentication Database and Protection Database entries, this type of account includes a volume mounted at the home directory with owner and ACL set appropriately.

- To create a full account, perform all steps in the following instructions. This type of account includes configuration files for basic functions such as logging in, printing, and mail delivery, making it more convenient and useful. For a discussion of some useful types of configuration files, see Creating Standard Files in New AFS Accounts.

### To create one user account with individual commands

1. Decide on the value to assign to each of the following account components. If you are creating an authentication-only account, you need to pick only a username, AFS UID, and initial password.

   - The username. By convention, the names of many components of the user account incorporate this name. For a discussion of restrictions and suggested naming schemes, see Choosing Usernames and Naming Other Account Components.

   - The AFS UID, if you want to assign a specific one. It is generally best to have the Protection Server allocate one instead, except when you are creating an AFS account for a user who already has an existing UNIX account. In that case, migrating the user's files into AFS is simplest if you set the AFS UID to match the existing UNIX UID. See Converting Existing UNIX Accounts.

   - The initial password. Advise the user to change this at the first login, using the password changing instructions in the OpenAFS User Guide.

   - The name of the user's home volume. The conventional name is user.username (for example, user.smith).

   - The volume's site (disk partition on a file server machine). Some cells designate certain machines or partitions for user volumes only, or it possibly makes sense to place the volume on the emptiest partition that meets your other criteria. To display the size and available space on a partition, use the vos partinfo command, which is fully described in Creating Read/write Volumes.

   - The name of the user's home directory (the mount point for the home volume). The conventional location is a directory (or one of a set of directories) directly under the cell directory, such as /afs/cellname/usr. For suggestions on how to avoid the slowed directory lookup that can result from having large numbers of user home directories in a single usr directory, see Evenly Distributing User Home Directories with the G Instruction.

   - The volume's space quota. Include the -maxquota argument to the vos create command, or accept the default quota of 5000 KB.

   - The ACL on the home directory. By default, the ACL on every new volume grants all seven permissions to the system:administrators group. After volume creation, use the fs setacl command to remove the entry if desired, and to grant all seven permissions to the user.

2. Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the admin user account has them, or you possibly have a personal administrative account. (To increase cell security, it is best to create special privileged accounts for use only while performing administrative procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog command to authenticate.

          % klog admin_user
          Password: <admin_password>

   The following list specifies the necessary privileges and indicates how to check that you have them.

   - Membership in the system:administrators group. If necessary, issue the pts membership command, which is fully described in To display the members of the system:administrators group.

            % pts membership system:administrators

   - Inclusion in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

            % bos listusers <machine name>

   - The `ADMIN` flag on your Authentication Database entry. However, the Authentication Server performs its own authentication, so in Step 4 you specify an administrative identity on the kas command line itself.

   - The i (insert) and a (administer) permissions on the ACL of the directory where you are mounting the user's volume. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

            % fs listacl [<dir/file path>]

     Members of the system:administrators group always implicitly have the a (administer) and by default also the l (lookup) permission on every ACL and can use the fs setacl command to grant other rights as necessary.

   - Knowledge of the password for the local superuser root.

3. Issue the pts createuser command to create an entry in the Protection Database. For a discussion of setting AFS UIDs, see Assigning AFS and UNIX UIDs that Match. If you are converting an existing UNIX account into an AFS account, also see Converting Existing UNIX Accounts.

          % pts createuser <user name> [<user id>]

   where

   cu

     Is an acceptable alias for createuser (and createu is the shortest acceptable abbreviation).

   user name

     Specifies the user's username (the character string typed at login). It is best to limit the name to eight or fewer lowercase letters, because many application programs impose that limit. The AFS servers themselves accept names of up to 63 lowercase letters. Also avoid the following characters: colon (:), semicolon (;), comma (,), at sign (@), space, newline, and the period (.), which is conventionally used only in special administrative names.

   user id

     Is optional and appropriate only if the user already has a UNIX UID that the AFS UID must match. If you do not provide this argument, the Protection Server assigns one automatically based on the counter described in Displaying and Setting the AFS UID and GID Counters. If the ID you specify is less than 1 (one) or is already in use, an error results.

4. Issue the kas create command to create an entry in the Authentication Database. To avoid having the user's temporary initial password echo visibly on the screen, omit the -initial_password argument; instead enter the password at the prompts that appear when you omit the argument, as shown in the following syntax specification.

   The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the `ADMIN` flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

          % kas create <name of user> \
                       -admin  <admin principal to use for authentication>
          Administrator's (admin_user) password: <admin_password>
          initial_password: <initial_password>
          Verifying, please re-enter initial_password: <initial_password>

   where

   cr

     Is the shortest acceptable abbreviation for create.

   name of user

     Specifies the same username as in Step 3.

   -admin

     Names an administrative account that has the `ADMIN` flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

   initial_password

     Specifies the initial password as a string of eight characters or less, to comply with the length restriction that some applications impose. Possible choices for an initial password include the username, a string of digits from a personal identification number such as the Social Security number, or a standard string such as changeme. Instruct the user to change the string to a truly secret password as soon as possible by using the kpasswd command as described in the IBM AFS User Guide.

5. Issue the vos create command to create the user's volume.

          % vos create <machine name> <partition name> <volume name>  \
                       [-maxquota <initial quota (KB)>]

   where

   cr

     Is the shortest acceptable abbreviation of create.

   machine name

     Names the file server machine on which to place the new volume.

   partition name

     Names the partition on which to place the new volume.

   volume name

     Names the new volume. The name can include up to 22 characters. By convention, user volume names have the form user.username, where username is the name assigned in Step 3.

   -maxquota

     Sets the volume's quota, as a number of kilobyte blocks. If you omit this argument, the default is 5000 KB.

6. Issue the fs mkmount command to mount the volume in the filespace and create the user's home directory.

          % fs mkmount <directory> <volume name>

   where

   mk

     Is the shortest acceptable abbreviation for mkmount.

   directory

     Names the mount point to create. A directory of the same name must not already exist. Partial pathnames are interpreted relative to the current working directory. By convention, user home directories are mounted in a directory called something like /afs/.cellname/usr, and the home directory name matches the username assigned in Step 3.

     Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create the new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the pathname's second level (for example, /afs/.example.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.

   volume name

     Is the name of the volume created in Step 5.

7. (Optional) Issue the fs setvol command with the -offlinemsg argument to record auxiliary information about the volume in its volume header. For example, you can record who owns the volume or where you have mounted it in the filespace. To display the information, use the fs examine command.

          % fs setvol <dir/file path> -offlinemsg <offline message>

   where

   sv

     Is an acceptable alias for setvol (and setv the shortest acceptable abbreviation).

   dir/file path

     Names the mount point of the volume with which to associate the message. Partial pathnames are interpreted relative to the current working directory.

     Specify the read/write path to the mount point, to avoid the failure that results when you attempt to change a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the pathname's second level (for example, /afs/.example.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.

   -offlinemsg

     Specifies up to 128 characters of auxiliary information to record in the volume header.

8. Issue the fs setacl command to set the ACL on the new home directory. At the least, create an entry that grants all permissions to the user, as shown.

   You can also use the command to edit or remove the entry that the vos create command automatically places on the ACL for a new volume's root directory, which grants all permissions to the system:administrators group. Keep in mind that even if you remove the entry, the members of the group by default have implicit a (administer) and by default l (lookup) permissions on every ACL, and can grant themselves other permissions as required.

   For detailed instructions for the fs setacl command, see Setting ACL Entries.

          % fs setacl <directory> -acl <user name> all \
                      [system:administrators desired_permissions]

9. (Optional) Create configuration files and subdirectories in the new home directory. Possibilities include .login and .logout files, a shell-initialization file such as .cshrc, files to help with printing and mail delivery, and so on.

   If you are converting an existing UNIX account into an AFS account, you possibly wish to move some files and directories into the user's new AFS home directory. See Converting Existing UNIX Accounts.

10. (Optional) In the new .login or shell initialization file, define the user's $PATH environment variable to include the directories where AFS binaries are kept (for example, the /usr/afsws/bin and /usr/afsws/etc directories).

11. In Step 12 and Step 14, you must know the user's AFS UID. If you had the Protection Server assign it in Step 3, you probably do not know it. If necessary, issue the pts examine command to display it.

           % pts examine <user or group name or id>

    where

    e

      Is the shortest acceptable abbreviation of examine.

    user or group name or id

      Is the username that you assigned in Step 3.

    The first line of the output displays the username and AFS UID. For further discussion and an example of the output, see Displaying Information from the Protection Database.

12. Designate the user as the owner of the home directory and any files and subdirectories created or moved in Step 9. Specify the owner by the AFS UID you learned in Step 11 rather than by username. This is necessary for new accounts because the user does not yet have an entry in your local machine's password file (/etc/passwd or equivalent). If you are converting an existing UNIX account, an entry possibly already exists, but the UID is possibly incorrect. In that case, specifying a username means that the corresponding (possibly incorrect) UID is recorded as the owner.

    Some operating systems allow only the local superuser root to issue the chown command. If necessary, issuing the su command before the chown command.

           % chown new_owner_ID  directory

    where

    new_owner_ID

      Is the user's AFS UID, which you learned in Step 11.

    directory

      Names the home directory you created in Step 6, plus each subdirectory or file you created in Step 9.

13. If the new user home directory resides in a replicated volume, use the vos release command to release the volume, as described in To replicate a read/write volume (create a read-only volume).

           % vos release <volume name or ID>

    This step can be necessary even if the home directory's parent directory is not itself a mount point for a replicated volume (and is easier to overlook in that case). Suppose, for example, that the Example Corporation puts the mount points for user volumes in the /afs/example.com/usr directory. Because that is a regular directory rather than a mount point, it resides in the root.cell volume mounted at the /afs/example.com directory. That volume is replicated, so after changing it by creating a new mount point the administrator must issue the vos release command.

14. Create or modify an entry for the new user in the local password file (/etc/passwd or equivalent) of each machine the user can log onto. Remember to make the UNIX UID the same as the AFS UID you learned in Step 11, and to fill the password field appropriately (for instructions, see Specifying Passwords in the Local Password File).

## Improving Password and Authentication Security

AFS provides several optional features than can help to protect your cell's filespace against unauthorized access. The following list summarizes them, and instructions follow.

- Limit the number of consecutive failed login attempts.

  One of the most common ways for an unauthorized user to access your filespace is to guess an authorized user's password. This method of attack is most dangerous if the attacker can use many login processes in parallel or use the RPC interfaces directly.

  To protect against this type of attack, use the -attempts argument to the kas setfields command to limit the number of times that a user can consecutively fail to enter the correct password when using either an AFS-modified login utility or the klog command. When the limit is exceeded, the Authentication Server locks the user's Authentication Database entry (disallows authentication attempts) for a period of time that you define with the -locktime argument to the kas setfields command. If desired, system administrators can use the kas unlock command to unlock the entry before the complete lockout time passes.

  In certain circumstances, the mechanism used to enforce the number of failed authentication attempts can cause a lockout even though the number of failed attempts is less than the limit set by the -attempts argument. Client-side authentication programs such as klog and an AFS-modified login utility normally choose an Authentication Server at random for each authentication attempt, and in case of a failure are likely to choose a different Authentication Server for the next attempt. The Authentication Servers running on the various database server machines do not communicate with each other about how many times a user has failed to provide the correct password to them. Instead, each Authentication Server maintains its own separate copy of the auxiliary database file kaserverauxdb (located in the /usr/afs/local directory by default), which records the number of consecutive authentication failures for each user account and the time of the most recent failure. This implementation means that on average each Authentication Server knows about only a fraction of the total number of failed attempts. The only way to avoid allowing more than the number of attempts set by the -attempts argument is to have each Authentication Server allow only some fraction of the total. More specifically, if the limit on failed attempts is f, and the number of Authentication Servers is S, then each Authentication Server can only permit a number of attempts equal to f divided by S (the Ubik synchronization site for the Authentication Server tracks any remainder, f mod S).

  Normally, this implementation does not reduce the number of allowed attempts to less than the configured limit (f). If one Authentication Server refuses an attempt, the client contacts another instance of the server, continuing until either it successfully authenticates or has contacted all of the servers. However, if one or more of the Authentication Server processes is unavailable, the limit is effectively reduced by a percentage equal to the quantity U divided by S, where U is the number of unavailable servers and S is the number normally available.

  To avoid the undesirable consequences of setting a limit on failed authentication attempts, note the following recommendations:

  - Do not set the -attempts argument (the limit on failed authentication attempts) too low. A limit of nine failed attempts is recommended for regular user accounts, to allow three failed attempts per Authentication Server in a cell with three database server machines.

  - Set fairly short lockout times when including the -locktime argument. Although guessing passwords is a common method of attack, it is not a very sophisticated one. Setting a lockout time can help discourage attackers, but excessively long times are likely to be more of a burden to authorized users than to potential attackers. A lockout time of 25 minutes is recommended for regular user accounts.

  - Do not assign an infinite lockout time on an account (by setting the -locktime argument to 0 [zero]) unless there is a highly compelling reason. Such accounts almost inevitably become locked at some point, because each Authentication Server never resets the account's failure counter in its copy of the kaauxdb file (in contrast, when the lockout time is not infinite, the counter resets after the specified amount of time has passed since the last failed attempt to that Authentication Server). Furthermore, the only way to unlock an account with an infinite lockout time is for an administrator to issue the kas unlock command. It is especially dangerous to set an infinite lockout time on an administrative account; if all administrative accounts become locked, the only way to unlock them is to shut down all instances of the Authentication Server and remove the kaauxdb file on each.

  In summary, the recommended limit on authentication attempts is nine and lockout time 25 minutes.

- Limit password lifetime.

  The longer a password is in use, the more time an attacker has to try to learn it. To protect against this type of attack, use the -pwexpires argument to the kas setfields command to limit how many days a user's password is valid. The user becomes unable to authenticate with AFS after the password expires, but has up to 30 days to use the kpasswd command to set a new password. After the 30 days pass, only an administrator who has the `ADMIN` flag on the Authentication Database entry can change the password.

  If you set a password lifetime, many AFS-modified login utilities (but not the klog command) set the PASSWORD_EXPIRES environment variable to the number of days remaining until the password expires. A setting of zero means that the password expires today. If desired, you can customize your users' login scripts to display the number of days remaining before expiration and even prompt for a password change when a small number of days remain before expiration.

- Prohibit reuse of passwords.

  Forcing users to select new passwords periodically is not effective if they simply set the new password to the current value. To prevent a user from setting a new password to a string similar to any of the last 20 passwords, use the -reuse argument to the kas setfields command.

  If you prohibit password reuse and the user specifies an excessively similar password, the Authentication Server generates the following message to reject it:

         Password was not changed because it seems like a reused password

  A persistent user can try to bypass this restriction by changing the password 20 times in quick succession (or running a script to do so). If you believe this is likely to be a problem, you can include the -minhours argument to the kaserver initialization command (for details, see the command's reference page in the OpenAFS Administration Reference. If the user attempts to change passwords too frequently, the following message appears.

         Password was not changed because you changed it too recently; see
         your systems administrator

- Check the quality of new passwords.

  You can impose a minimum quality standard on passwords by writing a script or program called kpwvalid. If the kpwvalid file exists, the kpasswd and kas setpassword command interpreters invoke it to check a new password. If the password does not comply with the quality standard, the kpwvalid program returns an appropriate code and the command interpreter rejects the password.

  The kpwvalid file must be executable, must reside in the same AFS directory as the kpasswd and kas binaries, and its directory's ACL must grant the w (write) permission only to the system:administrators group.

  If you choose to write a kpwvalid program, consider imposing standards such as the following.

  - A minimum length

  - Words found in the dictionary are prohibited

  - Numbers, punctuation, or both must appear along with letters

  The AFS distribution includes an example kpwvalid program. See the kpwvalid reference page in the OpenAFS Administration Reference.

### To limit the number of consecutive failed authentication attempts

1. Issue the kas setfields command with the -attempts and -locktime arguments.

   The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the `ADMIN` flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

          % kas setfields <name of user>  \
                          -admin <admin principal to use for authentication>  \
                          -attempts <maximum successive failed login tries ([0..254])>  \
                          -locktime <failure penalty [hh:mm or minutes]>
          Administrator's (admin_user) password: <admin_password>

   where

   name of user

     Names the Authentication Database entry to edit.

   -admin

     Names an administrative account that has the `ADMIN` flag on its Authentication Database entry, such as the admin account. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

   -attempts

     Specifies the maximum consecutive number of times that a user can fail to provide the correct password during authentication (via the klog command or an AFS-modified login utility) before the Authentication Server refuses further attempts for the amount of time specified by the -locktime argument. The range of valid values is 0 (zero) through 254. If you omit this argument or specify 0, the Authentication Server allows an unlimited number of failures.

   -locktime

     Specifies how long the Authentication Server refuses authentication attempts after the user exceeds the failure limit specified by the -attempts argument.

     Specify a time in either hours and minutes (hh:mm) or minutes only (mm), from the range 01 (one minute) through 36:00 (36 hours). The kas command interpreter automatically reduces any larger value to 36:00 and also rounds up each nonzero value to the next-higher multiple of 8.5 minutes.

     It is best not to provide a value of 0 (zero), especially on administrative accounts, because it sets an infinite lockout time. An administrator must always issue the kas unlock command to unlock such an account.

### To unlock a locked user account

1. Issue the kas command to enter interactive mode.

   The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the `ADMIN` flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

          % kas -admin <admin principal to use for authentication>
          Administrator's (admin_user) password: <admin_password>
          ka>

   where -admin names an administrative account that has the `ADMIN` flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

2. Issue the (kas) examine command to verify that the user's account is in fact locked, as indicated by the message shown:

          ka> examine <name of user>
          User is locked until time

3. Issue the (kas) unlock command to unlock the account.

          ka> unlock <authentication ID>

   where

   u

     Is the shortest acceptable abbreviation of unlock.

   authentication ID

     Names the Authentication Database entry to unlock.

### To set password lifetime

1. Issue the kas setfields command with the -pwexpires argument.

   The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the `ADMIN` flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

          % kas setfields <name of user>  \
                          -pwexpires <number days password is valid  [0..254])>  \
                          -admin <admin principal to use for authentication>
          Administrator's (admin_user) password: <admin_password>

   where

   name of user

     Specifies the Authentication Database entry on which to impose a password expiration.

   -pwexpires

     Sets the number of days after the user's password was last changed that it remains valid. Provide an integer from the range 1 through 254 to specify the number of days until expiration.

     When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in which to issue the kpasswd or kas setpassword command to change the password (after that, only an administrator can change it). Note that the clock starts at the time the password was last changed, not when the kas setfields command is issued. To avoid retroactive expiration, have the user change the password just before issuing the command.

   -admin

     Names an administrative account that has the `ADMIN` flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

### To prohibit reuse of passwords

1. Issue the kas setfields command with the -reuse argument.

   The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the `ADMIN` flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

          % kas setfields <name of user> -reuse < permit password reuse (yes/no)>  \
                          -admin <admin principal to use for authentication>
          Administrator's (admin_user) password: <admin_password>

   where

   name of user

     Names the Authentication Database entry for which to set the password reuse policy.

   -reuse

     Specifies whether the Authentication Server allows reuse of passwords similar to any of the user's last 20 passwords. Specify the value no to prohibit reuse, or the value yes to reinstate the default of allowing password reuse.

   -admin

     Names an administrative account that has the `ADMIN` flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

## Changing AFS Passwords

After setting an initial password during account creation, you normally do not need to change user passwords, since they can use the kpasswd command themselves by following the instructions in the OpenAFS User Guide. In the rare event that a user forgets the password or otherwise cannot log in, you can use the kas setpassword command to set a new password.

If entries in the local password file (/etc/passwd or equivalent) have actual scrambled passwords in their password field, remember to change the password there also. For further discussion, see Specifying Passwords in the Local Password File.

### To change an AFS password

1. Issue the kas setpassword command to change the password. To avoid having the new password echo visibly on the screen, omit the -new_password argument; instead enter the password at the prompts that appear when you omit the argument, as shown.

   The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the `ADMIN` flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

          % kas setpassword <name of user>  \
                            -admin <admin principal to use for authentication>
          Administrator's (admin_user) password: <admin_password>
          new_password: <new_password>
          Verifying, please re-enter new_password: <new_password>

   where

   sp

     Is an acceptable alias for setpassword (setp is the shortest acceptable abbreviation).

   name of user

     Names the Authentication Database entry for which to set the password.

   -admin

     Names an administrative account that has the `ADMIN` flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

   new_password

     Specifies the user's new password. It is subject to the restrictions imposed by the kpwvalid program, if you use it.

## Displaying and Setting the Quota on User Volumes

User volumes are like all other volumes with respect to quota. Each new AFS volume has a default quota of 5000 KB, unless you use the -maxquota argument to the vos create command to set a different quota. You can also use either of the following commands to change quota at any time:

- fs setquota

- fs setvol

You can use any of the three following commands to display a volume's quota:

- fs quota

- fs listquota

- fs examine

For instructions, see Setting and Displaying Volume Quota and Current Size.

## Changing Usernames

By convention, many components of a user account incorporate the username, including the Protection and Authentication Database entries, the volume name and the home directory name. When changing a username, it is best to maintain consistency by changing the names of all components, so the procedure for changing a username has almost as many steps as the procedure for creating a new user account.

### To change a username

1. Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the admin user account has them, or you possibly have a personal administrative account. (To increase cell security, it is best to create special privileged accounts for use only while performing administrative procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog command to authenticate.

          % klog admin_user
          Password: <admin_password>

   The following list specifies the necessary privileges and indicates how to check that you have them.

   - Membership in the system:administrators group. If necessary, issue the pts membership command, which is fully described in To display the members of the system:administrators group.

            % pts membership system:administrators

   - Inclusion in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

            % bos listusers <machine name>

   - The `ADMIN` flag on the Authentication Database entry. However, the Authentication Server performs its own authentication, so the following instructions direct you to specify an administrative identity on the kas command line itself.

   - The a (administer), d (delete), and i (insert) permissions on the ACL of the directory where you are removing the current mount point and creating a new one. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

            % fs listacl [<dir/file path>]

     Members of the system:administrators group always implicitly have the a (administer) and by default also the l (lookup) permission on every ACL and can use the fs setacl command to grant other rights as necessary.

2. Issue the pts listowned command to display the names of the groups the user owns. After you change the username in the Protection Database in Step 3, you must issue the pts rename command to change each group's owner prefix to match the new name, because the Protection Server does not automatically make this change. For a complete description of the pts listowned command, see Displaying Information from the Protection Database.

          % pts listowned <user or group name or id>

3. Issue the pts rename command to change the user's name in the Protection Database.

          % pts rename <old name> <new name>

4. Issue the pts rename command to change the group names you noted in Step 2, so that their owner prefix (the part of the group name before the colon) accurately reflects the owner's new name.

   Repeat the command for each group. Step 3 details its syntax.

          % pts rename <old name> <new name>

5. Issue the kas command to enter interactive mode.

   The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the `ADMIN` flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

          % kas -admin <admin principal to use for authentication>
          Administrator's (admin_user) password: <admin_password>
          ka>

   where -admin names an administrative account that has the `ADMIN` flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

6. Issue the (kas) delete command to delete the user's existing Authentication Database entry.

          ka> delete <name of user>

   where

   del

     Is the shortest acceptable abbreviation for delete, or you can use the alias rm.

   name of user

     Names the Authentication Database entry to delete.

7. Issue the (kas) create command to create an Authentication Database entry for the new username. To avoid having the user's password echo visibly on the screen, do not include the -initial_password argument; instead enter the password at the prompts that appear in that case, as shown in the following syntax specification.

          ka> create  <name of user>
          initial_password: <password>
          Verifying, please re-enter initial_password: <password>

   where

   cr

     Is the shortest acceptable abbreviation for create.

   name of user

     Specifies the new username.

   password

     Specifies the password for the new user account. If the user is willing to tell you his or her current password, you can retain it. Otherwise, provide a string of eight characters or less to comply with the length restriction that some applications impose. Possible choices for an initial password include the username, a string of digits from a personal identification number such as the Social Security number, or a standard string such as changeme. Instruct the user to change the string to a truly secret password as soon as possible by using the kpasswd command as instructed in the OpenAFS User Guide.

8. Issue the quit command to leave interactive mode.

          ka> quit

9. Issue the vos rename command to change the name of the user's volume. For complete syntax, see To rename a volume.

          % vos rename  <old volume name>  <new volume name>

10. Issue the fs rmmount command to remove the existing mount point. For the directory argument, specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete a mount point from a read-only volume.

           % fs rmmount <directory>

11. Issue the fs mkmount command to create a mount point for the volume's new name. Specify the read/write path to the mount point for the directory argument, as in the previous step. For complete syntax, see Step 6 in To create one user account with individual commands.

           % fs mkmount <directory> <volume name>

12. If the changes you made in Step 10 and Step 11 are to a mount point that resides in a replicated volume, use the vos release command to release the volume, as described in To replicate a read/write volume (create a read-only volume).

           % vos release <volume name or ID>

    This step can be necessary even if the home directory's parent directory is not itself a mount point for a replicated volume (and is easier to overlook in that case). For example, the Example Corporation template puts the mount points for user volumes in the /afs/example.com/usr directory. Because that is a regular directory rather than a mount point, it resides in the root.cell volume mounted at the /afs/example.com directory. That volume is replicated, so after changing it the administrator must issue the vos release command.

## Removing a User Account

Before removing an account, it is best to make a backup copy of the user's home volume on a permanent storage medium such as tape. If you need to remove several accounts, it is probably more efficient to use the uss delete command instead; see Deleting Individual Accounts with the uss delete Command.

### To remove a user account

1. Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the admin user account has them, or you possibly have a personal administrative account. (To increase cell security, it is best to create special privileged accounts for use only while performing administrative procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog command to authenticate.

          % klog admin_user
          Password: <admin_password>

   The following list specifies the necessary privileges and indicates how to check that you have them.

   - Membership in the system:administrators group. If necessary, issue the pts membership command, which is fully described in To display the members of the system:administrators group.

            % pts membership system:administrators

   - Inclusion in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

            % bos listusers <machine name>

   - The `ADMIN` flag on the Authentication Database entry. However, the Authentication Server performs its own authentication, so the following instructions direct you to specify an administrative identity on the kas command line itself.

   - The d (delete) permission on the ACL of the directory where you are removing the user volume's mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

            % fs listacl [<dir/file path>]

     Members of the system:administrators group always implicitly have the a (administer) and by default also the l (lookup) permission on every ACL and can use the fs setacl command to grant other rights as necessary.

2. (Optional) If it is possible you need to restore the user's account someday, note the username and AFS UID, possibly in a file designated for that purpose. You can later restore the account with its original AFS UID.

3. (Optional) Copy the contents of the user's volume to tape. You can use the vos dump command as described in Dumping and Restoring Volumes or the AFS Backup System as described in Backing Up Data.

4. (Optional) If you intend to remove groups that the user owns from the Protection Database after removing the user's entry, issue the pts listowned command to display them. For complete instructions, see Displaying Information from the Protection Database.

          % pts listowned <user or group name or id>

5. (Optional) Issue the pts delete command to remove the groups the user owns. However, if it is likely that other users have placed the groups on the ACLs of directories they own, it is best not to remove them.

          % pts delete <user or group name or id>+

   where

   del

     Is the shortest acceptable abbreviation for delete.

   user or group name or id

     Specifies the name or AFS UID of each group displayed in the output from Step 4.

6. Issue the kas delete command to remove the user's Authentication Database entry.

   The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the `ADMIN` flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

          % kas delete <name of user>  \
                       -admin  <admin principal to use for authentication>
          Administrator's (admin_user) password: <admin_password>

   where

   d

     Is the shortest acceptable abbreviation for delete.

   name of user

     Names the Authentication Database entry to delete.

   -admin

     Names an administrative account that has the `ADMIN` flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

7. Issue the vos listvldb command to display the site of the user's home volume in preparation for removing it. By convention, user volumes are named user.username.

          % vos listvldb <volume name or ID>

   where

   listvl

     Is the shortest acceptable abbreviation of listvldb.

   volume name or ID

     Specifies the volume's name or volume ID number.

8. Issue the vos remove command to remove the user's volume. It automatically removes the backup version of the volume, if it exists. It is not conventional to replicate user volumes, so the command usually also completely removes the volume's entry from the Volume Location Database (VLDB). If there are ReadOnly replicas of the volume, you must repeat the vos remove command to remove each one individually.

          % vos remove <machine name> <partition name> <volume name or ID>

   where

   remo

     Is the shortest acceptable abbreviation of remove.

   machine name

     Names the file server machine that houses the volume, as specified in the output from Step 7.

   partition name

     Names the partition that houses the volume, as specified in the output from Step 7.

   volume name or ID

     Specifies the volume's name or ID number.

9. Issue the fs rmmount command to remove the volume's mount point.

   If you mounted the user's backup volume as a subdirectory of the home directory, then this command is sufficient to unmount the backup version as well. If you mounted the backup version at an unrelated location in the filespace, repeat the fs rmmount command for it.

          % fs rmmount <directory>

   where

   rmm

     Is the shortest acceptable abbreviation of rmmount.

   directory

     Names the mount point for the volume's previous name (the former home directory). Partial pathnames are interpreted relative to the current working directory.

     Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the pathname's second level (for example, /afs/.example.com). For further discussion of the concept of read/write and read-only paths through the filespace, see Mounting Volumes.

10. Issue the pts delete command to remove the user's Protection Database entry. A complete description of this command appears in Step 5.

           % pts delete <user or group name or id>

11. If the deleted user home directory resided in a replicated volume, use the vos release command to release the volume, as described in To replicate a read/write volume (create a read-only volume).

           % vos release <volume name or ID>

    This step can be necessary even if the home directory's parent directory is not itself a mount point for a replicated volume (and is easier to overlook in that case). For example, the Example Corporation template puts the mount points for user volumes in the /afs/example.com/usr directory. Because that is a regular directory rather than a mount point, it resides in the root.cell volume mounted at the /afs/example.com directory. That volume is replicated, so after changing it by deleting a mount point the administrator must issue the vos release command.