sect5/uss.xml

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