![[Return to Library]](../books.gif)
![[Contents]](../toc.gif)
![[Previous Topic]](../prev.gif)
![[Bottom of Topic]](../bot.gif)
![[Next Topic]](../next.gif)
![[Index]](../index.gif)
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.
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 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.
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
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:
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:
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.
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.
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:
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.
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.
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:
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.
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.
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
% pts createuser <user name> [<user id>]
where
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
% vos create <machine name> <partition name> <volume name> \
[-maxquota <initial quota (KB)>]
where
% fs mkmount <directory> <volume name>
where
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/.abc.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.
% fs setvol <dir/file path> -offlinemsg <offline message>
where
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/.abc.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.
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]
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.
% pts examine <user or group name or id>
where
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.
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
% vos release <volume name or ID>
| Note: | 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 ABC Corporation puts the mount points for user volumes in the /afs/abc.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/abc.com directory. That volume is replicated, so after changing it by creating a new mount point the administrator must issue the vos release command. |
If you use the package utility to distribute a common version of the password file to all client machines, then you need to make the change only in the common version. See Configuring Client Machines with the package Program.
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.
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, fmodS).
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:
In summary, the recommended limit on authentication attempts is nine and lockout time 25 minutes.
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.
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 IBM AFS 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
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.
The AFS distribution includes an example kpwvalid program. See the kpwvalid reference page in the IBM AFS Administration Reference.
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
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.
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.
ka> examine <name of user> User is locked until time
ka> unlock <authentication ID>
where
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
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.
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
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 IBM AFS 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.
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
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:
You can use any of the three following commands to display a volume's quota:
For instructions, see Setting and Displaying Volume Quota and Current Size.
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.
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
% pts listowned <user or group name or id>
% pts rename <old name> <new name>
Repeat the command for each group. Step 3 details its syntax.
% pts rename <old name> <new name>
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.
ka> delete <name of user>
where
ka> create <name of user> initial_password: password Verifying, please re-enter initial_password: password
where
ka> quit
% vos rename <old volume name> <new volume name>
% fs rmmount <directory>
% fs mkmount <directory> <volume name>
% vos release <volume name or ID>
| Note: | 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 ABC Corporation template puts the mount points for user volumes in the /afs/abc.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/abc.com directory. That volume is replicated, so after changing it the administrator must issue the vos release command. |
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.
% klog admin_user Password: admin_password
The following list specifies the necessary privileges and indicates how to check that you have them.
% pts membership system:administrators
% bos listusers <machine name>
% 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.
% pts listowned <user or group name or id>
% pts delete <user or group name or id>+
where
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
% vos listvldb <volume name or ID>
where
% vos remove <machine name> <partition name> <volume name or ID>
where
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
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/.abc.com). For further discussion of the concept of read/write and read-only paths through the filespace, see Mounting Volumes.
% pts delete <user or group name or id>
% vos release <volume name or ID>
| Note: | 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 ABC Corporation template puts the mount points for user volumes in the /afs/abc.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/abc.com directory. That volume is replicated, so after changing it by deleting a mount point the administrator must issue the vos release command. |
![[Top of Topic]](../top.gif)