doc/man-pages/pod5/uss.pod

   1 =head1 NAME
   2
   3 uss - Provides instructions for the uss add command
   4
   5 =head1 DESCRIPTION
   6
   7 The uss template file defines the components of an AFS user account that
   8 the B<uss add> command (or B<add> instruction in a B<uss> bulk input file)
   9 creates. Use the B<-template> argument to the B<uss add> or B<uss bulk>
  10 command to identify the template file.
  11
  12 =head2 Summary of Template File Instructions
  13
  14 The template file can include the following instructions, each on its own
  15 line. A more detailed description of each instruction's syntax follows
  16 this list.
  17
  18 =over 4
  19
  20 =item A
  21
  22 Imposes restrictions on user passwords and authentication attempts.
  23
  24 =item D
  25
  26 Creates a directory.
  27
  28 =item E
  29
  30 Creates a single-line file.
  31
  32 =item F
  33
  34 Creates a file by copying a prototype.
  35
  36 =item G
  37
  38 Defines a directory that is one of a set of parent directories into which
  39 the B<uss> command interpreter evenly distributes newly created home
  40 directories.
  41
  42 =item L
  43
  44 Creates a hard link.
  45
  46 =item S
  47
  48 Creates a symbolic link.
  49
  50 =item V
  51
  52 Creates a volume, mounts it in the file space and sets the ACL on the
  53 mount point.
  54
  55 =item X
  56
  57 Executes a command.
  58
  59 =back
  60
  61 If the template file is empty (zero-length), the B<uss add> command or
  62 C<add> instruction in a bulk input file only creates an entry in the
  63 Protection and Authentication Databases, naming them according to the name
  64 specified with the B<uss add> command's B<-user> argument, or in the bulk
  65 input file C<add> instruction's I<username> field.
  66
  67 =head2 The A Instruction for Setting the Default Treatment of Volumes
  68
  69 The C<A> instruction in a uss template file enhances cell security by
  70 imposing the following restrictions on users' password choice and
  71 authentication attempts. For further information on these limits, see the
  72 I<IBM AFS Administration Guide> and the B<kas setfields> reference page.
  73
  74 =over 4
  75
  76 =item *
  77
  78 Limiting the user's password lifetime. When the lifetime expires, the user
  79 can no longer authenticate using that password, and must change it.
  80
  81 =item *
  82
  83 Prohibiting the reuse of the user's 20 most recently used passwords.
  84
  85 =item *
  86
  87 Limiting the number of consecutive times that a user can provide an
  88 incorrect password during authentication, and for how long the
  89 Authentication Server refuses further authentication attempts after the
  90 limit is exceeded (referred to as an I<account lockout>). For regular user
  91 accounts in most cells, the recommended limit is nine and lockout time is
  92 25 minutes.
  93
  94 =back
  95
  96 The instruction has the following syntax:
  97
  98    A <username> <lifetime> <reuse> <failures> <locktime>
  99
 100 where
 101
 102 =over 4
 103
 104 =item A
 105
 106 Indicates a security-enhancing instruction. It must be a capital letter.
 107
 108 =item <username>
 109
 110 Names the Authentication Database entry on which to impose security
 111 restrictions. Specify the value $USER to read in the username from the
 112 B<uss add> command's B<-user> argument, or from the I<username> field of
 113 an C<add> instruction in a bulk input file.
 114
 115 =item <lifetime>
 116
 117 Sets the number of days after the user's password is changed that it
 118 remains valid. When the password becomes invalid (expires), the user is
 119 unable to authenticate, but has 30 more days in which to issue the
 120 B<kpasswd> command to change the password (after that, only an
 121 administrator can change it).
 122
 123 Specify an integer from the range C<1> through C<254> to specify the
 124 number of days until expiration, the value C<0> to indicate that the
 125 password never expires, or the value $PWEXPIRES to read in the number
 126 of days from the B<uss add> or B<uss bulk> command's B<-pwexpires>
 127 argument. If the C<A> instruction does not appear in the template file,
 128 the default is for the user's password never to expire.
 129
 130 =item <reuse>
 131
 132 Determines whether or not the user can change his or her password (using
 133 the B<kpasswd> or B<kas setpassword> command) to one that is similar to
 134 any of the last twenty passwords. The acceptable values are C<reuse> to
 135 allow reuse and C<noreuse> to prohibit it.  If the C<A> instruction does
 136 not appear in the template file, the default is to allow password reuse.
 137
 138 =item <failures>
 139
 140 Sets the number of consecutive times the user can provide an incorrect
 141 password during authentication (using the B<klog> command or a login
 142 utility that grants AFS tokens). When the user exceeds the limit, the
 143 Authentication Server rejects further authentication attempts for the
 144 amount of time specified in the <locktime> field.
 145
 146 Specify an integer from the range C<1> through C<254> to specify the
 147 number of failures permitted, or the value C<0> to indicate that there is
 148 no limit to the number of unsuccessful attempts.  If the C<A> instruction
 149 does not appear in the template file, the default is to allow an unlimited
 150 number of failures.
 151
 152 =item <locktime>
 153
 154 Specifies how long the Authentication Server refuses authentication
 155 attempts from a user who has exceeded the failure limit set in the
 156 <failures> field.
 157
 158 Specify a number of hours and minutes (I<hh:mm>) or minutes only (I<mm>),
 159 from the range C<01> (one minute) through C<36:00> (36 hours). The
 160 Authentication Server automatically reduces any larger value to C<36:00>
 161 and also rounds up any non-zero value to the next higher multiple of 8.5
 162 minutes. A value of C<0> (zero) sets an infinite lockout time; an
 163 administrator must always issue the B<kas unlock> command to unlock the
 164 account.
 165
 166 =back
 167
 168 =head2 The D Instruction for Creating a Directory
 169
 170 The C<D> instruction in a uss template file creates a directory. Its
 171 intended use is to create a subdirectory in the user home directory
 172 created by the C<V> instruction in the template file.
 173
 174 Any number of C<D> instructions can appear in the template file. If any
 175 variables in the instruction take their values from the C<V> instruction
 176 (notably, the $MTPT variable), the instruction must follow the C<V>
 177 instruction in the file.
 178
 179 Although it is possible to use the C<D> instruction to create a directory
 180 on the local disk of the machine where the B<uss> command is issued, it is
 181 not recommended. The preferred method for automated creation of
 182 directories on a local disk is the B<package> program. Two complications
 183 arise if the <pathname> field refers to a local disk directory:
 184
 185 =over 4
 186
 187 =item *
 188
 189 The B<uss> command prints a warning message because it cannot associate an
 190 access control list (ACL) with a local disk directory. It creates the
 191 directory nonetheless, and some syntactically correct value must appear in
 192 the instruction's <ACL> field.
 193
 194 =item *
 195
 196 To designate any user other than the issuer as the new directory's owner,
 197 the issuer must log onto the machine as the local superuser C<root>. For
 198 local disk directories, only the local superuser C<root> is allowed to
 199 issue the UNIX B<chown> command that the B<uss> command interpreter
 200 invokes to change the owner from the default value (the directory's
 201 creator, which in this case is the issuer of the B<uss> command). The
 202 issuer must then also use the B<-admin> argument to the B<uss add> or
 203 B<uss bulk> command to authenticate as a privileged AFS administrator,
 204 which is required for creating the Authentication Database and Protection
 205 Database entries that the B<uss> command interpreter always creates for a
 206 new account.
 207
 208 =back
 209
 210 The instruction has the following syntax:
 211
 212    D <pathname> <mode> <owner> <ACL>
 213
 214 where
 215
 216 =over 4
 217
 218 =item D
 219
 220 Indicates a directory creation instruction. It must be a capital letter.
 221
 222 =item <pathname>
 223
 224 Specifies the directory's full pathname. It can include variables.
 225
 226 Specify the read/write path to the directory, to avoid the failure that
 227 results from attempting to create a new directory in a read-only
 228 volume. By convention, the read/write path is indicated by placing a
 229 period before the cell name at the pathname's second level (for example,
 230 F</afs/.abc.com>). For further discussion of the concept of read/write and
 231 read-only paths through the filespace, see the reference page for the B<fs
 232 mkmount> command.
 233
 234 =item <mode>
 235
 236 Sets the directory's UNIX mode bits. Acceptable values are the standard
 237 three- or four-digit numbers corresponding to combinations of
 238 permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
 239 C<rw-r--r-->. The first (owner) C<x> bit must be turned on to enable
 240 access to a directory.
 241
 242 =item <owner>
 243
 244 Specifies the username or UNIX user ID (UID) of the user to be designated
 245 the directory's owner in the output from the UNIX C<ls -ld> command. If
 246 the directory resides in AFS, place the $UID variable in this field. If
 247 the directory resides on the local disk, this field must be the username
 248 or UID of the B<uss> command's issuer, unless the issuer is logged in as
 249 the local superuser C<root>.
 250
 251 =item <ACL>
 252
 253 Sets the ACL on the new directory. It must appear even if the new
 254 directory resides on the local disk rather than in AFS, but is ignored in
 255 that case. Provide one or more paired values, each pair consisting of an
 256 AFS username or group name and the desired permissions, in that order.
 257 Separate the two parts of the pair, and each pair, with a space. The B<fs
 258 setacl> reference page describes the available permissions.
 259
 260 For an AFS directory, grant all permissions to the directory's owner at
 261 least. Usually that is the new user, in which case the appropriate value
 262 is C<$USER all>.
 263
 264 It is not possible to grant any permissions to the issuer of the B<uss>
 265 command. As the last step in account creation, the B<uss> command
 266 interpreter automatically deletes that person from any ACLs set during the
 267 creation process.
 268
 269 =back
 270
 271 =head2 The E Instruction for Creating a Single-line File
 272
 273 The C<E> instruction in a uss template file creates a file by echoing a
 274 specified character string into it. Its intended use is to create files in
 275 the user home directory created by the C<V> instruction in the template
 276 file, or in a subdirectory created by a C<D> instruction.
 277
 278 Any number of C<E> instructions can appear in the template file. If the
 279 file resides in a directory created by a C<D> instruction, the C<E>
 280 instruction must follow the C<D> instruction in the file.
 281
 282 The C<E> and C<F> instructions have complementary advantages. The
 283 character string echoed into the file by an C<E> instruction can be
 284 customized for each user, because it can include the standard variables
 285 for which the B<uss> command interpreter substitutes the values specified
 286 by arguments to the B<uss add> command or fields in a bulk input file
 287 B<add> instruction. In contrast, a file created using the C<F> instruction
 288 cannot include variables and so has the same content for all
 289 users. However, a file created by an C<E> instruction can be a single line
 290 only, because no carriage returns (newline characters) are allowed in the
 291 character string.
 292
 293 Although it is possible to use the C<E> instruction to create a file on
 294 the local disk of the machine where the B<uss> command is issued, it is
 295 not recommended. The preferred method for automated creation of files on a
 296 local disk is the B<package> program.  The main complication is that
 297 designating any user other than the issuer as the new file's owner
 298 requires logging onto the machine as the local superuser C<root>. For
 299 local disk files, only the local superuser C<root> is allowed to issue the
 300 UNIX B<chown> command that the B<uss> command interpreter invokes to
 301 change the owner from the default value (the file's creator, which in this
 302 case is the issuer of the B<uss> command). The issuer must then also use
 303 the B<-admin> argument to the B<uss add> or B<uss bulk> command to
 304 authenticate as a privileged AFS administrator, which is required for
 305 creating the Authentication Database and Protection Database entries that
 306 the B<uss> command interpreter always creates for a new account.
 307
 308 The instruction has the following syntax:
 309
 310    E <pathname> <mode> <owner> "<contents>"
 311
 312 where
 313
 314 =over 4
 315
 316 =item E
 317
 318 Indicates a file creation instruction. It must be a capital letter.
 319
 320 =item <pathname>
 321
 322 Specifies the file's full pathname. It can include variables.
 323
 324 Specify the read/write path to the file, to avoid the failure that results
 325 from attempting to create a new file in a read-only volume. By convention,
 326 the read/write path is indicated by placing a period before the cell name
 327 at the pathname's second level (for example, F</afs/.abc.com>). For
 328 further discussion of the concept of read/write and read-only paths
 329 through the filespace, see the reference page for the B<fs mkmount>
 330 command.
 331
 332 =item <mode>
 333
 334 Sets the file's UNIX mode bits. Acceptable values are the standard three-
 335 or four-digit numbers corresponding to combinations of
 336 permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
 337 C<rw-r--r-->.
 338
 339 =item <owner>
 340
 341 Specifies the username or UNIX user ID (UID) of the user to be designated
 342 the file's owner in the output from the UNIX C<ls -l> command. If the file
 343 resides in AFS, place the $UID variable in this field. If the file
 344 resides on the local disk, specify the username or UID of the B<uss>
 345 command's issuer; otherwise, the account creation operation halts
 346 immediately.
 347
 348 =item <contents>
 349
 350 Specifies the one-line character string to write into the new file.
 351 Surround it with double quotes if it contains one or more spaces. It
 352 cannot contain the newline character, but can contain any of the standard
 353 variables, which the command interpreter resolves as it creates the file.
 354
 355 =back
 356
 357 =head2 The F Instruction for Creating a File from a Prototype
 358
 359 The C<F> instruction in a uss template file creates a file by copying the
 360 contents of an existing file (the <prototype>) into it. Its intended use
 361 is to create files in the user home directory created by the C<V>
 362 instruction in the template file, or in a subdirectory created by a C<D>
 363 instruction.
 364
 365 Any number of C<F> instructions can appear in the template file. If the
 366 file resides in a directory created by a C<D> instruction, the C<F>
 367 instruction must follow the C<D> instruction in the file.
 368
 369 The C<E> and C<F> instructions have complementary advantages. A file
 370 created using the C<F> instruction has the same content for all users,
 371 whereas a file created by an C<E> instruction can be customized for each
 372 user if it includes variables.  However, a file created by an C<E>
 373 instruction can be a single line only, whereas the prototype file copied
 374 by an C<F> instruction can be any length.
 375
 376 Although it is possible to use the C<F> instruction to create a file on
 377 the local disk of the machine where the B<uss> command is issued, it is
 378 not recommended. The preferred method for automated creation of files on a
 379 local disk is the B<package> program.  The main complication is that
 380 designating any user other than the issuer as the new file's owner
 381 requires logging onto the machine as the local superuser C<root>. For
 382 local disk files, only the local superuser C<root> is allowed to issue the
 383 UNIX B<chown> command that the B<uss> command interpreter invokes to
 384 change the owner from the default value (the file's creator, which in this
 385 case is the issuer of the B<uss> command). The issuer must then also use
 386 the B<-admin> argument to the B<uss add> or B<uss bulk> command to
 387 authenticate as a privileged AFS administrator, which is required for
 388 creating the Authentication Database and Protection Database entries that
 389 the B<uss> command interpreter always creates for a new account.
 390
 391 The instruction has the following syntax:
 392
 393    F <pathname> <mode> <owner> <prototype_file>
 394
 395 where
 396
 397 =over 4
 398
 399 =item F
 400
 401 Indicates a file creation instruction. It must be a capital letter.
 402
 403 =item <pathname>
 404
 405 Specifies the full pathname of the file to create, including the
 406 filename. It can include variables.
 407
 408 Specify the read/write path to the file, to avoid the failure that results
 409 from attempting to create a new file in a read-only volume. By convention,
 410 the read/write path is indicated by placing a period before the cell name
 411 at the pathname's second level (for example, F</afs/.abc.com>). For
 412 further discussion of the concept of read/write and read-only paths
 413 through the filespace, see the reference page for the B<fs mkmount>
 414 command.
 415
 416 =item <mode>
 417
 418 Sets the file's UNIX mode bits. Acceptable values are the standard three-
 419 or four-digit numbers corresponding to combinations of
 420 permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
 421 C<rw-r--r-->.
 422
 423 =item <owner>
 424
 425 Specifies the username or UNIX user ID (UID) of the user to be designated
 426 the file's owner in the output from the UNIX C<ls -l> command. If the file
 427 resides in AFS, place the $UID variable in this field. If the file
 428 resides on the local disk, specify the username or UID of the B<uss>
 429 command's issuer; otherwise, the account creation operation halts
 430 immediately.
 431
 432 =item <prototype_file>
 433
 434 Names the AFS or local disk directory that houses the prototype file to
 435 copy. The prototype file's name must match the final element in the
 436 <pathname> field.
 437
 438 =back
 439
 440 =head2 The G Instruction for Even Distribution of Home Directories
 441
 442 The C<G> instruction in a uss template file creates a directory as one of
 443 the set of directories from which the B<uss> command interpreter selects
 444 when choosing a new user home directory's parent directory. More
 445 specifically, when the $AUTO variable appears in the <mount_point>
 446 field of a C<V> instruction, the command interpreter substitutes for it
 447 the directory defined by a C<G> instruction that currently has the fewest
 448 entries.
 449
 450 The instruction's intended use is to distribute user accounts evenly among
 451 several directories, rather than using directories that reflect divisions
 452 such as departmental affiliation. Distributing home directories in this
 453 fashion is useful mainly in very large cells where storing all user home
 454 directories under a single parent directory potentially slows directory
 455 lookup, or where a workplace-based division results in unevenly sized
 456 directories such that some users consistently experience slower directory
 457 lookup than others. See the chapter on B<uss> in the I<IBM AFS
 458 Administration Guide> for more information.
 459
 460 Any number of C<G> instructions can appear in the template file. If the
 461 C<V> instruction includes the $AUTO variable, it must appear after all
 462 of the C<G> instructions in the file.
 463
 464 The instruction has the following syntax:
 465
 466    G <directory>
 467
 468 where
 469
 470 =over 4
 471
 472 =item G
 473
 474 Indicates an instruction that creates a directory to be considered as a
 475 value for the $AUTO variable. It must be a capital letter.
 476
 477 =item <directory>
 478
 479 Specifies the directory's name as either a complete pathname or only the
 480 directory name. The choice determines the appropriate format for the
 481 <mount_point> field of a C<V> instruction, as discussed in the following
 482 example.
 483
 484 Specify the read/write path to the directory, to avoid the failure that
 485 results from attempting to create a new mount point in a read-only volume
 486 when the $AUTO variable is used in a C<V> instruction's <mount_point>
 487 field. By convention, the read/write path is indicated by placing a period
 488 before the cell name at the pathname's second level (for example,
 489 F</afs/.abc.com>). For further discussion of the concept of read/write and
 490 read-only paths through the filespace, see the reference page for the B<fs
 491 mkmount> command.
 492
 493 =back
 494
 495 =head2 The L and S Instructions for Creating a Link
 496
 497 The C<L> instruction in a uss template file creates a hard link between
 498 two files, as achieved by the standard UNIX B<ln> command. The C<S>
 499 instruction creates a symbolic link between two files, as achieved by the
 500 standard UNIX C<ln -s> command. A full explanation of links is beyond the
 501 scope of this document, but the basic effect is to create a second name
 502 for an existing file, enabling access via either name. Creating a link
 503 does not create a second copy of the file.
 504
 505 AFS allows hard links only if the linked files reside in the same
 506 directory, because it becomes difficult to determine which access control
 507 list (ACL) applies to the file if the two copies reside in directories
 508 with different ACLs. AFS allows symbolic links between two files that
 509 reside in different directories, or even different volumes. The File
 510 Server uses the ACL associated with the actual file rather than the link.
 511
 512 Any number of C<L> and C<S> instructions can appear in the template
 513 file. If the existing file or link is to reside in a directory created by
 514 a C<D> instruction, or if the existing file was created by an C<E> or C<F>
 515 instruction, the C<L> or C<S> instruction must follow the C<D>, C<E>, or
 516 C<F> instruction.
 517
 518 The instructions share the following syntax:
 519
 520    L <existing_file> <link>
 521    S <existing_file> <link>
 522
 523 where
 524
 525 =over 4
 526
 527 =item L
 528
 529 Indicates a hard link creation instruction. It must be a capital letter.
 530
 531 =item S
 532
 533 Indicates a symbolic link creation instruction. It must be a capital
 534 letter.
 535
 536 =item <existing_file>
 537
 538 Specifies the complete pathname of the existing file.
 539
 540 =item <link>
 541
 542 Specifies the complete pathname of the second name for the file.
 543
 544 Specify the read/write path to the link, to avoid the failure that results
 545 from attempting to create a new link in a read-only volume. By convention,
 546 the read/write path is indicated by placing a period before the cell name
 547 at the pathname's second level (for example, F</afs/.abc.com>). For
 548 further discussion of the concept of read/write and read-only paths
 549 through the filespace, see the reference page for the B<fs mkmount>
 550 command.
 551
 552 =back
 553
 554 =head2 The V Instruction for Creating and Mounting a Volume
 555
 556 The C<V> instruction in a uss template file creates a volume on a
 557 specified file server machine and partition and creates an entry for it in
 558 the Volume Location Database (VLDB). It mounts the volume at a location in
 559 the AFS file space that becomes the user's home directory, then designates
 560 the directory's owner and sets its access control list (ACL).
 561
 562 Only one C<V> instruction can appear in the template file, and one must
 563 appear if the template file contains any instructions at all (is not
 564 empty). All other instructions are optional, except that the template must
 565 include C<G> instructions if the $AUTO variable appears in it. (The
 566 C<V> instruction is not necessarily the first line in the template. If the
 567 template includes the $AUTO variable, then the C<G> instructions which
 568 provide values for the variable must precede it in the file.)
 569
 570 The instruction has the following syntax:
 571
 572    V <vname> <server> <partition> <quota> <mount_point> <owner> <ACL>
 573
 574 where
 575
 576 =over 4
 577
 578 =item V
 579
 580 Indicates a volume creation instruction. It must be a capital letter.
 581
 582 =item <name>
 583
 584 Specifies the volume's name. To follow the convention for AFS user volume
 585 names, specify the value C<user.$USER>.  Provide a value for the $USER
 586 variable via the B<uss add> command's B<-user> argument or the <username>
 587 field in the bulk input file B<add> instruction.
 588
 589 =item <server>
 590
 591 Names the file server machine on which to create the new user's volume. It
 592 is best to provide the fully-qualified hostname (for example,
 593 C<fs1.abc.com>), but an abbreviated form is acceptable provided that the
 594 cell's naming service is available to resolve it at the time the volume is
 595 created. To read in the value from the B<uss add> command's B<-server>
 596 argument, specify the value $SERVER.
 597
 598 =item <partition>
 599
 600 Specifies the partition on which to create the user's volume; it must be
 601 on the file server machine named in the <server> field.  Identify the
 602 partition by its complete name (for example, F</vicepa>) or use or use one
 603 of the following abbreviations.
 604
 605    /vicepa     =     vicepa      =      a      =      0
 606    /vicepb     =     vicepb      =      b      =      1
 607
 608 After F</vicepz> (for which the index is 25) comes
 609
 610    /vicepaa    =     vicepaa     =      aa     =      26
 611    /vicepab    =     vicepab     =      ab     =      27
 612
 613 and so on through
 614
 615    /vicepiv    =     vicepiv     =      iv     =      255
 616
 617 To read in the value from the B<uss add> command's B<-partition> argument,
 618 specify the value $PART.
 619
 620 =item <quota>
 621
 622 Sets the maximum number of kilobyte blocks the volume can occupy on the
 623 file server machine's disk. Specify an integer constant if all volumes
 624 have the same quota (C<1024> equals a megabyte), or use one of the number
 625 variables ($1 through $9) to assign different values to different volumes.
 626
 627 =item <mount_point>
 628
 629 Creates a mount point for the volume, which serves as the volume's root
 630 directory. Include the $USER variable as part of the pathname to follow
 631 the convention that user home directory names include the username.
 632
 633 Specify the read/write path to the mount point, to avoid the failure that
 634 results from attempting to create a new mount point in a read-only
 635 volume. By convention, the read/write path is indicated by placing a
 636 period before the cell name at the pathname's second level (for example,
 637 F</afs/.abc.com>). If the $AUTO variable appears in this field, the
 638 directories named by each C<G> instruction possibly already indicate the
 639 read/write path. For further discussion of the concept of read/write and
 640 read-only paths through the filespace, see the reference page for the B<fs
 641 mkmount> command.
 642
 643 =item <owner>
 644
 645 Specifies the username or UNIX user ID (UID) of the user to be designated
 646 the mount point's owner in the output from the UNIX C<ls -ld> command. To
 647 follow the convention for home directory ownership, place the value
 648 $UID in this field.
 649
 650 =item <ACL>
 651
 652 Sets the ACL on the new directory. Provide one or more paired values, each
 653 pair consisting of an AFS username or group name and the desired
 654 permissions, in that order. Separate the two parts of the pair, and each
 655 pair, with a space. The B<fs setacl> reference page describes the
 656 available permissions.
 657
 658 Grant all permissions to the new user at least. The appropriate
 659 value is C<$USER all>.
 660
 661 AFS automatically grants the system:administrators group all permissions
 662 as well. It is not possible to grant any permissions to the issuer of the
 663 B<uss> command. As the last step in account creation, the B<uss> command
 664 interpreter automatically deletes that user from any ACLs set during the
 665 creation process.
 666
 667 =back
 668
 669 =head2 The X Instruction for Running a Command
 670
 671 The C<X> instruction in a uss template file runs the indicated command,
 672 which can be a standard UNIX or AFS command. It can include any variables
 673 from the template file, which the B<uss> command interpreter resolves
 674 before passing the command on to the appropriate other command
 675 interpreter. It must be a single line only, however (cannot contain
 676 carriage returns or newline characters).
 677
 678 Any number of C<X> instructions can appear in the template file. If an
 679 instruction manipulates an element created by another instruction, it must
 680 follow that instruction in the file.
 681
 682 The instruction has the following syntax:
 683
 684    X "<command>"
 685
 686 where
 687
 688 =over 4
 689
 690 =item X
 691
 692 Indicates a command execution instruction. It must be a capital letter.
 693
 694 =item <command>
 695
 696 Specifies the command to run. Surround it with double quotes as shown if
 697 it contains one or more spaces. It can contain any variables from the
 698 template file, but not newline characters.
 699
 700 =back
 701
 702 =head1 EXAMPLES
 703
 704 The following example A instruction sets a password lifetime of 254 days,
 705 prohibits password reuse, limits the number of consecutive failed
 706 authentication attempts to nine and sets the corresponding locktime to
 707 25:30 minutes (which is a multiple of 8.5 minutes). The username is read
 708 in from the B<-user> argument to the B<uss add> command or from the
 709 I<username> field in each C<add> instruction in a bulk input file.
 710
 711    A $USER 254 noreuse 9 25:30
 712
 713 The following example C<D> instruction creates a directory called
 714 F<public> in a new user's home directory, designates the user as the
 715 directory's owner, and grants him or her all ACL permissions.
 716
 717    D $MTPT/public 0755 $UID $USER all
 718
 719 The following example C<E> instruction creates a file in the current
 720 working directory called F<I<username>.etcp>. The contents are an entry
 721 suitable for incorporating into the cell's global F</etc/password> file.
 722
 723    E  $USER.etcp  0644 root "$USER:X:$UID:10:$NAME:$MTPT:/bin/csh"
 724
 725 The following example C<F> instruction, appropriate for the ABC
 726 Corporation cell, copies a prototype F<.login> file into the user's home
 727 directory.
 728
 729    F $MTPT/.login 0644 $UID /afs/abc.com/common/uss/skel/.login
 730
 731 In the following example, the State University cell's administrators
 732 have decided to distribute user home directories evenly into three
 733 directories. They define three C<G> instructions:
 734
 735    G usr1
 736    G usr2
 737    G usr3
 738
 739 and then put the following value in the <mount_point> field of the C<V>
 740 instruction:
 741
 742    /afs/stateu.edu/$AUTO/$USER
 743
 744 Alternatively, if they include the entire directory pathname in the C<G>
 745 instruction:
 746
 747    G /afs/stateu.edu/usr1
 748    G /afs/stateu.edu/usr2
 749    G /afs/stateu.edu/usr3
 750
 751 then the <mount_point> field of the C<V> instruction specifies only the
 752 following:
 753
 754    $AUTO/$USER
 755
 756 The following example C<L> instruction creates a hard link between the
 757 files F<mail> and F<mbox> in the user's home directory.
 758
 759    L $MTPT/mbox $MTPT/mail
 760
 761 The following example C<S> instruction, appropriate for the ABC
 762 Corporation cell, links the file F<Mail/outgoing> in the user's home
 763 directory to the file F</afs/abc.com/common/mail/outgoing>.
 764
 765    S /afs/abc.com/common/mail/outgoing $MTPT/Mail/outgoing
 766
 767 The following example C<V> instruction creates a volume called
 768 C<user.I<username>> on the F</vicepa> partition of the specified file
 769 server machine, assigning it a quota of 3000 kilobyte blocks. The mount
 770 point is under F</afs/abc.com/usr> and matches the username (the value of
 771 the $USER variable). The user owns the home directory and has all
 772 access rights to it. The instruction appears on two lines only for
 773 legibility; it must appear on a single line in the template file.
 774
 775    V user.$USER $SERVER.abc.com /vicepa 3000 \
 776            /afs/abc.com/usr/$USER $UID $USER all
 777
 778 The following example C<X> instruction mounts the backup version of the
 779 user's volume at the F<OldFiles> subdirectory.
 780
 781    X "fs mkm /afs/abc.com/usr/$USER/OldFiles   user.$USER.backup"
 782
 783 =head1 SEE ALSO
 784
 785 L<uss_bulk(5)>,
 786 L<fs_mkmount(1)>,
 787 L<uss_add(8)>
 788
 789 =head1 COPYRIGHT
 790
 791 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 792
 793 This documentation is covered by the IBM Public License Version 1.0.  It was
 794 converted from HTML to POD by software written by Chas Williams and Russ
 795 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.