USS_BULK(5) AFS File Reference USS_BULK(5)NAMEuss_bulk - Provides instructions for the uss bulk command (deprecated)
CAUTIONS
The uss command suite is currently designed for cells using the
obsolete Authentication Server, and therefore is primarily useful for
sites that have not yet migrated to a Kerberos version 5 KDC. The
Authentication Server and supporting commands will be removed in a
future version of OpenAFS, which may include uss unless someone who
finds it useful converts it to work with a Kerberos version 5 KDC.
DESCRIPTION
The uss bulk input file lists instructions for the uss command
interpreter to execute when running the uss bulk command. If the file
includes "add" instructions that reference a uss template file, then
the template file must also exist.
Summary of Bulk Input File Instructions
The bulk input file can include the following instructions, each on its
own line. A more detailed description of each instruction's syntax
follows this list.
add Creates a user account. Equivalent to the uss add command.
delete
Deletes a user account. Equivalent to the uss delete command.
delvolume
Removes the volume and VLDB entry for each account referenced by a
"delete" instruction that follows this instruction in the bulk
input file.
exec
Executes a command.
savevolume
Preserves the volume and VLDB entry for each account referenced by
a "delete" instruction that follows this instruction in the bulk
input file.
The add Instruction for Creating an Account
The "add" instruction creates a user account. Each instance in the bulk
input file is equivalent in effect to a uss add command issued on the
command line. The order of the instruction's fields matches the order
of arguments to the uss add command, although some arguments do not
have a corresponding field. Like the uss add command's arguments, many
of the fields 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
here only for the sake of legibility -- each "add" instruction must
appear on a 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 the
template specifies a constant value for it), type nothing between the
two colons that surround it. After the last argument provided, end the
line with either a colon and carriage return, or a carriage return
alone.
The meaning of, and acceptable values for, each field are as follows.
<username>
Names the user's Authentication Database and Protection Database
entries. It can include up to eight alphanumeric characters, but
not the ":" (colon), "." (period), or "@" (at-sign) characters.
Because it becomes the username (the name under which a user logs
in), it is best not to include shell metacharacters and to obey the
restrictions that many operating systems impose on usernames
(usually, to contain no more than eight lowercase letters).
Corresponding argument to the uss add command: -user. Corresponding
variable in the template file: $USER.
<full_name>
Specifies the user's full name. Do not surround it with double
quotes (""), even if it contains spaces. If not provided, it
defaults to the username in the <username> field.
Corresponding argument to the uss add command: -realname.
Corresponding variable in the template file: $NAME. Many operating
systems include a field for the full name in a user's entry in the
local password file (/etc/passwd or equivalent), and this variable
can be used to pass a value to be used in that field.
<password>
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. If
not provided, this argument defaults to the string "changeme".
Corresponding argument to the uss add command: -pass. Corresponding
variable in the template file: none.
<expires>
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).
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).
Corresponding argument to the uss add command: -pwexpires.
Corresponding variable in the template file: $PWEXPIRES.
<file_server>
Names the file server machine on which to create the new user's
volume. It is best to provide a fully-qualified hostname (for
example, "fs1.abc.com"), but an abbreviated form is acceptable
provided that the cell's naming service is available to resolve it
at the time the volume is created.
Corresponding argument to the uss add command: -server.
Corresponding variable in the template file: $SERVER.
<partition>
Specifies the partition on which to create the user's volume; it
must reside 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 = 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
Corresponding argument to the uss add command: -partition.
Corresponding variable in template: $PART.
<mount_point>
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 "V" instruction only. Occurrences of the $MTPT variable in
template instructions that follow the "V" instruction take their
value from the "V" instruction's <mount_point> field. Thus the
value of this command line argument becomes the value for the $MTPT
variable in instructions that follow the "V" instruction only if
the string $MTPT appears alone in the "V" instruction's
<mount_point> field.
<uid>
Specifies a positive integer other than 0 (zero) to assign as the
user's AFS UID. If this argument is omitted, the Protection Server
assigns an AFS UID that is one greater than the current value of
the "max user id" counter (use the pts listmax command to display
the counter). If including this argument, first use the pts examine
command to verify that no existing account already has the desired
AFS UID; if one does, the account-creation process terminates with
an error.
Corresponding argument to the uss add command: -uid. Corresponding
variable in template: $UID.
<var1> through <var9>
Specifies values for each of the number variables $1 through $9
that can appear in the template file. The number variables allow
the administrator to provide values for variables other than the
set defined by the uss command suite.
Corresponding argument to the uss add command: -var. Corresponding
variables in template: $1 through $9.
If providing a value in any of the fields, then in every field that
precedes it either provide an actual value or indicate an empty
field by putting nothing between two colons. It is acceptable, but
not necessary, to indicate empty fields by putting colons after the
last field that contains an actual value.
The delete Instruction for Deleting an Account
The "delete" instruction deletes a user account from the system. Each
instance 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
fields matches the order of arguments to the uss delete command:
delete <username>:<mount_point>[:( savevolume | delvolume )][:]
where
<username>
Names the entry to delete from the Protection and Authentication
Databases.
<mount_point>
Specifies the complete pathname to the user's home directory, which
is deleted from the filespace. By default, the volume mounted there
is also deleted from the file server machine where it resides, as
is its record from the Volume Location Database (VLDB). To prevent
deletion, include the "savevolume" string in the instruction's
third field, or precede this "delete" instruction with a
"savevolume" instruction. Partial pathnames are interpreted
relative to the current working directory.
savevolume
Retains the volume on its file server machine, and the
corresponding entry in the VLDB. Provide this value or "delvolume"
in the third field, or omit both values to treat the volume
according to the prevailing default, which is set by a preceding
"savevolume" or "delvolume" instruction in the bulk input file.
delvolume
Removes the volume from its file server machine, and the
corresponding entry from the VLDB. Provide this value or
"savevolume" in the third field, or omit both values to treat the
volume according to the prevailing default, which is set by a
preceding "savevolume" or "delvolume" instruction in the bulk input
file.
After the last argument provided, end the line with either a colon and
carriage return or a carriage return alone.
The exec Instruction for Executing a Command
The "exec" instruction executes the specified command, which can be a
UNIX shell script or command, a program, or an AFS command. The uss
command interpreter must have the necessary privileges in AFS and the
local file system; it assumes the AFS and local identities of the
issuer of the uss bulk command.
The instruction's syntax is as follows:
exec <command>
The delvolume and savevolume Instructions
The "savevolume" and "delvolume" instructions determine 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
The "savevolume" 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 all subsequent "delete" instructions. Either setting
persists until its opposite 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
remove the volume and the VLDB entry; "delete" instructions that appear
before the first "savevolume" instruction are also subject to this
default. If a "delete" instruction's third field specifies either
"savevolume" or "delvolume", that setting overrides the default.
EXAMPLES
The following example add instruction creates an authentication-only
account. The user's initial password is "changeme" (the default).
add anderson
The following example add instructions refer to the indicated "V"
instruction in a template file (which must appear on a single line in
the template 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 the
Protection and Authentication Databases, with an initial password
"changeme" and a value for $UID provided by the Protection Server. The
volume "user.smith" resides on partition /vicepa of file server machine
"fs1.abc.com" and is mounted at /afs/abc.com/usr/marketing/smith. He
owns his home directory and has all access permissions on its root
directory's access control list (ACL). The account for "jones" is
similar, except that the volume resides on partition /vicepc of file
server machine "fs3.abc.com" and is mounted at
/afs/abc.com/usr/finance/jones.
Notice that the fields corresponding to the volume mount point, UID, $1
variable, and $2 variable are empty (between "a" and "marketing" on the
first example line), because their corresponding variables do not
appear in the template file. The initial password field is also empty.
The following add instructions are equivalent in effect to the
preceding example, but explicitly indicate empty fields for all of the
number variables 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 of
"delete" instructions combined with a "savevolume" instruction. Because
the "delete" instruction for users "smith", "pat", and "rogers" appear
before 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
because the third field of her "delete" instruction overrides the
current default.
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"
and "delete" instructions in a bulk input file. A message appears in
the command shell where the uss bulk command is issued, to indicate
when the additions are finished and the deletions beginning.
exec echo "Additions completed; beginning deletions..."
SEE ALSOuss(5), uss_add(8), uss_bulk(8), uss_delete(8)COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
This documentation is covered by the IBM Public License Version 1.0.
It was converted from HTML to POD by software written by Chas Williams
and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
OpenAFS 2013-10-09 USS_BULK(5)
