Configuring AFS User Accounts
| Chapter 2. Issues in Cell Configuration and Administration |

## Configuring AFS User Accounts

This section discusses some of the issues to consider when configuring AFS user accounts. Because AFS is separate from the UNIX file system, a user's AFS account is separate from her UNIX account.

The preferred method for creating a user account is with the uss suite of commands. With a single command, you can create all the components of one or many accounts, after you have prepared a template file that guides the account creation. See Creating and Deleting User Accounts with the uss Command Suite.

Alternatively, you can issue the individual commands that create each component of an account. For instructions, along with instructions for removing user accounts and changing user passwords, user volume quotas and usernames, see Administering User Accounts.

When users leave your system, it is often good policy to remove their accounts. Instructions appear in Deleting Individual Accounts with the uss delete Command and Removing a User Account.

An AFS user account consists of the following components, which are described in greater detail in The Components of an AFS User Account.

- A Protection Database entry

- An Authentication Database entry

- A volume

- A home directory at which the volume is mounted

- Ownership of the home directory and full permissions on its ACL

- An entry in the local password file (/etc/passwd or equivalent) of each machine the user needs to log into

- Optionally, standard files and subdirectories that make the account more useful

By creating some components but not others, you can create accounts at different levels of functionality, using either uss commands as described in Creating and Deleting User Accounts with the uss Command Suite or individual commands as described in Administering User Accounts. The levels of functionality include the following

- An authentication-only account enables the user to obtain AFS tokens and so to access protected AFS data and to issue privileged commands. It consists only of entries in the Authentication and Protection Database. This type of account is suitable for administrative accounts and for users from foreign cells who need to access protected data. Local users generally also need a volume and home directory.

- A basic user account includes a volume for the user, in addition to Authentication and Protection Database entries. The volume is mounted in the AFS filespace as the user's home directory, and provides a repository for the user's personal files.

- A full account adds configuration files for basic functions such as logging in, printing, and mail delivery to a basic account, making it more convenient and useful. For a discussion of some useful types of configuration files, see Creating Standard Files in New AFS Accounts.

If your users have UNIX user accounts that predate the introduction of AFS in the cell, you possibly want to convert them into AFS accounts. There are three main issues to consider:

- Making UNIX and AFS UIDs match

- Setting the password field in the local password file appropriately

- Moving files from the UNIX file system into AFS

For further discussion, see Converting Existing UNIX Accounts with uss or Converting Existing UNIX Accounts.

### Choosing Usernames and Naming Other Account Components

This section suggests schemes for choosing usernames, AFS UIDs, user volume names and mount point names, and also outlines some restrictions on your choices.

Usernames. AFS imposes very few restrictions on the form of usernames. It is best to keep usernames short, both because many utilities and applications can handle usernames of no more than eight characters and because by convention many components of and AFS account incorporate the name. These include the entries in the Protection and Authentication Databases, the volume, and the mount point. Depending on your electronic mail delivery system, the username can become part of the user's mailing address. The username is also the string that the user types when logging in to a client machine.

Some common choices for usernames are last names, first names, initials, or a combination, with numbers sometimes added. It is also best to avoid using the following characters, many of which have special meanings to the command shell.

- The comma (,)

- The colon (:), because AFS reserves it as a field separator in protection group names; see The Two Types of User-Defined Groups

- The semicolon (;)

- The "at-sign" (@); this character is reserved for Internet mailing addresses

- Spaces

- The newline character

- The period (.); it is conventional to use this character only in the special username that an administrator adopts while performing privileged tasks, such as pat.admin

AFS UIDs and UNIX UIDs. AFS associates a unique identification number, the AFS UID, with every username, recording the mapping in the user's Protection Database entry. The AFS UID functions within AFS much as the UNIX UID does in the local file system: the AFS server processes and the Cache Manager use it internally to identify a user, rather than the username.

Every AFS user also must have a UNIX UID recorded in the local password file (/etc/passwd or equivalent) of each client machine they log onto. Both administration and a user's AFS access are simplest if the AFS UID and UNIX UID match. One important consequence of matching UIDs is that the owner reported by the ls -l command matches the AFS username.

It is usually best to allow the Protection Server to allocate the AFS UID as it creates the Protection Database entry. However, both the pts createuser command and the uss commands that create user accounts enable you to assign AFS UIDs explicitly. This is appropriate in two cases:

- You wish to group together the AFS UIDs of related users

- You are converting an existing UNIX account into an AFS account and want to make the AFS UID match the existing UNIX UID

After the Protection Server initializes for the first time on a cell's first file server machine, it starts assigning AFS UIDs at a default value. To change the default before creating any user accounts, or at any time, use the pts setmax command to reset the `max user id counter`. To display the counter, use the pts listmax command. See Displaying and Setting the AFS UID and GID Counters.

AFS reserves one AFS UID, 32766, for the user anonymous. The AFS server processes assign this identity and AFS UID to any user who does not possess a token for the local cell. Do not assign this AFS UID to any other user or hardcode its current value into any programs or a file's owner field, because it is subject to change in future releases.

