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