Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / doc / xml / AdminGuide / auagd017.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="HDRWQ449">
  <title>Creating and Deleting User Accounts with the uss Command Suite</title>

  <para><indexterm>
      <primary>user account</primary>

      <secondary>two methods for creating and deleting</secondary>
    </indexterm></para>

  <para>The <emphasis role="bold">uss</emphasis> command suite helps you create and delete AFS user accounts quickly and easily. You
  can create a single account with the <emphasis role="bold">uss add</emphasis> command, delete a single account with the <emphasis
  role="bold">uss delete</emphasis> command, or create and delete multiple accounts with the <emphasis role="bold">uss
  bulk</emphasis> command.</para>

  <para>A single <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command can create a complete
  AFS user account because the <emphasis role="bold">uss</emphasis> command interpreter refers to a template file in which you
  predefine the configuration of many account components. The <emphasis role="bold">uss delete</emphasis> command deletes most of
  the components of a user account, but does not use a template file.</para>

  <para>The <emphasis role="bold">uss</emphasis> suite also easily incorporates shell scripts or other programs that you write to
  perform parts of account creation and deletion unique to your site. To invoke a script or program automatically as a <emphasis
  role="bold">uss</emphasis> command runs, use the appropriate instructions in the template file or bulk input file. Various
  sections of this chapter discuss possible uses for scripts.</para>

  <para>Using the <emphasis role="bold">uss</emphasis> commands to create and delete accounts is the recommended method because it
  automates and correctly orders most of the necessary steps. The alternative is to issue a series of separate commands to the
  various AFS servers, which requires more careful record keeping. For instructions, see <link linkend="HDRWQ491">Administering User
  Accounts</link>.</para>

  <sect1 id="HDRWQ450">
    <title>Summary of Instructions</title>

    <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>

    <informaltable frame="none">
      <tgroup cols="2">
        <colspec colwidth="80*" />

        <colspec colwidth="20*" />

        <tbody>
          <row>
            <entry>Add a single user account</entry>

            <entry><emphasis role="bold">uss add</emphasis></entry>
          </row>

          <row>
            <entry>Delete a single user account</entry>

            <entry><emphasis role="bold">uss delete</emphasis></entry>
          </row>

          <row>
            <entry>Add and delete multiple accounts</entry>

            <entry><emphasis role="bold">uss bulk</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </sect1>

  <sect1 id="HDRWQ452">
    <title>Overview of the uss Command Suite</title>

    <para>The commands in the <emphasis role="bold">uss</emphasis> suite help you to automate the creation and deletion of AFS user
    accounts: <itemizedlist>
        <listitem>
          <para>The <emphasis role="bold">uss add</emphasis> command creates all of the components of an account, one account at a
          time. It consults a template file that defines account configuration.</para>
        </listitem>

        <listitem>
          <para>The <emphasis role="bold">uss delete</emphasis> command deletes the major components of an account, one account at a
          time. It does not use a template file, so you possibly need to perform additional tasks manually.</para>
        </listitem>

        <listitem>
          <para>The <emphasis role="bold">uss bulk</emphasis> command can create and delete multiple accounts. It refers to a bulk
          input file that can contain any number of account-creation and deletion instructions, along with other instructions for
          further automating the process.</para>
        </listitem>
      </itemizedlist></para>

    <indexterm>
      <primary>user account</primary>

      <secondary>components</secondary>
    </indexterm>

    <indexterm>
      <primary>user</primary>

      <secondary>account</secondary>

      <see>user account</see>
    </indexterm>

    <sect2 id="Header_538">
      <title>The Components of an AFS User Account</title>

      <para>An AFS user account can have many components. The only two required components are entries in the Protection Database
      and Authentication Database, but the other components add functionality and usability. The following information also appears
      in a corresponding section of <link linkend="HDRWQ491">Administering User Accounts</link>, but is repeated here for your
      convenience. <itemizedlist>
          <listitem>
            <para>A <emphasis>Protection Database entry</emphasis> defines the username (the name provided when authenticating with
            AFS), and maps it to an AFS user ID (AFS UID), a number that the AFS servers use internally when referencing users. The
            Protection Database also tracks the groups to which the user belongs. For details, see <link
            linkend="HDRWQ531">Administering the Protection Database</link>.</para>
          </listitem>

          <listitem>
            <para>An <emphasis>Authentication Database entry</emphasis> records the user's AFS password in a scrambled form suitable
            for use as an encryption key.</para>
          </listitem>

          <listitem>
            <para>A home <emphasis>volume</emphasis> stores all the files in the user's home directory together on a single
            partition of a file server machine. The volume has an associated quota that limits its size. For a complete discussion
            of volumes, see <link linkend="HDRWQ174">Managing Volumes</link>.</para>
          </listitem>

          <listitem>
            <para>A <emphasis>mount point</emphasis> makes the contents of the user's volume visible and accessible in the AFS
            filespace, and acts as the user's home directory. For more details about mount points, see <link
            linkend="HDRWQ183">About Mounting Volumes</link>.</para>
          </listitem>

          <listitem>
            <para>Full access permissions on the home directory's <emphasis>access control list (ACL)</emphasis> and ownership of
            the directory (as displayed by the UNIX <emphasis role="bold">ls -ld</emphasis> command) enable the user to manage his
            or her files. For details on AFS file protection, see <link linkend="HDRWQ562">Managing Access Control
            Lists</link>.</para>
          </listitem>

          <listitem>
            <para>A <emphasis>local password file entry</emphasis> (in the <emphasis role="bold">/etc/passwd</emphasis> file or
            equivalent) of each AFS client machine enables the user to log in and access AFS files through the Cache Manager. A
            subsequent section in this chapter further discusses local password file entries.</para>
          </listitem>

          <listitem>
            <para>Other optional <emphasis>configuration files</emphasis> make the account more convenient to use. Such files help
            the user log in and log out more easily, receive electronic mail, print, and so on.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>privilege required</secondary>
      </indexterm>

      <indexterm>
        <primary>privilege</primary>

        <secondary>required for uss commands</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ453">
      <title>Privilege Requirements for the uss Commands</title>

      <para>To issue <emphasis role="bold">uss</emphasis> commands successfully, you usually need all of the standard AFS
      administrative privileges: membership in the <emphasis role="bold">system:administrators</emphasis> group, inclusion in the
      <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on every relevant server machine, and the
      <computeroutput>ADMIN</computeroutput> flag on your Authentication Database entry. For details on administrative privilege,
      see <link linkend="HDRWQ581">Managing Administrative Privilege</link>. <indexterm>
          <primary>uss commands</primary>

          <secondary>add</secondary>

          <tertiary>avoiding interruption</tertiary>
        </indexterm> <indexterm>
          <primary>uss commands</primary>

          <secondary>delete</secondary>

          <tertiary>avoiding interruption</tertiary>
        </indexterm> <indexterm>
          <primary>previewing</primary>

          <secondary>user account creation/deletion with uss</secondary>
        </indexterm> <indexterm>
          <primary>user account</primary>

          <secondary>uss commands to create/delete</secondary>

          <tertiary>previewing</tertiary>
        </indexterm> <indexterm>
          <primary>user account</primary>

          <secondary>creation using uss</secondary>

          <tertiary>previewing</tertiary>
        </indexterm> <indexterm>
          <primary>user account</primary>

          <secondary>deletion using uss</secondary>

          <tertiary>previewing</tertiary>
        </indexterm> <indexterm>
          <primary>uss</primary>

          <secondary>previewing effect of command</secondary>
        </indexterm></para>
    </sect2>

    <sect2 id="HDRWQ454">
      <title>Avoiding and Recovering from Errors and Interrupted Operations</title>

      <para>As for any complex operation, there are a number of possible reasons that an account-creation or deletion operation can
      halt before it completes. You can easily avoid several of the common reasons by making the following checks before issuing a
      <emphasis role="bold">uss</emphasis> command: <itemizedlist>
          <listitem>
            <para>Verify that you have all of the administrative privileges you need to complete an operation, as described in <link
            linkend="HDRWQ453">Privilege Requirements for the uss Commands</link>. The instructions for using the <emphasis
            role="bold">uss add</emphasis>, <emphasis role="bold">uss delete</emphasis>, and <emphasis role="bold">uss
            bulk</emphasis> commands include this check as a step.</para>
          </listitem>

          <listitem>
            <para>Proofread the template and bulk input files for correct syntax and acceptable values. For discussion, see <link
            linkend="HDRWQ463">Constructing a uss Template File</link> and <link linkend="HDRWQ489">Constructing a Bulk Input
            File</link>.</para>
          </listitem>

          <listitem>
            <para>Do not issue <emphasis role="bold">uss</emphasis> commands when you are aware of network, server machine, or
            server process outages. Because <emphasis role="bold">uss</emphasis> operations affect so many components of AFS, it is
            unlikely that the command can succeed when there are outages.</para>
          </listitem>
        </itemizedlist></para>

      <para>Another way to avoid errors that halt an operation is to preview the <emphasis role="bold">uss</emphasis> command by
      combining the <emphasis role="bold">-dryrun</emphasis> flag with the other arguments to be used on the actual command. The
      <emphasis role="bold">uss</emphasis> command interpreter generates a screen trace of the actions to be performed by the actual
      command, without performing them.</para>

      <para>Using the <emphasis role="bold">-dryrun</emphasis> flag reveals many basic errors that can halt an operation,
      particularly the ones due to incorrect syntax in the command line, template file, or bulk input file. It does not catch all
      possible errors, however, because the command interpreter is not actually attempting to perform the actions it is tracing. For
      example, a Volume Server outage does not necessarily halt the volume creation step when the <emphasis
      role="bold">-dryrun</emphasis> flag is included, because the command interpreter is not actually contacting the server; such
      an outage halts the actual creation operation. <indexterm>
          <primary>failure</primary>

          <secondary>of uss account creation</secondary>

          <tertiary>recovering from</tertiary>
        </indexterm> <indexterm>
          <primary>uss</primary>

          <secondary>account</secondary>

          <tertiary>recovering from account creation failure</tertiary>
        </indexterm> <indexterm>
          <primary>uss</primary>

          <secondary>command</secondary>

          <tertiary>reissuing, effect of</tertiary>
        </indexterm></para>

      <para>When the <emphasis role="bold">uss</emphasis> command interpreter encounters error conditions minor enough that they do
      not require halting the operation, it usually generates a message that begins with the string <computeroutput>uss:
      Warning:</computeroutput> and describes the action it is taking to avoid halting. For example, if a user's Protection Database
      entry already exists, the following message appears on the standard output stream:</para>

      <programlisting>
   uss: Warning: User 'user' already in the protection database
   The uid for user 'user' is AFS UID
</programlisting>

      <para>If an error is more serious, the word <computeroutput>Warning</computeroutput> does not appear in the message, which
      instead describes why the command interpreter cannot perform the requested action. Not all of these errors cause the <emphasis
      role="bold">uss</emphasis> operation to halt, but they still require you to take corrective action. For example, attempting to
      create a mount point fails if you lack the necessary permissions on the parent directory's ACL, or if the mount point pathname
      in the <emphasis role="bold">V</emphasis> instruction's mount_point field is malformed. However, this error does not cause the
      creation operation to halt until later instructions in the template attempt to install subdirectories or files under the
      nonexistent mount point.</para>

      <para>If the command shell prompts returns directly after an error message, then the error generally was serious enough to
      halt the operation. When an error halts account creation or deletion, the best way to recover is to find and fix the cause,
      and then reissue the same <emphasis role="bold">uss</emphasis> command. <indexterm>
          <primary>uss commands</primary>

          <secondary>overwriting existing account components</secondary>
        </indexterm> <indexterm>
          <primary>overwriting</primary>

          <secondary>existing directories/files/links with uss</secondary>
        </indexterm> <indexterm>
          <primary>directory</primary>

          <secondary>overwritten by uss if exists</secondary>
        </indexterm> <indexterm>
          <primary>file</primary>

          <secondary>overwritten by uss if exists</secondary>
        </indexterm> <indexterm>
          <primary>hard link</primary>

          <secondary>overwritten by uss if exists</secondary>
        </indexterm> <indexterm>
          <primary>symbolic link</primary>

          <secondary>overwritten by uss if exists</secondary>
        </indexterm></para>

      <para>The following list describes what happens when components of a user's account already exist when you reissue an
      account-creation command (the <emphasis role="bold">uss add</emphasis> command, or the <emphasis role="bold">uss
      bulk</emphasis> command when the bulk input file contains <emphasis role="bold">add</emphasis> instructions): <itemizedlist>
          <listitem>
            <para>If the Protection Database entry already exists, a message confirms its existence and specifies the associated AFS
            UID.</para>
          </listitem>

          <listitem>
            <para>If the Authentication Database entry already exists, a message confirms its existence.</para>
          </listitem>

          <listitem>
            <para>If the volume and associated Volume Location Database (VLDB) entry already exist, a message confirms their
            existence. However, the <emphasis role="bold">uss</emphasis> command interpreter does alter the volume's quota, mount
            point, or ACL if any of the relevant fields in the template <emphasis role="bold">V</emphasis> instruction have changed
            since the command last ran. If the value in the mount_point field has changed, the command interpreter creates the new
            mount point but does not remove any existing mount points.</para>
          </listitem>

          <listitem>
            <para>If any of the fields in the template <emphasis role="bold">A</emphasis> instruction have changed, the <emphasis
            role="bold">uss</emphasis> command interpreter makes the changes without comment.</para>
          </listitem>

          <listitem>
            <para>If a directory, file, or link defined by a template file <emphasis role="bold">D</emphasis>, <emphasis
            role="bold">E</emphasis>, <emphasis role="bold">F</emphasis>, <emphasis role="bold">L</emphasis>, or <emphasis
            role="bold">S</emphasis> instruction already exists, the <emphasis role="bold">uss</emphasis> command interpreter
            replaces the existing element with one that conforms to the template definition. To control whether the <emphasis
            role="bold">uss</emphasis> command interpreter prompts for confirmation that you wish to overwrite a given element, use
            the <emphasis role="bold">-overwrite</emphasis> flag to the <emphasis role="bold">uss add</emphasis> or <emphasis
            role="bold">uss bulk</emphasis> command: <itemizedlist>
                <listitem>
                  <para>If you include the <emphasis role="bold">-overwrite</emphasis> flag, the command interpreter automatically
                  overwrites all elements without asking for confirmation.</para>
                </listitem>

                <listitem>
                  <para>If you omit the flag, the command interpreter prompts once for each account to ask if you want to overwrite
                  all elements associated with it.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>

          <listitem>
            <para>The command interpreter always reexecutes <emphasis role="bold">X</emphasis> instructions in the template file. If
            a command's result already holds, reissuing it has the same effect as reissuing it outside the context of the <emphasis
            role="bold">uss</emphasis> commands.</para>
          </listitem>
        </itemizedlist></para>

      <para>The following describes what happens when a <emphasis role="bold">uss delete</emphasis> command references account
      components that have already been deleted. <itemizedlist>
          <listitem>
            <para>If the volume and VLDB entry no longer exist, a message confirms their absence.</para>
          </listitem>

          <listitem>
            <para>If the Authentication Database entry no longer exists, a message confirms its absence.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>local password file</primary>

        <secondary>creating entry for AFS user</secondary>

        <tertiary>with uss</tertiary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ455">
    <title>Creating Local Password File Entries with uss</title>

    <para>To obtain authenticated access to a cell's AFS filespace, a user must not only have a valid AFS token, but also an entry
    in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of the AFS client machine. This section
    discusses why it is important for the user's AFS UID to match to the UNIX UID listed in the local password file, the appropriate
    value to put in the file's password field, and outlines a method for creating a single source password file.</para>

    <para>For instructions on using the template file's <emphasis role="bold">E</emphasis> instruction to generate local password
    file entries automatically as part of account creation, see <link linkend="HDRWQ458">Creating a Common Source Password
    File</link>.</para>

    <para>The following information also appears in a corresponding section of <link linkend="HDRWQ491">Administering User
    Accounts</link>, but is repeated here for your convenience. <indexterm>
        <primary>AFS UID</primary>

        <secondary>matching with UNIX UID</secondary>
      </indexterm> <indexterm>
        <primary>user account</primary>

        <secondary>matching AFS and UNIX UIDs</secondary>
      </indexterm> <indexterm>
        <primary>uss</primary>

        <secondary>AFS UID, assigning</secondary>
      </indexterm> <indexterm>
        <primary>assigning</primary>

        <secondary>AFS UID with uss</secondary>
      </indexterm> <indexterm>
        <primary>UNIX UID</primary>

        <secondary>matching with AFS UID</secondary>
      </indexterm></para>

    <sect2 id="HDRWQ456">
      <title>Assigning AFS and UNIX UIDs that Match</title>

      <para>A user account is easiest to administer and use if the AFS user ID number (AFS UID) and UNIX UID match. All instructions
      in the AFS documentation assume that they do.</para>

      <para>The most basic reason to make AFS and UNIX UIDs the same is so that the owner name reported by the UNIX <emphasis
      role="bold">ls -l</emphasis> and <emphasis role="bold">ls -ld</emphasis> commands makes sense for AFS files and directories.
      Following standard UNIX practice, the File Server records a number rather than a username in an AFS file or directory's owner
      field: the owner's AFS UID. When you issue the <emphasis role="bold">ls -l</emphasis> command, it translates the UID to a
      username according to the mapping in the local password file, not the AFS Protection Database. If the AFS and UNIX UIDs do not
      match, the <emphasis role="bold">ls -l</emphasis> command reports an unexpected (and incorrect) owner. The output can even
      vary on different client machines if their local password files map the same UNIX UID to different names.</para>

      <para>Follow the recommendations in the indicated sections to make AFS and UNIX UIDs match when you are creating accounts for
      various types of users: <itemizedlist>
          <listitem>
            <para>If creating an AFS account for a user who already has a UNIX UID, see <link linkend="HDRWQ459">Converting Existing
            UNIX Accounts with uss</link>.</para>
          </listitem>

          <listitem>
            <para>If some users in your cell have existing UNIX accounts but the user for whom you are creating an AFS account does
            not, then it is best to allow the Protection Server to allocate an AFS UID automatically. To avoid overlap of AFS UIDs
            with existing UNIX UIDs, set the Protection Database's <computeroutput>max user id</computeroutput> counter higher than
            the largest UNIX UID, using the instructions in <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID
            Counters</link>.</para>
          </listitem>

          <listitem>
            <para>If none of your users have existing UNIX accounts, allow the Protection Server to allocate AFS UIDs automatically,
            starting either at its default or at the value you have set for the <computeroutput>max user id</computeroutput>
            counter.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>password</primary>

        <secondary>setting in local password file</secondary>

        <tertiary>with uss</tertiary>
      </indexterm>

      <indexterm>
        <primary>local password file</primary>

        <secondary>setting password in</secondary>

        <tertiary>with uss</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ457">
      <title>Specifying Passwords in the Local Password File</title>

      <para>Authenticating with AFS is easiest for your users if you install and configure an AFS-modified login utility, which logs
      a user into the local file system and obtains an AFS token in one step. In this case, the local password file no longer
      controls a user's ability to login in most circumstances, because the AFS-modified login utility does not consult the local
      password file if the user provides the correct AFS password. You can nonetheless use a password file entry's password field
      (usually, the second field) in the following ways to control login and authentication: <itemizedlist>
          <listitem>
            <para>To prevent both local login and AFS authentication, place an asterisk ( * ) in the field. This is useful mainly in
            emergencies, when you want to prevent a certain user from logging into the machine.</para>
          </listitem>

          <listitem>
            <para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
            string of any length other than the standard thirteen characters in the field. This is appropriate if you want to allow
            only people with local AFS accounts to log into to your machines. A single <emphasis role="bold">X</emphasis> or other
            character is the most easily recognizable way to do this.</para>
          </listitem>

          <listitem>
            <para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
            standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
            role="bold">passwd</emphasis> or equivalent).</para>
          </listitem>
        </itemizedlist></para>

      <para>If you do not use an AFS-modified login utility, you must place a standard UNIX password in the local password file of
      every client machine the user will use. The user logs into the local file system only, and then must issue the <emphasis
      role="bold">klog</emphasis> command to authenticate with AFS. It is simplest if the passwords in the local password file and
      the Authentication Database are the same, but this is not required. <indexterm>
          <primary>creating</primary>

          <secondary>common local password file with uss</secondary>
        </indexterm> <indexterm>
          <primary>local password file</primary>

          <secondary>creating common source version with uss</secondary>
        </indexterm> <indexterm>
          <primary>uss commands</primary>

          <secondary>local password file</secondary>

          <tertiary>creating common source version</tertiary>
        </indexterm> <indexterm>
          <primary>passwd file</primary>

          <secondary></secondary>

          <see>local password file</see>
        </indexterm></para>
    </sect2>

    <sect2 id="HDRWQ458">
      <title>Creating a Common Source Password File</title>

      <para>This section explains how to create a common source version of the local password file when using <emphasis
      role="bold">uss</emphasis> commands to create user accounts. The sequence of steps is as follows: <orderedlist>
          <listitem>
            <para>Include an <emphasis role="bold">E</emphasis> instruction in the template file to create a one-line file that has
            the format of a local password file entry.</para>
          </listitem>

          <listitem>
            <para>Incorporate the one-line file into the common source version of the local password file. It makes sense to store
            this file in AFS. See the following two example scripts for automating this step.</para>
          </listitem>
        </orderedlist></para>

      <para>As an example, the template file used by the Example Corporation includes the following <emphasis role="bold">E</emphasis>
      instruction to create a file called <emphasis role="bold">passwd_</emphasis>username in the directory <emphasis
      role="bold">/afs/.example.com/common/etc/newaccts</emphasis> (the entire contents of the template file appear in <link
      linkend="HDRWQ471">Example uss Templates</link> and a full description of the <emphasis role="bold">E</emphasis> instruction
      appears in <link linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>):</para>

      <programlisting>
   E /afs/.example.com/common/etc/newaccts/passwd_$USER 0644 root \
        "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
