3 uss Bulk Input File - Provides instructions for the uss bulk command
7 The uss bulk input file lists instructions for the
8 B<uss> command interpreter to execute when running the B<uss
9 bulk> command. If the file includes B<add> instructions
10 that reference a B<uss> template file, then the template file must
13 Summary of Bulk Input File Instructions
15 The bulk input file can include the following instructions, each on its own
16 line. A more detailed description of each instruction's syntax
23 Creates a user account. Equivalent to the uss add
28 Deletes a user account. Equivalent to the uss delete
33 Removes the volume and VLDB entry for each account referenced by a
34 B<delete> instruction that follows this instruction in the bulk input
43 Preserves the volume and VLDB entry for each account referenced by a
44 B<delete> instruction that follows this instruction in the bulk input
49 The add Instruction for Creating an Account
53 The add instruction creates a user account. Each instance
54 in the bulk input file is equivalent in effect to a B<uss add> command
55 issued on the command line. The order of the instruction's fields
56 matches the order of arguments to the B<uss add> command, although
57 some arguments do not have a corresponding field. Like the B<uss
58 add> command's arguments, many of the fields correspond to (provide
59 a value for) a variable in the B<uss> template file, as indicated in
60 the following description of each field.
62 The instruction's syntax is as follows. It appears on multiple
63 lines here only for the sake of legibility--each B<add>
64 instruction must appear on a single line in the bulk input file.
66 add I<username>[:I<full_name>][:I<initial_password>][:I<password_expires>]
67 [:I<file_server>][:I<partition>][:I<mount_point>][:I<uid>][:I<var1>][:I<var2>]
68 [:I<var3>][:I<var4>][:I<var5>][:I<var6>][:I<var7>][:I<var8>][:I<var9>][:]
70 To omit a value for a field (presumably because it is optional or the
71 template specifies a constant value for it), type nothing between the two
72 colons that surround it. After the last argument provided, end the line
73 with either a colon and carriage return, or a carriage return alone.
75 The meaning of, and acceptable values for, each field are as
83 Names the user's Authentication Database and Protection Database
84 entries. It can include up to eight alphanumeric characters, but not
85 the B<:> (colon), B<.> (period), or B<@>
86 (at-sign) characters. Because it becomes the username (the name under
87 which a user logs in), it is best not to include shell metacharacters and to
88 obey the restrictions that many operating systems impose on usernames
89 (usually, to contain no more than eight lowercase letters).
91 Corresponding argument to the uss add command:
92 B<-user>. Corresponding variable in the template file:
98 Specifies the user's full name. Do not surround it with double
99 quotes (""), even if it contains spaces. If not provided, it defaults
100 to the username in the I<username> field.
102 Corresponding argument to the uss add command:
103 B<-realname>. Corresponding variable in the template
104 file: $NAME. Many operating systems include a field for the full
105 name in a user's entry in the local password file (B</etc/passwd>
106 or equivalent), and this variable can be used to pass a value to be used in
109 =item I<initial_password
112 Specifies the user's initial password. Although the AFS
113 commands that handle passwords accept strings of virtually unlimited length,
114 it is best to use a password of eight characters or less, which is the maximum
115 length that many applications and utilities accept. If not provided,
116 this argument defaults to the string B<changeme>.
118 Corresponding argument to the uss add command:
119 B<-pass>. Corresponding variable in the template file:
122 =item I<password_expires
125 Sets the number of days after a user's password is changed that it
126 remains valid. Provide an integer from the range B<1> through
127 B<254> to specify the number of days until expiration, or the value
128 B<0> to indicate that the password never expires (the default).
130 When the password becomes invalid (expires), the user is unable to
131 authenticate, but has 30 more days in which to issue the B<kpasswd>
132 command to change the password (after that, only an administrator can change
135 Corresponding argument to the uss add command:
136 B<-pwexpires>. Corresponding variable in the template
142 Names the file server machine on which to create the new user's
143 volume. It is best to provide a fully-qualified hostname (for example,
144 B<fs1.abc.com>), but an abbreviated form is acceptable
145 provided that the cell's naming service is available to resolve it at the
146 time the volume is created.
148 Corresponding argument to the uss add command:
149 B<-server>. Corresponding variable in the template file:
155 Specifies the partition on which to create the user's volume; it
156 must reside on the file server machine named in the I<file_server>
157 field. Identify the partition by its complete name (for example,
158 B</vicepa>, or use one of the following abbreviations:
160 B</vicepa> = B<vicepa> = B<a> = 0
161 B</vicepb> = B<vicepb> = B<b> = 1
163 After /vicepz (for which the index is 25) comes
165 B</vicepaa> = B<vicepaa> = B<aa> = 26
166 B</vicepab> = B<vicepab> = B<ab> = 27
170 B</vicepiv> = B<vicepiv> = B<iv> = 255
172 Corresponding argument to the uss add command:
173 B<-partition>. Corresponding variable in template:
179 Specifies the complete pathname for the user's home directory.
181 Corresponding argument to the uss add command:
184 Corresponding variable in template: $MTPT, but in the template
185 file's B<V> instruction only. Occurrences of the $MTPT
186 variable in template instructions that follow the B<V> instruction
187 take their value from the B<V> instruction's I<mount_point>
188 field. Thus the value of this command line argument becomes the value
189 for the $MTPT variable in instructions that follow the B<V>
190 instruction only if the string $MTPT appears alone in the B<V>
191 instruction's I<mount_point> field.
196 Specifies a positive integer other than 0 (zero) to assign as
197 the user's AFS UID. If this argument is omitted, the Protection
198 Server assigns an AFS UID that is one greater than the current value of the
199 C<max> C<user> C<id> counter (use the B<pts
200 listmax> command to display the counter). If including this
201 argument, first use the B<pts examine> command to verify that no
202 existing account already has the desired AFS UID; if one does, the
203 account-creation process terminates with an error.
205 Corresponding argument to the uss add command:
206 B<-uid>. Corresponding variable in template: $UID.
208 =item I<var1 through I<var9>
211 Specifies values for each of the number variables $1 through $9 that can
212 appear in the template file. The number variables allow the
213 administrator to provide values for variables other than the set defined by
214 the B<uss> command suite.
216 Corresponding argument to the uss add command:
217 B<-var>. Corresponding variables in template: $1 through
220 If providing a value in any of the fields, then in every field that
221 precedes it either provide an actual value or indicate an empty field by
222 putting nothing between two colons. It is acceptable, but not
223 necessary, to indicate empty fields by putting colons after the last field
224 that contains an actual value.
228 The delete Instruction for Deleting an Account
232 The delete instruction deletes a user account from the
233 system. Each instance in the bulk input file is equivalent in effect to
234 a B<uss delete> command issued on the command line. The order
235 of the instruction's fields matches the order of arguments to the
236 B<uss delete> command:
238 delete I<username>:I<mount_point_path>[:{ savevolume | delvolume }][:]
247 Names the entry to delete from the Protection and Authentication
250 =item I<mount_point_path
253 Specifies the complete pathname to the user's home directory, which
254 is deleted from the filespace. By default, the volume mounted there is
255 also deleted from the file server machine where it resides, as is its record
256 from the Volume Location Database (VLDB). To prevent deletion, include
257 the B<savevolume> string in the instruction's third field, or
258 precede this B<delete> instruction with a B<savevolume>
259 instruction. Partial pathnames are interpreted relative to the current
264 Retains the volume on its file server machine, and the corresponding entry
265 in the VLDB. Provide this value or B<delvolume> in the third
266 field, or omit both values to treat the volume according to the prevailing
267 default, which is set by a preceding B<savevolume> or
268 B<delvolume> instruction in the bulk input file.
272 Removes the volume from its file server machine, and the corresponding
273 entry from the VLDB. Provide this value or B<savevolume> in the
274 third field, or omit both values to treat the volume according to the
275 prevailing default, which is set by a preceding B<savevolume> or
276 B<delvolume> instruction in the bulk input file.
280 After the last argument provided, end the line with either a colon and
281 carriage return or a carriage return alone.
283 The exec Instruction for Executing a Command
285 The exec instruction executes the specified command, which can
286 be a UNIX shell script or command, a program, or an AFS command. The
287 B<uss> command interpreter must have the necessary privileges in AFS
288 and the local file system; it assumes the AFS and local identities of the
289 issuer of the B<uss bulk> command.
291 The instruction's syntax is as follows:
295 The delvolume and savevolume Instructions for Setting the Default
302 The B<savevolume> and delvolume instructions determine
303 the default treatment of volumes referenced by the B<delete>
304 instructions that follow them in the bulk input file. Their syntax is
310 The savevolume instruction prevents the removal of the volume
311 and VLDB entry for all B<delete> instruction that follow it in the
312 bulk input file, and the B<delvolume> instruction removes the volume
313 and VLDB entry for all subsequent B<delete> instructions.
314 Either setting persists until its opposite appears in the file, or until the
315 end of the bulk file.
317 If neither line appears in the bulk input file, the default is to remove
318 the volume and the VLDB entry; B<delete> instructions that appear
319 before the first B<savevolume> instruction are also subject to this
320 default. If a B<delete> instruction's third field
321 specifies either B<savevolume> or B<delvolume>, that setting
322 overrides the default.
326 The following example add instruction creates an
327 authentication-only account. The user's initial password is
328 B<changeme> (the default).
332 The following example add instructions refer to the indicated
333 B<V> instruction in a template file (which must appear on a single
334 line in the template file).
336 add smith:John Smith:::fs1:a:::::marketing
337 add jones:Pat Jones:::fs3:c:::::finance
338 V user.$USER $SERVER.abc.com /vicep$PART 2000 \
339 /afs/abc.com/usr/$3/$USER $UID $USER all
341 The first add instruction creates an account called
342 B<smith> in the Protection and Authentication Databases, with an
343 initial password B<changeme> and a value for $UID provided by the
344 Protection Server. The volume B<user.smith> resides on
345 partition B</vicepa> of file server machine
346 B<fs1.abc.com> and is mounted at
347 B</afs/abc.com/usr/marketing/smith>. He owns his home
348 directory and has all access permissions on its root directory's access
349 control list (ACL). The account for B<jones> is similar, except
350 that the volume resides on partition B</vicepc> of file server machine
351 B<fs3.abc.com> and is mounted at
352 B</afs/abc.com/usr/finance/jones>.
354 Notice that the fields corresponding to the volume mount point, UID, $1
355 variable, and $2 variable are empty (between C<a> and
356 C<marketing> on the first example line), because their corresponding
357 variables do not appear in the template file. The initial password
360 The following add instructions are equivalent in effect to the
361 preceding example, but explicitly indicate empty fields for all of the number
362 variables that don't have a value:
364 add smith:John Smith:::fs1:a:::::marketing::::::
365 add jones:Pat Jones:::fs3:c:::::finance::::::
367 The following example shows a complete bulk file containing a set of
368 B<delete> instructions combined with a B<savevolume>
369 instruction. Because the B<delete> instruction for users
370 B<smith>, B<pat>, and B<rogers> appear before the
371 B<savevolume> instruction and the third field is blank in each, the
372 corresponding home volumes are removed. The volume for user
373 B<terry> is retained because the default established by the
374 B<savevolume> instruction applies to it, but user
375 B<johnson>'s volume is removed because the third field of her
376 B<delete> instruction overrides the current default.
378 delete smith:/afs/abc.com/usr/smith
379 delete pat:/afs/abc.com/usr/pat
380 delete rogers:/afs/abc.com/usr/rogers
382 delete terry:/afs/abc.com/usr/terry
383 delete johnson:/afs/abc.com/usr/johnson:delvolume
385 The following example exec instruction appears between sets of
386 B<add> and B<delete> instructions in a bulk input file.
387 A message appears in the command shell where the B<uss bulk> command
388 is issued, to indicate when the additions are finished and the deletions
391 exec echo "Additions completed; beginning deletions..."
395 L<uss Template File(1)>
403 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
405 This documentation is covered by the IBM Public License Version 1.0. It was
406 converted from HTML to POD by software written by Chas Williams and Russ
407 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.