Creating Individual Accounts with the uss add Command

Creating Individual Accounts with the uss add Command
	Chapter 11. Creating and Deleting User Accounts with the uss Command Suite

After you have created a template file, you can create an individual account by issuing the uss add command (for template creation instructions see Constructing a uss Template File). When you issue the command, the uss command interpreter contacts various AFS servers to perform the following actions:

Create a Protection Database entry. By default, the Protection Server assigns an AFS UID which becomes the value of the $UID variable used in the template.
Create an Authentication Database entry, recording an encrypted version of the initial password.
Create the account components defined in the indicated template file, contacting the File Server, Volume Server, and Volume Location (VL) Server as necessary.

To review which types of instructions to include in a template to create different file system objects, see Constructing a uss Template File. If the template is empty, the uss add command creates an authentication-only account consisting of Protection Database and Authentication Database entries.

When you issue the uss add command, provide a value for each variable in the template file by including the corresponding command-line argument. If you fail to supply a value for a variable, the uss command interpreter substitutes a null string, which usually causes the account creation to fail. If you include a command line argument for which the corresponding variable does not appear in the template, it is ignored.

Table 4 summarizes the mappings between variables and the arguments to the uss add command. It is adapted from Table 3, but includes only those variables that take their value from command line arguments.

Table 4. Command-line argument sources for uss template variables

Variable	Command-line Argument
$MTPT	-mount (for occurrence in V instruction)
$NAME	-realname if provided; otherwise -user
$PART	-partition
$PWEXPIRES	-pwexpires
$SERVER	-server
$UID	-uid if provided; otherwise allocated by Protection Server
$USER	-user
$1 through $9	-var

