Creating Local Password File Entries with uss

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 AFS client machine. 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, the appropriate value to put in the file's password field, and outlines a method for creating a single source password file.

For instructions on using the template file's E instruction to generate local password file entries automatically as part of account creation, see Creating a Common Source Password File.

The following information also appears in a corresponding section of Administering User Accounts, 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 you are creating accounts for various types of users:

  • If creating an AFS account for a user who already has a UNIX UID, see Converting Existing UNIX Accounts with uss.

  • 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.

Creating a Common Source Password File

This section explains how to create a common source version of the local password file when using uss commands to create user accounts. The sequence of steps is as follows:

  1. Include an E instruction in the template file to create a one-line file that has the format of a local password file entry.

  2. Incorporate the one-line file into the common source version of the local password file. It makes sense to store this file in AFS. See the following two example scripts for automating this step.

As an example, the template file used by the Example Corporation includes the following E instruction to create a file called passwd_username in the directory /afs/ (the entire contents of the template file appear in Example uss Templates and a full description of the E instruction appears in Creating One-Line Files with the E Instruction):

   E /afs/$USER 0644 root \

For the user Joe L. Smith with username smith, this instruction creates a file called passwd_smith which contains the following line:

   smith:X:1205:11:Joe L. Smith:/afs/

A shell script is probably the easiest way to incorporate a set of files created in this manner into a common source password file, and two sample shell scripts appear here. To automate the process even further, you can create a cron process in a file server machine's /usr/afs/local/BosConfig directory to execute the shell script, perhaps each day at a given time; for details, see To create and start a new process.


The following example scripts are suggestions only. If you choose to use them, or to model similar scripts on them, you must test that your script has the desired result, preferably in a test environment.

Example C Shell Script

The first example is a simple C shell script suitable for the Example Corporation cell. It incorporates the individual files found in the /afs/ directory into a new version of the global password file found in the /afs/ directory, sorting the files into alphabetical order. It takes care to save the current version with a .old extension, then removes the individual files when done.

   set  dir = /afs/
   cat  $dir/uss/newaccts/passwd_* $dir/etc/passwd  >!  $dir/etc/
   mv  $dir/etc/passwd  $dir/etc/passwd.old
   sort  $dir/etc/  >  $dir/etc/passwd
   rm  $dir/etc/  $dir/uss/newaccts/passwd_*

Example Bourne Shell Script

The second, more elaborate, example is a Bourne shell script that first verifies that there are new passwd_username files to be incorporated into the global password file. While running, it checks that each new entry does not already exist. Like the shorter C shell example, it incorporates the individual files found in the /afs/ directory into a new version of the global passwd file found in the /afs/ directory.

   cd  $DESTDIR
   cp /afs/   /afs/
   echo "copied in passwd file."
   ENTRIES=`ls passwd_*`
   case $ENTRIES in 
        echo No new entry found to be added to passwd file
        echo  "Adding new users to passwd file."
        for  i  in  $ENTRIES
           cat  $i  |  awk  -F:  '{print $1  >  "foo"}'
           USER=`cat foo`
           case  `egrep  -e  \^$USER\: $PASSWD` in 
                   echo  adding  $USER
                   cat  $i  >>  $PASSWD
                   echo  $USER already in passwd file
           mv  $i  ../old.passdir/done_${i}
        cd  /afs/
        echo  "sorting password file"
        sort  ${PASSWD}  >  ${PASSWD}.sorted
        echo  "installing files"     
        install  ${PASSWD}.sorted ${DEST}/passwd
        echo  "Password file is built, sorted and installed."