doc/man-pages/pod5/uss_bulk.pod

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