</programlisting>

      <para>For the user Joe L. Smith with username <emphasis role="bold">smith</emphasis>, this instruction creates a file called
      <emphasis role="bold">passwd_smith</emphasis> which contains the following line:</para>

      <programlisting>
   smith:X:1205:11:Joe L. Smith:/afs/example.com/usr/usr1/smith:/bin/csh
</programlisting>

      <para>A shell script is probably the easiest way to incorporate a set of files created in this manner into a common source
      password file, and two sample shell scripts appear here. To automate the process even further, you can create a <emphasis
      role="bold">cron</emphasis> process in a file server machine's <emphasis role="bold">/usr/afs/local/BosConfig</emphasis>
      directory to execute the shell script, perhaps each day at a given time; for details, see <link linkend="HDRWQ162">To create
      and start a new process</link>.</para>

      <note>
        <para>The following example scripts are suggestions only. If you choose to use them, or to model similar scripts on them,
        you must test that your script has the desired result, preferably in a test environment.</para>
      </note>

      <para><emphasis role="bold">Example C Shell Script</emphasis></para>

      <para>The first example is a simple C shell script suitable for the Example Corporation cell. It incorporates the individual files
      found in the <emphasis role="bold">/afs/.example.com/common/uss/newaccts</emphasis> directory into a new version of the global
      password file found in the <emphasis role="bold">/afs/.example.com/common/etc</emphasis> directory, sorting the files into
      alphabetical order. It takes care to save the current version with a <emphasis role="bold">.old</emphasis> extension, then
      removes the individual files when done.</para>

      <programlisting>
   set  dir = /afs/.example.com/common
   cat  $dir/uss/newaccts/passwd_* $dir/etc/passwd  &gt;!  $dir/etc/passwd.new
   mv  $dir/etc/passwd  $dir/etc/passwd.old
   sort  $dir/etc/passwd.new  &gt;  $dir/etc/passwd
   rm  $dir/etc/passwd.new  $dir/uss/newaccts/passwd_*
</programlisting>

      <para><emphasis role="bold">Example Bourne Shell Script</emphasis></para>

      <para>The second, more elaborate, example is a Bourne shell script that first verifies that there are new <emphasis
      role="bold">passwd_</emphasis>username files to be incorporated into the global password file. While running, it checks that
      each new entry does not already exist. Like the shorter C shell example, it incorporates the individual files found in the
      <emphasis role="bold">/afs/.example.com/common/uss/newaccts</emphasis> directory into a new version of the global <emphasis
      role="bold">passwd</emphasis> file found in the <emphasis role="bold">/afs/.example.com/common/etc</emphasis> directory.</para>

      <programlisting>
   #!/bin/sh
   DESTDIR=/afs/.example.com/common/uss/newaccts
   cd  $DESTDIR
   DEST=/afs/.example.com/common/etc
   cp /afs/.example.com/common/etc/passwd   /afs/.example.com/common/uss/newaccts/passwd
   echo "copied in passwd file."
   PASSWD=/afs/.example.com/common/uss/newaccts/passwd
   ENTRIES=`ls passwd_*`
   case $ENTRIES in 
   "")
        echo No new entry found to be added to passwd file
        ;;
   *)
        echo  "Adding new users to passwd file."
        for  i  in  $ENTRIES
        do
           cat  $i  |  awk  -F:  '{print $1  &gt;  "foo"}'
           USER=`cat foo`
           case  `egrep  -e  \^$USER\: $PASSWD` in 
           "")
                   echo  adding  $USER
                   cat  $i  &gt;&gt;  $PASSWD
                   ;;
           *)
                   echo  $USER already in passwd file
                   ;;
           esac
           mv  $i  ../old.passdir/done_${i}
        done
        cd  /afs/.example.com/common/uss/newaccts
        echo  "sorting password file"
        sort  ${PASSWD}  &gt;  ${PASSWD}.sorted
        echo  "installing files"     
        install  ${PASSWD}.sorted ${DEST}/passwd
        echo  "Password file is built, sorted and installed."
        ;;
   esac
</programlisting>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>converting existing UNIX accounts</secondary>
      </indexterm>

      <indexterm>
        <primary>converting</primary>

        <secondary>existing UNIX accounts to AFS accounts</secondary>

        <tertiary>with uss</tertiary>
      </indexterm>

      <indexterm>
        <primary>user account</primary>

        <secondary>converting existing UNIX to AFS</secondary>

        <tertiary>with uss</tertiary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ459">
    <title>Converting Existing UNIX Accounts with uss</title>

    <para>This section discusses the three main issues you need to consider if there are existing UNIX accounts to be converted to
    AFS accounts.</para>

    <sect2 id="HDRWQ460">
      <title>Making UNIX and AFS UIDs Match</title>

      <para>As previously mentioned, AFS users must have an entry in the local password file on every client machine from which they
      access the AFS filespace as an authenticated user. Both administration and use are much simpler if the UNIX UID and AFS UID
      match. When converting existing UNIX accounts, you have two alternatives: <itemizedlist>
          <listitem>
            <para>Make the AFS UIDs match the existing UNIX UIDs. In this case, you need to assign the AFS UID yourself as you
            create an AFS account: <itemizedlist>
                <listitem>
                  <para>If using the <emphasis role="bold">uss add</emphasis> command, include the <emphasis
                  role="bold">-uid</emphasis> argument.</para>
                </listitem>

                <listitem>
                  <para>If using the <emphasis role="bold">uss bulk</emphasis> command, specify the desired UID in the uid field of
                  the <emphasis role="bold">add</emphasis> instruction in the bulk input file.</para>
                </listitem>
              </itemizedlist></para>

            <para>Because you are retaining the user's UNIX UID, you do not need to alter the UID in the local password file entry.
            However, if you are using an AFS-modified login utility, you possibly need to change the password field in the entry.
            For a discussion of how the value in the password field affects login with an AFS-modified login utility, see <link
            linkend="HDRWQ455">Creating Local Password File Entries with uss</link>.</para>

            <para>If now or in the future you need to create AFS accounts for users who do not have an existing UNIX UID, then you
            must guarantee that new AFS UIDs do not conflict with any existing UNIX UIDs. The simplest way is to set the
            <computeroutput>max user id</computeroutput> counter in the Protection Database to a value higher than the largest
            existing UNIX UID. See <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID Counters</link>.</para>
          </listitem>

          <listitem>
            <para>Change the existing UNIX UIDs to match the new AFS UIDs that the Protection Server assigns automatically.</para>

            <para>Allow the Protection Server to allocate the AFS UIDs automatically as you create AFS accounts. For instructions on
            creating a new entry for the local password file during account creation, see <link linkend="HDRWQ455">Creating Local
            Password File Entries with uss</link>.</para>

            <para>There is one drawback to changing the UNIX UID: any files and directories that the user owned in the local file
            system before becoming an AFS user still have the former UID in their owner field. If you want the <emphasis
            role="bold">ls -l</emphasis> and <emphasis role="bold">ls -ld</emphasis> commands to display the correct owner, you must
            use the <emphasis role="bold">chown</emphasis> command to change the value to the user's new UID, whether you are
            leaving the file in the local file system or moving it to AFS. See <link linkend="HDRWQ462">Moving Local Files into
            AFS</link>.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ461">
      <title>Setting the Password Field Appropriately</title>

      <para>Existing UNIX accounts already have an entry in the local password file, probably with a (scrambled) password in the
      password field. You possibly need to change the value in the field, depending on the type of login utility you use:
      <itemizedlist>
          <listitem>
            <para>If the login utility is not modified for use with AFS, the actual password must appear (in scrambled form) in the
            password field of the local password file entry.</para>
          </listitem>

          <listitem>
            <para>If the login utility is modified for use with AFS, choose one of the acceptable values, each of which affects the
            login utility's behavior differently. See <link linkend="HDRWQ455">Creating Local Password File Entries with
            uss</link>.</para>
          </listitem>
        </itemizedlist></para>

      <para>If you choose to place an actual password in a local password file entry, then you can define a dummy password when you
      use a template file <emphasis role="bold">E</emphasis> instruction to create the entry, as described in <link
      linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>. Have the user issue the UNIX password-setting
      command (<emphasis role="bold">passwd</emphasis> or equivalent) to replace the dummy with an actual secret password.</para>
    </sect2>

    <sect2 id="HDRWQ462">
      <title>Moving Local Files into AFS</title>

      <para>New AFS users with existing UNIX accounts probably already own files and directories stored in a machine's local file
      system, and it usually makes sense to transfer them into the new home volume. The easiest method is to move them onto the
      local disk of an AFS client machine, and then use the UNIX <emphasis role="bold">mv</emphasis> command to transfer them into
      the user's new AFS home directory.</para>

      <para>As you move files and directories into AFS, keep in mind that the meaning of their mode bits changes. AFS ignores the
      second and third sets of mode bits (group and other), and does not use the first set (the owner bits) directly, but only in
      conjunction with entries on the ACL (for details, see <link linkend="HDRWQ580">How AFS Interprets the UNIX Mode Bits</link>).
      Be sure that the ACL protects the file or directory at least as securely as the mode bits.</para>

      <para>If you have chosen to change a user's UNIX UID to match a new AFS UID, you must change the ownership of UNIX files and
      directories as well. Only members of the <emphasis role="bold">system:administrators</emphasis> group can issue the <emphasis
      role="bold">chown</emphasis> command on files and directories once they reside in AFS. <indexterm>
          <primary>uss commands</primary>

          <secondary>advantages over individual account-creation commands</secondary>
        </indexterm> <indexterm>
          <primary>uss template file</primary>

          <secondary>advantages</secondary>
        </indexterm> <indexterm>
          <primary>uss template file</primary>

          <secondary>instructions summarized</secondary>
        </indexterm></para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ463">
    <title>Constructing a uss Template File</title>

    <para>Creating user accounts with <emphasis role="bold">uss</emphasis> commands is generally more convenient than using
    individual commands. You control the account creation process just as closely, but the <emphasis role="bold">uss</emphasis>
    template file enables you to predefine many aspects of account configuration. Because you construct the template before issuing
    <emphasis role="bold">uss</emphasis> commands, you have time to consider configuration details carefully and correct syntax
    errors. The following list summarizes some further advantages of using a template: <itemizedlist>
        <listitem>
          <para>You do not have to remember the correct order in which to create or delete account components, or the order of each
          command's arguments, which reduces the likelihood of errors.</para>
        </listitem>

        <listitem>
          <para>You do not have to type the same information multiple times. Instead, you can place constants and variables in the
          template file that enable you to type as little on the command line as possible. See <link linkend="HDRWQ465">Using
          Constants and Variables in the Template File</link>.</para>
        </listitem>

        <listitem>
          <para>You can create different templates for different types of users. Instead of having to remember which components
          differ for a given user, specify the appropriate template when issuing the <emphasis role="bold">uss add</emphasis> or
          <emphasis role="bold">uss bulk</emphasis> command.</para>
        </listitem>

        <listitem>
          <para>You can create any of the three types of AFS account (authentication-only, basic, or full) by including or omitting
          certain information in the template, as described in <link linkend="HDRWQ464">Creating the Three Types of User
          Accounts</link>.</para>
        </listitem>
      </itemizedlist></para>

    <para>The following list briefly describes the instructions that can appear in a template file and points you to a later section
    for more details. It lists them in the order that is usually optimal for correct handling of dependencies between the different
    types of instruction. <variablelist>
        <varlistentry>
          <term><emphasis role="bold">G</emphasis></term>

          <listitem>
            <para>Defines a directory that is one of a set of parent directories into which the <emphasis role="bold">uss</emphasis>
            command interpreter evenly distributes newly created home directories. Place the corresponding template file variable,
            $AUTO, in the mount_point field of the <emphasis role="bold">V</emphasis> instruction. See <link
            linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link> and <link
            linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">V</emphasis></term>

          <listitem>
            <para>Creates a volume, mounts it as the user's home directory at a specified location in the AFS filespace, sets the
            volume's quota, and defines the owner and ACL for the directory. This instruction must appear in any template that is
            not empty (zero-length). See <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">D</emphasis></term>

          <listitem>
            <para>Creates a directory, generally a subdirectory of the new home directory, and sets its mode bits, owner, and ACL.
            See <link linkend="HDRWQ474">Creating a Directory with the D Instruction</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">F</emphasis></term>

          <listitem>
            <para>Creates a file by copying a prototype and sets its mode bits and owner. See <link linkend="HDRWQ475">Creating a
            File from a Prototype with the F Instruction</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">E</emphasis></term>

          <listitem>
            <para>Creates a single-line file by copying in the contents of the instruction itself, then sets the file's mode bits
            and owner. See <link linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">L</emphasis></term>

          <listitem>
            <para>Creates a hard link. See <link linkend="HDRWQ477">Creating Links with the L and S Instructions</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">S</emphasis></term>

          <listitem>
            <para>Creates a symbolic link. See <link linkend="HDRWQ477">Creating Links with the L and S Instructions</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">A</emphasis></term>

          <listitem>
            <para>Improves account security by imposing restrictions on passwords and authentication attempts. See <link
            linkend="HDRWQ478">Increasing Account Security with the A Instruction</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">X</emphasis></term>

          <listitem>
            <para>Executes a command. See <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>.</para>
          </listitem>
        </varlistentry>
      </variablelist></para>

    <indexterm>
      <primary>uss template file</primary>

      <secondary>instructions for different account types</secondary>
    </indexterm>

    <indexterm>
      <primary>user account</primary>

      <secondary>creating different types with uss</secondary>
    </indexterm>

    <indexterm>
      <primary>creating</primary>

      <secondary>user account types with uss</secondary>
    </indexterm>

    <sect2 id="HDRWQ464">
      <title>Creating the Three Types of User Accounts</title>

      <para>Using the <emphasis role="bold">uss add</emphasis> and <emphasis role="bold">uss bulk</emphasis> commands, you can
      create three types of accounts that differ in their levels of functionality. For a description of the types, see <link
      linkend="HDRWQ57">Configuring AFS User Accounts</link>. The following list explains how to construct a template for each type:
      <itemizedlist>
          <listitem>
            <para>To create an authentication-only account, create an empty (zero-length) template file. Such an account has only
            two components: entries in the Authentication Database and Protection Database.</para>
          </listitem>

          <listitem>
            <para>To create a basic account, include a <emphasis role="bold">V</emphasis> instruction, and <emphasis
            role="bold">G</emphasis> instructions if you want to distribute home directories evenly as described in <link
            linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link>. In addition to
            Authentication Database and Protection Database entries, this type of account includes a volume mounted at the home
            directory with owner and ACL set appropriately.</para>
          </listitem>

          <listitem>
            <para>To create a full account, include <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>,
            <emphasis role="bold">F</emphasis>, <emphasis role="bold">L</emphasis>, and <emphasis role="bold">S</emphasis>
            instructions as appropriate, in addition to the <emphasis role="bold">V</emphasis> and <emphasis
            role="bold">G</emphasis> instructions. This type of account includes configuration files for basic functions such as
            logging in, printing, and mail delivery. For a discussion of some useful types of configuration files, see <link
            linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>constants</primary>

        <secondary>uss template file</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>constants</secondary>
      </indexterm>

      <indexterm>
        <primary>variables</primary>

        <secondary>in uss template file</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>variables</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ465">
      <title>Using Constants and Variables in the Template File</title>

      <para>Each instruction in the <emphasis role="bold">uss</emphasis> template file has several fields that define the
      characteristics of the element that it creates. The <emphasis role="bold">D</emphasis> instruction's fields, for instance,
      define a directory's pathname, owner, mode bits, and ACL.</para>

      <para>You can place three types of values in a field: a variable, a constant, or a combination of the two. The appropriate
      value depends on the desired configuration, and determines which arguments you provide to the <emphasis role="bold">uss
      add</emphasis> command or which fields you include in a bulk input file <emphasis role="bold">add</emphasis>
      instruction.</para>

      <para>If an aspect of account configuration is the same for every user, define a constant value in the appropriate field by
      inserting a character string. For example, to assign a space quota of 10,000 KB to every user volume, place the string
      <emphasis role="bold">10000</emphasis> in the <emphasis role="bold">V</emphasis> instruction's quota field.</para>

      <para>If, on the other hand, an aspect of account configuration varies for each user, put a variable in the appropriate field.
      When creating each account, provide a value for the variable by providing either the corresponding argument to the <emphasis
      role="bold">uss add</emphasis> command or a value in the corresponding field of the <emphasis role="bold">add</emphasis>
      instruction in the bulk input file.</para>

      <para>The <emphasis role="bold">uss</emphasis> command suite defines a set of template variables, each of which has a
      corresponding source for its value, as summarized in <link linkend="TBLWQ466">Table 3</link>. For a discussion of their
      intended uses, see the following sections about each template instruction (<link linkend="HDRWQ473">Creating a Volume with the
      V Instruction</link> through <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>).</para>

      <table id="TBLWQ466" label="3">
        <title>Source for values of uss template variables</title>

        <tgroup cols="2">
          <colspec colwidth="20*" />

          <colspec colwidth="80*" />

          <thead>
            <row>
              <entry><emphasis role="bold">Variable</emphasis></entry>

              <entry><emphasis role="bold">Source for value</emphasis></entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>$AUTO</entry>

              <entry>Previous <emphasis role="bold">G</emphasis> instructions in template</entry>
            </row>

            <row>
              <entry>$MTPT</entry>

              <entry><emphasis role="bold">-mount</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
              mount_point field of bulk input file <emphasis role="bold">add</emphasis> instruction, when in <emphasis
              role="bold">V</emphasis> instruction; <emphasis role="bold">V</emphasis> instruction's mount_point field when in
              subsequent instructions</entry>
            </row>

            <row>
              <entry>$NAME</entry>

              <entry><emphasis role="bold">-realname</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
              mount_point field of bulk input file <emphasis role="bold">add</emphasis> instruction, if provided; otherwise,
              <emphasis role="bold">-user</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or username field
              of in bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
            </row>

            <row>
              <entry>$PART</entry>

              <entry><emphasis role="bold">-partition</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
              partition field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
            </row>

            <row>
              <entry>$PWEXPIRES</entry>

              <entry><emphasis role="bold">-pwexpires</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
              password_expires field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
            </row>

            <row>
              <entry>$SERVER</entry>

              <entry><emphasis role="bold">-server</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
              file_server field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
            </row>

            <row>
              <entry>$UID</entry>

              <entry><emphasis role="bold">-uid</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or uid field
              of bulk input file <emphasis role="bold">add</emphasis> instruction, if provided; otherwise, allocated automatically
              by Protection Server</entry>
            </row>

            <row>
              <entry>$USER</entry>

              <entry><emphasis role="bold">-user</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or username
              field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
            </row>

            <row>
              <entry>$1 through $9</entry>

              <entry><emphasis role="bold">-var</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or var1
              through var9 fields of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>A common use of variables is to define the file server machine and partition that house the user's volume, which often
      vary from user to user. Place the $SERVER variable in the <emphasis role="bold">V</emphasis> instruction's server field, and
      the $PART variable in its partition field. If using the <emphasis role="bold">uss add</emphasis> command, provide the desired
      value with the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. If using
      the <emphasis role="bold">uss bulk</emphasis> command, provide the desired values in the file_server and partition fields of
      each user's <emphasis role="bold">add</emphasis> instruction in the bulk input file. <indexterm>
          <primary>number variables</primary>

          <secondary>uss template file</secondary>
        </indexterm> <indexterm>
          <primary>uss template file</primary>

          <secondary>number variables</secondary>
        </indexterm></para>

      <para>The variables $1 through $9 can be used to customize other aspects of the account. Provide a value for these variables
      with the <emphasis role="bold">-var</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or in the
      appropriate field of the bulk input file <emphasis role="bold">add</emphasis> instruction. The <emphasis
      role="bold">-var</emphasis> argument is unusual in that each instance for it has two parts: the number index and the value,
      separated by a space. For examples of the use of a number variable, see the discussions of the mount_point and quota fields in
      <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>

      <para>If some aspect of account configuration is partly constant and partly variable, you can combine variables and constants
      in an instruction field. For example, suppose that the Example Corporation mounts user volumes in the <emphasis
      role="bold">/afs/example.com/usr</emphasis> directory. That part of the pathname is constant, but the name of the mount point and
      home directory is the user's username, which corresponds to the $USER variable. To configure accounts in this way, combine a
      constant string and a variable in the <emphasis role="bold">V</emphasis> instruction's mount_point field as follows:</para>

      <programlisting>
   /afs/example.com/usr/$USER
