user account two methods for creating and deleting The uss command suite helps you create and delete AFS user accounts quickly and easily. You can create a single account with the uss add command, delete a single account with the uss delete command, or create and delete multiple accounts with the uss bulk command. A single uss add or uss bulk command can create a complete AFS user account because the uss command interpreter refers to a template file in which you predefine the configuration of many account components. The uss delete command deletes most of the components of a user account, but does not use a template file. The uss suite also easily incorporates shell scripts or other programs that you write to perform parts of account creation and deletion unique to your site. To invoke a script or program automatically as a uss command runs, use the appropriate instructions in the template file or bulk input file. Various sections of this chapter discuss possible uses for scripts. Using the uss commands to create and delete accounts is the recommended method because it automates and correctly orders most of the necessary steps. The alternative is to issue a series of separate commands to the various AFS servers, which requires more careful record keeping. For instructions, see Administering User Accounts. This chapter explains how to perform the following tasks by using the indicated commands: Add a single user account uss add Delete a single user account uss delete Add and delete multiple accounts uss bulk 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. user account components user account user account 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. uss commands privilege required privilege required for uss commands 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. uss commands add avoiding interruption uss commands delete avoiding interruption previewing user account creation/deletion with uss user account uss commands to create/delete previewing user account creation using uss previewing user account deletion using uss previewing uss previewing effect of command 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. failure of uss account creation recovering from uss account recovering from account creation failure uss command reissuing, effect of 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. uss commands overwriting existing account components overwriting existing directories/files/links with uss directory overwritten by uss if exists file overwritten by uss if exists hard link overwritten by uss if exists symbolic link overwritten by uss if exists 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. local password file creating entry for AFS user 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. AFS UID matching with UNIX UID user account matching AFS and UNIX UIDs uss AFS UID, assigning assigning AFS UID with uss UNIX UID matching with AFS UID 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. password setting in local password file with uss local password file setting password in with uss 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 common local password file with uss local password file creating common source version with uss uss commands local password file creating common source version passwd file local 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: Include an E instruction in the template file to create a one-line file that has the format of a local password file entry. 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/.example.com/common/etc/newaccts (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/.example.com/common/etc/newaccts/passwd_$USER 0644 root \ "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh" 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/example.com/usr/usr1/smith:/bin/csh 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/.example.com/common/uss/newaccts directory into a new version of the global password file found in the /afs/.example.com/common/etc 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/.example.com/common cat $dir/uss/newaccts/passwd_* $dir/etc/passwd >! $dir/etc/passwd.new mv $dir/etc/passwd $dir/etc/passwd.old sort $dir/etc/passwd.new > $dir/etc/passwd rm $dir/etc/passwd.new $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/.example.com/common/uss/newaccts directory into a new version of the global passwd file found in the /afs/.example.com/common/etc directory. #!/bin/sh DESTDIR=/afs/.example.com/common/uss/newaccts cd $DESTDIR DEST=/afs/.example.com/common/etc cp /afs/.example.com/common/etc/passwd /afs/.example.com/common/uss/newaccts/passwd echo "copied in passwd file." PASSWD=/afs/.example.com/common/uss/newaccts/passwd 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 do 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 ;; esac mv $i ../old.passdir/done_${i} done cd /afs/.example.com/common/uss/newaccts echo "sorting password file" sort ${PASSWD} > ${PASSWD}.sorted echo "installing files" install ${PASSWD}.sorted ${DEST}/passwd echo "Password file is built, sorted and installed." ;; esac uss commands converting existing UNIX accounts converting existing UNIX accounts to AFS accounts with uss user account converting existing UNIX to AFS with uss This section discusses the three main issues you need to consider if there are existing UNIX accounts to be converted to AFS accounts. As previously mentioned, AFS users must have an entry in the local password file on every client machine from which they access the AFS filespace as an authenticated user. Both administration and use are much simpler if the UNIX UID and AFS UID match. When converting existing UNIX accounts, you have two alternatives: Make the AFS UIDs match the existing UNIX UIDs. In this case, you need to assign the AFS UID yourself as you create an AFS account: If using the uss add command, include the -uid argument. If using the uss bulk command, specify the desired UID in the uid field of the add instruction in the bulk input file. Because you are retaining the user's UNIX UID, you do not need to alter the UID in the local password file entry. However, if you are using an AFS-modified login utility, you possibly need to change the password field in the entry. For a discussion of how the value in the password field affects login with an AFS-modified login utility, see Creating Local Password File Entries with uss. If now or in the future you need to create AFS accounts for users who do not have an existing UNIX UID, then you must guarantee that new AFS UIDs do not conflict with any existing UNIX UIDs. The simplest way is to set the max user id counter in the Protection Database to a value higher than the largest existing UNIX UID. See Displaying and Setting the AFS UID and GID Counters. Change the existing UNIX UIDs to match the new AFS UIDs that the Protection Server assigns automatically. Allow the Protection Server to allocate the AFS UIDs automatically as you create AFS accounts. For instructions on creating a new entry for the local password file during account creation, see Creating Local Password File Entries with uss. There is one drawback to changing the UNIX UID: any files and directories that the user owned in the local file system before becoming an AFS user still have the former UID in their owner field. If you want the ls -l and ls -ld commands to display the correct owner, you must use the chown command to change the value to the user's new UID, whether you are leaving the file in the local file system or moving it to AFS. See Moving Local Files into AFS. Existing UNIX accounts already have an entry in the local password file, probably with a (scrambled) password in the password field. You possibly need to change the value in the field, depending on the type of login utility you use: If the login utility is not modified for use with AFS, the actual password must appear (in scrambled form) in the password field of the local password file entry. If the login utility is modified for use with AFS, choose one of the acceptable values, each of which affects the login utility's behavior differently. See Creating Local Password File Entries with uss. If you choose to place an actual password in a local password file entry, then you can define a dummy password when you use a template file E instruction to create the entry, as described in Creating One-Line Files with the E Instruction. Have the user issue the UNIX password-setting command (passwd or equivalent) to replace the dummy with an actual secret password. New AFS users with existing UNIX accounts probably already own files and directories stored in a machine's local file system, and it usually makes sense to transfer them into the new home volume. The easiest method is to move them onto the local disk of an AFS client machine, and then use the UNIX mv command to transfer them into the user's new AFS home directory. As you move files and directories into AFS, keep in mind that the meaning of their mode bits changes. AFS ignores the second and third sets of mode bits (group and other), and does not use the first set (the owner bits) directly, but only in conjunction with entries on the ACL (for details, see How AFS Interprets the UNIX Mode Bits). Be sure that the ACL protects the file or directory at least as securely as the mode bits. If you have chosen to change a user's UNIX UID to match a new AFS UID, you must change the ownership of UNIX files and directories as well. Only members of the system:administrators group can issue the chown command on files and directories once they reside in AFS. uss commands advantages over individual account-creation commands uss template file advantages uss template file instructions summarized Creating user accounts with uss commands is generally more convenient than using individual commands. You control the account creation process just as closely, but the uss template file enables you to predefine many aspects of account configuration. Because you construct the template before issuing uss commands, you have time to consider configuration details carefully and correct syntax errors. The following list summarizes some further advantages of using a template: You do not have to remember the correct order in which to create or delete account components, or the order of each command's arguments, which reduces the likelihood of errors. You do not have to type the same information multiple times. Instead, you can place constants and variables in the template file that enable you to type as little on the command line as possible. See Using Constants and Variables in the Template File. You can create different templates for different types of users. Instead of having to remember which components differ for a given user, specify the appropriate template when issuing the uss add or uss bulk command. You can create any of the three types of AFS account (authentication-only, basic, or full) by including or omitting certain information in the template, as described in Creating the Three Types of User Accounts. The following list briefly describes the instructions that can appear in a template file and points you to a later section for more details. It lists them in the order that is usually optimal for correct handling of dependencies between the different types of instruction. G Defines a directory that is one of a set of parent directories into which the uss command interpreter evenly distributes newly created home directories. Place the corresponding template file variable, $AUTO, in the mount_point field of the V instruction. See Evenly Distributing User Home Directories with the G Instruction and Creating a Volume with the V Instruction. V Creates a volume, mounts it as the user's home directory at a specified location in the AFS filespace, sets the volume's quota, and defines the owner and ACL for the directory. This instruction must appear in any template that is not empty (zero-length). See Creating a Volume with the V Instruction. D Creates a directory, generally a subdirectory of the new home directory, and sets its mode bits, owner, and ACL. See Creating a Directory with the D Instruction. F Creates a file by copying a prototype and sets its mode bits and owner. See Creating a File from a Prototype with the F Instruction. E Creates a single-line file by copying in the contents of the instruction itself, then sets the file's mode bits and owner. See Creating One-Line Files with the E Instruction. L Creates a hard link. See Creating Links with the L and S Instructions. S Creates a symbolic link. See Creating Links with the L and S Instructions. A Improves account security by imposing restrictions on passwords and authentication attempts. See Increasing Account Security with the A Instruction. X Executes a command. See Executing Commands with the X Instruction. uss template file instructions for different account types user account creating different types with uss creating user account types with uss Using the uss add and uss bulk commands, you can create three types of accounts that differ in their levels of functionality. For a description of the types, see Configuring AFS User Accounts. The following list explains how to construct a template for each type: To create an authentication-only account, create an empty (zero-length) template file. Such an account has only two components: entries in the Authentication Database and Protection Database. To create a basic account, include a V instruction, and G instructions if you want to distribute home directories evenly as described in Evenly Distributing User Home Directories with the G Instruction. In addition to Authentication Database and Protection Database entries, this type of account includes a volume mounted at the home directory with owner and ACL set appropriately. To create a full account, include D, E, F, L, and S instructions as appropriate, in addition to the V and G instructions. This type of account includes configuration files for basic functions such as logging in, printing, and mail delivery. For a discussion of some useful types of configuration files, see Creating Standard Files in New AFS Accounts. constants uss template file uss template file constants variables in uss template file uss template file variables Each instruction in the uss template file has several fields that define the characteristics of the element that it creates. The D instruction's fields, for instance, define a directory's pathname, owner, mode bits, and ACL. You can place three types of values in a field: a variable, a constant, or a combination of the two. The appropriate value depends on the desired configuration, and determines which arguments you provide to the uss add command or which fields you include in a bulk input file add instruction. If an aspect of account configuration is the same for every user, define a constant value in the appropriate field by inserting a character string. For example, to assign a space quota of 10,000 KB to every user volume, place the string 10000 in the V instruction's quota field. If, on the other hand, an aspect of account configuration varies for each user, put a variable in the appropriate field. When creating each account, provide a value for the variable by providing either the corresponding argument to the uss add command or a value in the corresponding field of the add instruction in the bulk input file. The uss command suite defines a set of template variables, each of which has a corresponding source for its value, as summarized in Table 3. For a discussion of their intended uses, see the following sections about each template instruction (Creating a Volume with the V Instruction through Executing Commands with the X Instruction). Variable Source for value $AUTO Previous G instructions in template $MTPT -mount argument to uss add command or mount_point field of bulk input file add instruction, when in V instruction; V instruction's mount_point field when in subsequent instructions $NAME -realname argument to uss add command or mount_point field of bulk input file add instruction, if provided; otherwise, -user argument to uss add command or username field of in bulk input file add instruction $PART -partition argument to uss add command or partition field of bulk input file add instruction $PWEXPIRES -pwexpires argument to uss add command or password_expires field of bulk input file add instruction $SERVER -server argument to uss add command or file_server field of bulk input file add instruction $UID -uid argument to uss add command or uid field of bulk input file add instruction, if provided; otherwise, allocated automatically by Protection Server $USER -user argument to uss add command or username field of bulk input file add instruction $1 through $9 -var argument to uss add command or var1 through var9 fields of bulk input file add instruction A common use of variables is to define the file server machine and partition that house the user's volume, which often vary from user to user. Place the $SERVER variable in the V instruction's server field, and the $PART variable in its partition field. If using the uss add command, provide the desired value with the -server and -partition arguments. If using the uss bulk command, provide the desired values in the file_server and partition fields of each user's add instruction in the bulk input file. number variables uss template file uss template file number variables The variables $1 through $9 can be used to customize other aspects of the account. Provide a value for these variables with the -var argument to the uss add command or in the appropriate field of the bulk input file add instruction. The -var argument is unusual in that each instance for it has two parts: the number index and the value, separated by a space. For examples of the use of a number variable, see the discussions of the mount_point and quota fields in Creating a Volume with the V Instruction. If some aspect of account configuration is partly constant and partly variable, you can combine variables and constants in an instruction field. For example, suppose that the Example Corporation mounts user volumes in the /afs/example.com/usr directory. That part of the pathname is constant, but the name of the mount point and home directory is the user's username, which corresponds to the $USER variable. To configure accounts in this way, combine a constant string and a variable in the V instruction's mount_point field as follows: /afs/example.com/usr/$USER Then provide the value for the $USER variable with the -user argument to the uss add command, or in the username field of each user's add instruction in the bulk input file. location standard for uss template file uss template file standard locations A template must be available to the uss command interpreter as it executes a uss add or uss bulk command, even if it is the zero-length file appropriate for creating an authentication-only account. If you do not provide the -template argument to the uss add or uss bulk command, then 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 is the local cell /etc To use a template file with a different name or stored in a different directory, include the -template argument to the uss add or uss bulk command. If you provide a filename only, the command interpreter looks for it in the directories listed just previously. If you provide a pathname and filename, it looks only in the specified directory, interpreting a partial pathname relative to the current working directory. rules uss template file uss template file rules for constructing This section summarizes some general rules to follow when constructing a template file. For each instruction's syntax definition, see the following sections (Evenly Distributing User Home Directories with the G Instruction through Executing Commands with the X Instruction). If a variable takes its value from an element elsewhere within the template, the definition must precede the reference. Putting the instruction lines in the following order usually results in correct resolution of variables: G V D F E L S A X The fields in each instruction must appear in the order specified by the instruction's syntax definition, which appear in the following sections about each instruction. You cannot omit a field. Separate each field from its neighbors with one or more spaces. When specifying a pathname, provide a full one. Partial pathnames are interpreted relative to the current working directory (the one in which the uss command is issued), with possibly unintended results. Each instruction must appear on a single line in the template file, with a newline character (<Return>) only at the end of the instruction. Some example instructions appear in this document on more than one line, but that is only for legibility. Provide a value for every variable that appears in the template by including the corresponding argument to the uss add command or placing a value in the corresponding field of the bulk input file add instruction. A missing value halts the entire creation operation. If a variable does not appear in the template file, the command interpreter ignores the corresponding command-line argument or field in the bulk input file, even if you provide it. You can use blank lines in the template file to increase its legibility. If you place comments in the file, begin each comment line with the number sign (#). It is possible to use the D, E, and F instructions to create directories or files in the local file system of the machine on which you are issuing the uss command, but that usage is not recommended. It introduces two potential complications: The local file system automatically assigns ownership of a new local disk directory or file to its creator. Because you are the issuer of the uss command that is creating the object, it records your current UNIX UID. If that is not appropriate and you want to designate another owner as the object is created, then you must be logged in as the local superuser root (the local file system allows only the root user to issue the UNIX chown command, which the uss command interpreter invokes to change the owner from the default value). You must also use the -admin argument to the uss add or uss bulk command to authenticate as a privileged AFS administrator. Only an administrator can create Authentication Database and Protection Database entries, which the uss command interpreter always creates as part of a new account. The alternative is to become the local superuser root after the uss operation completes, and issue the necessary chown command then. However, that makes the account creation process that much less automated. Creating a local disk directory always generates an error message because the uss command interpreter cannot successfully set a local directory's ACL. The directory is created nevertheless, and a value still must appear in the D instruction's ACL field. This section describes example templates for the basic and full account types (the template for an authentication-only account is empty). The first example creates a basic account. It contains two G instructions and a V instruction that defines the volume name, file server machine, partition, quota in kilobytes, mount point, home directory owner, and home directory access control list. In the Example Corporation cell, a suitable template is: G /afs/.example.com/usr1 G /afs/.example.com/usr2 V user.$USER $SERVER.example.com /vicep$PART 5000 $AUTO/$USER $UID \ $USER all staff rl When issuing the uss add command with this type of template, provide the following arguments: -user to specify the username for the $USER variable -server to specify the unique part of the file server machine name for the $SERVER variable -partition to specify the unique part of the partition name for the $PART variable The Protection Server automatically assigns an AFS UID for the $UID variable, and the G instructions provide a value for the $AUTO variable. The following example template file creates a full account in the Example Corporation cell. The following sections about each type of instruction describe the effect of the examples. Note that the V and E instructions appear on two lines each only for the sake of legibility. # # Specify the available grouping directories # G /afs/.example.com/usr1 G /afs/.example.com/usr2 # # Create the user's home volume # V user.$USER $SERVER.example.com /vicep$PART 5000 /afs/.example.com/$AUTO/$USER \ $UID $USER all abc:staff rl # # Create directories and files for mail # D $MTPT/.MESSAGES 0700 $UID $USER all abc:staff none D $MTPT/.Outgoing 0700 $UID $USER rlidwk postman rlidwk D $MTPT/Mailbox 0700 $UID $USER all abc:staff none system:anyuser lik # # Here are some useful scripts for login etc. # F $MTPT/.Xbiff 0755 $UID /afs/example.com/admin/user/proto F $MTPT/.Xresources 0644 $UID /afs/example.com/admin/user/proto F $MTPT/.Xsession 0755 $UID /afs/example.com/admin/user/proto F $MTPT/.cshrc 0755 $UID /afs/example.com/admin/user/proto F $MTPT/.login 0755 $UID /afs/example.com/admin/user/proto F $MTPT/.logout 0755 $UID /afs/example.com/admin/user/proto F $MTPT/.twmrc 0644 $UID /afs/example.com/admin/user/proto F $MTPT/preferences 0644 $UID /afs/example.com/admin/user/proto # # Make a passwd entry # E /afs/.example.com/common/etc/newaccts/passwd_$USER 0644 root \ "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh" # # Put in the standard password/authentication checks # A $USER 250 noreuse 9 25 # # Create and mount a public volume for the user # X "create_public_vol $USER $1 $2" # # Here we set up the symbolic link to public directory # S /afs/example.com/public/$USER $MTPT/public uss commands directory distributing evenly with G instruction defining directory for even distribution of accounts with uss directory defining for even distribution of accounts with uss uss template file G instruction uss template file directory G instruction for even distribution In cells with thousands of user accounts, it often makes sense to distribute the mount points for user volumes into multiple parent directories, because placing them all in one directory noticeably slows down directory lookup when a user home directory is accessed. A possible solution is to create parent directories that group user home directories alphabetically, or that reflect divisions like academic or corporate departments. However, in a really large cell, some such groups can still be large enough to slow directory lookup, and users who belong to those groups are unfairly penalized every time they access their home directory. Another drawback to groupings that reflect workplace divisions is that you must move mount points when users change departmental affiliation. An alternative is an even distribution of user home directories into multiple parent directories that do not represent workplace divisions. The uss command suite enables you to define a list of directories by placing a G instruction for each one at the top of the template file, and then using the $AUTO variable in the V instruction's mount_point field. When the uss command interpreter encounters the $AUTO variable, it substitutes the directory named by a G instruction that currently has the fewest entries. (Actually, the $AUTO variable can appear in any field that includes a pathname, in any type of instruction. In all cases, the command interpreter substitutes the directory that currently has the fewest entries.) The G instruction's syntax is as follows: G directory where directory specifies either a complete directory pathname or only the final element (the directory itself). The choice determines the appropriate value to place in the V instruction's mount_point field. Specify the read/write path to each directory, to avoid the failure that results when you attempt to create a 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 Mounting Volumes. For example, the Example Corporation example template for a full account in Example uss Templates defines two directories: G /afs/.example.com/usr1 G /afs/.example.com/usr2 and puts the value $AUTO/$USER in the V instruction's mount_point field. An alternative with the same result is to define the directories as follows: G usr1 G usr2 and specify a more complete pathname in the V instruction's mount_point field: /afs/.example.com/$AUTO/$USER. uss commands volume creating with V instruction creating volume with uss volume creating with uss uss template file V instruction uss template file volume creating with V instruction uss template file zero-length Unless the template file is empty (zero-length), one and only one V instruction must appear in it. (To create other volumes for a user as part of a uss account-creation operation, use the X instruction to invoke the vos create command or a script that invokes that command along with others, such as the fs mkmount command. For an example, see Executing Commands with the X Instruction.) The V instruction defines the following AFS entities: A volume and associated VLDB entry The volume's site (file server machine and partition) The volume's mount point in the AFS filespace, which becomes the user's home directory The volume's space quota The home directory's owner, usually the new user The home directory's ACL, which normally at least grants all permissions to the user The following discussion of the fields in a V instruction refers to the example in the full account template from Example uss Templates (the instruction appears here on two lines only for legibility): V user.$USER $SERVER.example.com /vicep$PART 5000 \ /afs/.example.com/$AUTO/$USER $UID $USER all abc:staff rl The V instruction's syntax is as follows: V volume_name server partition quota mount_point owner ACL where V Indicates a volume creation instruction. volume_name Specifies the volume's name as recorded in the VLDB. To follow the convention of including the user's name as part of the volume name, include the $USER variable in this field. The variable takes its value from the -user argument to the uss add command or from the bulk input file add instruction's username field. The Example Corporation example uses the value user.$USER to assign the conventional volume name, user.username. When creating an account for user smith, for example, you then include -user smith as an argument to the uss add command, or place the value smith in the bulk input file add instruction's username field. server Names the file server machine on which to create the new volume. It is best to provide a fully qualified host name (for example, fs1.example.com), but an abbreviated form is acceptable if the cell's naming service is available to resolve it at the time the volume is created. To place different users' volumes on different file server machines, use the $SERVER variable in this field, and provide a value for it either with the -server argument to the uss add command or in the server field of the bulk input file add instruction. One easy way to specify a fully qualified hostname without having to type it completely on the command line is to combine a constant and the $SERVER variable. Specifically, the constant specifies the domain-name suffix common to all the file server machines. In the Example Corporation example, all of the file server machines in the cell share the example.com domain name suffix, so the server field combines a variable and constant: $SERVER.example.com. To place the new volume on the machine fs1.example.com, you then include -server fs1 as an argument to the uss add command, or place the value fs1 in the bulk input file add instruction's server field. partition Specifies the partition on which to create the user's volume; it must be on the file server machine named in the server field. Identify the partition by its complete name (for example, /vicepa) or use one of the abbreviations listed in Rules for Using Abbreviations and Aliases. To place different users' volumes on different partitions, use the $PART variable in this field, and provide a value for it either with the -partition argument to the uss add command or in the partition field of the bulk input file add instruction. Because all full partition names start with the /vicep string, it is convenient to combine that string as a constant with the $PART variable. The Example Corporation example template combines the constant string /vicep and the $PART variable in this way, as /vicep$PART. uss commands volume setting quota volume quota setting with uss uss template file quota on volume, setting with V instruction setting volume quota with uss quota Sets the maximum number of kilobyte blocks the volume can occupy on the file server machine's disk. It must be an integer. If you assign the same quota to all user volumes, specify a constant value. To assign different quotas to different volumes, place one of the number variables ($1 through $9) in this field, and provide a value for it either with the -var argument to the uss add command or in the appropriate field of the bulk input file add instruction. The Example Corporation example grants a 5000 KB initial quota to every new user. uss commands volume mounting creating mount point with uss uss template file mount point, creating with V instruction mount point creating with uss mount_point Creates a mount point for the volume, which serves as the volume's root directory and the user's home directory. By convention, user home directory names include the username, which you can read in by including the $USER variable in this field. 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). If you use the $AUTO variable in this field, the directories named by each G instruction possibly already indicate the read/write path. For further discussion of the concept of read/write and read-only paths through the filespace, see Mounting Volumes. If other parts of the mount point name also vary from user to user, you can use the $MTPT variable in this field, and provide a value with the uss add command's -mount argument or in the mount_point field of a bulk input file add instruction. Note, however, that when the $MTPT variable appears in subsequent instructions in the template (usually, in D, E, or F instructions), it instead takes as its value the complete contents of this field. Combine constants and variables based on how you have decided to group home directories together in one or more parent directories. Note that the parent directories must already exist before you run a uss add or uss bulk command that references the template. Possibilities for grouping home directories include the following: user account methods for grouping Placing all user home directories in a single parent directory; the name /afs/cellname/usr is an AFS-appropriate variation on the UNIX /usr convention. This choice is most appropriate for a cell with a small number of user accounts. The simplest way to implement this choice is to combine a constant string and the $USER variable, as in /afs/.example.com/usr/$USER. Distributing home directories evenly into a set of parent directories that do not correspond to workplace divisions. This choice is appropriate in cells with tens of thousands of accounts, where the number of home directories is large enough to slow directory lookup significantly if they all reside together in one parent directory, but distribution according to workplace divisions is not feasible. The $AUTO variable is designed to distribute home directories evenly in this manner. As explained in Evenly Distributing User Home Directories with the G Instruction, the uss command interpreter substitutes the directory that is defined by a preceding G template instruction and that currently has the fewest entries. The example Example Corporation template illustrates this choice by using the value /afs/.example.com/$AUTO/$USER. Distributing home directories into multiple directories that reflect divisions like academic or corporate departments. Perhaps the simplest way to implement this scheme is to use the $MTPT variable to represent the department, as in /afs/.example.com/usr/$MTPT/$USER. You then provide -user smith and -mount acctg arguments to the uss add command to create the mount point /afs/.example.com/usr/acctg/smith. Distributing home directories into alphabetic subdirectories of usr (usr/a, usr/b and so on), based on the first letter or letters in the username. The advantage is that knowing the username enables you easily to locate a home directory. A potential drawback is that the distribution is not likely to be even, and if there are a large number of accounts, then slowed directory lookup unfairly affects users whose names begins with popular letters. Perhaps the simplest way to implement this scheme is to use the $MTPT variable to represent the letter or letters, as in /afs/.example.com/usr/$MTPT/$USER. Then provide the -user smith and -mount s/m arguments to the uss add command to create the mount point /afs/.example.com/usr/s/m/smith. owner Specifies the username or UID of the user to be designated the mount point's owner in the output from the UNIX ls -ld command. To follow the standard convention for home directory ownership, use the $UID variable in this field, as in the Example Corporation example template. The Protection Server then automatically assigns an AFS UID unless you provide the -uid argument to the uss add command or fill in the uid field in the bulk input file add instruction. (If you are converting existing UNIX accounts, see the discussion of additional considerations in Converting Existing UNIX Accounts with uss.) uss commands ACL, setting on home directory ACL setting on user home directory with uss uss template file ACL, setting user home directory with V instruction setting ACL on home directory with uss ACL Sets the ACL on the new home directory. Provide one or more paired values, each pair consisting of an AFS username or group name and the desired permissions, in that order (a group name must already exist in the Protection Database to be used). Separate the two parts of the pair, and each pair, with a space. For a discussion of the available permissions, see The AFS ACL Permissions. At minimum, grant all permissions to the new user by including the value $USER all in this field. The File Server automatically grants all permissions to the system:administrators group as well. You cannot grant permissions to the issuer of the uss command, because as the last step in account creation the uss command interpreter automatically deletes that user from any ACLs set during the creation process. The Example Corporation example uses the following value to grant all permissions to the new user and r (read) and l (lookup) permissions to the members of the abc:staff group: $USER all abc:staff rl uss template file D instruction uss commands directory creating uss template file directory creating with D instruction creating directory with uss directory creating with uss D instruction uss template file Each D instruction in the template file creates a directory; there is no limit on the number of them in the template. If a D instruction creates a subdirectory in a new user's home directory (its intended use), then it must follow the V instruction. Creating a directory on the local disk of the machine where the uss command runs is not recommended for the reasons outlined in About Creating Local Disk Directories and Files. The following discussion of the fields in a D instruction refers to one of the examples in the full account template in Example uss Templates: D $MTPT/Mailbox 0700 $UID $USER all abc:staff none system:anyuser lik The D instruction's syntax is as follows: D pathname mode_bits owner ACL where D Indicates a directory creation instruction. pathname Specifies the directory's full pathname. If it is a subdirectory of the user's home directory, it is simplest to use the $MTPT variable to specify the home directory pathname. When the $MTPT variable appears in a D instruction, it takes its value from the preceding V instruction's mount_point field (this dependency is why a D instruction must follow the V instruction). Specify the read/write pathname to the directory, to avoid the failure that results when you attempt to create a new directory 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). If you use the $MTPT variable in this field, the value in the V instruction's mount_point field possibly already indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the filespace, see Mounting Volumes. The Example Corporation example uses the value $MTPT/Mailbox to place the Mailbox subdirectory in the user's home directory. mode_bits Defines the directory's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding to a combination of permissions. Examples: 0755 corresponds to rwxr-xr-x, and 0644 to rw-r--r--. The first (owner) x bit must be turned on to enable access to a directory. The Example Corporation example uses the value 0700 to set the mode bits on the Mailbox subdirectory to rwxr-----. owner Specifies the username or UID of the user to be designated the directory's owner in the output from the UNIX ls -ld command. If the directory resides in AFS, place the $UID variable in this field, as in the Example Corporation example template. The Protection Server then automatically assigns an AFS UID unless you provide the -uid argument to the uss add command or fill in the uid field in the bulk input file add instruction. (If you are converting existing UNIX accounts, see the discussion of additional considerations in Converting Existing UNIX Accounts with uss.) If the directory resides on the local disk, it is simplest to specify the username or UNIX UID under which you are issuing the uss command. For a discussion of the complications that arise from designating another user, see About Creating Local Disk Directories and Files. ACL setting for directory with uss setting ACL for directory with uss uss template file ACL, setting directory created by D instruction uss commands ACL, setting for directory ACL Sets the ACL on the new directory. Provide one or more paired values, each pair consisting of an AFS username or group name and the desired permissions, in that order (a group name must already exist in the Protection Database to be used). Separate the two parts of the pair, and each pair, with a space. For a description of the available permissions, see The AFS ACL Permissions. At minimum, grant all permissions to the new user by including the value $USER all. You cannot grant permissions to the issuer of the uss command, because as the last step in account creation the uss command interpreter automatically deletes that user from any ACLs set during the creation process. An error message always appears if the directory is on the local disk, as detailed in About Creating Local Disk Directories and Files. The Example Corporation example uses the following value to grant all permissions to the new user, no permissions to the members of the abc:staff group, and the l (lookup), i (insert), and k (lock) permissions to the members of the system:anyuser group: $USER all abc:staff none system:anyuser lik It grants such extensive permissions to the system:anyuser group to enable any system user (including a mail-delivery daemon) to insert mail into the Mailbox directory. The absence of the r (read) permission prevents members of the system:anyuser group from reading the mail files. uss commands file, creating from prototype creating file with uss file creating with uss uss template file F instruction uss template file file creating from prototype F instruction uss template file Each F instruction in the template file creates a file by copying the contents of an existing prototype file; there is no limit on the number of them in the template, and each can refer to a different prototype. If an F instruction creates a file in a new user's home directory or a subdirectory of it (the intended use), then it must follow the V or D instruction that creates the parent directory. Creating a file on the local disk of the machine where the uss command runs is not recommended for the reasons detailed in About Creating Local Disk Directories and Files. The E instruction also creates a file, but the two types of instruction have complementary advantages. Files created with an E instruction can be customized for each user, because variables can appear in the field that specifies the contents of the file. In contrast, the contents of a file created using the F instruction are the same for every user. An E file can be only a single line, however, whereas an F file can be any length. The following discussion of the fields in a F instruction refers to one of the examples in the full account template in Example uss Templates: F $MTPT/.login 0755 $UID /afs/example.com/admin/user/proto The F instruction's syntax is as follows: F pathname mode_bits owner prototype_file where F Indicates a file creation instruction. pathname Specifies the full pathname of the file to create, including the filename. If it resides in the user's home directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname. When the $MTPT variable appears in an F instruction, it takes its value from the preceding V instruction's mount_point field (this dependency is why an F instruction must follow the V instruction). Specify the read/write path to the file, to avoid the failure that results when you attempt to create a new file 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). If you use the $MTPT variable in this field, the value in the V instruction's mount_point field possibly already indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the filespace, see Mounting Volumes. The Example Corporation example uses the value $MTPT/.login to place a file called .login in the user's home directory. mode_bits Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding to a combination of permissions. Examples: 0755 corresponds to rwxr-xr-x, and 0644 to rw-r--r--. The Example Corporation example uses the value 0755 to set the mode bits on the .login file to rwxr-xr-x. owner Specifies the username or UID of the user to be designated the file's owner in the output from the UNIX ls -l command. If the file resides in AFS, place the $UID variable in this field, as in the Example Corporation example template. The Protection Server then automatically assigns an AFS UID unless you provide the -uid argument to the uss add command or fill in the uid field in the bulk input file add instruction. (If you are converting existing UNIX accounts, see the discussion of additional considerations in Converting Existing UNIX Accounts with uss.) If the file resides on the local disk, it is simplest to specify the username or UNIX UID under which you are issuing the uss command. For a discussion of the complications that arise from designating another user, see About Creating Local Disk Directories and Files. prototype_file Names the AFS or local directory that houses the prototype file to copy. The prototype file's name must match the final element in the pathname field. The Example Corporation example references a prototype file called .login in the directory /afs/example.com/admin/user/proto. uss commands file, creating by echoing one line creating file with uss file creating with uss uss template file E instruction uss template file file creating by echoing one line E instruction uss template file Each E instruction in the template file creates a file by echoing a specified single line into it; there is no limit on the number of them in the template. If an E instruction creates a file in a new user's home directory or a subdirectory of it (the intended use), then it must follow the V or D instruction that creates the parent directory. Creating a file on the local disk of the machine where the uss command runs is not recommended for the reasons detailed in About Creating Local Disk Directories and Files. The F instruction also creates a file, but the two types of instruction have complementary advantages. Files created with an E instruction can be customized for each user, because variables can appear in the field that specifies the contents of the file. The command interpreter replaces the variables with appropriate values before creating the file. In contrast, the contents of a file created using the F instruction are the same for every user. An E file can be only a single line, however, whereas an F file can be any length. The E instruction is particularly suited to creating an entry for the new user in the cell's common source password file, which is then copied to client machines to serve as the local password file (/etc/passwd or equivalent). The following discussion of the fields refers to an example of this type of use, from the Example Corporation's full account template shown in Example uss Templates. For further discussion of how to incorporate the files created in this way into a common source password file, see Creating a Common Source Password File. E /afs/.example.com/common/etc/newaccts/passwd_$USER 0644 root \ "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh" The E instruction's syntax is as follows: E pathname mode_bits owner "contents" where E Indicates a file creation instruction. pathname Specifies the full pathname of the file to create, including the filename. It can include variables. If it resides in the user's home directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname. When the $MTPT variable appears in an E instruction, it takes its value from the preceding V instruction's mount_point field (this dependency is why an E instruction must follow the V instruction.) Specify the read/write path to the file, to avoid the failure that results when you attempt to create a new file 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). If you use the $MTPT variable in this field, the value in the V instruction's mount_point field possibly already indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the filespace, see Mounting Volumes. The Example Corporation example writes the file created by the E instruction to /afs/.example.com/common/etc/newaccts directory, naming it after the new user: /afs/.example.com/common/etc/newaccts/passwd_$USER mode_bits Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding to a combination of permissions. Examples: 0755 corresponds to rwxr-xr-x, and 0644 to rw-r--r--. The Example Corporation example uses the value 0644 to set the mode bits on the passwd_user file to r-xr--r--. owner Specifies the username or UID of the user to be designated the file's owner in the output from the UNIX ls -l command. If the file resides in AFS and is to be owned by the user, place the $UID variable in this field. The Protection Server then automatically assigns an AFS UID unless you provide the -uid argument to the uss add command or fill in the uid field in the bulk input file add instruction. (If you are converting existing UNIX accounts, see the discussion of additional considerations in Converting Existing UNIX Accounts with uss.) If the file resides on the local disk, specify the username or UNIX UID under which you are issuing the uss command. For a discussion of the complications that arise from designating another user, see About Creating Local Disk Directories and Files. The Example Corporation example is creating an AFS file intended for incorporation into the common password file, rather than for direct use by the new user. It therefore designates the local superuser root as the owner of the new file. Designating an alternate owner on an AFS file does not introduce complications: issuing the chown command on AFS files requires membership in the system:administrators group, but the issuer of the uss command is necessarily authenticated as a member of that group. contents Specifies the one-line character string to write into the new file. Surround it with double quotes if it contains one or more spaces. It cannot contain the newline character, but can contain any of the standard variables, which the command interpreter resolves as it creates the file. The Example Corporation example has the following value in the contents field, to create a password file entry: $USER:X:$UID:10:$NAME:$MTPT:/bin/csh L instruction uss template file S instruction uss template file uss hard link, creating creating link (hard or symbolic) with uss hard link creating with uss uss template file L instruction uss template file hard link, creating uss symbolic link, creating symbolic link creating with uss uss template file S instruction uss template file symbolic link, creating Each L instruction in the template file creates a hard link between two files, as achieved by the standard UNIX ln command. The S instruction creates a symbolic link between two files, as achieved by the standard UNIX ln -s command. An explanation of links is beyond the scope of this document, but the basic effect in both cases is to create a second name for an existing file, so that it can be accessed via either name. Creating a link does not create a second copy of the file. There is no limit on the number of L or S instructions in a template file. If the link is in a new user's home directory or a subdirectory of it (the intended use), then it must follow the V or D instruction that creates the parent directory, and the F, E, or X instruction that creates the file being linked to. Creating a file on the local disk of the machine where the uss command runs is not recommended, for the reasons detailed in About Creating Local Disk Directories and Files. Note that AFS allows hard links only between files that reside in the same directory. This restriction is necessary to eliminate the confusion that results from associating two potentially different ACLs (those of the two directories) with the same file. Symbolic links are legal between two files that reside in different directories and even in different volumes. The ACL on the actual file applies to the link as well. You do not set the owner or mode bits on a link created with an L or S instruction, as you do for directories or files. The uss command interpreter automatically records the UNIX UID of the uss command's issuer as the owner, and sets the mode bits to lrwxrwxrwx (777). The following discussion of the fields in an L or S instruction refers to an example in the full account template from Example uss Templates, namely S /afs/example.com/public/$USER $MTPT/public The L and S instructions' syntax is as follows: L existing_file link S existing_file link where L Indicates a hard link creation instruction. S Indicates a symbolic link creation instruction. existing_file Specifies the complete pathname of the existing file. If it resides in the user's home directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname. When the $MTPT variable appears in an L or S instruction, it takes its value from the preceding V instruction's mount_point field (this dependency is why the instruction must follow the V instruction). Do not create a symbolic link to a file whose name begins with the number sign (#) or percent sign (%). When the Cache Manager reads a symbolic link whose contents begin with one of those characters, it interprets it as a regular or read/write mount point, respectively. The Example Corporation example creates a link to the publicly readable volume created and mounted by a preceding X instruction, by specifying the path to its mount point: /afs/example.com/public/$USER link Specifies the complete pathname of the second name for the file. If it resides in the user's home directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname. Specify the read/write path to the link, to avoid the failure that results when you attempt to create a new link 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). If you use the $MTPT variable in this field, the value in the V instruction's mount_point field possibly already indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the filespace, see Mounting Volumes. The Example Corporation example creates a link called public in the user's home directory: $MTPT/public A instruction uss template file uss commands password/authentication security, setting with A instruction uss template file A instruction uss template file password/authentication security, setting with A instruction The A instruction in the template file enhances cell security by imposing the following restrictions on users' password choice and authentication attempts. Limiting the user's password lifetime. When the lifetime expires, the user can no longer use the password to authenticate and must change it. Prohibiting the reuse of the user's 20 most-recently used passwords. Limiting the number of consecutive times that a user can provide an incorrect password during authentication, and for how long the Authentication Server refuses further authentication attempts after the limit is exceeded (referred to as an account lockout). For regular user accounts in most cells, the recommended limit is nine and lockout time is 25 minutes. The following discussion of the fields in an A instruction refers to the example in the full account template from Example uss Templates, which sets a password lifetime of 250 days, prohibits reuse of passwords, limits the number of failed authentication attempts to nine, and creates a lockout time of 25 minutes if the authentication limit is exceeded: A $USER 250 noreuse 9 25 The A instruction's syntax is as follows: A username password_lifetime password_reuse failures locktime where A Indicates a security enhancing instruction. username Names the Authentication Database entry on which to impose security restrictions. Use the $USER variable to read in the username from the uss add command's -user argument, or from the username field of an add instruction in the bulk input file. The Example Corporation example uses this value. password_lifetime Sets the number of days after the user's password is changed that it remains valid. 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). Specify an integer from the range 1 through 254 to specify the number of days until expiration, the value 0 to indicate that the password never expires, or the value $PWEXPIRES to read in the number of days from the uss add or uss bulk command's -pwexpires argument. If the A instruction does not appear in the template file, by default the user's password never expires. The Example Corporation example sets a password lifetime of 250 days. password_reuse Determines whether or not the user can change his or her password (using the kpasswd or kas setpassword command) to one that is similar to any of his or her last 20 passwords. The acceptable values are reuse to allow reuse and noreuse to prohibit it. If the A instruction does not appear in the template file, the default is to allow password reuse. The Example Corporation example prohibits password reuse. failures Sets the number of consecutive times the user can provide an incorrect password during authentication (using the klog command or a login utility that grants AFS tokens). When the user exceeds the limit, the Authentication Server rejects further authentication attempts for the amount of time specified in the locktime field. Specify an integer from the range 1 through 254 to specify the number of failures permitted, or the value 0 to indicate that there is no limit to the number of unsuccessful attempts. If the A instruction does not appear in the template file, the default is to allow an unlimited number of failures. The Example Corporation example sets the limit to nine failed attempts. locktime Specifies how long the Authentication Server refuses authentication attempts from a user who has exceeded the failure limit set in the failures field. Specify a number of hours and minutes (hh:mm) or minutes only (mm), from the range 01 (one minute) through 36:00 (36 hours). The Authentication Server automatically reduces any larger value to 36:00 and also rounds up any nonzero value to the next highest multiple of 8.5 minutes. A value of 0 (zero) sets an infinite lockout time, in which case an administrator must always issue the kas unlock command to unlock the account. The Example Corporation example sets the lockout time to 25 minutes, which is rounded up to 25 minutes 30 seconds (the next highest multiple of 8.5 minutes). uss commands command, executing with X instruction executing command using uss template line commands executing from uss template file uss template file X instruction uss template file command, executing with X instruction X instruction uss template file The X instruction in the template file executes a command, which can be a standard UNIX command, a shell script or program, or an AFS command. The command string can include standard template variables, and any number of X instructions can appear in a template file. If an instruction manipulates an element created by another instruction, it must appear after that instruction. The following discussion of the field in an X instruction refers to the example in the full account template from Example uss Templates: X "create_public_vol $USER $1 $2" The X instruction's syntax is as follows: X "command" where command specifies the command to execute. Surround it with double quotes if it contains spaces. The command string can contain any of the standard variables, which the uss command interpreter resolves before passing the command on to the appropriate other command interpreter, but it cannot contain newline characters. The Example Corporation example invokes a script called create_public_vol, which creates another volume associated with the new user and mounts it in a publicly readable part of the Example Corporation's filespace: "create_public_vol $USER $1 $2" It uses the $USER variable to read in the username and make it part of both the volume name and mount point name. The uss command issuer supplies a file server machine name for the $1 variable and a partition name for the $2 variable, to specify the site for the new volume. creating user account with uss user account user account user account creating with uss username assigning with uss creating Protection Database user entry with uss creating Authentication Database entry with uss Protection Database user entry creating with uss Authentication Database entry creating with uss uss commands creating individual user account AFS UID assigning with uss user AFS UID, assigning 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. 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 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. uss commands add commands uss add 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> 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. deleting user accounts with uss user account deleting with uss deleting Protection Database user entry with uss deleting Authentication Database entry with uss Protection Database user entry deleting with uss Authentication Database entry deleting with uss uss commands deleting individual user account The uss delete command deletes an AFS user account according to the arguments you provide on the command line; unlike the uss add command, it does not use a template file. When you issue the command, the uss command interpreter contacts various AFS servers to perform the following actions: Remove the mount point for the user's home volume Remove the user's home volume and delete the associated VLDB entry, unless you include the -savevolume flag Delete the user's Authentication Database entry Delete the user's Protection Database entry Before issuing the uss delete command, you can also perform the following optional tasks: Copy the user's home volume to tape or another permanent medium and record the username and UID on a reserved list. This information enables you to restore the user's account easily if he or she returns to your cell. For information about using the AFS Backup System to back up volumes, see Configuring the AFS Backup System and Backing Up and Restoring AFS Data. If the user has exclusive use of any other volumes (such as a volume for storing project-related data), make a backup copy of each one and then remove it and its mount point as instructed in Removing Volumes and their Mount Points. Use the pts listowned command to display any groups that the user owns; instructions appear in To list the groups that a user or group owns. Decide whether to use the pts delete command to remove the groups or the pts chown command to transfer ownership to another user or group. Instructions appear in To delete Protection Database entries and To change a group's owner. Alternatively, you can have the user remove or transfer ownership of the groups before leaving. A group that remains in the Protection Database after its owner is removed is considered orphaned, and only members of the system:administrators group can administer it. You can automate some of these tasks by including exec instructions in the bulk input file and using the uss bulk command to delete the account. See Creating and Deleting Multiple Accounts with the uss bulk 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 d (delete) permission on the ACL of the directory that houses the user's home directory. 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. Consider and resolve the issues discussed in the introduction to this section concerning the continued maintenance of a deleted user's account information, owned groups, and volumes. (Optional) Run the uss delete command with the -dryrun flag to preview the deletion 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 delete command's syntax. uss commands delete commands uss delete Issue the uss delete command to delete the account. Enter the command on a single line; it appears here on multiple lines only for legibility. The delete operation always removes the user's entry from the Authentication Database. 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 delete -user <login name> \ -mountpoint <mountpoint for user's volume> \ [-savevolume] -admin <administrator to authenticate> \ [-dryrun] Administrator's (admin_user) password: <admin_password> where d Is the shortest acceptable abbreviation of delete. -user Names the entry to delete from the Protection and Authentication Databases. -mountpoint Specifies the pathname of the mount point to delete (the user's home directory). Unless the -savevolume argument is included, the volume mounted there is also deleted from the file server machine where it resides, as is its record from the VLDB. 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 delete a mount point from 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 Mounting Volumes. -savevolume Retains the user's volume and VLDB entry. -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. -dryrun Reports actions that the command interpreter needs to perform to run the command, without actually performing them. If the deleted user home directory resided 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> 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 deleting a mount point the administrator must issue the vos release command. Delete the user's entry from the local password file (/etc/passwd or equivalent) of each client machine. If you intend to reactivate the user's account in the future, it is simpler to comment out the entry or place an asterisk (*) in the password field. creating user accounts in bulk with uss user account creating/deleting many at once bulk mode in uss deleting user accounts in bulk with uss uss commands creating/deleting user accounts in bulk The uss bulk command allows you to create and delete many accounts at once. Before executing the command, you must Construct a template if you plan to create any accounts, just as you must do before running the uss add command. The same template applies to all accounts created by a single uss bulk command. Construct a bulk input file of instructions that create and delete accounts and execute any related commands, as described in Constructing a Bulk Input File. rules for uss bulk input file uss bulk input file rules for constructing You can include five types of instructions in a bulk input file: add, delete, exec, savevolume, and delvolume. The following sections discuss their uses. Creating a User Account with the add Instruction Each add instruction creates a single user account, and so is basically the equivalent of issuing one uss add command. There is no limit to the number of add instructions in the bulk input file. As indicated by the following syntax statement, the order of the instruction's fields matches the order of arguments to the uss add command (though some of the command's arguments do not have a corresponding field). Like the uss add command's arguments, many of the fields provide a value for a variable in the uss template file. Each instruction must be a single line in the file (have a newline character only at its end); it appears on multiple lines here only for legibility. add username[:full_name][:initial_password][:password_expires] [:file_server][:partition][:mount_point][:uid] [:var1][:var2][:var3][:var4][:var5][:var6][:var7][:var8][:var9][:] For a complete description of the acceptable values in each field, see the uss Bulk Input File reference page in the OpenAFS Administration Reference, or the description of the corresponding arguments to the uss add command, in To create an AFS account with the uss add command. Following are some basic notes: Begin the line with the string add only, not uss add. Only the first argument, username, is required. It corresponds to the -user argument to the uss add command. Do not surround the full_name value with double quotes, even though you must use them around the value for the -realname argument to the uss add command. If you want to omit a value for an argument, indicate an empty field by using two colons with nothing between them. Leaving a field empty is acceptable if the corresponding command line argument is optional or if the corresponding variable does not appear in the template file. For every field that precedes the last one to which you assign an actual value, you must either provide a value or indicate an empty field. It is acceptable, but not necessary, to indicate empty fields after the last one in which you assign a value. After the last field, end the line with either a colon and newline character (<Return>), or a newline alone. The final nine fields are for assigning values to the number variables ($1 through $9), with the fields listed in increasing numerical order. Specify the value only, not the variable number. Deleting a User Account with the delete Instruction Each delete instruction deletes a single user account, and so is basically the equivalent of issuing one uss delete command. There is no limit to the number of delete instructions in the bulk input file. Like all instructions in the bulk input file, each delete instruction must be a single line in the file (have a newline character only at its end), even though it can cover multiple lines on a display screen. The curly braces ({ }) indicate two mutually exclusive choices. delete username:mount_point_path[:{ savevolume | delvolume }][:] For a complete description of the acceptable values in each field, see the uss Bulk Input File reference page in the OpenAFS Administration Reference or the description of the corresponding arguments to the uss delete command, in To delete an AFS account. Following are some basic notes: Begin the line with the string delete only, not uss delete. The first two arguments, username and mount_point_path, are required. They correspond to the -user and -mountpoint arguments to the uss delete command. The third field, which is optional, controls whether the user's home volume is removed from the file server where it resides, along with the corresponding VLDB entry. There are three possible values: No value treats the volume and VLDB entry according to the prevailing default, which is established by a preceding savevolume or delvolume instruction in the template file. See the following discussion of those instructions to learn how the default is set. The string savevolume preserves the volume and VLDB entry, overriding the default. The string delvolume removes the volume and VLDB entry, overriding the default. After the last field, end the line with either a colon and newline character (<Return>), or a newline alone. Running a Command or Script with the exec Instruction The exec instruction runs the indicated AFS command, compiled program, or UNIX shell script or command. The command processor assumes the AFS and local identities of the issuer of the uss bulk command, who must have the privileges required to run the command. The instruction's syntax is as follows: exec command It is not necessary to surround the command string with double quotes (" ") or other delimiters. Setting the Default Treatment of Volumes with the delvolume and savevolume Instructions The savevolume and delvolume instructions set the default treatment of volumes referenced by the delete instructions that follow them in the bulk input file. Their syntax is as follows: savevolume delvolume Both instructions are optional and take no arguments. If neither appears in the bulk input file, then by default all volumes and VLDB entries referenced by delete instructions are removed. If the savevolume instruction appears in the file, it prevents the removal of the volume and VLDB entry referenced by all subsequent delete instructions in the file. The delvolume instruction explicitly establishes the default (which is deletion) for subsequent delete instructions. The effect of either instruction lasts until the end of the bulk input file, or until its opposite appears. To override the prevailing default for a particular delete instruction, put the savevolume or delvolume string in the instruction's third field. (You can also use multiple instances of the savevolume and delvolume instructions to toggle back and forth between default preservation and deletion of volumes.) To create an authentication-only account, use an add instruction like the following example, which includes only the first (username) argument. The user's real name is set to match the username (anderson) and her initial password is set to the string changeme. add anderson The following example also creates an authentication-only account, but sets nondefault values for the real name and initial password. add smith:John Smith:js_pswd The next two example add instructions require that the administrator of the Example Corporation cell (example.com) has written a uss template file with the following V instruction in it: V user.$USER $SERVER.example.com /vicep$PART 10000 /afs/.example.com/usr/$3/$USER \ $UID $USER all To create accounts for users named John Smith from the Marketing Department and Pat Jones from the Finance Department, the appropriate add instructions in the bulk input file are as follows: add smith:John Smith:::fs1:a:::::marketing add jones:Pat Jones:::fs3:c:::::finance The new account for Smith consists of Protection and Authentication Database entries called smith. His initial password is the default string changeme, and the Protection Server generates his AFS UID. His home volume, called user.smith, has a 10,000 KB quota, resides on partition /vicepa of file server machine fs1.example.com, and is mounted at /afs/.example.com/usr/marketing/smith. The final $UID $USER all part of the V instruction gives him ownership of his home directory and all permissions on its ACL. The account for jones is similar, except that it resides on partition /vicepc of file server machine fs3.example.com and is mounted at /afs/.example.com/usr/finance/jones. Notice that the fields corresponding to mount_point, uid, var1, and var2 are empty (between the values a and marketing on the first example line) because the corresponding variables do not appear in the V instruction in the template file. The initial_passwd and password_expires fields are also empty. If you wish, you can specify values or empty fields for all nine number variables in an add instruction. In that case, the bulk input file instructions are as follows: add smith:John Smith:::fs1:a:::::marketing:::::: add jones:Pat Jones:::fs3:c:::::finance:::::: The following example is a section of a bulk input file with a number of delete instructions and a savevolume instruction. Because the first three instructions appear before the savevolume instruction and their third field is blank, the corresponding volumes and VLDB entries are removed. The delete instruction for user terry follows the savevolume instruction, so her volume is not removed, but the volume for user johnson is, because the delvolume string in the third field of the delete instruction overrides the current default. delete smith:/afs/example.com/usr/smith delete pat:/afs/example.com/usr/pat delete rogers:/afs/example.com/usr/rogers savevolume delete terry:/afs/example.com/usr/terry delete johnson:/afs/example.com/usr/johnson:delvolume The following example exec instruction is useful as a separator between a set of add instructions and a set of delete instructions. It generates a message on the standard output stream that informs you of the uss bulk command's progress. exec echo "Additions completed; beginning deletions..." 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 d (delete), i (insert) and l (lookup) permissions on the ACL of the parent directory for each volume mount point. 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. If the bulk input file includes add instructions, verify the location and functionality of the template 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 which variables appear in the template, to be sure that you provide the corresponding arguments in the add instruction or on the uss bulk command line. Create a bulk input file that complies with the rules listed in Constructing a Bulk Input File. It is simplest to put the file in the same directory as the template file you are using. (Optional.) Change to the directory where the bulk input file and template file reside. % cd template_directory uss commands bulk commands uss bulk Issue the uss bulk command to create or delete accounts, or both. Enter the command on a single line; it appears here on multiple lines only for legibility. The bulk operation always manipulates user entries in the Authentication Database. 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 bulk <bulk input file> \ [-template <pathname of template file>] \ -admin <administrator to authenticate> \ [-dryrun] [-overwrite] \ [-pwexpires <password expires in [0..254] days (0 => never)>] \ [-pipe] Administrator's (admin_user) password: <admin_password> where b Is the shortest acceptable abbreviation of bulk. bulk input file Specifies the pathname of the bulk input file. Partial pathnames are interpreted relative to the current working directory. For a discussion of the required file format, see Constructing a Bulk Input File. -template Specifies the pathname of the template file for any uss add commands that appear in the bulk input file. Partial pathnames are interpreted relative to the current working directory. For a discussion of the required file format, see Constructing a uss Template File. -admin Names an administrative account that has the ADMIN flag on its Authentication Database entry, such as the admin account. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password. -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 also D, E, F, L, or S instructions in the template file named by the -template argument. If this flag is omitted, the command interpreter prompts, once for each add instruction in the bulk input file, for confirmation that it is to overwrite such elements. Do not include this flag if there are no add instructions in the bulk input file. -pwexpires Sets the number of days after a user's password is changed that it remains valid, for each user named by an add instruction in the bulk input file. 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). 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). -pipe Suppresses the Authentication Server's prompt for the password of the issuer or the user named by the -admin argument (the Authentication Server always separately authenticates the user who is creating or deleting an entry in the Authentication Database). Instead, the command interpreter accepts the password as piped input from another program, enabling you to run the uss bulk command in unattended batch jobs. If a newly created or deleted 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> 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 or deleting a mount point, the administrator must issue the vos release command. If you are creating accounts, 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. If you are deleting accounts, delete the user's entry from the local password file (/etc/passwd or equivalent) of each client machine. If you intend to reactivate the user's account in the future, it is simpler to comment out the entry or place an asterisk (*) in the password field.