To create an AFS account with the uss add command

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 the Authentication Database entry. However, the Authentication Server always prompts you for a password in order to perform its own authentication. The following instructions direct you to specify the administrative identity on the uss command line itself.
- The i (insert) and l (lookup) permissions on the ACL of the directory in which 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.
(Optional) Log in as the local superuser root. This is necessary only if you are creating new files or directories in the local file system and want to designate an alternate owner as the object is created. For a discussion of the issues involved, see About Creating Local Disk Directories and Files.
Verify the location and functionality of the template file you are using. For a description of where the uss command interpreter expects to find the template, see Where to Place Template Files. You can always provide an alternate pathname if you wish. Also note the variables used in the template, to be sure that you provide the corresponding arguments on the uss command line.
(Optional) Change to the directory where the template resides. This affects the type of pathname you must type in Step 6.
```
   % cd template_directory
```
(Optional) Run the uss add command with the -dryrun flag to preview the creation of the account. Note any error messages and correct the cause before reissuing the command without the -dryrun flag. The next step describes the uss add command's syntax. For more information on the -dryrun flag, see Avoiding and Recovering from Errors and Interrupted Operations.
Issue the uss add command to create the account. Enter the command on a single line; it appears here on multiple lines only for legibility.
The uss add operation creates an Authentication Database entry. 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.
```
   % uss add -user <login name>  -admin <administrator to authenticate>   \
             [-realname <full name in quotes>] [-pass <initial passwd>]   \
             [-pwexpires <password expires in [0..254] days (0 => never)>]  \
             [-server <FileServer for home volume>]  \
             [-partition <FileServer's disk partition for home volume>]  \
             [-mount <home directory mount point>]  \
             [-uid <uid to assign the user>]  \
             [-template <pathname of template file>]  \
             [-var <auxiliary argument pairs (Numval)>+] [-dryrun] \
             [-overwrite] 
   Administrator's (admin_user) password: <admin_password>
```
where
ad
Is the shortest acceptable abbreviation of add.
-user
Names the user's Authentication Database and Protection Database entries. Because it becomes the username (the name under which a user logs in), it must obey the restrictions that many operating systems impose on usernames (usually, to contain no more than eight 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.
This argument provides the value for the $USER variable in the template file. For suggestions on standardizing usernames, see Choosing Usernames and Naming Other Account Components.
-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.
-realname
Specifies the user's actual full name. If it contains spaces or punctuation, surround it with double quotes. If you do not provide it, it defaults to the username provided with the -user argument.
This argument provides the value for the $NAME variable in the template file. For information about using this argument and variable as part of an automated process for creating entries in a local password file such as /etc/passwd, see Creating a Common Source Password File.
-pass
Specifies the user's initial password. Although the AFS commands that handle passwords accept strings of virtually unlimited length, it is best to use a password of eight characters or less, which is the maximum length that many applications and utilities accept.
Possible choices for initial passwords include the username, a string of digits such as those from a Social Security number, or a standard string such as changeme, which is the default if you do not provide this argument. There is no corresponding variable in the template file.
Instruct users to change their passwords to a truly secret string as soon as they authenticate with AFS for the first time. The OpenAFS User Guide explains how to use the kpasswd command to change an AFS password.
-pwexpires
Sets the number of days after a user's password is changed that it remains valid. Provide an integer from the range 1 through 254 to specify the number of days until expiration, or the value 0 to indicate that the password never expires (the default if you do not provide this argument). When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in which to issue the kpasswd command to change the password; after that, only an administrator can change it.
This argument provides the value for the $PWEXPIRES variable in the template file.
-server
Names the file server machine on which to create the new user's home volume. It is best to provide a fully qualified hostname (for example, fs1.example.com), but an abbreviated form is acceptable provided that the cell's naming service is available to resolve it when you issue the uss add command.
This argument provides the value for the $SERVER variable in the template file. To avoid having to type a fully qualified hostname on the command line, combine the $SERVER variable with a constant (for example, the cell's domain name) in the server field of the V instruction in the template file. For an example, see Creating a Volume with the V Instruction.
-partition
Specifies the partition on which to create the user's home volume; it must be on the file server machine named by the -server argument. Identify the partition by its complete name (for example, /vicepa), or use one of the abbreviations listed in Rules for Using Abbreviations and Aliases.
This argument provides the value for the $PART variable in the template file.
-mount
Specifies the pathname for the user's home directory in the cell's read/write filespace. Partial pathnames are interpreted relative to the current working directory.
This argument provides the value for the $MTPT variable in the template file, but only when it appears in the V instruction's mount_point field. When the $MTPT variable appears in any subsequent instructions, it takes its value from the V instruction's mount_point field, rather than directly from this argument. For more details, and for suggestions about how to use this argument and the $MTPT variable, see Creating a Volume with the V Instruction.
-uid
Specifies a positive integer other than 0 (zero) to assign as the user's AFS UID. It is best to omit this argument and allow the Protection Server to assign an AFS UID that is one greater than the current value of the max user id counter. (To display the counter, use the pts listmax command as described in To display the AFS ID counters.)
If you have a reason to use this argument (perhaps because the user already has a UNIX UID), first use the pts examine command to verify that there is no existing account with the desired AFS UID; if there is, the account creation process terminates with an error.
This argument provides the value for the $UID variable in the template file.
-template
Specifies the pathname of the template file. If you omit this argument, the command interpreter searches for a template file called uss.template in each of the following directories in turn:
The current working directory
/afs/cellname/common/uss, where cellname names the local cell
/etc
If you specify a filename other than uss.template but without a pathname, the command interpreter searches for it in the indicated directories. If you provide a full or partial pathname, the command interpreter consults the specified file only; it interprets partial pathnames relative to the current working directory.
If the specified template file is empty (zero-length), the command creates Protection and Authentication Database entries only.
To learn how to construct a template file, see Constructing a uss Template File.
-var
Specifies values for each of the number variables $1 through $9 that can appear in the template file. You can use the number variables to assign values to variables in the uss template file that are not part of the standard set.
For each instance of this argument, provide two parts in the indicated order, separated by a space:
The integer from the range 1 through 9 that matches the variable in the template file. Do not precede it with a dollar sign.
A string of alphanumeric characters to assign as the value of the variable.
To learn about suggested uses for the number variables, see the description of the V instruction's quota field in Creating a Volume with the V Instruction.
-dryrun
Reports actions that the command interpreter needs to perform to run the command, without actually performing them.
-overwrite
Overwrites any directories, files, and links that exist in the file system and for which there are definitions in D, E, F, L, or S instructions in the template file named by the -template argument. If you omit this flag, the command interpreter prompts you once for confirmation that you want to overwrite all such elements.
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). For example, the Example Corporation template 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.
Create an entry for the new user in the local password file (/etc/passwd or equivalent) on each AFS client machine that he or she can log into. For suggestions on automating this step, see Creating a Common Source Password File.
Even if you do not use the automated method, set the user's UNIX UID to match the AFS UID assigned automatically by the Protection Server or assigned with the -uid argument. The new user's AFS UID appears in the trace produced by the uss add output, or you can use the pts examine command to display it, as described in To display a Protection Database entry.


Constructing a uss Template File		Deleting Individual Accounts with the uss delete Command

Creating Individual Accounts with the uss add Command

To create an AFS account with the uss add command

Note