Section: AFS File Reference (5)
uss_bulk - Provides instructions for the uss bulk command
The uss bulk input file lists instructions for the uss
commandinterpreter to execute when running the uss bulk
command. If the fileincludes add
instructions that reference a uss
template file, thenthe template file must also exist.
Summary of Bulk Input File Instructions
The bulk input file can include the following instructions, each on itsown line. A more detailed description of each instruction's syntax followsthis list.
- Creates a user account. Equivalent to the uss add command.
- Deletes a user account. Equivalent to the uss delete command.
- Removes the volume and VLDB entry for each account referenced by adelete instruction that follows this instruction in the bulk inputfile.
- Executes a command.
- Preserves the volume and VLDB entry for each account referenced by adelete instruction that follows this instruction in the bulk inputfile.
The add Instruction for Creating an Account
instruction creates a user account. Each instance in the bulkinput file is equivalent in effect to a uss add
command issued on thecommand line. The order of the instruction's fields matches the order ofarguments to the uss add
command, although some arguments do not have acorresponding field. Like the uss add
command's arguments, many of thefields correspond to (provide a value for) a variable in the uss
template file, as indicated in the following description of each field.
The instruction's syntax is as follows. It appears on multiple lines hereonly for the sake of legibility -- each add instruction must appear ona single line in the bulk input file.
add <username>[:<full_name>][:<password>][:<expires>] [:<file_server>][:<partition>][:<mount_point>][:<uid>] [:<var1>][:<var2>][:<var3>][:<var4>][:<var5>][:<var6>][:<var7>] [:<var8>][:<var9>][:]
To omit a value for a field (presumably because it is optional or thetemplate specifies a constant value for it), type nothing between the twocolons that surround it. After the last argument provided, end the linewith either a colon and carriage return, or a carriage return alone.
The meaning of, and acceptable values for, each field are as follows.
- Names the user's Authentication Database and Protection Databaseentries. It can include up to eight alphanumeric characters, but not the: (colon), . (period), or @ (at-sign) characters. Because itbecomes the username (the name under which a user logs in), it is best notto include shell metacharacters and to obey the restrictions that manyoperating systems impose on usernames (usually, to contain no more thaneight lowercase letters).
Corresponding argument to the uss add command: -user. Correspondingvariable in the template file: $USER.
- Specifies the user's full name. Do not surround it with double quotes(""), even if it contains spaces. If not provided, it defaults to theusername in the <username> field.
Corresponding argument to the uss add command: -realname.Corresponding variable in the template file: $NAME. Many operating systemsinclude a field for the full name in a user's entry in the local passwordfile (/etc/passwd or equivalent), and this variable can be used to passa value to be used in that field.
- Specifies the user's initial password. Although the AFS commands thathandle passwords accept strings of virtually unlimited length, it is bestto use a password of eight characters or less, which is the maximum lengththat many applications and utilities accept. If not provided, thisargument defaults to the string changeme.
Corresponding argument to the uss add command: -pass. Correspondingvariable in the template file: none.
- Sets the number of days after a user's password is changed that it remainsvalid. Provide an integer from the range 1 through 254 to specifythe number of days until expiration, or the value 0 to indicate thatthe password never expires (the default).
When the password becomes invalid (expires), the user is unable toauthenticate, but has 30 more days in which to issue the kpasswdcommand to change the password (after that, only an administrator canchange it).
Corresponding argument to the uss add command: -pwexpires.Corresponding variable in the template file: $PWEXPIRES.
- Names the file server machine on which to create the new user's volume. Itis best to provide a fully-qualified hostname (for example,fs1.abc.com), but an abbreviated form is acceptable provided that thecell's naming service is available to resolve it at the time the volume iscreated.
Corresponding argument to the uss add command: -server.Corresponding variable in the template file: $SERVER.
- Specifies the partition on which to create the user's volume; it mustreside on the file server machine named in the <file_server>field. Identify the partition by its complete name (for example,/vicepa, or use one of the following abbreviations:
/vicepa = vicepa = a = 0 /vicepb = vicepb = b = 1After /vicepz (for which the index is 25) comes
/vicepaa = vicepaa = aa = 26 /vicepab = vicepab = ab = 27and so on through
/vicepiv = vicepiv = iv = 255Corresponding argument to the uss add command: -partition.Corresponding variable in template: $PART.
- Specifies the complete pathname for the user's home directory.
Corresponding argument to the uss add command: -mount.
Corresponding variable in template: $MTPT, but in the template file's Vinstruction only. Occurrences of the $MTPT variable in templateinstructions that follow the V instruction take their value from theV instruction's <mount_point> field. Thus the value of this commandline argument becomes the value for the $MTPT variable in instructionsthat follow the V instruction only if the string $MTPT appears alone inthe V instruction's <mount_point> field.
- Specifies a positive integer other than 0 (zero) to assign as theuser's AFS UID. If this argument is omitted, the Protection Server assignsan AFS UID that is one greater than the current value of the max userid counter (use the pts listmax command to display the counter). Ifincluding this argument, first use the pts examine command to verifythat no existing account already has the desired AFS UID; if one does, theaccount-creation process terminates with an error.
Corresponding argument to the uss add command: -uid. Correspondingvariable in template: $UID.
- <var1> through <var9>
- Specifies values for each of the number variables $1 through $9 that canappear in the template file. The number variables allow the administratorto provide values for variables other than the set defined by the usscommand suite.
Corresponding argument to the uss add command: -var. Correspondingvariables in template: $1 through $9.
If providing a value in any of the fields, then in every field thatprecedes it either provide an actual value or indicate an empty field byputting nothing between two colons. It is acceptable, but not necessary,to indicate empty fields by putting colons after the last field thatcontains an actual value.
The delete Instruction for Deleting an Account
instruction deletes a user account from the system. Eachinstance in the bulk input file is equivalent in effect to a uss delete
command issued on the command line. The order of the instruction's fieldsmatches the order of arguments to the uss delete
delete <username>:<mount_point>[:( savevolume | delvolume )][:]
- Names the entry to delete from the Protection and AuthenticationDatabases.
- Specifies the complete pathname to the user's home directory, which isdeleted from the filespace. By default, the volume mounted there is alsodeleted from the file server machine where it resides, as is its recordfrom the Volume Location Database (VLDB). To prevent deletion, include thesavevolume string in the instruction's third field, or precede thisdelete instruction with a savevolume instruction. Partial pathnamesare interpreted relative to the current working directory.
- Retains the volume on its file server machine, and the corresponding entryin the VLDB. Provide this value or delvolume in the third field, oromit both values to treat the volume according to the prevailing default,which is set by a preceding savevolume or delvolume instruction inthe bulk input file.
- Removes the volume from its file server machine, and the correspondingentry from the VLDB. Provide this value or savevolume in the thirdfield, or omit both values to treat the volume according to the prevailingdefault, which is set by a preceding savevolume or delvolumeinstruction in the bulk input file.
After the last argument provided, end the line with either a colon andcarriage return or a carriage return alone.
The exec Instruction for Executing a Command
instruction executes the specified command, which can be aUNIX
shell script or command, a program, or an AFS
command. The uss
command interpreter must have the necessary privileges in AFS
and thelocal file system; it assumes the AFS
and local identities of the issuerof the uss bulk
The instruction's syntax is as follows:
The delvolume and savevolume Instructions
instructions determine the defaulttreatment of volumes referenced by the delete
instructions that followthem in the bulk input file. Their syntax is as follows:
instruction prevents the removal of the volume and VLDB
entry for all delete
instruction that follow it in the bulk input file,and the delvolume
instruction removes the volume and VLDB
entry for allsubsequent delete
instructions. Either setting persists until itsopposite appears in the file, or until the end of the bulk file.
If neither line appears in the bulk input file, the default is to removethe volume and the VLDB entry; delete instructions that appear beforethe first savevolume instruction are also subject to this default. If adelete instruction's third field specifies either savevolume ordelvolume, that setting overrides the default.
The following example add instruction creates an authentication-onlyaccount. The user's initial password is changeme
The following example add instructions refer to the indicated V
instruction in a template file (which must appear on a single line in thetemplate file).
add smith:John Smith:::fs1:a:::::marketing add jones:Pat Jones:::fs3:c:::::finance V user.$USER $SERVER.abc.com /vicep$PART 2000 \ /afs/abc.com/usr/$3/$USER $UID $USER all
The first add instruction creates an account called smith
in theProtection and Authentication Databases, with an initial passwordchangeme
and a value for $UID
provided by the Protection Server. Thevolume user.smith
resides on partition /vicepa
of file servermachine fs1.abc.com
and is mounted at/afs/abc.com/usr/marketing/smith
. He owns his home directory and hasall access permissions on its root directory's access control list(ACL). The account for jones
is similar, except that the volume resideson partition /vicepc
of file server machine fs3.abc.com
and ismounted at /afs/abc.com/usr/finance/jones
Notice that the fields corresponding to the volume mount point, UID, $1variable, and $2 variable are empty (between a and marketing on thefirst example line), because their corresponding variables do not appearin the template file. The initial password field is also empty.
The following add instructions are equivalent in effect to the precedingexample, but explicitly indicate empty fields for all of the numbervariables that don't have a value:
add smith:John Smith:::fs1:a:::::marketing:::::: add jones:Pat Jones:::fs3:c:::::finance::::::
The following example shows a complete bulk file containing a set ofdelete
instructions combined with a savevolume
instruction. Becausethe delete
instruction for users smith
, and rogers
appearbefore the savevolume
instruction and the third field is blank in each,the corresponding home volumes are removed. The volume for user terry
is retained because the default established by the savevolume
instruction applies to it, but user johnson
's volume is removed becausethe third field of her delete
instruction overrides the currentdefault.
delete smith:/afs/abc.com/usr/smith delete pat:/afs/abc.com/usr/pat delete rogers:/afs/abc.com/usr/rogers savevolume delete terry:/afs/abc.com/usr/terry delete johnson:/afs/abc.com/usr/johnson:delvolume
The following example exec instruction appears between sets of add
instructions in a bulk input file. A message appears in thecommand shell where the uss bulk
command is issued, to indicate whenthe additions are finished and the deletions beginning.
exec echo "Additions completed; beginning deletions..."
IBM Corporation 2000. <http://www.ibm.com/
> All Rights Reserved.
This documentation is covered by the IBM Public License Version 1.0. It wasconverted from HTML to POD by software written by Chas Williams and RussAllbery, based on work by Alf Wachsmann and Elizabeth Cassell.
- Summary of Bulk Input File Instructions
- The add Instruction for Creating an Account
- The delete Instruction for Deleting an Account
- The exec Instruction for Executing a Command
- The delvolume and savevolume Instructions
- SEE ALSO
This document was created byman2html,using the manual pages.