</programlisting>

      <para>Then provide the value for the $USER variable with the <emphasis role="bold">-user</emphasis> argument to the <emphasis
      role="bold">uss add</emphasis> command, or in the username field of each user's <emphasis role="bold">add</emphasis>
      instruction in the bulk input file. <indexterm>
          <primary>location</primary>

          <secondary>standard for uss template file</secondary>
        </indexterm> <indexterm>
          <primary>uss template file</primary>

          <secondary>standard locations</secondary>
        </indexterm></para>
    </sect2>

    <sect2 id="HDRWQ468">
      <title>Where to Place Template Files</title>

      <para>A template must be available to the <emphasis role="bold">uss</emphasis> command interpreter as it executes a <emphasis
      role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command, even if it is the zero-length file
      appropriate for creating an authentication-only account.</para>

      <para>If you do not provide the <emphasis role="bold">-template</emphasis> argument to the <emphasis role="bold">uss
      add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command, then the command interpreter searches for a template file
      called <emphasis role="bold">uss.template</emphasis> in each of the following directories in turn: <orderedlist>
          <listitem>
            <para>The current working directory</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">/afs/cellname/common/uss</emphasis>, where cellname is the local cell</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">/etc</emphasis></para>
          </listitem>
        </orderedlist></para>

      <para>To use a template file with a different name or stored in a different directory, include the <emphasis
      role="bold">-template</emphasis> argument to the <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss
      bulk</emphasis> command. If you provide a filename only, the command interpreter looks for it in the directories listed just
      previously. If you provide a pathname and filename, it looks only in the specified directory, interpreting a partial pathname
      relative to the current working directory. <indexterm>
          <primary>rules</primary>

          <secondary>uss template file</secondary>
        </indexterm> <indexterm>
          <primary>uss template file</primary>

          <secondary>rules for constructing</secondary>
        </indexterm></para>
    </sect2>

    <sect2 id="HDRWQ469">
      <title>Some General Rules for Constructing a Template</title>

      <para>This section summarizes some general rules to follow when constructing a template file. For each instruction's syntax
      definition, see the following sections (<link linkend="HDRWQ472">Evenly Distributing User Home Directories with the G
      Instruction</link> through <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>). <itemizedlist>
          <listitem>
            <para>If a variable takes its value from an element elsewhere within the template, the definition must precede the
            reference. Putting the instruction lines in the following order usually results in correct resolution of
            variables:</para>

            <para><emphasis role="bold">G V D F E L S A X</emphasis></para>
          </listitem>

          <listitem>
            <para>The fields in each instruction must appear in the order specified by the instruction's syntax definition, which
            appear in the following sections about each instruction. You cannot omit a field. Separate each field from its neighbors
            with one or more spaces.</para>
          </listitem>

          <listitem>
            <para>When specifying a pathname, provide a full one. Partial pathnames are interpreted relative to the current working
            directory (the one in which the <emphasis role="bold">uss</emphasis> command is issued), with possibly unintended
            results.</para>
          </listitem>

          <listitem>
            <para>Each instruction must appear on a single line in the template file, with a newline character (<emphasis
            role="bold">&lt;Return&gt;</emphasis>) only at the end of the instruction. Some example instructions appear in this
            document on more than one line, but that is only for legibility.</para>
          </listitem>

          <listitem>
            <para>Provide a value for every variable that appears in the template by including the corresponding argument to the
            <emphasis role="bold">uss add</emphasis> command or placing a value in the corresponding field of the bulk input file
            <emphasis role="bold">add</emphasis> instruction. A missing value halts the entire creation operation. If a variable
            does not appear in the template file, the command interpreter ignores the corresponding command-line argument or field
            in the bulk input file, even if you provide it.</para>
          </listitem>

          <listitem>
            <para>You can use blank lines in the template file to increase its legibility. If you place comments in the file, begin
            each comment line with the number sign (<emphasis role="bold">#</emphasis>).</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ470">
      <title>About Creating Local Disk Directories and Files</title>

      <para>It is possible to use the <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, and <emphasis
      role="bold">F</emphasis> instructions to create directories or files in the local file system of the machine on which you are
      issuing the <emphasis role="bold">uss</emphasis> command, but that usage is not recommended. It introduces two potential
      complications: <itemizedlist>
          <listitem>
            <para>The local file system automatically assigns ownership of a new local disk directory or file to its creator.
            Because you are the issuer of the <emphasis role="bold">uss</emphasis> command that is creating the object, it records
            your current UNIX UID. If that is not appropriate and you want to designate another owner as the object is created, then
            you must be logged in as the local superuser <emphasis role="bold">root</emphasis> (the local file system allows only
            the <emphasis role="bold">root</emphasis> user to issue the UNIX <emphasis role="bold">chown</emphasis> command, which
            the <emphasis role="bold">uss</emphasis> command interpreter invokes to change the owner from the default value). You
            must also use the <emphasis role="bold">-admin</emphasis> argument to the <emphasis role="bold">uss add</emphasis> or
            <emphasis role="bold">uss bulk</emphasis> command to authenticate as a privileged AFS administrator. Only an
            administrator can create Authentication Database and Protection Database entries, which the <emphasis
            role="bold">uss</emphasis> command interpreter always creates as part of a new account.</para>

            <para>The alternative is to become the local superuser <emphasis role="bold">root</emphasis> after the <emphasis
            role="bold">uss</emphasis> operation completes, and issue the necessary <emphasis role="bold">chown</emphasis> command
            then. However, that makes the account creation process that much less automated.</para>
          </listitem>

          <listitem>
            <para>Creating a local disk directory always generates an error message because the <emphasis role="bold">uss</emphasis>
            command interpreter cannot successfully set a local directory's ACL. The directory is created nevertheless, and a value
            still must appear in the <emphasis role="bold">D</emphasis> instruction's ACL field.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ471">
      <title>Example uss Templates</title>

      <para>This section describes example templates for the basic and full account types (the template for an authentication-only
      account is empty).</para>

      <para>The first example creates a basic account. It contains two <emphasis role="bold">G</emphasis> instructions and a
      <emphasis role="bold">V</emphasis> instruction that defines the volume name, file server machine, partition, quota in
      kilobytes, mount point, home directory owner, and home directory access control list. In the Example Corporation cell, a suitable
      template is:</para>

      <programlisting>
   G /afs/.example.com/usr1
   G /afs/.example.com/usr2
   V  user.$USER  $SERVER.example.com  /vicep$PART  5000  $AUTO/$USER   $UID  \
        $USER all staff rl
</programlisting>

      <para>When issuing the <emphasis role="bold">uss add</emphasis> command with this type of template, provide the following
      arguments: <itemizedlist>
          <listitem>
            <para><emphasis role="bold">-user</emphasis> to specify the username for the $USER variable</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">-server</emphasis> to specify the unique part of the file server machine name for the
            $SERVER variable</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">-partition</emphasis> to specify the unique part of the partition name for the $PART
            variable</para>
          </listitem>
        </itemizedlist></para>

      <para>The Protection Server automatically assigns an AFS UID for the $UID variable, and the <emphasis role="bold">G</emphasis>
      instructions provide a value for the $AUTO variable.</para>

      <para>The following example template file creates a full account in the Example Corporation cell. The following sections about
      each type of instruction describe the effect of the examples. Note that the <emphasis role="bold">V</emphasis> and <emphasis
      role="bold">E</emphasis> instructions appear on two lines each only for the sake of legibility.</para>

      <programlisting>
   #
   # Specify the available grouping directories
   #
   G /afs/.example.com/usr1
   G /afs/.example.com/usr2
   #
   # Create the user's home volume
   #
   V user.$USER $SERVER.example.com /vicep$PART 5000 /afs/.example.com/$AUTO/$USER \
        $UID $USER all abc:staff rl
   #
   # Create directories and files for mail
   #
   D $MTPT/.MESSAGES 0700 $UID $USER all abc:staff none 
   D $MTPT/.Outgoing 0700 $UID $USER rlidwk postman rlidwk 
   D $MTPT/Mailbox 0700 $UID $USER all abc:staff none system:anyuser lik
   #
   # Here are some useful scripts for login etc.
   #
   F $MTPT/.Xbiff 0755 $UID /afs/example.com/admin/user/proto
   F $MTPT/.Xresources 0644 $UID /afs/example.com/admin/user/proto
   F $MTPT/.Xsession 0755 $UID /afs/example.com/admin/user/proto
   F $MTPT/.cshrc 0755 $UID /afs/example.com/admin/user/proto
   F $MTPT/.login 0755 $UID /afs/example.com/admin/user/proto
   F $MTPT/.logout 0755 $UID /afs/example.com/admin/user/proto
   F $MTPT/.twmrc 0644 $UID /afs/example.com/admin/user/proto
   F $MTPT/preferences 0644 $UID /afs/example.com/admin/user/proto
   #
   # Make a passwd entry
   #
   E /afs/.example.com/common/etc/newaccts/passwd_$USER 0644 root \
        "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
   #
   # Put in the standard password/authentication checks
   #
   A $USER 250 noreuse 9 25
   #
   # Create and mount a public volume for the user
   #
   X "create_public_vol $USER $1 $2"
   #
   # Here we set up the symbolic link to public directory
   #
   S /afs/example.com/public/$USER $MTPT/public
</programlisting>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>directory</secondary>

        <tertiary>distributing evenly with G instruction</tertiary>
      </indexterm>

      <indexterm>
        <primary>defining</primary>

        <secondary>directory for even distribution of accounts with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>directory</primary>

        <secondary>defining for even distribution of accounts with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>G instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>directory</secondary>

        <tertiary>G instruction for even distribution</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ472">
      <title>Evenly Distributing User Home Directories with the G Instruction</title>

      <para>In cells with thousands of user accounts, it often makes sense to distribute the mount points for user volumes into
      multiple parent directories, because placing them all in one directory noticeably slows down directory lookup when a user home
      directory is accessed. A possible solution is to create parent directories that group user home directories alphabetically, or
      that reflect divisions like academic or corporate departments. However, in a really large cell, some such groups can still be
      large enough to slow directory lookup, and users who belong to those groups are unfairly penalized every time they access
      their home directory. Another drawback to groupings that reflect workplace divisions is that you must move mount points when
      users change departmental affiliation.</para>

      <para>An alternative is an even distribution of user home directories into multiple parent directories that do not represent
      workplace divisions. The <emphasis role="bold">uss</emphasis> command suite enables you to define a list of directories by
      placing a <emphasis role="bold">G</emphasis> instruction for each one at the top of the template file, and then using the
      $AUTO variable in the <emphasis role="bold">V</emphasis> instruction's mount_point field. When the <emphasis
      role="bold">uss</emphasis> command interpreter encounters the $AUTO variable, it substitutes the directory named by a
      <emphasis role="bold">G</emphasis> instruction that currently has the fewest entries. (Actually, the $AUTO variable can appear
      in any field that includes a pathname, in any type of instruction. In all cases, the command interpreter substitutes the
      directory that currently has the fewest entries.)</para>

      <para>The <emphasis role="bold">G</emphasis> instruction's syntax is as follows:</para>

      <programlisting>
   G  directory
</programlisting>

      <para>where directory specifies either a complete directory pathname or only the final element (the directory itself). The
      choice determines the appropriate value to place in the <emphasis role="bold">V</emphasis> instruction's mount_point
      field.</para>

      <para>Specify the read/write path to each directory, to avoid the failure that results when you attempt to create a new mount
      point in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
      pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For further discussion of the concept
      of read/write and read-only paths through the filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>

      <para>For example, the Example Corporation example template for a full account in <link linkend="HDRWQ471">Example uss
      Templates</link> defines two directories:</para>

      <programlisting>
   G /afs/.example.com/usr1
   G /afs/.example.com/usr2
</programlisting>

      <para>and puts the value <emphasis role="bold">$AUTO/$USER</emphasis> in the <emphasis role="bold">V</emphasis> instruction's
      mount_point field. An alternative with the same result is to define the directories as follows:</para>

      <programlisting>
   G usr1
   G usr2
</programlisting>

      <para>and specify a more complete pathname in the <emphasis role="bold">V</emphasis> instruction's mount_point field:
      <emphasis role="bold">/afs/.example.com/$AUTO/$USER</emphasis>. <indexterm>
          <primary>uss commands</primary>

          <secondary>volume</secondary>

          <tertiary>creating with V instruction</tertiary>
        </indexterm> <indexterm>
          <primary>creating</primary>

          <secondary>volume with uss</secondary>
        </indexterm> <indexterm>
          <primary>volume</primary>

          <secondary>creating with uss</secondary>
        </indexterm> <indexterm>
          <primary>uss template file</primary>

          <secondary>V instruction</secondary>
        </indexterm> <indexterm>
          <primary>uss template file</primary>

          <secondary>volume</secondary>

          <tertiary>creating with V instruction</tertiary>
        </indexterm> <indexterm>
          <primary>uss template file</primary>

          <secondary>zero-length</secondary>
        </indexterm></para>
    </sect2>

    <sect2 id="HDRWQ473">
      <title>Creating a Volume with the V Instruction</title>

      <para>Unless the template file is empty (zero-length), one and only one <emphasis role="bold">V</emphasis> instruction must
      appear in it. (To create other volumes for a user as part of a <emphasis role="bold">uss</emphasis> account-creation
      operation, use the <emphasis role="bold">X</emphasis> instruction to invoke the <emphasis role="bold">vos create</emphasis>
      command or a script that invokes that command along with others, such as the <emphasis role="bold">fs mkmount</emphasis>
      command. For an example, see <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>.)</para>

      <para>The <emphasis role="bold">V</emphasis> instruction defines the following AFS entities:</para>

      <itemizedlist>
        <listitem>
          <para>A volume and associated VLDB entry</para>
        </listitem>

        <listitem>
          <para>The volume's site (file server machine and partition)</para>
        </listitem>

        <listitem>
          <para>The volume's mount point in the AFS filespace, which becomes the user's home directory</para>
        </listitem>

        <listitem>
          <para>The volume's space quota</para>
        </listitem>

        <listitem>
          <para>The home directory's owner, usually the new user</para>
        </listitem>

        <listitem>
          <para>The home directory's ACL, which normally at least grants all permissions to the user</para>
        </listitem>
      </itemizedlist>

      <para>The following discussion of the fields in a <emphasis role="bold">V</emphasis> instruction refers to the example in the
      full account template from <link linkend="HDRWQ471">Example uss Templates</link> (the instruction appears here on two lines
      only for legibility):</para>

      <programlisting>
   V  user.$USER  $SERVER.example.com  /vicep$PART  5000  \
       /afs/.example.com/$AUTO/$USER  $UID  $USER all abc:staff rl
</programlisting>

      <para>The <emphasis role="bold">V</emphasis> instruction's syntax is as follows:</para>

      <programlisting>
   V  volume_name  server  partition  quota  mount_point owner  ACL
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">V</emphasis></term>

            <listitem>
              <para>Indicates a volume creation instruction.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">volume_name</emphasis></term>

            <listitem>
              <para>Specifies the volume's name as recorded in the VLDB.</para>

              <para>To follow the convention of including the user's name as part of the volume name, include the $USER variable in
              this field. The variable takes its value from the <emphasis role="bold">-user</emphasis> argument to the <emphasis
              role="bold">uss add</emphasis> command or from the bulk input file <emphasis role="bold">add</emphasis> instruction's
              username field.</para>

              <para>The Example Corporation example uses the value <emphasis role="bold">user.$USER</emphasis> to assign the
              conventional volume name, <emphasis role="bold">user.</emphasis>username. When creating an account for user <emphasis
              role="bold">smith</emphasis>, for example, you then include <emphasis role="bold">-user smith</emphasis> as an
              argument to the <emphasis role="bold">uss add</emphasis> command, or place the value <emphasis
              role="bold">smith</emphasis> in the bulk input file <emphasis role="bold">add</emphasis> instruction's username
              field.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">server</emphasis></term>

            <listitem>
              <para>Names the file server machine on which to create the new volume. It is best to provide a fully qualified host
              name (for example, <emphasis role="bold">fs1.example.com</emphasis>), but an abbreviated form is acceptable if the cell's
              naming service is available to resolve it at the time the volume is created.</para>

              <para>To place different users' volumes on different file server machines, use the $SERVER variable in this field, and
              provide a value for it either with the <emphasis role="bold">-server</emphasis> argument to the <emphasis
              role="bold">uss add</emphasis> command or in the server field of the bulk input file <emphasis
              role="bold">add</emphasis> instruction. One easy way to specify a fully qualified hostname without having to type it
              completely on the command line is to combine a constant and the $SERVER variable. Specifically, the constant specifies
              the domain-name suffix common to all the file server machines.</para>

              <para>In the Example Corporation example, all of the file server machines in the cell share the <emphasis
              role="bold">example.com</emphasis> domain name suffix, so the server field combines a variable and constant: <emphasis
              role="bold">$SERVER.example.com</emphasis>. To place the new volume on the machine <emphasis
              role="bold">fs1.example.com</emphasis>, you then include <emphasis role="bold">-server fs1</emphasis> as an argument to
              the <emphasis role="bold">uss add</emphasis> command, or place the value <emphasis role="bold">fs1</emphasis> in the
              bulk input file <emphasis role="bold">add</emphasis> instruction's server field.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">partition</emphasis></term>

            <listitem>
              <para>Specifies the partition on which to create the user's volume; it must be on the file server machine named in the
              server field. Identify the partition by its complete name (for example, <emphasis role="bold">/vicepa</emphasis>) or
              use one of the abbreviations listed in <link linkend="HDRWQ615">Rules for Using Abbreviations and
              Aliases</link>.</para>

              <para>To place different users' volumes on different partitions, use the $PART variable in this field, and provide a
              value for it either with the <emphasis role="bold">-partition</emphasis> argument to the <emphasis role="bold">uss
              add</emphasis> command or in the partition field of the bulk input file <emphasis role="bold">add</emphasis>
              instruction. Because all full partition names start with the <emphasis role="bold">/vicep</emphasis> string, it is
              convenient to combine that string as a constant with the $PART variable.</para>

              <para>The Example Corporation example template combines the constant string <emphasis role="bold">/vicep</emphasis> and
              the $PART variable in this way, as <emphasis role="bold">/vicep$PART</emphasis>. <indexterm>
                  <primary>uss commands</primary>

                  <secondary>volume</secondary>

                  <tertiary>setting quota</tertiary>
                </indexterm> <indexterm>
                  <primary>volume quota</primary>

                  <secondary>setting</secondary>

                  <tertiary>with uss</tertiary>
                </indexterm> <indexterm>
                  <primary>uss template file</primary>

                  <secondary>quota on volume, setting with V instruction</secondary>
                </indexterm> <indexterm>
                  <primary>setting</primary>

                  <secondary>volume quota with uss</secondary>
                </indexterm></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">quota</emphasis></term>

            <listitem>
              <para>Sets the maximum number of kilobyte blocks the volume can occupy on the file server machine's disk. It must be
              an integer. If you assign the same quota to all user volumes, specify a constant value. To assign different quotas to
              different volumes, place one of the number variables ($1 through $9) in this field, and provide a value for it either
              with the <emphasis role="bold">-var</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or in
              the appropriate field of the bulk input file <emphasis role="bold">add</emphasis> instruction.</para>

              <para>The Example Corporation example grants a 5000 KB initial quota to every new user. <indexterm>
                  <primary>uss commands</primary>

                  <secondary>volume</secondary>

                  <tertiary>mounting</tertiary>
                </indexterm> <indexterm>
                  <primary>creating</primary>

                  <secondary>mount point with uss</secondary>
                </indexterm> <indexterm>
                  <primary>uss template file</primary>

                  <secondary>mount point, creating with V instruction</secondary>
                </indexterm> <indexterm>
                  <primary>mount point</primary>

                  <secondary>creating with uss</secondary>
                </indexterm></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">mount_point</emphasis></term>

            <listitem>
              <para>Creates a mount point for the volume, which serves as the volume's root directory and the user's home directory.
              By convention, user home directory names include the username, which you can read in by including the $USER variable
              in this field.</para>

              <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create the
              new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period before the
              cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the
              $AUTO variable in this field, the directories named by each <emphasis role="bold">G</emphasis> instruction possibly
              already indicate the read/write path. For further discussion of the concept of read/write and read-only paths through
              the filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>

              <para>If other parts of the mount point name also vary from user to user, you can use the $MTPT variable in this
              field, and provide a value with the <emphasis role="bold">uss add</emphasis> command's <emphasis
              role="bold">-mount</emphasis> argument or in the mount_point field of a bulk input file <emphasis
              role="bold">add</emphasis> instruction. Note, however, that when the $MTPT variable appears in subsequent instructions
              in the template (usually, in <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, or <emphasis
              role="bold">F</emphasis> instructions), it instead takes as its value the complete contents of this field.</para>

              <para>Combine constants and variables based on how you have decided to group home directories together in one or more
              parent directories. Note that the parent directories must already exist before you run a <emphasis role="bold">uss
              add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command that references the template. Possibilities for
              grouping home directories include the following: <indexterm>
                  <primary>user account</primary>

                  <secondary>methods for grouping</secondary>
                </indexterm> <itemizedlist>
                  <listitem>
                    <para>Placing all user home directories in a single parent directory; the name <emphasis
                    role="bold">/afs/</emphasis>cellname<emphasis role="bold">/usr</emphasis> is an AFS-appropriate variation on the
                    UNIX <emphasis role="bold">/usr</emphasis> convention. This choice is most appropriate for a cell with a small
                    number of user accounts. The simplest way to implement this choice is to combine a constant string and the $USER
                    variable, as in <emphasis role="bold">/afs/.example.com/usr/$USER</emphasis>.</para>
                  </listitem>

                  <listitem>
                    <para>Distributing home directories evenly into a set of parent directories that do not correspond to workplace
                    divisions. This choice is appropriate in cells with tens of thousands of accounts, where the number of home
                    directories is large enough to slow directory lookup significantly if they all reside together in one parent
                    directory, but distribution according to workplace divisions is not feasible.</para>

                    <para>The $AUTO variable is designed to distribute home directories evenly in this manner. As explained in <link
                    linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link>, the <emphasis
                    role="bold">uss</emphasis> command interpreter substitutes the directory that is defined by a preceding
                    <emphasis role="bold">G</emphasis> template instruction and that currently has the fewest entries. The example
                    Example Corporation template illustrates this choice by using the value <emphasis
                    role="bold">/afs/.example.com/$AUTO/$USER</emphasis>.</para>
                  </listitem>

                  <listitem>
                    <para>Distributing home directories into multiple directories that reflect divisions like academic or corporate
                    departments. Perhaps the simplest way to implement this scheme is to use the $MTPT variable to represent the
                    department, as in <emphasis role="bold">/afs/.example.com/usr/$MTPT/$USER</emphasis>. You then provide <emphasis
                    role="bold">-user smith</emphasis> and <emphasis role="bold">-mount acctg</emphasis> arguments to the <emphasis
                    role="bold">uss add</emphasis> command to create the mount point <emphasis
                    role="bold">/afs/.example.com/usr/acctg/smith</emphasis>.</para>
                  </listitem>

                  <listitem>
                    <para>Distributing home directories into alphabetic subdirectories of <emphasis role="bold">usr</emphasis>
                    (<emphasis role="bold">usr/a</emphasis>, <emphasis role="bold">usr/b</emphasis> and so on), based on the first
                    letter or letters in the username. The advantage is that knowing the username enables you easily to locate a
                    home directory. A potential drawback is that the distribution is not likely to be even, and if there are a large
                    number of accounts, then slowed directory lookup unfairly affects users whose names begins with popular
                    letters.</para>

                    <para>Perhaps the simplest way to implement this scheme is to use the $MTPT variable to represent the letter or
                    letters, as in <emphasis role="bold">/afs/.example.com/usr/$MTPT/$USER</emphasis>. Then provide the <emphasis
                    role="bold">-user smith</emphasis> and <emphasis role="bold">-mount s/m</emphasis> arguments to the <emphasis
                    role="bold">uss add</emphasis> command to create the mount point <emphasis
                    role="bold">/afs/.example.com/usr/s/m/smith</emphasis>.</para>
                  </listitem>
                </itemizedlist></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">owner</emphasis></term>

            <listitem>
              <para>Specifies the username or UID of the user to be designated the mount point's owner in the output from the UNIX
              <emphasis role="bold">ls -ld</emphasis> command. To follow the standard convention for home directory ownership, use
              the $UID variable in this field, as in the Example Corporation example template. The Protection Server then automatically
              assigns an AFS UID unless you provide the <emphasis role="bold">-uid</emphasis> argument to the <emphasis
              role="bold">uss add</emphasis> command or fill in the uid field in the bulk input file <emphasis
              role="bold">add</emphasis> instruction. (If you are converting existing UNIX accounts, see the discussion of
              additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link>.) <indexterm>
                  <primary>uss commands</primary>

                  <secondary>ACL, setting on home directory</secondary>
                </indexterm> <indexterm>
                  <primary>ACL</primary>

                  <secondary>setting on user home directory with uss</secondary>
                </indexterm> <indexterm>
                  <primary>uss template file</primary>

                  <secondary>ACL, setting</secondary>

                  <tertiary>user home directory with V instruction</tertiary>
                </indexterm> <indexterm>
                  <primary>setting</primary>

                  <secondary>ACL on home directory with uss</secondary>
                </indexterm></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">ACL</emphasis></term>

            <listitem>
              <para>Sets the ACL on the new home directory. Provide one or more paired values, each pair consisting of an AFS
              username or group name and the desired permissions, in that order (a group name must already exist in the Protection
              Database to be used). Separate the two parts of the pair, and each pair, with a space. For a discussion of the
              available permissions, see <link linkend="HDRWQ567">The AFS ACL Permissions</link>.</para>

              <para>At minimum, grant all permissions to the new user by including the value <emphasis role="bold">$USER
              all</emphasis> in this field. The File Server automatically grants all permissions to the <emphasis
              role="bold">system:administrators</emphasis> group as well. You cannot grant permissions to the issuer of the
              <emphasis role="bold">uss</emphasis> command, because as the last step in account creation the <emphasis
              role="bold">uss</emphasis> command interpreter automatically deletes that user from any ACLs set during the creation
              process.</para>

              <para>The Example Corporation example uses the following value to grant all permissions to the new user and <emphasis
              role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis
              role="bold">lookup</emphasis>) permissions to the members of the <emphasis role="bold">abc:staff</emphasis>
              group:</para>

              <para><emphasis role="bold">$USER all abc:staff rl</emphasis></para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>D instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>directory</secondary>

        <tertiary>creating</tertiary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>directory</secondary>

        <tertiary>creating with D instruction</tertiary>
      </indexterm>

      <indexterm>
        <primary>creating</primary>

        <secondary>directory with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>directory</primary>

        <secondary>creating with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>D instruction</primary>

        <secondary>uss template file</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ474">
      <title>Creating a Directory with the D Instruction</title>

      <para>Each <emphasis role="bold">D</emphasis> instruction in the template file creates a directory; there is no limit on the
      number of them in the template. If a <emphasis role="bold">D</emphasis> instruction creates a subdirectory in a new user's
      home directory (its intended use), then it must follow the <emphasis role="bold">V</emphasis> instruction. Creating a
      directory on the local disk of the machine where the <emphasis role="bold">uss</emphasis> command runs is not recommended for
      the reasons outlined in <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>

      <para>The following discussion of the fields in a <emphasis role="bold">D</emphasis> instruction refers to one of the examples
      in the full account template in <link linkend="HDRWQ471">Example uss Templates</link>:</para>

      <programlisting>
   D $MTPT/Mailbox 0700 $UID $USER all abc:staff none  system:anyuser lik
