8e80249d1e91966b0bd45486094f229e54049fe0
[openafs.git] / doc / man-pages / pod5 / uss_bulk.pod
1 =head1 NAME
2
3 uss_bulk - Provides instructions for the uss bulk command (deprecated)
4
5 =head1 CAUTIONS
6
7 The B<uss> command suite is currently designed for cells using the
8 obsolete Authentication Server, and therefore is primarily useful for
9 sites that have not yet migrated to a Kerberos version 5 KDC. The
10 Authentication Server and supporting commands will be removed in a future
11 version of OpenAFS, which may include B<uss> unless someone who finds it
12 useful converts it to work with a Kerberos version 5 KDC.
13
14 =head1 DESCRIPTION
15
16 The uss bulk input file lists instructions for the B<uss> command
17 interpreter to execute when running the B<uss bulk> command. If the file
18 includes C<add> instructions that reference a B<uss> template file, then
19 the template file must also exist.
20
21 =head2 Summary of Bulk Input File Instructions
22
23 The bulk input file can include the following instructions, each on its
24 own line. A more detailed description of each instruction's syntax follows
25 this list.
26
27 =over 4
28
29 =item add
30
31 Creates a user account. Equivalent to the B<uss add> command.
32
33 =item delete
34
35 Deletes a user account. Equivalent to the B<uss delete> command.
36
37 =item delvolume
38
39 Removes the volume and VLDB entry for each account referenced by a
40 C<delete> instruction that follows this instruction in the bulk input
41 file.
42
43 =item exec
44
45 Executes a command.
46
47 =item savevolume
48
49 Preserves the volume and VLDB entry for each account referenced by a
50 C<delete> instruction that follows this instruction in the bulk input
51 file.
52
53 =back
54
55 =head2 The add Instruction for Creating an Account
56
57 The C<add> instruction creates a user account. Each instance in the bulk
58 input file is equivalent in effect to a B<uss add> command issued on the
59 command line. The order of the instruction's fields matches the order of
60 arguments to the B<uss add> command, although some arguments do not have a
61 corresponding field. Like the B<uss add> command's arguments, many of the
62 fields correspond to (provide a value for) a variable in the B<uss>
63 template file, as indicated in the following description of each field.
64
65 The instruction's syntax is as follows. It appears on multiple lines here
66 only for the sake of legibility -- each C<add> instruction must appear on
67 a single line in the bulk input file.
68
69    add <username>[:<full_name>][:<password>][:<expires>]
70        [:<file_server>][:<partition>][:<mount_point>][:<uid>]
71        [:<var1>][:<var2>][:<var3>][:<var4>][:<var5>][:<var6>][:<var7>]
72        [:<var8>][:<var9>][:]
73
74 To omit a value for a field (presumably because it is optional or the
75 template specifies a constant value for it), type nothing between the two
76 colons that surround it. After the last argument provided, end the line
77 with either a colon and carriage return, or a carriage return alone.
78
79 The meaning of, and acceptable values for, each field are as follows.
80
81 =over 4
82
83 =item <username>
84
85 Names the user's Authentication Database and Protection Database
86 entries. It can include up to eight alphanumeric characters, but not the
87 C<:> (colon), C<.> (period), or C<@> (at-sign) characters. Because it
88 becomes the username (the name under which a user logs in), it is best not
89 to include shell metacharacters and to obey the restrictions that many
90 operating systems impose on usernames (usually, to contain no more than
91 eight lowercase letters).
92
93 Corresponding argument to the B<uss add> command: B<-user>. Corresponding
94 variable in the template file: $USER.
95
96 =item <full_name>
97
98 Specifies the user's full name. Do not surround it with double quotes
99 (C<"">), even if it contains spaces. If not provided, it defaults to the
100 username in the <username> field.
101
102 Corresponding argument to the B<uss add> command: B<-realname>.
103 Corresponding variable in the template file: $NAME. Many operating systems
104 include a field for the full name in a user's entry in the local password
105 file (F</etc/passwd> or equivalent), and this variable can be used to pass
106 a value to be used in that field.
107
108 =item <password>
109
110 Specifies the user's initial password. Although the AFS commands that
111 handle passwords accept strings of virtually unlimited length, it is best
112 to use a password of eight characters or less, which is the maximum length
113 that many applications and utilities accept. If not provided, this
114 argument defaults to the string C<changeme>.
115
116 Corresponding argument to the B<uss add> command: B<-pass>. Corresponding
117 variable in the template file: none.
118
119 =item <expires>
120
121 Sets the number of days after a user's password is changed that it remains
122 valid. Provide an integer from the range C<1> through C<254> to specify
123 the number of days until expiration, or the value C<0> to indicate that
124 the password never expires (the default).
125
126 When the password becomes invalid (expires), the user is unable to
127 authenticate, but has 30 more days in which to issue the B<kpasswd>
128 command to change the password (after that, only an administrator can
129 change it).
130
131 Corresponding argument to the B<uss add> command: B<-pwexpires>.
132 Corresponding variable in the template file: $PWEXPIRES.
133
134 =item <file_server>
135
136 Names the file server machine on which to create the new user's volume. It
137 is best to provide a fully-qualified hostname (for example,
138 C<fs1.example.com>), but an abbreviated form is acceptable provided that the
139 cell's naming service is available to resolve it at the time the volume is
140 created.
141
142 Corresponding argument to the B<uss add> command: B<-server>.
143 Corresponding variable in the template file: $SERVER.
144
145 =item <partition>
146
147 Specifies the partition on which to create the user's volume; it must
148 reside on the file server machine named in the <file_server>
149 field. Identify the partition by its complete name (for example,
150 F</vicepa>, or use one of the following abbreviations:
151
152    /vicepa     =     vicepa      =      a      =      0
153    /vicepb     =     vicepb      =      b      =      1
154
155 After F</vicepz> (for which the index is 25) comes
156
157    /vicepaa    =     vicepaa     =      aa     =      26
158    /vicepab    =     vicepab     =      ab     =      27
159
160 and so on through
161
162    /vicepiv    =     vicepiv     =      iv     =      255
163
164 Corresponding argument to the B<uss add> command: B<-partition>.
165 Corresponding variable in template: $PART.
166
167 =item <mount_point>
168
169 Specifies the complete pathname for the user's home directory.
170
171 Corresponding argument to the B<uss add> command: B<-mount>.
172
173 Corresponding variable in template: $MTPT, but in the template file's C<V>
174 instruction only. Occurrences of the $MTPT variable in template
175 instructions that follow the C<V> instruction take their value from the
176 C<V> instruction's <mount_point> field. Thus the value of this command
177 line argument becomes the value for the $MTPT variable in instructions
178 that follow the C<V> instruction only if the string $MTPT appears alone in
179 the C<V> instruction's <mount_point> field.
180
181 =item <uid>
182
183 Specifies a positive integer other than C<0> (zero) to assign as the
184 user's AFS UID. If this argument is omitted, the Protection Server assigns
185 an AFS UID that is one greater than the current value of the C<max user
186 id> counter (use the B<pts listmax> command to display the counter). If
187 including this argument, first use the B<pts examine> command to verify
188 that no existing account already has the desired AFS UID; if one does, the
189 account-creation process terminates with an error.
190
191 Corresponding argument to the B<uss add> command: B<-uid>. Corresponding
192 variable in template: $UID.
193
194 =item <var1> through <var9>
195
196 Specifies values for each of the number variables $1 through $9 that can
197 appear in the template file. The number variables allow the administrator
198 to provide values for variables other than the set defined by the B<uss>
199 command suite.
200
201 Corresponding argument to the B<uss add> command: B<-var>. Corresponding
202 variables in template: $1 through $9.
203
204 If providing a value in any of the fields, then in every field that
205 precedes it either provide an actual value or indicate an empty field by
206 putting nothing between two colons. It is acceptable, but not necessary,
207 to indicate empty fields by putting colons after the last field that
208 contains an actual value.
209
210 =back
211
212 =head2 The delete Instruction for Deleting an Account
213
214 The C<delete> instruction deletes a user account from the system. Each
215 instance in the bulk input file is equivalent in effect to a B<uss delete>
216 command issued on the command line. The order of the instruction's fields
217 matches the order of arguments to the B<uss delete> command:
218
219    delete <username>:<mount_point>[:( savevolume | delvolume )][:]
220
221 where
222
223 =over 4
224
225 =item <username>
226
227 Names the entry to delete from the Protection and Authentication
228 Databases.
229
230 =item <mount_point>
231
232 Specifies the complete pathname to the user's home directory, which is
233 deleted from the filespace. By default, the volume mounted there is also
234 deleted from the file server machine where it resides, as is its record
235 from the Volume Location Database (VLDB). To prevent deletion, include the
236 C<savevolume> string in the instruction's third field, or precede this
237 C<delete> instruction with a C<savevolume> instruction. Partial pathnames
238 are interpreted relative to the current working directory.
239
240 =item savevolume
241
242 Retains the volume on its file server machine, and the corresponding entry
243 in the VLDB. Provide this value or C<delvolume> in the third field, or
244 omit both values to treat the volume according to the prevailing default,
245 which is set by a preceding C<savevolume> or C<delvolume> instruction in
246 the bulk input file.
247
248 =item delvolume
249
250 Removes the volume from its file server machine, and the corresponding
251 entry from the VLDB. Provide this value or C<savevolume> in the third
252 field, or omit both values to treat the volume according to the prevailing
253 default, which is set by a preceding C<savevolume> or C<delvolume>
254 instruction in the bulk input file.
255
256 =back
257
258 After the last argument provided, end the line with either a colon and
259 carriage return or a carriage return alone.
260
261 =head2 The exec Instruction for Executing a Command
262
263 The C<exec> instruction executes the specified command, which can be a
264 UNIX shell script or command, a program, or an AFS command. The B<uss>
265 command interpreter must have the necessary privileges in AFS and the
266 local file system; it assumes the AFS and local identities of the issuer
267 of the B<uss bulk> command.
268
269 The instruction's syntax is as follows:
270
271    exec <command>
272
273 =head2 The delvolume and savevolume Instructions
274
275 The C<savevolume> and C<delvolume> instructions determine the default
276 treatment of volumes referenced by the C<delete> instructions that follow
277 them in the bulk input file. Their syntax is as follows:
278
279    savevolume
280    delvolume
281
282 The C<savevolume> instruction prevents the removal of the volume and VLDB
283 entry for all C<delete> instruction that follow it in the bulk input file,
284 and the C<delvolume> instruction removes the volume and VLDB entry for all
285 subsequent C<delete> instructions.  Either setting persists until its
286 opposite appears in the file, or until the end of the bulk file.
287
288 If neither line appears in the bulk input file, the default is to remove
289 the volume and the VLDB entry; C<delete> instructions that appear before
290 the first C<savevolume> instruction are also subject to this default. If a
291 C<delete> instruction's third field specifies either C<savevolume> or
292 C<delvolume>, that setting overrides the default.
293
294 =head1 EXAMPLES
295
296 The following example add instruction creates an authentication-only
297 account. The user's initial password is C<changeme> (the default).
298
299    add anderson
300
301 The following example add instructions refer to the indicated C<V>
302 instruction in a template file (which must appear on a single line in the
303 template file).
304
305    add smith:John Smith:::fs1:a:::::marketing
306    add jones:Pat Jones:::fs3:c:::::finance
307    V user.$USER $SERVER.example.com /vicep$PART 2000 \
308        /afs/example.com/usr/$3/$USER $UID $USER all
309
310 The first add instruction creates an account called C<smith> in the
311 Protection and Authentication Databases, with an initial password
312 C<changeme> and a value for $UID provided by the Protection Server. The
313 volume C<user.smith> resides on partition F</vicepa> of file server
314 machine C<fs1.example.com> and is mounted at
315 F</afs/example.com/usr/marketing/smith>. He owns his home directory and has
316 all access permissions on its root directory's access control list
317 (ACL). The account for C<jones> is similar, except that the volume resides
318 on partition F</vicepc> of file server machine C<fs3.example.com> and is
319 mounted at F</afs/example.com/usr/finance/jones>.
320
321 Notice that the fields corresponding to the volume mount point, UID, $1
322 variable, and $2 variable are empty (between C<a> and C<marketing> on the
323 first example line), because their corresponding variables do not appear
324 in the template file. The initial password field is also empty.
325
326 The following add instructions are equivalent in effect to the preceding
327 example, but explicitly indicate empty fields for all of the number
328 variables that don't have a value:
329
330    add smith:John Smith:::fs1:a:::::marketing::::::
331    add jones:Pat Jones:::fs3:c:::::finance::::::
332
333 The following example shows a complete bulk file containing a set of
334 C<delete> instructions combined with a C<savevolume> instruction. Because
335 the C<delete> instruction for users C<smith>, C<pat>, and C<rogers> appear
336 before the C<savevolume> instruction and the third field is blank in each,
337 the corresponding home volumes are removed. The volume for user C<terry>
338 is retained because the default established by the C<savevolume>
339 instruction applies to it, but user C<johnson>'s volume is removed because
340 the third field of her C<delete> instruction overrides the current
341 default.
342
343    delete smith:/afs/example.com/usr/smith
344    delete pat:/afs/example.com/usr/pat
345    delete rogers:/afs/example.com/usr/rogers
346    savevolume
347    delete terry:/afs/example.com/usr/terry
348    delete johnson:/afs/example.com/usr/johnson:delvolume
349
350 The following example exec instruction appears between sets of C<add> and
351 C<delete> instructions in a bulk input file.  A message appears in the
352 command shell where the B<uss bulk> command is issued, to indicate when
353 the additions are finished and the deletions beginning.
354
355    exec echo "Additions completed; beginning deletions..."
356
357 =head1 SEE ALSO
358
359 L<uss(5)>,
360 L<uss_add(8)>,
361 L<uss_bulk(8)>,
362 L<uss_delete(8)>
363
364 =head1 COPYRIGHT
365
366 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
367
368 This documentation is covered by the IBM Public License Version 1.0.  It was
369 converted from HTML to POD by software written by Chas Williams and Russ
370 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.