![[Return to Library]](../books.gif)
![[Contents]](../toc.gif)
![[Previous Topic]](../prev.gif)
![[Bottom of Topic]](../bot.gif)
![[Next Topic]](../next.gif)
![[Index]](../index.gif)
Provides instructions for the uss add command
Description
The uss template file defines the components of an AFS user account that the uss add command (or add instruction in a uss bulk input file) creates. Use the -template argument to the uss add or uss bulk command to identify the template file.
Summary of Template File Instructions
The template file can include the following instructions, each on its own line. A more detailed description of each instruction's syntax follows this list.
If the template file is empty (zero-length), the uss add command or add instruction in a bulk input file only creates an entry in the Protection and Authentication Databases, naming them according to the name specified with the uss add command's -user argument, or in the bulk input file add instruction's username field.
The A Instruction for Setting the Default Treatment of Volumes
The A instruction in a uss template file enhances cell security by imposing the following restrictions on users' password choice and authentication attempts. For further information on these limits, see the IBM AFS Administration Guide and the kas setfields reference page.
The instruction has the following syntax:
A username password_lifetime password_reuse failures locktime
where
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, the default is for the user's password never to expire.
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.
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 non-zero value to the next higher multiple of 8.5 minutes. A value of 0 (zero) sets an infinite lockout time; an administrator must always issue the kas unlock command to unlock the account.
The D Instruction for Creating a Directory
The D instruction in a uss template file creates a directory. Its intended use is to create a subdirectory in the user home directory created by the V instruction in the template file.
Any number of D instructions can appear in the template file. If any variables in the instruction take their values from the V instruction (notably, the $MTPT variable), the instruction must follow the V instruction in the file.
Although it is possible to use the D instruction to create a directory on the local disk of the machine where the uss command is issued, it is not recommended. The preferred method for automated creation of directories on a local disk is the package program. Two complications arise if the pathname field refers to a local disk directory:
The instruction has the following syntax:
D pathname mode_bits owner ACL
where
Specify the read/write path to the directory, to avoid the failure that results from attempting to create a new directory in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, /afs/.abc.com). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the fs mkmount command.
For an AFS directory, grant all permissions to the directory's owner at least. Usually that is the new user, in which case the appropriate value is $USER all.
It is not possible to grant any permissions to the issuer of the uss command. As the last step in account creation, the uss command interpreter automatically deletes that person from any ACLs set during the creation process.
The E Instruction for Creating a Single-line File
The E instruction in a uss template file creates a file by echoing a specified character string into it. Its intended use is to create files in the user home directory created by the V instruction in the template file, or in a subdirectory created by a D instruction.
Any number of E instructions can appear in the template file. If the file resides in a directory created by a D instruction, the E instruction must follow the D instruction in the file.
The E and F instructions have complementary advantages. The character string echoed into the file by an E instruction can be customized for each user, because it can include the standard variables for which the uss command interpreter substitutes the values specified by arguments to the uss add command or fields in a bulk input file add instruction. In contrast, a file created using the F instruction cannot include variables and so has the same content for all users. However, a file created by an E instruction can be a single line only, because no carriage returns (newline characters) are allowed in the character string.
Although it is possible to use the E instruction to create a file on the local disk of the machine where the uss command is issued, it is not recommended. The preferred method for automated creation of files on a local disk is the package program. The main complication is that designating any user other than the issuer as the new file's owner requires logging onto the machine as the local superuser root. For local disk files, only the local superuser root is allowed to issue the UNIX chown command that the uss command interpreter invokes to change the owner from the default value (the file's creator, which in this case is the issuer of the uss command). The issuer must then also use the -admin argument to the uss add or uss bulk command to authenticate as a privileged AFS administrator, which is required for creating the Authentication Database and Protection Database entries that the uss command interpreter always creates for a new account.
The instruction has the following syntax:
E pathname mode_bits owner "contents"
where
Specify the read/write path to the file, to avoid the failure that results from attempting to create a new file in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, /afs/.abc.com). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the fs mkmount command.
The F Instruction for Creating a File from a Prototype
The F instruction in a uss template file creates a file by copying the contents of an existing file (the prototype) into it. Its intended use is to create files in the user home directory created by the V instruction in the template file, or in a subdirectory created by a D instruction.
Any number of F instructions can appear in the template file. If the file resides in a directory created by a D instruction, the F instruction must follow the D instruction in the file.
The E and F instructions have complementary advantages. A file created using the F instruction has the same content for all users, whereas a file created by an E instruction can be customized for each user if it includes variables. However, a file created by an E instruction can be a single line only, whereas the prototype file copied by an F instruction can be any length.
Although it is possible to use the F instruction to create a file on the local disk of the machine where the uss command is issued, it is not recommended. The preferred method for automated creation of files on a local disk is the package program. The main complication is that designating any user other than the issuer as the new file's owner requires logging onto the machine as the local superuser root. For local disk files, only the local superuser root is allowed to issue the UNIX chown command that the uss command interpreter invokes to change the owner from the default value (the file's creator, which in this case is the issuer of the uss command). The issuer must then also use the -admin argument to the uss add or uss bulk command to authenticate as a privileged AFS administrator, which is required for creating the Authentication Database and Protection Database entries that the uss command interpreter always creates for a new account.
The instruction has the following syntax:
F pathname mode_bits owner prototype_file
where
Specify the read/write path to the file, to avoid the failure that results from attempting to create a new file in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, /afs/.abc.com). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the fs mkmount command.
The G Instruction for Facilitating Even Distribution of Home Directories
The G instruction in a uss template file creates a directory as one of the set of directories from which the uss command interpreter selects when choosing a new user home directory's parent directory. More specifically, when the $AUTO variable appears in the mount_point field of a V instruction, the command interpreter substitutes for it the directory defined by a G instruction that currently has the fewest entries.
The instruction's intended use is to distribute user accounts evenly among several directories, rather than using directories that reflect divisions such as departmental affiliation. Distributing home directories in this fashion is useful mainly in very large cells where storing all user home directories under a single parent directory potentially slows directory lookup, or where a workplace-based division results in unevenly sized directories such that some users consistently experience slower directory lookup than others. See the chapter on uss in the IBM AFS Administration Guide for more information.
Any number of G instructions can appear in the template file. If the V instruction includes the $AUTO variable, it must appear after all of the G instructions in the file.
The instruction has the following syntax:
G directory
where
Specify the read/write path to the directory, to avoid the failure that results from attempting to create a new mount point in a read-only volume when the $AUTO variable is used in a V instruction's mount_point field. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, /afs/.abc.com). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the fs mkmount command.
The L and S Instructions for Creating a Link
The L instruction in a uss 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. A full explanation of links is beyond the scope of this document, but the basic effect is to create a second name for an existing file, enabling access via either name. Creating a link does not create a second copy of the file.
AFS allows hard links only if the linked files reside in the same directory, because it becomes difficult to determine which access control list (ACL) applies to the file if the two copies reside in directories with different ACLs. AFS allows symbolic links between two files that reside in different directories, or even different volumes. The File Server uses the ACL associated with the actual file rather than the link.
Any number of L and S instructions can appear in the template file. If the existing file or link is to reside in a directory created by a D instruction, or if the existing file was created by an E or F instruction, the L or S instruction must follow the D, E, or F instruction.
The instructions share the following syntax:
L existing_file link S existing_file link
where
Specify the read/write path to the link, to avoid the failure that results from attempting to create a new link in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, /afs/.abc.com). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the fs mkmount command.
The V Instruction for Creating and Mounting a Volume
The V instruction in a uss template file creates a volume on a specified file server machine and partition and creates an entry for it in the Volume Location Database (VLDB). It mounts the volume at a location in the AFS file space that becomes the user's home directory, then designates the directory's owner and sets its access control list (ACL).
Only one V instruction can appear in the template file, and one must appear if the template file contains any instructions at all (is not empty). All other instructions are optional, except that the template must include G instructions if the $AUTO variable appears in it. (The V instruction is not necessarily the first line in the template. If the template includes the $AUTO variable, then the G instructions which provide values for the variable must precede it in the file.)
The instruction has the following syntax:
V volume_name server partition quota mount_point owner ACL
where
/vicepa = vicepa = a = 0 /vicepb = vicepb = b = 1
After /vicepz (for which the index is 25) comes
/vicepaa = vicepaa = aa = 26 /vicepab = vicepab = ab = 27
and so on through
/vicepiv = vicepiv = iv = 255
To read in the value from the uss add command's -partition argument, specify the value $PART.
Specify the read/write path to the mount point, to avoid the failure that results from attempting to create a new mount point in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, /afs/.abc.com). If the $AUTO variable appears 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 the reference page for the fs mkmount command..
| Note: | If used, the $MTPT variable in this field takes its value from the uss add command's -mount argument or from the mount_point field of an add instruction in the bulk input file. However, subsequent uses of the $MTPT variable (usually in following D, E, or F instructions) take as their value the complete contents of this field. |
Grant all permissions to the new user at least. The appropriate value is $USER all.
AFS automatically grants the system:administrators group all permissions as well. It is not possible to grant any permissions to the issuer of the uss command. As the last step in account creation, the uss command interpreter automatically deletes that user from any ACLs set during the creation process.
The X Instruction for Running a Command
The X instruction in a uss template file runs the indicated command, which can be a standard UNIX or AFS command. It can include any variables from the template file, which the uss command interpreter resolves before passing the command on to the appropriate other command interpreter. It must be a single line only, however (cannot contain carriage returns or newline characters).
Any number of X instructions can appear in the template file. If an instruction manipulates an element created by another instruction, it must follow that instruction in the file.
The instruction has the following syntax:
X "command"
where
Examples
The following example A instruction sets a password lifetime of 254 days, prohibits password reuse, limits the number of consecutive failed authentication attempts to nine and sets the corresponding locktime to 25:30 minutes (which is a multiple of 8.5 minutes). The username is read in from the -user argument to the uss add command or from the username field in each add instruction in a bulk input file.
A $USER 254 noreuse 9 25:30
The following example D instruction creates a directory called public in a new user's home directory, designates the user as the directory's owner, and grants him or her all ACL permissions.
D $MTPT/public 0755 $UID $USER all
The following example E instruction creates a file in the current working directory called username.etcp. The contents are an entry suitable for incorporating into the cell's global /etc/password file.
E $USER.etcp 0644 root "$USER:X:$UID:10:$NAME:$MTPT:/bin/csh"
The following example F instruction, appropriate for the ABC Corporation cell, copies a prototype .login file into the user's home directory.
F $MTPT/.login 0644 $UID /afs/abc.com/common/uss/skel/.login
In the following example, the State University cell's administrators have decided to distribute user home directories evenly into three directories. They define three G instructions:
G usr1 G usr2 G usr3
and then put the following value in the mount_point field of the V instruction:
/afs/stateu.edu/$AUTO/$USER
Alternatively, if they include the entire directory pathname in the G instruction:
G /afs/stateu.edu/usr1 G /afs/stateu.edu/usr2 G /afs/stateu.edu/usr3
then the mount_point field of the V instruction specifies only the following:
$AUTO/$USER
The following example L instruction creates a hard link between the files mail and mbox in the user's home directory.
L $MTPT/mbox $MTPT/mail
The following example S instruction, appropriate for the ABC Corporation cell, links the file Mail/outgoing in the user's home directory to the file /afs/abc.com/common/mail/outgoing.
S /afs/abc.com/common/mail/outgoing $MTPT/Mail/outgoing
The following example V instruction creates a volume called user.username on the /vicepa partition of the specified file server machine, assigning it a quota of 3000 kilobyte blocks. The mount point is under /afs/abc.com/usr and matches the username (the value of the $USER variable). The user owns the home directory and has all access rights to it. The instruction appears on two lines only for legibility; it must appear on a single line in the template file.
V user.$USER $SERVER.abc.com /vicepa 3000 \
/afs/abc.com/usr/$USER $UID $USER all
The following example X instruction mounts the backup version of the user's volume at the OldFiles subdirectory.
X "fs mkm /afs/abc.com/usr/$USER/OldFiles user.$USER.backup"
Related Information
![[Top of Topic]](../top.gif)