</programlisting>

      <para>The <emphasis role="bold">D</emphasis> instruction's syntax is as follows:</para>

      <programlisting>
   D  pathname  mode_bits  owner  ACL
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">D</emphasis></term>

            <listitem>
              <para>Indicates a directory creation instruction.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">pathname</emphasis></term>

            <listitem>
              <para>Specifies the directory's full pathname. If it is a subdirectory of the user's home directory, it is simplest to
              use the $MTPT variable to specify the home directory pathname. When the $MTPT variable appears in a <emphasis
              role="bold">D</emphasis> instruction, it takes its value from the preceding <emphasis role="bold">V</emphasis>
              instruction's mount_point field (this dependency is why a <emphasis role="bold">D</emphasis> instruction must follow
              the <emphasis role="bold">V</emphasis> instruction).</para>

              <para>Specify the read/write pathname to the directory, to avoid the failure that results when you attempt to create a
              new directory in a read-only volume. By convention, you indicate the read/write path by placing a period before the
              cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the
              $MTPT variable in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field
              possibly already indicates the read/write path. For further discussion of the concept of read/write and read-only
              paths through the filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>

              <para>The Example Corporation example uses the value <emphasis role="bold">$MTPT/Mailbox</emphasis> to place the <emphasis
              role="bold">Mailbox</emphasis> subdirectory in the user's home directory.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">mode_bits</emphasis></term>

            <listitem>
              <para>Defines the directory's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers
              corresponding to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to
              <emphasis role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
              role="bold">rw-r--r--</emphasis>. The first (owner) <emphasis role="bold">x</emphasis> bit must be turned on to enable
              access to a directory.</para>

              <para>The Example Corporation example uses the value <emphasis role="bold">0700</emphasis> to set the mode bits on the
              <emphasis role="bold">Mailbox</emphasis> subdirectory to <emphasis role="bold">rwxr-----</emphasis>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">owner</emphasis></term>

            <listitem>
              <para>Specifies the username or UID of the user to be designated the directory's owner in the output from the UNIX
              <emphasis role="bold">ls -ld</emphasis> command.</para>

              <para>If the directory resides in AFS, place the $UID variable in this field, as in the Example Corporation example
              template. The Protection Server then automatically assigns an AFS UID unless you provide the <emphasis
              role="bold">-uid</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or fill in the uid field
              in the bulk input file <emphasis role="bold">add</emphasis> instruction. (If you are converting existing UNIX
              accounts, see the discussion of additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX
              Accounts with uss</link>.)</para>

              <para>If the directory resides on the local disk, it is simplest to specify the username or UNIX UID under which you
              are issuing the <emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from
              designating another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.
              <indexterm>
                  <primary>ACL</primary>

                  <secondary>setting for directory with uss</secondary>
                </indexterm> <indexterm>
                  <primary>setting</primary>

                  <secondary>ACL for directory with uss</secondary>
                </indexterm> <indexterm>
                  <primary>uss template file</primary>

                  <secondary>ACL, setting</secondary>

                  <tertiary>directory created by D instruction</tertiary>
                </indexterm> <indexterm>
                  <primary>uss commands</primary>

                  <secondary>ACL, setting for directory</secondary>
                </indexterm></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">ACL</emphasis></term>

            <listitem>
              <para>Sets the ACL on the new directory. Provide one or more paired values, each pair consisting of an AFS username or
              group name and the desired permissions, in that order (a group name must already exist in the Protection Database to
              be used). Separate the two parts of the pair, and each pair, with a space. For a description of the available
              permissions, see <link linkend="HDRWQ567">The AFS ACL Permissions</link>.</para>

              <para>At minimum, grant all permissions to the new user by including the value <emphasis role="bold">$USER
              all</emphasis>. You cannot grant permissions to the issuer of the <emphasis role="bold">uss</emphasis> command,
              because as the last step in account creation the <emphasis role="bold">uss</emphasis> command interpreter
              automatically deletes that user from any ACLs set during the creation process. An error message always appears if the
              directory is on the local disk, as detailed in <link linkend="HDRWQ470">About Creating Local Disk Directories and
              Files</link>.</para>

              <para>The Example Corporation example uses the following value to grant all permissions to the new user, no permissions to
              the members of the <emphasis role="bold">abc:staff</emphasis> group, and the <emphasis role="bold">l</emphasis>
              (<emphasis role="bold">lookup</emphasis>), <emphasis role="bold">i</emphasis> (<emphasis
              role="bold">insert</emphasis>), and <emphasis role="bold">k</emphasis> (<emphasis role="bold">lock</emphasis>)
              permissions to the members of the <emphasis role="bold">system:anyuser</emphasis> group:</para>

              <para><emphasis role="bold">$USER all abc:staff none system:anyuser lik</emphasis></para>

              <para>It grants such extensive permissions to the <emphasis role="bold">system:anyuser</emphasis> group to enable any
              system user (including a mail-delivery daemon) to insert mail into the <emphasis role="bold">Mailbox</emphasis>
              directory. The absence of the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission
              prevents members of the <emphasis role="bold">system:anyuser</emphasis> group from reading the mail files.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>file, creating from prototype</secondary>
      </indexterm>

      <indexterm>
        <primary>creating</primary>

        <secondary>file with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>file</primary>

        <secondary>creating with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>F instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>file</secondary>

        <tertiary>creating from prototype</tertiary>
      </indexterm>

      <indexterm>
        <primary>F instruction</primary>

        <secondary>uss template file</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ475">
      <title>Creating a File from a Prototype with the F Instruction</title>

      <para>Each <emphasis role="bold">F</emphasis> instruction in the template file creates a file by copying the contents of an
      existing prototype file; there is no limit on the number of them in the template, and each can refer to a different prototype.
      If an <emphasis role="bold">F</emphasis> instruction creates a file in a new user's home directory or a subdirectory of it
      (the intended use), then it must follow the <emphasis role="bold">V</emphasis> or <emphasis role="bold">D</emphasis>
      instruction that creates the parent directory. Creating a file on the local disk of the machine where the <emphasis
      role="bold">uss</emphasis> command runs is not recommended for the reasons detailed in <link linkend="HDRWQ470">About Creating
      Local Disk Directories and Files</link>.</para>

      <para>The <emphasis role="bold">E</emphasis> instruction also creates a file, but the two types of instruction have
      complementary advantages. Files created with an <emphasis role="bold">E</emphasis> instruction can be customized for each
      user, because variables can appear in the field that specifies the contents of the file. In contrast, the contents of a file
      created using the <emphasis role="bold">F</emphasis> instruction are the same for every user. An <emphasis
      role="bold">E</emphasis> file can be only a single line, however, whereas an <emphasis role="bold">F</emphasis> file can be
      any length.</para>

      <para>The following discussion of the fields in a <emphasis role="bold">F</emphasis> instruction refers to one of the examples
      in the full account template in <link linkend="HDRWQ471">Example uss Templates</link>:</para>

      <programlisting>
   F $MTPT/.login 0755 $UID /afs/example.com/admin/user/proto
