doc/man-pages/pod5/uss.pod

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