| Constructing a uss Template File | ||
|---|---|---|
 | Chapter 11. Creating and Deleting User Accounts with the uss Command Suite |  |
| Constructing a uss Template File | ||
|---|---|---|
| | Chapter 11. Creating and Deleting User Accounts with the uss Command Suite | |
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.
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.
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.
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.
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.
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.
Creates a hard link. See Creating Links with the L and S Instructions.
Creates a symbolic link. See Creating Links with the L and S Instructions.
Improves account security by imposing restrictions on passwords and authentication attempts. See Increasing Account Security with the A Instruction.
Executes a command. See Executing Commands with the X Instruction.
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.
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).
Table 3. Source for values of uss template variables
| 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.
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.
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.
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
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.
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
Indicates a volume creation instruction.
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.
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.
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.
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.
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:
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.
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.)
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
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
Indicates a directory creation instruction.
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.
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-----.
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.
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.
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
Indicates a file creation instruction.
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.
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.
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.
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.
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
Indicates a file creation instruction.
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
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--.
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.
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
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
Indicates a hard link creation instruction.
Indicates a symbolic link creation instruction.
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
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
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
Indicates a security enhancing instruction.
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.
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.
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.
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.
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).
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.
| |  | |
| Converting Existing UNIX Accounts with uss |  | Creating Individual Accounts with the uss add Command |