</programlisting>

      <para>The <emphasis role="bold">F</emphasis> instruction's syntax is as follows:</para>

      <programlisting>
   F  pathname  mode_bits  owner  prototype_file
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">F</emphasis></term>

            <listitem>
              <para>Indicates a file creation instruction.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">pathname</emphasis></term>

            <listitem>
              <para>Specifies the full pathname of the file to create, including the filename. If it resides in the user's home
              directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname.
              When the $MTPT variable appears in an <emphasis role="bold">F</emphasis> instruction, it takes its value from the
              preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency is why an <emphasis
              role="bold">F</emphasis> instruction must follow the <emphasis role="bold">V</emphasis> instruction).</para>

              <para>Specify the read/write path to the file, to avoid the failure that results when you attempt to create a new file
              in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
              pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the $MTPT variable
              in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
              indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
              filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>

              <para>The Example Corporation example uses the value <emphasis role="bold">$MTPT/.login</emphasis> to place a file called
              <emphasis role="bold">.login</emphasis> in the user's home directory.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">mode_bits</emphasis></term>

            <listitem>
              <para>Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding
              to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to <emphasis
              role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
              role="bold">rw-r--r--</emphasis>.</para>

              <para>The Example Corporation example uses the value <emphasis role="bold">0755</emphasis> to set the mode bits on the
              <emphasis role="bold">.login</emphasis> file to <emphasis role="bold">rwxr-xr-x</emphasis>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">owner</emphasis></term>

            <listitem>
              <para>Specifies the username or UID of the user to be designated the file's owner in the output from the UNIX
              <emphasis role="bold">ls -l</emphasis> command.</para>

              <para>If the file resides in AFS, place the $UID variable in this field, as in the Example Corporation example template.
              The Protection Server then automatically assigns an AFS UID unless you provide the <emphasis
              role="bold">-uid</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or fill in the uid field
              in the bulk input file <emphasis role="bold">add</emphasis> instruction. (If you are converting existing UNIX
              accounts, see the discussion of additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX
              Accounts with uss</link>.)</para>

              <para>If the file resides on the local disk, it is simplest to specify the username or UNIX UID under which you are
              issuing the <emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from
              designating another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">prototype_file</emphasis></term>

            <listitem>
              <para>Names the AFS or local directory that houses the prototype file to copy. The prototype file's name must match
              the final element in the pathname field.</para>

              <para>The Example Corporation example references a prototype file called <emphasis role="bold">.login</emphasis> in the
              directory <emphasis role="bold">/afs/example.com/admin/user/proto</emphasis>.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>file, creating by echoing one line</secondary>
      </indexterm>

      <indexterm>
        <primary>creating</primary>

        <secondary>file with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>file</primary>

        <secondary>creating with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>E instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>file</secondary>

        <tertiary>creating by echoing one line</tertiary>
      </indexterm>

      <indexterm>
        <primary>E instruction</primary>

        <secondary>uss template file</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ476">
      <title>Creating One-Line Files with the E Instruction</title>

      <para>Each <emphasis role="bold">E</emphasis> instruction in the template file creates a file by echoing a specified single
      line into it; there is no limit on the number of them in the template. If an <emphasis role="bold">E</emphasis> instruction
      creates a file in a new user's home directory or a subdirectory of it (the intended use), then it must follow the <emphasis
      role="bold">V</emphasis> or <emphasis role="bold">D</emphasis> instruction that creates the parent directory. Creating a file
      on the local disk of the machine where the <emphasis role="bold">uss</emphasis> command runs is not recommended for the
      reasons detailed in <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>

      <para>The <emphasis role="bold">F</emphasis> instruction also creates a file, but the two types of instruction have
      complementary advantages. Files created with an <emphasis role="bold">E</emphasis> instruction can be customized for each
      user, because variables can appear in the field that specifies the contents of the file. The command interpreter replaces the
      variables with appropriate values before creating the file. In contrast, the contents of a file created using the <emphasis
      role="bold">F</emphasis> instruction are the same for every user. An <emphasis role="bold">E</emphasis> file can be only a
      single line, however, whereas an <emphasis role="bold">F</emphasis> file can be any length.</para>

      <para>The <emphasis role="bold">E</emphasis> instruction is particularly suited to creating an entry for the new user in the
      cell's common source password file, which is then copied to client machines to serve as the local password file (<emphasis
      role="bold">/etc/passwd</emphasis> or equivalent). The following discussion of the fields refers to an example of this type of
      use, from the Example Corporation's full account template shown in <link linkend="HDRWQ471">Example uss Templates</link>. For
      further discussion of how to incorporate the files created in this way into a common source password file, see <link
      linkend="HDRWQ458">Creating a Common Source Password File</link>.</para>

      <programlisting>
   E /afs/.example.com/common/etc/newaccts/passwd_$USER 0644 root  \
      "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
</programlisting>

      <para>The <emphasis role="bold">E</emphasis> instruction's syntax is as follows:</para>

      <programlisting>
   E  pathname  mode_bits  owner  "contents"
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">E</emphasis></term>

            <listitem>
              <para>Indicates a file creation instruction.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">pathname</emphasis></term>

            <listitem>
              <para>Specifies the full pathname of the file to create, including the filename. It can include variables. If it
              resides in the user's home directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the
              home directory pathname. When the $MTPT variable appears in an <emphasis role="bold">E</emphasis> instruction, it
              takes its value from the preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency
              is why an <emphasis role="bold">E</emphasis> instruction must follow the <emphasis role="bold">V</emphasis>
              instruction.)</para>

              <para>Specify the read/write path to the file, to avoid the failure that results when you attempt to create a new file
              in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
              pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the $MTPT variable
              in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
              indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
              filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>

              <para>The Example Corporation example writes the file created by the <emphasis role="bold">E</emphasis> instruction to
              <emphasis role="bold">/afs/.example.com/common/etc/newaccts</emphasis> directory, naming it after the new user:</para>

              <programlisting>
   /afs/.example.com/common/etc/newaccts/passwd_$USER
</programlisting>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">mode_bits</emphasis></term>

            <listitem>
              <para>Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding
              to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to <emphasis
              role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
              role="bold">rw-r--r--</emphasis>.</para>

              <para>The Example Corporation example uses the value <emphasis role="bold">0644</emphasis> to set the mode bits on the
              <emphasis role="bold">passwd_</emphasis>user file to <emphasis role="bold">r-xr--r--</emphasis>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">owner</emphasis></term>

            <listitem>
              <para>Specifies the username or UID of the user to be designated the file's owner in the output from the UNIX
              <emphasis role="bold">ls -l</emphasis> command.</para>

              <para>If the file resides in AFS and is to be owned by the user, place the $UID variable in this field. The Protection
              Server then automatically assigns an AFS UID unless you provide the <emphasis role="bold">-uid</emphasis> argument to
              the <emphasis role="bold">uss add</emphasis> command or fill in the uid field in the bulk input file <emphasis
              role="bold">add</emphasis> instruction. (If you are converting existing UNIX accounts, see the discussion of
              additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link>.)</para>

              <para>If the file resides on the local disk, specify the username or UNIX UID under which you are issuing the
              <emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from designating
              another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>

              <para>The Example Corporation example is creating an AFS file intended for incorporation into the common password file,
              rather than for direct use by the new user. It therefore designates the local superuser <emphasis
              role="bold">root</emphasis> as the owner of the new file. Designating an alternate owner on an AFS file does not
              introduce complications: issuing the <emphasis role="bold">chown</emphasis> command on AFS files requires membership
              in the <emphasis role="bold">system:administrators</emphasis> group, but the issuer of the <emphasis
              role="bold">uss</emphasis> command is necessarily authenticated as a member of that group.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">contents</emphasis></term>

            <listitem>
              <para>Specifies the one-line character string to write into the new file. Surround it with double quotes if it
              contains one or more spaces. It cannot contain the newline character, but can contain any of the standard variables,
              which the command interpreter resolves as it creates the file.</para>

              <para>The Example Corporation example has the following value in the contents field, to create a password file
              entry:</para>

              <programlisting>
   $USER:X:$UID:10:$NAME:$MTPT:/bin/csh
</programlisting>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>L instruction</primary>

        <secondary>uss template file</secondary>
      </indexterm>

      <indexterm>
        <primary>S instruction</primary>

        <secondary>uss template file</secondary>
      </indexterm>

      <indexterm>
        <primary>uss</primary>

        <secondary>hard link, creating</secondary>
      </indexterm>

      <indexterm>
        <primary>creating</primary>

        <secondary>link (hard or symbolic) with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>hard link</primary>

        <secondary>creating with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>L instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>hard link, creating</secondary>
      </indexterm>

      <indexterm>
        <primary>uss</primary>

        <secondary>symbolic link, creating</secondary>
      </indexterm>

      <indexterm>
        <primary>symbolic link</primary>

        <secondary>creating with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>S instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>symbolic link, creating</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ477">
      <title>Creating Links with the L and S Instructions</title>

      <para>Each <emphasis role="bold">L</emphasis> instruction in the template file creates a hard link between two files, as
      achieved by the standard UNIX <emphasis role="bold">ln</emphasis> command. The <emphasis role="bold">S</emphasis> instruction
      creates a symbolic link between two files, as achieved by the standard UNIX <emphasis role="bold">ln -s</emphasis> command. An
      explanation of links is beyond the scope of this document, but the basic effect in both cases is to create a second name for
      an existing file, so that it can be accessed via either name. Creating a link does not create a second copy of the
      file.</para>

      <para>There is no limit on the number of <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis> instructions
      in a template file. If the link is in a new user's home directory or a subdirectory of it (the intended use), then it must
      follow the <emphasis role="bold">V</emphasis> or <emphasis role="bold">D</emphasis> instruction that creates the parent
      directory, and the <emphasis role="bold">F</emphasis>, <emphasis role="bold">E</emphasis>, or <emphasis
      role="bold">X</emphasis> instruction that creates the file being linked to. Creating a file on the local disk of the machine
      where the <emphasis role="bold">uss</emphasis> command runs is not recommended, for the reasons detailed in <link
      linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>

      <para>Note that AFS allows hard links only between files that reside in the same directory. This restriction is necessary to
      eliminate the confusion that results from associating two potentially different ACLs (those of the two directories) with the
      same file. Symbolic links are legal between two files that reside in different directories and even in different volumes. The
      ACL on the actual file applies to the link as well.</para>

      <para>You do not set the owner or mode bits on a link created with an <emphasis role="bold">L</emphasis> or <emphasis
      role="bold">S</emphasis> instruction, as you do for directories or files. The <emphasis role="bold">uss</emphasis> command
      interpreter automatically records the UNIX UID of the <emphasis role="bold">uss</emphasis> command's issuer as the owner, and
      sets the mode bits to <emphasis role="bold">lrwxrwxrwx</emphasis> (777).</para>

      <para>The following discussion of the fields in an <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis>
      instruction refers to an example in the full account template from <link linkend="HDRWQ471">Example uss Templates</link>,
      namely</para>

      <programlisting>
   S /afs/example.com/public/$USER $MTPT/public
