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.