| Overview of the uss Command Suite | ||
|---|---|---|
 | Chapter 11. Creating and Deleting User Accounts with the uss Command Suite |  |
| Overview of the uss Command Suite | ||
|---|---|---|
| | Chapter 11. Creating and Deleting User Accounts with the uss Command Suite | |
The commands in the uss suite help you to automate the creation and deletion of AFS user accounts:
The uss add command creates all of the components of an account, one account at a time. It consults a template file that defines account configuration.
The uss delete command deletes the major components of an account, one account at a time. It does not use a template file, so you possibly need to perform additional tasks manually.
The uss bulk command can create and delete multiple accounts. It refers to a bulk input file that can contain any number of account-creation and deletion instructions, along with other instructions for further automating the process.
An AFS user account can have many components. The only two required components are entries in the Protection Database and Authentication Database, but the other components add functionality and usability. The following information also appears in a corresponding section of Administering User Accounts, 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.
To issue uss commands successfully, you usually need all of the standard AFS
administrative privileges: membership in the system:administrators group, inclusion in the
/usr/afs/etc/UserList file on every relevant server machine, and the
ADMIN flag on your Authentication Database entry. For details on administrative privilege,
see Managing Administrative Privilege.
As for any complex operation, there are a number of possible reasons that an account-creation or deletion operation can halt before it completes. You can easily avoid several of the common reasons by making the following checks before issuing a uss command:
Verify that you have all of the administrative privileges you need to complete an operation, as described in Privilege Requirements for the uss Commands. The instructions for using the uss add, uss delete, and uss bulk commands include this check as a step.
Proofread the template and bulk input files for correct syntax and acceptable values. For discussion, see Constructing a uss Template File and Constructing a Bulk Input File.
Do not issue uss commands when you are aware of network, server machine, or server process outages. Because uss operations affect so many components of AFS, it is unlikely that the command can succeed when there are outages.
Another way to avoid errors that halt an operation is to preview the uss command by combining the -dryrun flag with the other arguments to be used on the actual command. The uss command interpreter generates a screen trace of the actions to be performed by the actual command, without performing them.
Using the -dryrun flag reveals many basic errors that can halt an operation, particularly the ones due to incorrect syntax in the command line, template file, or bulk input file. It does not catch all possible errors, however, because the command interpreter is not actually attempting to perform the actions it is tracing. For example, a Volume Server outage does not necessarily halt the volume creation step when the -dryrun flag is included, because the command interpreter is not actually contacting the server; such an outage halts the actual creation operation.
When the uss command interpreter encounters error conditions minor enough that they do
not require halting the operation, it usually generates a message that begins with the string uss:
Warning: and describes the action it is taking to avoid halting. For example, if a user's Protection Database
entry already exists, the following message appears on the standard output stream:
uss: Warning: User 'user' already in the protection database The uid for user 'user' is AFS UID
If an error is more serious, the word Warning does not appear in the message, which
instead describes why the command interpreter cannot perform the requested action. Not all of these errors cause the uss operation to halt, but they still require you to take corrective action. For example, attempting to
create a mount point fails if you lack the necessary permissions on the parent directory's ACL, or if the mount point pathname
in the V instruction's mount_point field is malformed. However, this error does not cause the
creation operation to halt until later instructions in the template attempt to install subdirectories or files under the
nonexistent mount point.
If the command shell prompts returns directly after an error message, then the error generally was serious enough to halt the operation. When an error halts account creation or deletion, the best way to recover is to find and fix the cause, and then reissue the same uss command.
The following list describes what happens when components of a user's account already exist when you reissue an account-creation command (the uss add command, or the uss bulk command when the bulk input file contains add instructions):
If the Protection Database entry already exists, a message confirms its existence and specifies the associated AFS UID.
If the Authentication Database entry already exists, a message confirms its existence.
If the volume and associated Volume Location Database (VLDB) entry already exist, a message confirms their existence. However, the uss command interpreter does alter the volume's quota, mount point, or ACL if any of the relevant fields in the template V instruction have changed since the command last ran. If the value in the mount_point field has changed, the command interpreter creates the new mount point but does not remove any existing mount points.
If any of the fields in the template A instruction have changed, the uss command interpreter makes the changes without comment.
If a directory, file, or link defined by a template file D, E, F, L, or S instruction already exists, the uss command interpreter replaces the existing element with one that conforms to the template definition. To control whether the uss command interpreter prompts for confirmation that you wish to overwrite a given element, use the -overwrite flag to the uss add or uss bulk command:
If you include the -overwrite flag, the command interpreter automatically overwrites all elements without asking for confirmation.
If you omit the flag, the command interpreter prompts once for each account to ask if you want to overwrite all elements associated with it.
The command interpreter always reexecutes X instructions in the template file. If a command's result already holds, reissuing it has the same effect as reissuing it outside the context of the uss commands.
The following describes what happens when a uss delete command references account components that have already been deleted.
If the volume and VLDB entry no longer exist, a message confirms their absence.
If the Authentication Database entry no longer exists, a message confirms its absence.
| |  | |
| Chapter 11. Creating and Deleting User Accounts with the uss Command Suite |  | Creating Local Password File Entries with uss |