</programlisting>

      <para>The <emphasis role="bold">L</emphasis> and <emphasis role="bold">S</emphasis> instructions' syntax is as follows:</para>

      <programlisting>
   L  existing_file  link
   S  existing_file  link
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">L</emphasis></term>

            <listitem>
              <para>Indicates a hard link creation instruction.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">S</emphasis></term>

            <listitem>
              <para>Indicates a symbolic link creation instruction.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">existing_file</emphasis></term>

            <listitem>
              <para>Specifies the complete pathname of the existing file. If it resides in the user's home directory or a
              subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname. When the $MTPT
              variable appears in an <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis> instruction, it takes
              its value from the preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency is
              why the instruction must follow the <emphasis role="bold">V</emphasis> instruction).</para>

              <para>Do not create a symbolic link to a file whose name begins with the number sign (<emphasis
              role="bold">#</emphasis>) or percent sign (<emphasis role="bold">%</emphasis>). When the Cache Manager reads a
              symbolic link whose contents begin with one of those characters, it interprets it as a regular or read/write mount
              point, respectively.</para>

              <para>The Example Corporation example creates a link to the publicly readable volume created and mounted by a preceding
              <emphasis role="bold">X</emphasis> instruction, by specifying the path to its mount point:</para>

              <programlisting>
   /afs/example.com/public/$USER
</programlisting>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">link</emphasis></term>

            <listitem>
              <para>Specifies the complete pathname of the second name for the file. If it resides in the user's home directory or a
              subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname.</para>

              <para>Specify the read/write path to the link, to avoid the failure that results when you attempt to create a new link
              in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
              pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the $MTPT variable
              in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
              indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
              filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>

              <para>The Example Corporation example creates a link called <emphasis role="bold">public</emphasis> in the user's home
              directory:</para>

              <programlisting>
   $MTPT/public
</programlisting>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>A instruction</primary>

        <secondary>uss template file</secondary>
      </indexterm>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>password/authentication security, setting with A instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>A instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>password/authentication security, setting with A instruction</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ478">
      <title>Increasing Account Security with the A Instruction</title>

      <para>The <emphasis role="bold">A</emphasis> instruction in the template file enhances cell security by imposing the following
      restrictions on users' password choice and authentication attempts. <itemizedlist>
          <listitem>
            <para>Limiting the user's password lifetime. When the lifetime expires, the user can no longer use the password to
            authenticate and must change it.</para>
          </listitem>

          <listitem>
            <para>Prohibiting the reuse of the user's 20 most-recently used passwords.</para>
          </listitem>

          <listitem>
            <para>Limiting the number of consecutive times that a user can provide an incorrect password during authentication, and
            for how long the Authentication Server refuses further authentication attempts after the limit is exceeded (referred to
            as an <emphasis>account lockout</emphasis>). For regular user accounts in most cells, the recommended limit is nine and
            lockout time is 25 minutes.</para>
          </listitem>
        </itemizedlist></para>

      <para>The following discussion of the fields in an <emphasis role="bold">A</emphasis> instruction refers to the example in the
      full account template from <link linkend="HDRWQ471">Example uss Templates</link>, which sets a password lifetime of 250 days,
      prohibits reuse of passwords, limits the number of failed authentication attempts to nine, and creates a lockout time of 25
      minutes if the authentication limit is exceeded:</para>

      <programlisting>
   A $USER 250 noreuse 9 25
</programlisting>

      <para>The <emphasis role="bold">A</emphasis> instruction's syntax is as follows:</para>

      <programlisting>
   A  username  password_lifetime  password_reuse  failures  locktime
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">A</emphasis></term>

            <listitem>
              <para>Indicates a security enhancing instruction.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">username</emphasis></term>

            <listitem>
              <para>Names the Authentication Database entry on which to impose security restrictions. Use the $USER variable to read
              in the username from the <emphasis role="bold">uss add</emphasis> command's <emphasis role="bold">-user</emphasis>
              argument, or from the username field of an <emphasis role="bold">add</emphasis> instruction in the bulk input file.
              The Example Corporation example uses this value.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">password_lifetime</emphasis></term>

            <listitem>
              <para>Sets the number of days after the user's password is changed that it remains valid. When the password becomes
              invalid (expires), the user is unable to authenticate, but has 30 more days in which to issue the <emphasis
              role="bold">kpasswd</emphasis> command to change the password (after that, only an administrator can change
              it).</para>

              <para>Specify an integer from the range <emphasis role="bold">1</emphasis> through <emphasis
              role="bold">254</emphasis> to specify the number of days until expiration, the value <emphasis
              role="bold">0</emphasis> to indicate that the password never expires, or the value $PWEXPIRES to read in the number of
              days from the <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command's
              <emphasis role="bold">-pwexpires</emphasis> argument. If the <emphasis role="bold">A</emphasis> instruction does not
              appear in the template file, by default the user's password never expires.</para>

              <para>The Example Corporation example sets a password lifetime of 250 days.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">password_reuse</emphasis></term>

            <listitem>
              <para>Determines whether or not the user can change his or her password (using the <emphasis
              role="bold">kpasswd</emphasis> or <emphasis role="bold">kas setpassword</emphasis> command) to one that is similar to
              any of his or her last 20 passwords. The acceptable values are <emphasis role="bold">reuse</emphasis> to allow reuse
              and <emphasis role="bold">noreuse</emphasis> to prohibit it. If the <emphasis role="bold">A</emphasis> instruction
              does not appear in the template file, the default is to allow password reuse.</para>

              <para>The Example Corporation example prohibits password reuse.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">failures</emphasis></term>

            <listitem>
              <para>Sets the number of consecutive times the user can provide an incorrect password during authentication (using the
              <emphasis role="bold">klog</emphasis> command or a login utility that grants AFS tokens). When the user exceeds the
              limit, the Authentication Server rejects further authentication attempts for the amount of time specified in the
              locktime field.</para>

              <para>Specify an integer from the range <emphasis role="bold">1</emphasis> through <emphasis
              role="bold">254</emphasis> to specify the number of failures permitted, or the value <emphasis
              role="bold">0</emphasis> to indicate that there is no limit to the number of unsuccessful attempts. If the <emphasis
              role="bold">A</emphasis> instruction does not appear in the template file, the default is to allow an unlimited number
              of failures.</para>

              <para>The Example Corporation example sets the limit to nine failed attempts.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">locktime</emphasis></term>

            <listitem>
              <para>Specifies how long the Authentication Server refuses authentication attempts from a user who has exceeded the
              failure limit set in the failures field.</para>

              <para>Specify a number of hours and minutes (hh:mm) or minutes only (mm), from the range <emphasis
              role="bold">01</emphasis> (one minute) through <emphasis role="bold">36:00</emphasis> (36 hours). The Authentication
              Server automatically reduces any larger value to <emphasis role="bold">36:00</emphasis> and also rounds up any nonzero
              value to the next highest multiple of 8.5 minutes. A value of <emphasis role="bold">0</emphasis> (zero) sets an
              infinite lockout time, in which case an administrator must always issue the <emphasis role="bold">kas
              unlock</emphasis> command to unlock the account.</para>

              <para>The Example Corporation example sets the lockout time to 25 minutes, which is rounded up to 25 minutes 30 seconds
              (the next highest multiple of 8.5 minutes).</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>command, executing with X instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>executing</primary>

        <secondary>command using uss template line</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>executing from uss template file</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>X instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>uss template file</primary>

        <secondary>command, executing with X instruction</secondary>
      </indexterm>

      <indexterm>
        <primary>X instruction</primary>

        <secondary>uss template file</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ479">
      <title>Executing Commands with the X Instruction</title>

      <para>The <emphasis role="bold">X</emphasis> instruction in the template file executes a command, which can be a standard UNIX
      command, a shell script or program, or an AFS command. The command string can include standard template variables, and any
      number of <emphasis role="bold">X</emphasis> instructions can appear in a template file. If an instruction manipulates an
      element created by another instruction, it must appear after that instruction.</para>

      <para>The following discussion of the field in an <emphasis role="bold">X</emphasis> instruction refers to the example in the
      full account template from <link linkend="HDRWQ471">Example uss Templates</link>:</para>

      <programlisting>
   X "create_public_vol $USER $1 $2"
</programlisting>

      <para>The <emphasis role="bold">X</emphasis> instruction's syntax is as follows:</para>

      <programlisting>
   X "command"
</programlisting>

      <para>where command specifies the command to execute. Surround it with double quotes if it contains spaces. The command string
      can contain any of the standard variables, which the <emphasis role="bold">uss</emphasis> command interpreter resolves before
      passing the command on to the appropriate other command interpreter, but it cannot contain newline characters.</para>

      <para>The Example Corporation example invokes a script called <emphasis role="bold">create_public_vol</emphasis>, which creates
      another volume associated with the new user and mounts it in a publicly readable part of the Example Corporation's
      filespace:</para>

      <programlisting>
   "create_public_vol $USER $1 $2"
</programlisting>

      <para>It uses the $USER variable to read in the username and make it part of both the volume name and mount point name. The
      <emphasis role="bold">uss</emphasis> command issuer supplies a file server machine name for the $1 variable and a partition
      name for the $2 variable, to specify the site for the new volume. <indexterm>
          <primary>creating</primary>

          <secondary>user account</secondary>

          <tertiary>with uss</tertiary>
        </indexterm> <indexterm>
          <primary>user</primary>

          <secondary>account</secondary>

          <see>user account</see>
        </indexterm> <indexterm>
          <primary>user account</primary>

          <secondary>creating</secondary>

          <tertiary>with uss</tertiary>
        </indexterm> <indexterm>
          <primary>username</primary>

          <secondary>assigning</secondary>

          <tertiary>with uss</tertiary>
        </indexterm> <indexterm>
          <primary>creating</primary>

          <secondary>Protection Database user entry</secondary>

          <tertiary>with uss</tertiary>
        </indexterm> <indexterm>
          <primary>creating</primary>

          <secondary>Authentication Database entry</secondary>

          <tertiary>with uss</tertiary>
        </indexterm> <indexterm>
          <primary>Protection Database</primary>

          <secondary>user entry</secondary>

          <tertiary>creating with uss</tertiary>
        </indexterm> <indexterm>
          <primary>Authentication Database</primary>

          <secondary>entry</secondary>

          <tertiary>creating with uss</tertiary>
        </indexterm> <indexterm>
          <primary>uss commands</primary>

          <secondary>creating individual user account</secondary>
        </indexterm> <indexterm>
          <primary>AFS UID</primary>

          <secondary>assigning</secondary>

          <tertiary>with uss</tertiary>
        </indexterm> <indexterm>
          <primary>user</primary>

          <secondary>AFS UID, assigning</secondary>
        </indexterm></para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ480">
    <title>Creating Individual Accounts with the uss add Command</title>

    <para>After you have created a template file, you can create an individual account by issuing the <emphasis role="bold">uss
    add</emphasis> command (for template creation instructions see <link linkend="HDRWQ463">Constructing a uss Template
    File</link>). When you issue the command, the <emphasis role="bold">uss</emphasis> command interpreter contacts various AFS
    servers to perform the following actions: <itemizedlist>
        <listitem>
          <para>Create a Protection Database entry. By default, the Protection Server assigns an AFS UID which becomes the value of
          the $UID variable used in the template.</para>
        </listitem>

        <listitem>
          <para>Create an Authentication Database entry, recording an encrypted version of the initial password.</para>
        </listitem>

        <listitem>
          <para>Create the account components defined in the indicated template file, contacting the File Server, Volume Server, and
          Volume Location (VL) Server as necessary.</para>
        </listitem>
      </itemizedlist></para>

    <para>To review which types of instructions to include in a template to create different file system objects, see <link
    linkend="HDRWQ463">Constructing a uss Template File</link>. If the template is empty, the <emphasis role="bold">uss
    add</emphasis> command creates an authentication-only account consisting of Protection Database and Authentication Database
    entries.</para>

    <para>When you issue the <emphasis role="bold">uss add</emphasis> command, provide a value for each variable in the template
    file by including the corresponding command-line argument. If you fail to supply a value for a variable, the <emphasis
    role="bold">uss</emphasis> command interpreter substitutes a null string, which usually causes the account creation to fail. If
    you include a command line argument for which the corresponding variable does not appear in the template, it is ignored.</para>

    <para><link linkend="TBLWQ481">Table 4</link> summarizes the mappings between variables and the arguments to the <emphasis
    role="bold">uss add</emphasis> command. It is adapted from <link linkend="TBLWQ466">Table 3</link>, but includes only those
    variables that take their value from command line arguments.</para>

    <table id="TBLWQ481" label="4">
      <title>Command-line argument sources for uss template variables</title>

      <tgroup cols="2">
        <colspec colwidth="20*" />

        <colspec colwidth="80*" />

        <thead>
          <row>
            <entry><emphasis role="bold">Variable</emphasis></entry>

            <entry><emphasis role="bold">Command-line Argument</emphasis></entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>$MTPT</entry>

            <entry><emphasis role="bold">-mount</emphasis> (for occurrence in <emphasis role="bold">V</emphasis>
            instruction)</entry>
          </row>

          <row>
            <entry>$NAME</entry>

            <entry><emphasis role="bold">-realname</emphasis> if provided; otherwise <emphasis role="bold">-user</emphasis></entry>
          </row>

          <row>
            <entry>$PART</entry>

            <entry><emphasis role="bold">-partition</emphasis></entry>
          </row>

          <row>
            <entry>$PWEXPIRES</entry>

            <entry><emphasis role="bold">-pwexpires</emphasis></entry>
          </row>

          <row>
            <entry>$SERVER</entry>

            <entry><emphasis role="bold">-server</emphasis></entry>
          </row>

          <row>
            <entry>$UID</entry>

            <entry><emphasis role="bold">-uid</emphasis> if provided; otherwise allocated by Protection Server</entry>
          </row>

          <row>
            <entry>$USER</entry>

            <entry><emphasis role="bold">-user</emphasis></entry>
          </row>

          <row>
            <entry>$1 through $9</entry>

            <entry><emphasis role="bold">-var</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <sect2 id="HDRWQ483">
      <title>To create an AFS account with the uss add command</title>

      <orderedlist>
        <listitem>
          <para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
          <emphasis role="bold">admin</emphasis> user account has them, or you possibly have a personal administrative account. (To
          increase cell security, it is best to create special privileged accounts for use only while performing administrative
          procedures; for further discussion, see <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
          necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
   % <emphasis role="bold">klog</emphasis> admin_user
   Password: &lt;<replaceable>admin_password</replaceable>&gt;
</programlisting></para>

          <para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>

          <itemizedlist>
            <listitem>
              <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
              <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
              display the members of the system:administrators group</link>. <programlisting>
   % <emphasis role="bold">pts membership system:administrators</emphasis>
</programlisting></para>
            </listitem>

            <listitem>
              <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
              role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
              users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
            </listitem>

            <listitem>
              <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. However, the
              Authentication Server always prompts you for a password in order to perform its own authentication. The following
              instructions direct you to specify the administrative identity on the <emphasis role="bold">uss</emphasis> command
              line itself.</para>
            </listitem>

            <listitem>
              <para>The <emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) and <emphasis
              role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions on the ACL of the directory in which
              you are mounting the user's volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which
              is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
   % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
</programlisting></para>

              <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
              role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
              role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
              role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Log in as the local superuser <emphasis role="bold">root</emphasis>.
          This is necessary only if you are creating new files or directories in the local file system and want to designate an
          alternate owner as the object is created. For a discussion of the issues involved, see <link linkend="HDRWQ470">About
          Creating Local Disk Directories and Files</link>.</para>
        </listitem>

        <listitem>
          <para>Verify the location and functionality of the template file you are using. For a description of where the <emphasis
          role="bold">uss</emphasis> command interpreter expects to find the template, see <link linkend="HDRWQ468">Where to Place
          Template Files</link>. You can always provide an alternate pathname if you wish. Also note the variables used in the
          template, to be sure that you provide the corresponding arguments on the <emphasis role="bold">uss</emphasis> command
          line.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Change to the directory where the template
          resides. This affects the type of pathname you must type in Step <link linkend="LIWQ485">6</link>. <programlisting>
   % <emphasis role="bold">cd</emphasis> template_directory
</programlisting></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Run the <emphasis role="bold">uss add</emphasis> command with the
          <emphasis role="bold">-dryrun</emphasis> flag to preview the creation of the account. Note any error messages and correct
          the cause before reissuing the command without the <emphasis role="bold">-dryrun</emphasis> flag. The next step describes
          the <emphasis role="bold">uss add</emphasis> command's syntax. For more information on the <emphasis
          role="bold">-dryrun</emphasis> flag, see <link linkend="HDRWQ454">Avoiding and Recovering from Errors and Interrupted
          Operations</link>. <indexterm>
              <primary>uss commands</primary>

              <secondary>add</secondary>
            </indexterm><indexterm>
              <primary>commands</primary>

              <secondary>uss add</secondary>
            </indexterm></para>
        </listitem>

        <listitem id="LIWQ485">
          <para>Issue the <emphasis role="bold">uss add</emphasis> command to create the account. Enter the
          command on a single line; it appears here on multiple lines only for legibility.</para>

          <para>The <emphasis role="bold">uss add</emphasis> operation creates an Authentication Database entry. The Authentication
          Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your
          local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the <emphasis
          role="bold">-admin</emphasis> argument to name an identity that has the <computeroutput>ADMIN</computeroutput> flag on its
          Authentication Database entry. To verify that an entry has the flag, issue the <emphasis role="bold">kas
          examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the ADMIN flag is set</link>.</para>

          <programlisting>
   % <emphasis role="bold">uss add</emphasis> <emphasis role="bold">-user</emphasis> &lt;<replaceable>login name</replaceable>&gt;  <emphasis
              role="bold">-admin</emphasis> &lt;<replaceable>administrator to authenticate</replaceable>&gt;   \
             [<emphasis role="bold">-realname</emphasis> &lt;<replaceable>full name in quotes</replaceable>&gt;] [<emphasis
              role="bold">-pass</emphasis> &lt;<replaceable>initial passwd</replaceable>&gt;]   \
             [<emphasis role="bold">-pwexpires</emphasis> &lt;<replaceable>password expires in [0..254] days (0 =</replaceable>&gt; never)&gt;]  \
             [<emphasis role="bold">-server</emphasis> &lt;<replaceable>FileServer for home volume</replaceable>&gt;]  \
             [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>FileServer's disk partition for home volume</replaceable>&gt;]  \
             [<emphasis role="bold">-mount</emphasis> &lt;<replaceable>home directory mount point</replaceable>&gt;]  \
             [<emphasis role="bold">-uid</emphasis> &lt;<replaceable>uid to assign the user</replaceable>&gt;]  \
             [<emphasis role="bold">-template</emphasis> &lt;<replaceable>pathname of template file</replaceable>&gt;]  \
             [<emphasis role="bold">-var</emphasis> &lt;<replaceable>auxiliary argument pairs (Numval)</replaceable>&gt;+] [<emphasis
              role="bold">-dryrun</emphasis>] \
             [<emphasis role="bold">-overwrite</emphasis>] 
   Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
</programlisting>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">ad</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">add</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-user</emphasis></term>

                <listitem>
                  <para>Names the user's Authentication Database and Protection Database entries. Because it becomes the username
                  (the name under which a user logs in), it must obey the restrictions that many operating systems impose on
                  usernames (usually, to contain no more than eight lowercase letters). Also avoid the following characters: colon
                  (<emphasis role="bold">:</emphasis>), semicolon (<emphasis role="bold">;</emphasis>), comma (<emphasis
                  role="bold">,</emphasis>), at sign (<emphasis role="bold">@</emphasis>), space, newline, and the period (<emphasis
                  role="bold">.</emphasis>), which is conventionally used only in special administrative names.</para>

                  <para>This argument provides the value for the $USER variable in the template file. For suggestions on
                  standardizing usernames, see <link linkend="HDRWQ58">Choosing Usernames and Naming Other Account
                  Components</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-admin</emphasis></term>

                <listitem>
                  <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
                  Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
                  admin_user. Enter the appropriate password as admin_password.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-realname</emphasis></term>

                <listitem>
                  <para>Specifies the user's actual full name. If it contains spaces or punctuation, surround it with double quotes.
                  If you do not provide it, it defaults to the username provided with the <emphasis role="bold">-user</emphasis>
                  argument.</para>

                  <para>This argument provides the value for the $NAME variable in the template file. For information about using
                  this argument and variable as part of an automated process for creating entries in a local password file such as
                  <emphasis role="bold">/etc/passwd</emphasis>, see <link linkend="HDRWQ458">Creating a Common Source Password
                  File</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-pass</emphasis></term>

                <listitem>
                  <para>Specifies the user's initial password. Although the AFS commands that handle passwords accept strings of
                  virtually unlimited length, it is best to use a password of eight characters or less, which is the maximum length
                  that many applications and utilities accept.</para>

                  <para>Possible choices for initial passwords include the username, a string of digits such as those from a Social
                  Security number, or a standard string such as <emphasis role="bold">changeme</emphasis>, which is the default if
                  you do not provide this argument. There is no corresponding variable in the template file.</para>

                  <para>Instruct users to change their passwords to a truly secret string as soon as they authenticate with AFS for
                  the first time. The <emphasis>OpenAFS User Guide</emphasis> explains how to use the <emphasis
                  role="bold">kpasswd</emphasis> command to change an AFS password.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-pwexpires</emphasis></term>

                <listitem>
                  <para>Sets the number of days after a user's password is changed that it remains valid. Provide an integer from
                  the range <emphasis role="bold">1</emphasis> through <emphasis role="bold">254</emphasis> to specify the number of
                  days until expiration, or the value <emphasis role="bold">0</emphasis> to indicate that the password never expires
                  (the default if you do not provide this argument). When the password becomes invalid (expires), the user is unable
                  to authenticate, but has 30 more days in which to issue the <emphasis role="bold">kpasswd</emphasis> command to
                  change the password; after that, only an administrator can change it.</para>

                  <para>This argument provides the value for the $PWEXPIRES variable in the template file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-server</emphasis></term>

                <listitem>
                  <para>Names the file server machine on which to create the new user's home volume. It is best to provide a fully
                  qualified hostname (for example, <emphasis role="bold">fs1.example.com</emphasis>), but an abbreviated form is
                  acceptable provided that the cell's naming service is available to resolve it when you issue the <emphasis
                  role="bold">uss add</emphasis> command.</para>

                  <para>This argument provides the value for the $SERVER variable in the template file. To avoid having to type a
                  fully qualified hostname on the command line, combine the $SERVER variable with a constant (for example, the
                  cell's domain name) in the server field of the <emphasis role="bold">V</emphasis> instruction in the template
                  file. For an example, see <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-partition</emphasis></term>

                <listitem>
                  <para>Specifies the partition on which to create the user's home volume; it must be on the file server machine
                  named by the <emphasis role="bold">-server</emphasis> argument. Identify the partition by its complete name (for
                  example, <emphasis role="bold">/vicepa</emphasis>), or use one of the abbreviations listed in <link
                  linkend="HDRWQ615">Rules for Using Abbreviations and Aliases</link>.</para>

                  <para>This argument provides the value for the $PART variable in the template file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-mount</emphasis></term>

                <listitem>
                  <para>Specifies the pathname for the user's home directory in the cell's read/write filespace. Partial pathnames
                  are interpreted relative to the current working directory.</para>

                  <para>This argument provides the value for the $MTPT variable in the template file, but only when it appears in
                  the <emphasis role="bold">V</emphasis> instruction's mount_point field. When the $MTPT variable appears in any
                  subsequent instructions, it takes its value from the <emphasis role="bold">V</emphasis> instruction's mount_point
                  field, rather than directly from this argument. For more details, and for suggestions about how to use this
                  argument and the $MTPT variable, see <link linkend="HDRWQ473">Creating a Volume with the V
                  Instruction</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-uid</emphasis></term>

                <listitem>
                  <para>Specifies a positive integer other than <emphasis role="bold">0</emphasis> (zero) to assign as the user's
                  AFS UID. It is best to omit this argument and allow the Protection Server to assign an AFS UID that is one greater
                  than the current value of the <computeroutput>max user id</computeroutput> counter. (To display the counter, use
                  the <emphasis role="bold">pts listmax</emphasis> command as described in <link linkend="HDRWQ561">To display the
                  AFS ID counters</link>.)</para>

                  <para>If you have a reason to use this argument (perhaps because the user already has a UNIX UID), first use the
                  <emphasis role="bold">pts examine</emphasis> command to verify that there is no existing account with the desired
                  AFS UID; if there is, the account creation process terminates with an error.</para>

                  <para>This argument provides the value for the $UID variable in the template file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-template</emphasis></term>

                <listitem>
                  <para>Specifies the pathname of the template file. If you omit this argument, the command interpreter searches for
                  a template file called <emphasis role="bold">uss.template</emphasis> in each of the following directories in turn:
                  <orderedlist>
                      <listitem>
                        <para>The current working directory</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">/afs/</emphasis>cellname<emphasis role="bold">/common/uss</emphasis>, where
                        cellname names the local cell</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">/etc</emphasis></para>
                      </listitem>
                    </orderedlist></para>

                  <para>If you specify a filename other than <emphasis role="bold">uss.template</emphasis> but without a pathname,
                  the command interpreter searches for it in the indicated directories. If you provide a full or partial pathname,
                  the command interpreter consults the specified file only; it interprets partial pathnames relative to the current
                  working directory.</para>

                  <para>If the specified template file is empty (zero-length), the command creates Protection and Authentication
                  Database entries only.</para>

                  <para>To learn how to construct a template file, see <link linkend="HDRWQ463">Constructing a uss Template
                  File</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-var</emphasis></term>

                <listitem>
                  <para>Specifies values for each of the number variables $1 through $9 that can appear in the template file. You
                  can use the number variables to assign values to variables in the <emphasis role="bold">uss</emphasis> template
                  file that are not part of the standard set.</para>

                  <para>For each instance of this argument, provide two parts in the indicated order, separated by a space:
                  <itemizedlist>
                      <listitem>
                        <para>The integer from the range <emphasis role="bold">1</emphasis> through <emphasis
                        role="bold">9</emphasis> that matches the variable in the template file. Do not precede it with a dollar
                        sign.</para>
                      </listitem>

                      <listitem>
                        <para>A string of alphanumeric characters to assign as the value of the variable.</para>
                      </listitem>
                    </itemizedlist></para>

                  <para>To learn about suggested uses for the number variables, see the description of the <emphasis
                  role="bold">V</emphasis> instruction's quota field in <link linkend="HDRWQ473">Creating a Volume with the V
                  Instruction</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-dryrun</emphasis></term>

                <listitem>
                  <para>Reports actions that the command interpreter needs to perform to run the command, without actually
                  performing them.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-overwrite</emphasis></term>

                <listitem>
                  <para>Overwrites any directories, files, and links that exist in the file system and for which there are
                  definitions in <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, <emphasis
                  role="bold">F</emphasis>, <emphasis role="bold">L</emphasis>, or <emphasis role="bold">S</emphasis> instructions
                  in the template file named by the <emphasis role="bold">-template</emphasis> argument. If you omit this flag, the
                  command interpreter prompts you once for confirmation that you want to overwrite all such elements.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>If the new user home directory resides in a replicated volume, use the <emphasis role="bold">vos release</emphasis>
          command to release the volume, as described in <link linkend="HDRWQ194">To replicate a read/write volume (create a
          read-only volume)</link>. <programlisting>
   % <emphasis role="bold">vos release</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
</programlisting></para>

          <note>
            <para>This step can be necessary even if the home directory's parent directory is not itself a mount point for a
            replicated volume (and is easier to overlook in that case). For example, the Example Corporation template puts the mount
            points for user volumes in the <emphasis role="bold">/afs/example.com/usr</emphasis> directory. Because that is a regular
            directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted at the
            <emphasis role="bold">/afs/example.com</emphasis> directory. That volume is replicated, so after changing it by creating a
            new mount point the administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>
          </note>
        </listitem>

        <listitem>
          <para>Create an entry for the new user in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or
          equivalent) on each AFS client machine that he or she can log into. For suggestions on automating this step, see <link
          linkend="HDRWQ458">Creating a Common Source Password File</link>.</para>

          <para>Even if you do not use the automated method, set the user's UNIX UID to match the AFS UID assigned automatically by
          the Protection Server or assigned with the <emphasis role="bold">-uid</emphasis> argument. The new user's AFS UID appears
          in the trace produced by the <emphasis role="bold">uss add</emphasis> output, or you can use the <emphasis role="bold">pts
          examine</emphasis> command to display it, as described in <link linkend="HDRWQ537">To display a Protection Database
          entry</link>.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>deleting</primary>

        <secondary>user accounts with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>user account</primary>

        <secondary>deleting with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>deleting</primary>

        <secondary>Protection Database user entry with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>deleting</primary>

        <secondary>Authentication Database entry with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>Protection Database</primary>

        <secondary>user entry</secondary>

        <tertiary>deleting with uss</tertiary>
      </indexterm>

      <indexterm>
        <primary>Authentication Database</primary>

        <secondary>entry</secondary>

        <tertiary>deleting with uss</tertiary>
      </indexterm>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>deleting individual user account</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ486">
    <title>Deleting Individual Accounts with the uss delete Command</title>

    <para>The <emphasis role="bold">uss delete</emphasis> command deletes an AFS user account according to the arguments you provide
    on the command line; unlike the <emphasis role="bold">uss add</emphasis> command, it does not use a template file. When you
    issue the command, the <emphasis role="bold">uss</emphasis> command interpreter contacts various AFS servers to perform the
    following actions: <itemizedlist>
        <listitem>
          <para>Remove the mount point for the user's home volume</para>
        </listitem>

        <listitem>
          <para>Remove the user's home volume and delete the associated VLDB entry, unless you include the <emphasis
          role="bold">-savevolume</emphasis> flag</para>
        </listitem>

        <listitem>
          <para>Delete the user's Authentication Database entry</para>
        </listitem>

        <listitem>
          <para>Delete the user's Protection Database entry</para>
        </listitem>
      </itemizedlist></para>

    <para>Before issuing the <emphasis role="bold">uss delete</emphasis> command, you can also perform the following optional tasks:
    <itemizedlist>
        <listitem>
          <para>Copy the user's home volume to tape or another permanent medium and record the username and UID on a reserved list.
          This information enables you to restore the user's account easily if he or she returns to your cell. For information about
          using the AFS Backup System to back up volumes, see <link linkend="HDRWQ248">Configuring the AFS Backup System</link> and
          <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
        </listitem>

        <listitem>
          <para>If the user has exclusive use of any other volumes (such as a volume for storing project-related data), make a
          backup copy of each one and then remove it and its mount point as instructed in <link linkend="HDRWQ235">Removing Volumes
          and their Mount Points</link>.</para>
        </listitem>

        <listitem>
          <para>Use the <emphasis role="bold">pts listowned</emphasis> command to display any groups that the user owns;
          instructions appear in <link linkend="HDRWQ540">To list the groups that a user or group owns</link>. Decide whether to use
          the <emphasis role="bold">pts delete</emphasis> command to remove the groups or the <emphasis role="bold">pts
          chown</emphasis> command to transfer ownership to another user or group. Instructions appear in <link
          linkend="HDRWQ553">To delete Protection Database entries</link> and <link linkend="HDRWQ555">To change a group's
          owner</link>. Alternatively, you can have the user remove or transfer ownership of the groups before leaving. A group that
          remains in the Protection Database after its owner is removed is considered orphaned, and only members of the <emphasis
          role="bold">system:administrators</emphasis> group can administer it.</para>
        </listitem>
      </itemizedlist></para>

    <para>You can automate some of these tasks by including <emphasis role="bold">exec</emphasis> instructions in the bulk input
    file and using the <emphasis role="bold">uss bulk</emphasis> command to delete the account. See <link
    linkend="HDRWQ488">Creating and Deleting Multiple Accounts with the uss bulk Command</link>.</para>

    <sect2 id="HDRWQ487">
      <title>To delete an AFS account</title>

      <orderedlist>
        <listitem>
          <para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
          <emphasis role="bold">admin</emphasis> user account has them, or you possibly have a personal administrative account. (To
          increase cell security, it is best to create special privileged accounts for use only while performing administrative
          procedures; for further discussion, see <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
          necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
   % <emphasis role="bold">klog</emphasis> admin_user
   Password: &lt;<replaceable>admin_password</replaceable>&gt;
</programlisting></para>

          <para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>

          <itemizedlist>
            <listitem>
              <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
              <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
              display the members of the system:administrators group</link>. <programlisting>
   % <emphasis role="bold">pts membership system:administrators</emphasis>
</programlisting></para>
            </listitem>

            <listitem>
              <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
              role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
              users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
            </listitem>

            <listitem>
              <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. However, the
              Authentication Server always prompts you for a password in order to perform its own authentication. The following
              instructions direct you to specify the administrative identity on the <emphasis role="bold">uss</emphasis> command
              line itself.</para>
            </listitem>

            <listitem>
              <para>The <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>) permission on the ACL of the
              directory that houses the user's home directory. If necessary, issue the <emphasis role="bold">fs listacl</emphasis>
              command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
   % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
</programlisting></para>

              <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
              role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
              role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
              role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Consider and resolve the issues discussed in the introduction to this section concerning the continued maintenance
          of a deleted user's account information, owned groups, and volumes.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Run the <emphasis role="bold">uss delete</emphasis> command with the
          <emphasis role="bold">-dryrun</emphasis> flag to preview the deletion of the account. Note any error messages and correct
          the cause before reissuing the command without the <emphasis role="bold">-dryrun</emphasis> flag. The next step describes
          the <emphasis role="bold">uss delete</emphasis> command's syntax. <indexterm>
              <primary>uss commands</primary>

              <secondary>delete</secondary>
            </indexterm><indexterm>
              <primary>commands</primary>

              <secondary>uss delete</secondary>
            </indexterm></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">uss delete</emphasis> command to delete the account. Enter the command on a single
          line; it appears here on multiple lines only for legibility.</para>

          <para>The delete operation always removes the user's entry from the Authentication Database. The Authentication Server
          performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local
          (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the <emphasis
          role="bold">-admin</emphasis> argument to name an identity that has the <computeroutput>ADMIN</computeroutput> flag on its
          Authentication Database entry. To verify that an entry has the flag, issue the <emphasis role="bold">kas
          examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the ADMIN flag is set</link>.</para>

          <programlisting>
   % <emphasis role="bold">uss delete</emphasis> <emphasis role="bold">-user</emphasis> &lt;<replaceable>login name</replaceable>&gt;  \ 
                <emphasis role="bold">-mountpoint</emphasis> &lt;<replaceable>mountpoint for user's volume</replaceable>&gt;  \
                [<emphasis role="bold">-savevolume</emphasis>]  <emphasis role="bold">-admin</emphasis>  &lt;<replaceable>administrator to authenticate</replaceable>&gt;  \
                [<emphasis role="bold">-dryrun</emphasis>] 
   Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
</programlisting>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">d</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">delete</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-user</emphasis></term>

                <listitem>
                  <para>Names the entry to delete from the Protection and Authentication Databases.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-mountpoint</emphasis></term>

                <listitem>
                  <para>Specifies the pathname of the mount point to delete (the user's home directory). Unless the <emphasis
                  role="bold">-savevolume</emphasis> argument is included, the volume mounted there is also deleted from the file
                  server machine where it resides, as is its record from the VLDB. Partial pathnames are interpreted relative to the
                  current working directory.</para>

                  <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete
                  a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before
                  the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For
                  further discussion of the concept of read/write and read-only paths through the filespace, see <link
                  linkend="HDRWQ208">Mounting Volumes</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-savevolume</emphasis></term>

                <listitem>
                  <para>Retains the user's volume and VLDB entry.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-admin</emphasis></term>

                <listitem>
                  <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
                  Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
                  admin_user. Enter the appropriate password as admin_password.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-dryrun</emphasis></term>

                <listitem>
                  <para>Reports actions that the command interpreter needs to perform to run the command, without actually
                  performing them.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>If the deleted user home directory resided in a replicated volume, use the <emphasis role="bold">vos
          release</emphasis> command to release the volume, as described in <link linkend="HDRWQ194">To replicate a read/write
          volume (create a read-only volume)</link>. <programlisting>
   % <emphasis role="bold">vos release</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
</programlisting></para>

          <note>
            <para>This step can be necessary even if the home directory's parent directory is not itself a mount point for a
            replicated volume (and is easier to overlook in that case). For example, the Example Corporation template puts the mount
            points for user volumes in the <emphasis role="bold">/afs/example.com/usr</emphasis> directory. Because that is a regular
            directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted at the
            <emphasis role="bold">/afs/example.com</emphasis> directory. That volume is replicated, so after changing it by deleting a
            mount point the administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>
          </note>
        </listitem>

        <listitem>
          <para>Delete the user's entry from the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of
          each client machine.
          If you intend to reactivate the user's account in the future, it is
          simpler to comment out the entry or place an asterisk (*) in the password field.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>creating</primary>

        <secondary>user accounts in bulk with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>user account</primary>

        <secondary>creating/deleting many at once</secondary>
      </indexterm>

      <indexterm>
        <primary>bulk mode in uss</primary>
      </indexterm>

      <indexterm>
        <primary>deleting</primary>

        <secondary>user accounts in bulk with uss</secondary>
      </indexterm>

      <indexterm>
        <primary>uss commands</primary>

        <secondary>creating/deleting user accounts in bulk</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ488">
    <title>Creating and Deleting Multiple Accounts with the uss bulk Command</title>

    <para>The <emphasis role="bold">uss bulk</emphasis> command allows you to create and delete many accounts at once. Before
    executing the command, you must <itemizedlist>
        <listitem>
          <para>Construct a template if you plan to create any accounts, just as you must do before running the <emphasis
          role="bold">uss add</emphasis> command. The same template applies to all accounts created by a single <emphasis
          role="bold">uss bulk</emphasis> command.</para>
        </listitem>

        <listitem>
          <para>Construct a bulk input file of instructions that create and delete accounts and execute any related commands, as
          described in <link linkend="HDRWQ489">Constructing a Bulk Input File</link>.</para>
        </listitem>
      </itemizedlist></para>

    <indexterm>
      <primary>rules</primary>

      <secondary>for uss bulk input file</secondary>
    </indexterm>

    <indexterm>
      <primary>uss bulk input file</primary>

      <secondary>rules for constructing</secondary>
    </indexterm>

    <sect2 id="HDRWQ489">
      <title>Constructing a Bulk Input File</title>

      <para>You can include five types of instructions in a bulk input file: <emphasis role="bold">add</emphasis>, <emphasis
      role="bold">delete</emphasis>, <emphasis role="bold">exec</emphasis>, <emphasis role="bold">savevolume</emphasis>, and
      <emphasis role="bold">delvolume</emphasis>. The following sections discuss their uses.</para>

      <para><emphasis role="bold">Creating a User Account with the add Instruction</emphasis></para>

      <para>Each <emphasis role="bold">add</emphasis> instruction creates a single user account, and so is basically the equivalent
      of issuing one <emphasis role="bold">uss add</emphasis> command. There is no limit to the number of <emphasis
      role="bold">add</emphasis> instructions in the bulk input file.</para>

      <para>As indicated by the following syntax statement, the order of the instruction's fields matches the order of arguments to
      the <emphasis role="bold">uss add</emphasis> command (though some of the command's arguments do not have a corresponding
      field). Like the <emphasis role="bold">uss add</emphasis> command's arguments, many of the fields provide a value for a
      variable in the <emphasis role="bold">uss</emphasis> template file. Each instruction must be a single line in the file (have a
      newline character only at its end); it appears on multiple lines here only for legibility.</para>

      <programlisting><emphasis role="bold">add</emphasis> username[<emphasis role="bold">:</emphasis>full_name][<emphasis
          role="bold">:</emphasis>initial_password][<emphasis role="bold">:</emphasis>password_expires]
   [<emphasis role="bold">:</emphasis>file_server][<emphasis role="bold">:</emphasis>partition][<emphasis role="bold">:</emphasis>mount_point][<emphasis
          role="bold">:</emphasis>uid]
   [<emphasis role="bold">:</emphasis>var1][<emphasis role="bold">:</emphasis>var2][<emphasis role="bold">:</emphasis>var3][<emphasis
          role="bold">:</emphasis>var4][<emphasis role="bold">:</emphasis>var5][<emphasis role="bold">:</emphasis>var6][<emphasis
          role="bold">:</emphasis>var7][<emphasis role="bold">:</emphasis>var8][<emphasis role="bold">:</emphasis>var9][<emphasis
          role="bold">:</emphasis>]
</programlisting>

      <para>For a complete description of the acceptable values in each field, see the <emphasis role="bold">uss Bulk Input
      File</emphasis> reference page in the <emphasis>OpenAFS Administration Reference</emphasis>, or the description of the
      corresponding arguments to the <emphasis role="bold">uss add</emphasis> command, in <link linkend="HDRWQ483">To create an AFS
      account with the uss add command</link>. Following are some basic notes: <itemizedlist>
          <listitem>
            <para>Begin the line with the string <emphasis role="bold">add</emphasis> only, not <emphasis role="bold">uss
            add</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Only the first argument, username, is required. It corresponds to the <emphasis role="bold">-user</emphasis>
            argument to the <emphasis role="bold">uss add</emphasis> command.</para>
          </listitem>

          <listitem>
            <para>Do not surround the full_name value with double quotes, even though you must use them around the value for the
            <emphasis role="bold">-realname</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command.</para>
          </listitem>

          <listitem>
            <para>If you want to omit a value for an argument, indicate an empty field by using two colons with nothing between
            them. Leaving a field empty is acceptable if the corresponding command line argument is optional or if the corresponding
            variable does not appear in the template file. For every field that precedes the last one to which you assign an actual
            value, you must either provide a value or indicate an empty field. It is acceptable, but not necessary, to indicate
            empty fields after the last one in which you assign a value.</para>
          </listitem>

          <listitem>
            <para>After the last field, end the line with either a colon and newline character (<emphasis
            role="bold">&lt;Return&gt;</emphasis>), or a newline alone.</para>
          </listitem>

          <listitem>
            <para>The final nine fields are for assigning values to the number variables ($1 through $9), with the fields listed in
            increasing numerical order. Specify the value only, not the variable number.</para>
          </listitem>
        </itemizedlist></para>

      <para><emphasis role="bold">Deleting a User Account with the delete Instruction</emphasis></para>

      <para>Each <emphasis role="bold">delete</emphasis> instruction deletes a single user account, and so is basically the
      equivalent of issuing one <emphasis role="bold">uss delete</emphasis> command. There is no limit to the number of <emphasis
      role="bold">delete</emphasis> instructions in the bulk input file.</para>

      <para>Like all instructions in the bulk input file, each <emphasis role="bold">delete</emphasis> instruction must be a single
      line in the file (have a newline character only at its end), even though it can cover multiple lines on a display screen. The
      curly braces (<emphasis role="bold">{ }</emphasis>) indicate two mutually exclusive choices.</para>

      <programlisting><emphasis role="bold">delete</emphasis> username<emphasis role="bold">:</emphasis>mount_point_path[:{ <emphasis
          role="bold">savevolume</emphasis> | <emphasis role="bold">delvolume</emphasis> }][<emphasis role="bold">:</emphasis>]
</programlisting>

      <para>For a complete description of the acceptable values in each field, see the <emphasis role="bold">uss Bulk Input
      File</emphasis> reference page in the <emphasis>OpenAFS Administration Reference</emphasis> or the description of the
      corresponding arguments to the <emphasis role="bold">uss delete</emphasis> command, in <link linkend="HDRWQ487">To delete an
      AFS account</link>. Following are some basic notes: <itemizedlist>
          <listitem>
            <para>Begin the line with the string <emphasis role="bold">delete</emphasis> only, not <emphasis role="bold">uss
            delete</emphasis>.</para>
          </listitem>

          <listitem>
            <para>The first two arguments, username and mount_point_path, are required. They correspond to the <emphasis
            role="bold">-user</emphasis> and <emphasis role="bold">-mountpoint</emphasis> arguments to the <emphasis role="bold">uss
            delete</emphasis> command.</para>
          </listitem>

          <listitem>
            <para>The third field, which is optional, controls whether the user's home volume is removed from the file server where
            it resides, along with the corresponding VLDB entry. There are three possible values: <itemizedlist>
                <listitem>
                  <para>No value treats the volume and VLDB entry according to the prevailing default, which is established by a
                  preceding <emphasis role="bold">savevolume</emphasis> or <emphasis role="bold">delvolume</emphasis> instruction in
                  the template file. See the following discussion of those instructions to learn how the default is set.</para>
                </listitem>

                <listitem>
                  <para>The string <emphasis role="bold">savevolume</emphasis> preserves the volume and VLDB entry, overriding the
                  default.</para>
                </listitem>

                <listitem>
                  <para>The string <emphasis role="bold">delvolume</emphasis> removes the volume and VLDB entry, overriding the
                  default.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>

          <listitem>
            <para>After the last field, end the line with either a colon and newline character (<emphasis
            role="bold">&lt;Return&gt;</emphasis>), or a newline alone.</para>
          </listitem>
        </itemizedlist></para>

      <para><emphasis role="bold">Running a Command or Script with the exec Instruction</emphasis></para>

      <para>The <emphasis role="bold">exec</emphasis> instruction runs the indicated AFS command, compiled program, or UNIX shell
      script or command. The command processor assumes the AFS and local identities of the issuer of the <emphasis role="bold">uss
      bulk</emphasis> command, who must have the privileges required to run the command.</para>

      <para>The instruction's syntax is as follows:</para>

      <programlisting><emphasis role="bold">exec</emphasis> command
</programlisting>

      <para>It is not necessary to surround the command string with double quotes (" ") or other delimiters.</para>

      <para><emphasis role="bold">Setting the Default Treatment of Volumes with the delvolume and savevolume
      Instructions</emphasis></para>

      <para>The <emphasis role="bold">savevolume</emphasis> and <emphasis role="bold">delvolume</emphasis> instructions set the
      default treatment of volumes referenced by the <emphasis role="bold">delete</emphasis> instructions that follow them in the
      bulk input file. Their syntax is as follows:</para>

      <programlisting>
        <emphasis role="bold">savevolume</emphasis>
        <emphasis role="bold">delvolume</emphasis>
      </programlisting>

      <para>Both instructions are optional and take no arguments. If neither appears in the bulk input file, then by default all
      volumes and VLDB entries referenced by <emphasis role="bold">delete</emphasis> instructions are removed. If the <emphasis
      role="bold">savevolume</emphasis> instruction appears in the file, it prevents the removal of the volume and VLDB entry
      referenced by all subsequent <emphasis role="bold">delete</emphasis> instructions in the file. The <emphasis
      role="bold">delvolume</emphasis> instruction explicitly establishes the default (which is deletion) for subsequent <emphasis
      role="bold">delete</emphasis> instructions.</para>

      <para>The effect of either instruction lasts until the end of the bulk input file, or until its opposite appears. To override
      the prevailing default for a particular <emphasis role="bold">delete</emphasis> instruction, put the <emphasis
      role="bold">savevolume</emphasis> or <emphasis role="bold">delvolume</emphasis> string in the instruction's third field. (You
      can also use multiple instances of the <emphasis role="bold">savevolume</emphasis> and <emphasis
      role="bold">delvolume</emphasis> instructions to toggle back and forth between default preservation and deletion of
      volumes.)</para>
    </sect2>

    <sect2 id="Header_570">
      <title>Example Bulk Input File Instructions</title>

      <para>To create an authentication-only account, use an <emphasis role="bold">add</emphasis> instruction like the following
      example, which includes only the first (username) argument. The user's real name is set to match the username (<emphasis
      role="bold">anderson</emphasis>) and her initial password is set to the string <emphasis
      role="bold">changeme</emphasis>.</para>

      <programlisting>
   add anderson 
</programlisting>

      <para>The following example also creates an authentication-only account, but sets nondefault values for the real name and
      initial password.</para>

      <programlisting>
   add smith:John Smith:js_pswd
</programlisting>

      <para>The next two example <emphasis role="bold">add</emphasis> instructions require that the administrator of the Example
      Corporation cell (<emphasis role="bold">example.com</emphasis>) has written a <emphasis role="bold">uss</emphasis> template file
      with the following <emphasis role="bold">V</emphasis> instruction in it:</para>

      <programlisting>
   V user.$USER $SERVER.example.com /vicep$PART 10000 /afs/.example.com/usr/$3/$USER \
       $UID $USER all
</programlisting>

      <para>To create accounts for users named John Smith from the Marketing Department and Pat Jones from the Finance Department,
      the appropriate <emphasis role="bold">add</emphasis> instructions in the bulk input file are as follows:</para>

      <programlisting>
   add smith:John Smith:::fs1:a:::::marketing
   add jones:Pat Jones:::fs3:c:::::finance
</programlisting>

      <para>The new account for Smith consists of Protection and Authentication Database entries called <emphasis
      role="bold">smith</emphasis>. His initial password is the default string <emphasis role="bold">changeme</emphasis>, and the
      Protection Server generates his AFS UID. His home volume, called <emphasis role="bold">user.smith</emphasis>, has a 10,000 KB
      quota, resides on partition <emphasis role="bold">/vicepa</emphasis> of file server machine <emphasis
      role="bold">fs1.example.com</emphasis>, and is mounted at <emphasis role="bold">/afs/.example.com/usr/marketing/smith</emphasis>. The
      final <emphasis role="bold">$UID $USER all</emphasis> part of the <emphasis role="bold">V</emphasis> instruction gives him
      ownership of his home directory and all permissions on its ACL. The account for <emphasis role="bold">jones</emphasis> is
      similar, except that it resides on partition <emphasis role="bold">/vicepc</emphasis> of file server machine <emphasis
      role="bold">fs3.example.com</emphasis> and is mounted at <emphasis role="bold">/afs/.example.com/usr/finance/jones</emphasis>.</para>

      <para>Notice that the fields corresponding to mount_point, uid, var1, and var2 are empty (between the values
      <computeroutput>a</computeroutput> and <computeroutput>marketing</computeroutput> on the first example line) because the
      corresponding variables do not appear in the <emphasis role="bold">V</emphasis> instruction in the template file. The
      initial_passwd and password_expires fields are also empty.</para>

      <para>If you wish, you can specify values or empty fields for all nine number variables in an <emphasis
      role="bold">add</emphasis> instruction. In that case, the bulk input file instructions are as follows:</para>

      <programlisting>
   add smith:John Smith:::fs1:a:::::marketing::::::
   add jones:Pat Jones:::fs3:c:::::finance::::::
</programlisting>

      <para>The following example is a section of a bulk input file with a number of <emphasis role="bold">delete</emphasis>
      instructions and a <emphasis role="bold">savevolume</emphasis> instruction. Because the first three instructions appear before
      the <emphasis role="bold">savevolume</emphasis> instruction and their third field is blank, the corresponding volumes and VLDB
      entries are removed. The <emphasis role="bold">delete</emphasis> instruction for user <emphasis role="bold">terry</emphasis>
      follows the <emphasis role="bold">savevolume</emphasis> instruction, so her volume is not removed, but the volume for user
      <emphasis role="bold">johnson</emphasis> is, because the <emphasis role="bold">delvolume</emphasis> string in the third field
      of the <emphasis role="bold">delete</emphasis> instruction overrides the current default.</para>

      <programlisting>
   delete smith:/afs/example.com/usr/smith
   delete pat:/afs/example.com/usr/pat
   delete rogers:/afs/example.com/usr/rogers
   savevolume
   delete terry:/afs/example.com/usr/terry
   delete johnson:/afs/example.com/usr/johnson:delvolume
</programlisting>

      <para>The following example <emphasis role="bold">exec</emphasis> instruction is useful as a separator between a set of
      <emphasis role="bold">add</emphasis> instructions and a set of <emphasis role="bold">delete</emphasis> instructions. It
      generates a message on the standard output stream that informs you of the <emphasis role="bold">uss bulk</emphasis> command's
      progress.</para>

      <programlisting>
   exec echo "Additions completed; beginning deletions..."
</programlisting>
    </sect2>

    <sect2 id="Header_571">
      <title>To create and delete multiple AFS user accounts</title>

      <orderedlist>
        <listitem>
          <para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
          <emphasis role="bold">admin</emphasis> user account has them, or you possibly have a personal administrative account. (To
          increase cell security, it is best to create special privileged accounts for use only while performing administrative
          procedures; for further discussion, see <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
          necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
   % <emphasis role="bold">klog</emphasis> admin_user
   Password: &lt;<replaceable>admin_password</replaceable>&gt;
</programlisting></para>

          <para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>

          <itemizedlist>
            <listitem>
              <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
              <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
              display the members of the system:administrators group</link>. <programlisting>
   % <emphasis role="bold">pts membership system:administrators</emphasis>
</programlisting></para>
            </listitem>

            <listitem>
              <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
              role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
              users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
            </listitem>

            <listitem>
              <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. However, the
              Authentication Server always prompts you for a password in order to perform its own authentication. The following
              instructions direct you to specify the administrative identity on the <emphasis role="bold">uss</emphasis> command
              line itself.</para>
            </listitem>

            <listitem>
              <para>The <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>), <emphasis
              role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis
              role="bold">lookup</emphasis>) permissions on the ACL of the parent directory for each volume mount point. If
              necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link
              linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
   % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
