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

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