User Volume Names. Like any volume name, a user volume's base (read/write) name cannot exceed 22 characters in length or include the .readonly or .backup extension. See Creating Volumes to Simplify Administration. By convention, user volume names have the format user.username. Using the user. prefix not only makes it easy to identify the volume's contents, but also to create a backup version of all user volumes by issuing a single vos backupsys command.

Mount Point Names. By convention, the mount point for a user's volume is named after the username. Many cells follow the convention of mounting user volumes in the /afs/`cellname`/usr directory, as discussed in The Third Level. Very large cells sometimes find that mounting all user volumes in the same directory slows directory lookup, however; for suggested alternatives, see the following section.

### Grouping Home Directories

Mounting user volumes in the /afs/`cellname`/usr directory is an AFS-appropriate variation on the standard UNIX practice of putting user home directories under the /usr subdirectory. However, cells with more than a few hundred users sometimes find that mounting all user volumes in a single directory results in slow directory lookup. The solution is to distribute user volume mount points into several directories; there are a number of alternative methods to accomplish this.

- Distribute user home directories into multiple directories that reflect organizational divisions, such as academic or corporate departments. For example, a company can create group directories called usr/marketing, usr/research, usr/finance. A good feature of this scheme is that knowing a user's department is enough to find the user's home directory. Also, it makes it easy to set the ACL to limit access to members of the department only. A potential drawback arises if departments are of sufficiently unequal size that users in large departments experience slower lookup than users in small departments. This scheme is also not appropriate in cells where users frequently change between divisions.

- Distribute home directories into alphabetic subdirectories of the usr directory (the usr/a subdirectory, the usr/b subdirectory, and so on), based on the first letter of the username. If the cell is very large, create subdirectories under each letter that correspond to the second letter in the user name. This scheme has the same advantages and disadvantages of a department-based scheme. Anyone who knows the user's username can find the user's home directory, but users with names that begin with popular letters sometimes experience slower lookup.

- Distribute home directories randomly but evenly into more than one grouping directory. One cell that uses this scheme has over twenty such directories called the usr1 directory, the usr2 directory, and so on. This scheme is especially appropriate in cells where the other two schemes do not seem feasible. It eliminates the potential problem of differences in lookup speed, because all directories are about the same size. Its disadvantage is that there is no way to guess which directory a given user's volume is mounted in, but a solution is to create a symbolic link in the regular usr directory that references the actual mount point. For example, if user smith's volume is mounted at the /afs/bigcell.example.com/usr17/smith directory, then the /afs/bigcell.example.com/usr/smith directory is a symbolic link to the ../usr17/smith directory. This way, if someone does not know which directory the user smith is in, he or she can access it through the link called usr/smith; people who do know the appropriate directory save lookup time by specifying it.

For instructions on how to implement the various schemes when using the uss program to create user accounts, see Evenly Distributing User Home Directories with the G Instruction and Creating a Volume with the V Instruction.

### Making a Backup Version of User Volumes Available

Mounting the backup version of a user's volume is a simple way to enable users themselves to restore data they have accidentally removed or deleted. It is conventional to mount the backup version at a subdirectory of the user's home directory (called perhaps the OldFiles subdirectory), but other schemes are possible. Once per day you create a new backup version to capture the changes made that day, overwriting the previous day's backup version with the new one. Users can always retrieve the previous day's copy of a file without your assistance, freeing you to deal with more pressing tasks.

Users sometimes want to delete the mount point to their backup volume, because they erroneously believe that the backup volume's contents count against their quota. Remind them that the backup volume is separate, so the only space it uses in the user volume is the amount needed for the mount point.

For further discussion of backup volumes, see Backing Up AFS Data and Creating Backup Volumes.

### Creating Standard Files in New AFS Accounts

From your experience as a UNIX administrator, you are probably familiar with the use of login and shell initialization files (such as the .login and .cshrc files) to make an account easier to use.

It is often practical to add some AFS-specific directories to the definition of the user's `PATH` environment variable, including the following:

- The path to a bin subdirectory in the user's home directory for binaries the user has created (that is, /afs/`cellname`/usr/`username`/bin)

- The /usr/afsws/bin path, which conventionally includes programs like fs, klog, kpasswd, pts, tokens, and unlog

- The /usr/afsws/etc path, if the user is an administrator; it usually houses the AFS command suites that require privilege (the backup, butc, kas, uss, vos commands), and others.

If you are not using an AFS-modified login utility, it can be helpful to users to invoke the klog command in their .login file so that they obtain AFS tokens as part of logging in. In the following example command sequence, the first line echoes the string `klog` to the standard output stream, so that the user understands the purpose of the `Password:` prompt that appears when the second line is executed. The -setpag flag associates the new tokens with a process authentication group (PAG), which is discussed further in Identifying AFS Tokens by PAG.

        echo -n "klog " klog -setpag

The following sequence of commands has a similar effect, except that the pagsh command forks a new shell with which the PAG and tokens are associated.

        pagsh echo -n "klog " klog

If you use an AFS-modified login utility, this sequence is not necessary, because such utilities both log a user in locally and obtain AFS tokens.

Configuring Client Machines |  | Using AFS Protection Groups