</programlisting></para>

              <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
              role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
              role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
              role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional.)</emphasis> Log in as the local superuser <emphasis role="bold">root</emphasis>.
          This is necessary only if you are creating new files or directories in the local file system and want to designate an
          alternate owner as the object is created. For a discussion of the issues involved, see <link linkend="HDRWQ470">About
          Creating Local Disk Directories and Files</link>.</para>
        </listitem>

        <listitem>
          <para>If the bulk input file includes <emphasis role="bold">add</emphasis> instructions, verify the location and
          functionality of the template you are using. For a description of where the <emphasis role="bold">uss</emphasis> command
          interpreter expects to find the template, see <link linkend="HDRWQ468">Where to Place Template Files</link>. You can
          always provide an alternate pathname if you wish. Also note which variables appear in the template, to be sure that you
          provide the corresponding arguments in the <emphasis role="bold">add</emphasis> instruction or on the <emphasis
          role="bold">uss bulk</emphasis> command line.</para>
        </listitem>

        <listitem>
          <para>Create a bulk input file that complies with the rules listed in <link linkend="HDRWQ489">Constructing a Bulk Input
          File</link>. It is simplest to put the file in the same directory as the template file you are using.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional.)</emphasis> Change to the directory where the bulk input file and template file
          reside. <programlisting>
   % <emphasis role="bold">cd</emphasis> template_directory
</programlisting><indexterm>
              <primary>uss commands</primary>

              <secondary>bulk</secondary>
            </indexterm><indexterm>
              <primary>commands</primary>

              <secondary>uss bulk</secondary>
            </indexterm></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">uss bulk</emphasis> command to create or delete accounts, or
          both. Enter the command on a single line; it appears here on multiple lines only for legibility.</para>

          <para>The bulk operation always manipulates user entries in the Authentication Database. The Authentication Server
          performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local
          (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the <emphasis
          role="bold">-admin</emphasis> argument to name an identity that has the <computeroutput>ADMIN</computeroutput> flag on its
          Authentication Database entry. To verify that an entry has the flag, issue the <emphasis role="bold">kas
          examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the ADMIN flag is set</link>.</para>

          <programlisting>
   % <emphasis role="bold">uss bulk</emphasis> &lt;<replaceable>bulk input file</replaceable>&gt;  \
              [<emphasis role="bold">-template</emphasis> &lt;<replaceable>pathname of template file</replaceable>&gt;]  \
              <emphasis role="bold">-admin</emphasis> &lt;<replaceable>administrator to authenticate</replaceable>&gt;  \
              [<emphasis role="bold">-dryrun</emphasis>] [<emphasis role="bold">-overwrite</emphasis>]  \
              [<emphasis role="bold">-pwexpires</emphasis> &lt;<replaceable>password expires in [0..254] days (0 =</replaceable>&gt; never)&gt;]  \
              [<emphasis role="bold">-pipe</emphasis>]
   Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
</programlisting>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">b</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">bulk</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">bulk input file</emphasis></term>

                <listitem>
                  <para>Specifies the pathname of the bulk input file. Partial pathnames are interpreted relative to the current
                  working directory. For a discussion of the required file format, see <link linkend="HDRWQ489">Constructing a Bulk
                  Input File</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-template</emphasis></term>

                <listitem>
                  <para>Specifies the pathname of the template file for any <emphasis role="bold">uss add</emphasis> commands that
                  appear in the bulk input file. Partial pathnames are interpreted relative to the current working directory. For a
                  discussion of the required file format, see <link linkend="HDRWQ463">Constructing a uss Template
                  File</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-admin</emphasis></term>

                <listitem>
                  <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
                  Authentication Database entry, such as the <emphasis role="bold">admin</emphasis> account. The password prompt
                  echoes it as admin_user. Enter the appropriate password as admin_password.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-dryrun</emphasis></term>

                <listitem>
                  <para>Reports actions that the command interpreter needs to perform to run the command, without actually
                  performing them.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-overwrite</emphasis></term>

                <listitem>
                  <para>Overwrites any directories, files and links that exist in the file system and for which there are also
                  <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, <emphasis role="bold">F</emphasis>,
                  <emphasis role="bold">L</emphasis>, or <emphasis role="bold">S</emphasis> instructions in the template file named
                  by the <emphasis role="bold">-template</emphasis> argument. If this flag is omitted, the command interpreter
                  prompts, once for each <emphasis role="bold">add</emphasis> instruction in the bulk input file, for confirmation
                  that it is to overwrite such elements. Do not include this flag if there are no <emphasis
                  role="bold">add</emphasis> instructions in the bulk input file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-pwexpires</emphasis></term>

                <listitem>
                  <para>Sets the number of days after a user's password is changed that it remains valid, for each user named by an
                  <emphasis role="bold">add</emphasis> instruction in the bulk input file. Provide an integer from the range
                  <emphasis role="bold">1</emphasis> through <emphasis role="bold">254</emphasis> to specify the number of days
                  until expiration, or the value <emphasis role="bold">0</emphasis> to indicate that the password never expires (the
                  default).</para>

                  <para>When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in
                  which to issue the <emphasis role="bold">kpasswd</emphasis> command to change the password (after that, only an
                  administrator can change it).</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-pipe</emphasis></term>

                <listitem>
                  <para>Suppresses the Authentication Server's prompt for the password of the issuer or the user named by the
                  <emphasis role="bold">-admin</emphasis> argument (the Authentication Server always separately authenticates the
                  user who is creating or deleting an entry in the Authentication Database). Instead, the command interpreter
                  accepts the password as piped input from another program, enabling you to run the <emphasis role="bold">uss
                  bulk</emphasis> command in unattended batch jobs.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>If a newly created or deleted user home directory resides in a replicated volume, use the <emphasis role="bold">vos
          release</emphasis> command to release the volume, as described in <link linkend="HDRWQ194">To replicate a read/write
          volume (create a read-only volume)</link>. <programlisting>
   % <emphasis role="bold">vos release</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
</programlisting></para>

          <note>
            <para>This step can be necessary even if the home directory's parent directory is not itself a mount point for a
            replicated volume (and is easier to overlook in that case). For example, the Example Corporation template puts the mount
            points for user volumes in the <emphasis role="bold">/afs/example.com/usr</emphasis> directory. Because that is a regular
            directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted at the
            <emphasis role="bold">/afs/example.com</emphasis> directory. That volume is replicated, so after changing it by creating or
            deleting a mount point, the administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>
          </note>
        </listitem>

        <listitem>
          <para>If you are creating accounts, create an entry for the new user in the local password file (<emphasis
          role="bold">/etc/passwd</emphasis> or equivalent) on each AFS client machine that he or she can log into. For suggestions
          on automating this step, see <link linkend="HDRWQ458">Creating a Common Source Password File</link>.</para>

          <para>Even if you do not use the automated method, set the user's UNIX UID to match the AFS UID assigned automatically by
          the Protection Server or assigned with the <emphasis role="bold">-uid</emphasis> argument. The new user's AFS UID appears
          in the trace produced by the <emphasis role="bold">uss add</emphasis> output or you can use the <emphasis role="bold">pts
          examine</emphasis> command to display it, as described in <link linkend="HDRWQ537">To display a Protection Database
          entry</link>.</para>
        </listitem>

        <listitem>
          <para>If you are deleting accounts, delete the user's entry from the local password file (<emphasis
          role="bold">/etc/passwd</emphasis> or equivalent) of each client machine.
          If you intend to reactivate the user's account in the future, it is simpler to comment out the entry or place an asterisk
          (*) in the password field.</para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>
</chapter>