doc/html/AdminGuide/auagd017.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Guide</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
   8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
   9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Guide</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd016.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auagd018.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <A NAME="IDX7583"></A>
  19 <HR><H1><A NAME="HDRWQ449" HREF="auagd002.htm#ToC_535">Creating and Deleting User Accounts with the uss Command Suite</A></H1>
  20 <P>The <B>uss</B> command suite helps you create and delete
  21 AFS user accounts quickly and easily. You can create a single account
  22 with the <B>uss add</B> command, delete a single account with the <B>uss
  23 delete</B> command, or create and delete multiple accounts with the <B>uss
  24 bulk</B> command.
  25 <P>A single <B>uss add</B> or <B>uss bulk</B> command can create a
  26 complete AFS user account because the <B>uss</B> command interpreter
  27 refers to a template file in which you predefine the configuration of many
  28 account components. The <B>uss delete</B> command deletes most of
  29 the components of a user account, but does not use a template file.
  30 <P>The <B>uss</B> suite also easily incorporates shell scripts or other
  31 programs that you write to perform parts of account creation and deletion
  32 unique to your site. To invoke a script or program automatically as a
  33 <B>uss</B> command runs, use the appropriate instructions in the template
  34 file or bulk input file. Various sections of this chapter discuss
  35 possible uses for scripts.
  36 <P>Using the <B>uss</B> commands to create and delete accounts is the
  37 recommended method because it automates and correctly orders most of the
  38 necessary steps. The alternative is to issue a series of separate
  39 commands to the various AFS servers, which requires more careful record
  40 keeping. For instructions, see <A HREF="auagd018.htm#HDRWQ491">Administering User Accounts</A>.
  41 <HR><H2><A NAME="HDRWQ450" HREF="auagd002.htm#ToC_536">Summary of Instructions</A></H2>
  42 <P>This chapter explains how to perform the following tasks by
  43 using the indicated commands:
  44 <BR>
  45 <TABLE WIDTH="100%">
  46 <TR>
  47 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">Add a single user account
  48 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>uss add</B>
  49 </TD></TR><TR>
  50 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">Delete a single user account
  51 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>uss delete</B>
  52 </TD></TR><TR>
  53 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">Add and delete multiple accounts
  54 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>uss bulk</B>
  55 </TD></TR></TABLE>
  56 <HR><H2><A NAME="HDRWQ452" HREF="auagd002.htm#ToC_537">Overview of the uss Command Suite</A></H2>
  57 <P>The commands in the <B>uss</B> suite help you to
  58 automate the creation and deletion of AFS user accounts:
  59 <UL>
  60 <P><LI>The <B>uss add</B> command creates all of the components of an
  61 account, one account at a time. It consults a template file that
  62 defines account configuration.
  63 <P><LI>The <B>uss delete</B> command deletes the major components of an
  64 account, one account at a time. It does not use a template file, so you
  65 possibly need to perform additional tasks manually.
  66 <P><LI>The <B>uss bulk</B> command can create and delete multiple
  67 accounts. It refers to a bulk input file that can contain any number of
  68 account-creation and deletion instructions, along with other instructions for
  69 further automating the process.
  70 </UL>
  71 <A NAME="IDX7584"></A>
  72 <A NAME="IDX7585"></A>
  73 <P><H3><A NAME="Header_538" HREF="auagd002.htm#ToC_538">The Components of an AFS User Account</A></H3>
  74 <P>An AFS user account can have many components. The only two
  75 required components are entries in the Protection Database and Authentication
  76 Database, but the other components add functionality and usability. The
  77 following information also appears in a corresponding section of <A HREF="auagd018.htm#HDRWQ491">Administering User Accounts</A>, but is repeated here for your convenience.
  78 <UL>
  79 <P><LI>A <I>Protection Database entry</I> defines the username (the name
  80 provided when authenticating with AFS), and maps it to an AFS user ID (AFS
  81 UID), a number that the AFS servers use internally when referencing
  82 users. The Protection Database also tracks the groups to which the user
  83 belongs. For details, see <A HREF="auagd019.htm#HDRWQ531">Administering the Protection Database</A>.
  84 <P><LI>An <I>Authentication Database entry</I> records the user's AFS
  85 password in a scrambled form suitable for use as an encryption key.
  86 <P><LI>A home <I>volume</I> stores all the files in the user's home
  87 directory together on a single partition of a file server machine. The
  88 volume has an associated <VAR>quota</VAR> that limits its size. For a
  89 complete discussion of volumes, see <A HREF="auagd010.htm#HDRWQ174">Managing Volumes</A>.
  90 <P><LI>A <I>mount point</I> makes the contents of the user's volume
  91 visible and accessible in the AFS filespace, and acts as the user's home
  92 directory. For more details about mount points, see <A HREF="auagd010.htm#HDRWQ183">About Mounting Volumes</A>.
  93 <P><LI>Full access permissions on the home directory's <I>access control
  94 list (ACL)</I> and ownership of the directory (as displayed by the UNIX
  95 <B>ls -ld</B> command) enable the user to manage his or her files.
  96 For details on AFS file protection, see <A HREF="auagd020.htm#HDRWQ562">Managing Access Control Lists</A>.
  97 <P><LI>A <I>local password file entry</I> (in the <B>/etc/passwd</B> file
  98 or equivalent) of each AFS client machine enables the user to log in and
  99 access AFS files through the Cache Manager. A subsequent section in
 100 this chapter further discusses local password file entries.
 101 <P><LI>Other optional <I>configuration files</I> make the account more
 102 convenient to use. Such files help the user log in and log out more
 103 easily, receive electronic mail, print, and so on.
 104 </UL>
 105 <A NAME="IDX7586"></A>
 106 <A NAME="IDX7587"></A>
 107 <P><H3><A NAME="HDRWQ453" HREF="auagd002.htm#ToC_539">Privilege Requirements for the uss Commands</A></H3>
 108 <P>To issue <B>uss</B> commands successfully, you usually
 109 need all of the standard AFS administrative privileges: membership in
 110 the <B>system:administrators</B> group, inclusion in the
 111 <B>/usr/afs/etc/UserList</B> file on every relevant server machine, and
 112 the <TT>ADMIN</TT> flag on your Authentication Database entry. For
 113 details on administrative privilege, see <A HREF="auagd021.htm#HDRWQ581">Managing Administrative Privilege</A>.
 114 <A NAME="IDX7588"></A>
 115 <A NAME="IDX7589"></A>
 116 <A NAME="IDX7590"></A>
 117 <A NAME="IDX7591"></A>
 118 <A NAME="IDX7592"></A>
 119 <A NAME="IDX7593"></A>
 120 <A NAME="IDX7594"></A>
 121 <P><H3><A NAME="HDRWQ454" HREF="auagd002.htm#ToC_540">Avoiding and Recovering from Errors and Interrupted Operations</A></H3>
 122 <P>As for any complex operation, there are a number of possible
 123 reasons that an account-creation or deletion operation can halt before it
 124 completes. You can easily avoid several of the common reasons by making
 125 the following checks before issuing a <B>uss</B> command:
 126 <UL>
 127 <P><LI>Verify that you have all of the administrative privileges you need to
 128 complete an operation, as described in <A HREF="#HDRWQ453">Privilege Requirements for the uss Commands</A>. The instructions for using the <B>uss add</B>,
 129 <B>uss delete</B>, and <B>uss bulk</B> commands include this check as
 130 a step.
 131 <P><LI>Proofread the template and bulk input files for correct syntax and
 132 acceptable values. For discussion, see <A HREF="#HDRWQ463">Constructing a uss Template File</A> and <A HREF="#HDRWQ489">Constructing a Bulk Input File</A>.
 133 <P><LI>Do not issue <B>uss</B> commands when you are aware of network, server
 134 machine, or server process outages. Because <B>uss</B> operations
 135 affect so many components of AFS, it is unlikely that the command can succeed
 136 when there are outages.
 137 </UL>
 138 <P>Another way to avoid errors that halt an operation is to preview the
 139 <B>uss</B> command by combining the <B>-dryrun</B> flag with the other
 140 arguments to be used on the actual command. The <B>uss</B> command
 141 interpreter generates a screen trace of the actions to be performed by the
 142 actual command, without performing them.
 143 <P>Using the <B>-dryrun</B> flag reveals many basic errors that can halt
 144 an operation, particularly the ones due to incorrect syntax in the command
 145 line, template file, or bulk input file. It does not catch all possible
 146 errors, however, because the command interpreter is not actually attempting to
 147 perform the actions it is tracing. For example, a Volume Server outage
 148 does not necessarily halt the volume creation step when the <B>-dryrun</B>
 149 flag is included, because the command interpreter is not actually contacting
 150 the server; such an outage halts the actual creation operation.
 151 <A NAME="IDX7595"></A>
 152 <A NAME="IDX7596"></A>
 153 <A NAME="IDX7597"></A>
 154 <P>When the <B>uss</B> command interpreter encounters error conditions
 155 minor enough that they do not require halting the operation, it usually
 156 generates a message that begins with the string <TT>uss:
 157 Warning:</TT> and describes the action it is taking to avoid
 158 halting. For example, if a user's Protection Database entry
 159 already exists, the following message appears on the standard output
 160 stream:
 161 <PRE>   uss: Warning: User '<VAR>user</VAR>' already in the protection database
 162    The uid for user '<VAR>user</VAR>' is <VAR>AFS UID</VAR>
 163 </PRE>
 164 <P>If an error is more serious, the word <TT>Warning</TT> does not appear in
 165 the message, which instead describes why the command interpreter cannot
 166 perform the requested action. Not all of these errors cause the
 167 <B>uss</B> operation to halt, but they still require you to take
 168 corrective action. For example, attempting to create a mount point
 169 fails if you lack the necessary permissions on the parent directory's
 170 ACL, or if the mount point pathname in the <B>V</B> instruction's
 171 <VAR>mount_point</VAR> field is malformed. However, this error does not
 172 cause the creation operation to halt until later instructions in the template
 173 attempt to install subdirectories or files under the nonexistent mount
 174 point.
 175 <P>If the command shell prompts returns directly after an error message, then
 176 the error generally was serious enough to halt the operation. When an
 177 error halts account creation or deletion, the best way to recover is to find
 178 and fix the cause, and then reissue the same <B>uss</B> command.
 179 <A NAME="IDX7598"></A>
 180 <A NAME="IDX7599"></A>
 181 <A NAME="IDX7600"></A>
 182 <A NAME="IDX7601"></A>
 183 <A NAME="IDX7602"></A>
 184 <A NAME="IDX7603"></A>
 185 <P>The following list describes what happens when components of a user's
 186 account already exist when you reissue an account-creation command (the
 187 <B>uss add</B> command, or the <B>uss bulk</B> command when the bulk
 188 input file contains <B>add</B> instructions):
 189 <UL>
 190 <P><LI>If the Protection Database entry already exists, a message confirms its
 191 existence and specifies the associated AFS UID.
 192 <P><LI>If the Authentication Database entry already exists, a message confirms
 193 its existence.
 194 <P><LI>If the volume and associated Volume Location Database (VLDB) entry already
 195 exist, a message confirms their existence. However, the <B>uss</B>
 196 command interpreter does alter the volume's quota, mount point, or ACL if
 197 any of the relevant fields in the template <B>V</B> instruction have
 198 changed since the command last ran. If the value in the
 199 <VAR>mount_point</VAR> field has changed, the command interpreter creates the
 200 new mount point but does not remove any existing mount points.
 201 <P><LI>If any of the fields in the template <B>A</B> instruction have
 202 changed, the <B>uss</B> command interpreter makes the changes without
 203 comment.
 204 <P><LI>If a directory, file, or link defined by a template file <B>D</B>,
 205 <B>E</B>, <B>F</B>, <B>L</B>, or <B>S</B> instruction already
 206 exists, the <B>uss</B> command interpreter replaces the existing element
 207 with one that conforms to the template definition. To control whether
 208 the <B>uss</B> command interpreter prompts for confirmation that you wish
 209 to overwrite a given element, use the <B>-overwrite</B> flag to the
 210 <B>uss add</B> or <B>uss bulk</B> command:
 211 <UL>
 212 <P><LI>If you include the <B>-overwrite</B> flag, the command interpreter
 213 automatically overwrites all elements without asking for confirmation.
 214 <P><LI>If you omit the flag, the command interpreter prompts once for each
 215 account to ask if you want to overwrite all elements associated with
 216 it.
 217 </UL>
 218 <P><LI>The command interpreter always reexecutes <B>X</B> instructions in the
 219 template file. If a command's result already holds, reissuing it
 220 has the same effect as reissuing it outside the context of the <B>uss</B>
 221 commands.
 222 </UL>
 223 <P>The following describes what happens when a <B>uss delete</B> command
 224 references account components that have already been deleted.
 225 <UL>
 226 <P><LI>If the volume and VLDB entry no longer exist, a message confirms their
 227 absence.
 228 <P><LI>If the Authentication Database entry no longer exists, a message confirms
 229 its absence.
 230 </UL>
 231 <A NAME="IDX7604"></A>
 232 <HR><H2><A NAME="HDRWQ455" HREF="auagd002.htm#ToC_541">Creating Local Password File Entries with uss</A></H2>
 233 <P>To obtain authenticated access to a cell's AFS
 234 filespace, a user must not only have a valid AFS token, but also an entry in
 235 the local password file (<B>/etc/passwd</B> or equivalent) of the AFS
 236 client machine. This section discusses why it is important for the
 237 user's AFS UID to match to the UNIX UID listed in the local password
 238 file, the appropriate value to put in the file's password field, and
 239 outlines a method for creating a single source password file.
 240 <P>For instructions on using the template file's <B>E</B> instruction
 241 to generate local password file entries automatically as part of account
 242 creation, see <A HREF="#HDRWQ458">Creating a Common Source Password File</A>.
 243 <P>The following information also appears in a corresponding section of <A HREF="auagd018.htm#HDRWQ491">Administering User Accounts</A>, but is repeated here for your convenience.
 244 <A NAME="IDX7605"></A>
 245 <A NAME="IDX7606"></A>
 246 <A NAME="IDX7607"></A>
 247 <A NAME="IDX7608"></A>
 248 <A NAME="IDX7609"></A>
 249 <P><H3><A NAME="HDRWQ456" HREF="auagd002.htm#ToC_542">Assigning AFS and UNIX UIDs that Match</A></H3>
 250 <P>A user account is easiest to administer and use if the AFS
 251 user ID number (AFS UID) and UNIX UID match. All instructions in the
 252 AFS documentation assume that they do.
 253 <P>The most basic reason to make AFS and UNIX UIDs the same is so that the
 254 owner name reported by the UNIX <B>ls -l</B> and <B>ls -ld</B>
 255 commands makes sense for AFS files and directories. Following standard
 256 UNIX practice, the File Server records a number rather than a username in an
 257 AFS file or directory's owner field: the owner's AFS
 258 UID. When you issue the <B>ls -l</B> command, it translates the UID
 259 to a username according to the mapping in the local password file, not the AFS
 260 Protection Database. If the AFS and UNIX UIDs do not match, the <B>ls
 261 -l</B> command reports an unexpected (and incorrect) owner. The
 262 output can even vary on different client machines if their local password
 263 files map the same UNIX UID to different names.
 264 <P>Follow the recommendations in the indicated sections to make AFS and UNIX
 265 UIDs match when you are creating accounts for various types of users:
 266 <UL>
 267 <P><LI>If creating an AFS account for a user who already has a UNIX UID, see <A HREF="#HDRWQ459">Converting Existing UNIX Accounts with uss</A>.
 268 <P><LI>If some users in your cell have existing UNIX accounts but the user for
 269 whom you are creating an AFS account does not, then it is best to allow the
 270 Protection Server to allocate an AFS UID automatically. To avoid
 271 overlap of AFS UIDs with existing UNIX UIDs, set the Protection
 272 Database's <TT>max user id</TT> counter higher than the largest UNIX
 273 UID, using the instructions in <A HREF="auagd019.htm#HDRWQ560">Displaying and Setting the AFS UID and GID Counters</A>.
 274 <P><LI>If none of your users have existing UNIX accounts, allow the Protection
 275 Server to allocate AFS UIDs automatically, starting either at its default or
 276 at the value you have set for the <TT>max user id</TT> counter.
 277 </UL>
 278 <A NAME="IDX7610"></A>
 279 <A NAME="IDX7611"></A>
 280 <P><H3><A NAME="HDRWQ457" HREF="auagd002.htm#ToC_543">Specifying Passwords in the Local Password File</A></H3>
 281 <P>Authenticating with AFS is easiest for your users if you
 282 install and configure an AFS-modified login utility, which logs a user into
 283 the local file system and obtains an AFS token in one step. In this
 284 case, the local password file no longer controls a user's ability to
 285 login in most circumstances, because the AFS-modified login utility does not
 286 consult the local password file if the user provides the correct AFS
 287 password. You can nonetheless use a password file entry's password
 288 field (usually, the second field) in the following ways to control login and
 289 authentication:
 290 <UL>
 291 <P><LI>To prevent both local login and AFS authentication, place an asterisk ( *
 292 ) in the field. This is useful mainly in emergencies, when you want to
 293 prevent a certain user from logging into the machine.
 294 <P><LI>To prevent login to the local file system if the user does not provide the
 295 correct AFS password, place a character string of any length other than the
 296 standard thirteen characters in the field. This is appropriate if you
 297 want to allow only people with local AFS accounts to log into to your
 298 machines. A single <B>X</B> or other character is the most easily
 299 recognizable way to do this.
 300 <P><LI>To enable a user to log into the local file system even after providing an
 301 incorrect AFS password, record a standard UNIX encrypted password in the field
 302 by issuing the standard UNIX password-setting command (<B>passwd</B> or
 303 equivalent).
 304 </UL>
 305 <P>If you do not use an AFS-modified login utility, you must place a standard
 306 UNIX password in the local password file of every client machine the user will
 307 use. The user logs into the local file system only, and then must issue
 308 the <B>klog</B> command to authenticate with AFS. It is simplest if
 309 the passwords in the local password file and the Authentication Database are
 310 the same, but this is not required.
 311 <A NAME="IDX7612"></A>
 312 <A NAME="IDX7613"></A>
 313 <A NAME="IDX7614"></A>
 314 <A NAME="IDX7615"></A>
 315 <A NAME="IDX7616"></A>
 316 <P><H3><A NAME="HDRWQ458" HREF="auagd002.htm#ToC_544">Creating a Common Source Password File</A></H3>
 317 <P>This section explains how to create a common source version
 318 of the local password file when using <B>uss</B> commands to create user
 319 accounts. The sequence of steps is as follows:
 320 <OL TYPE=1>
 321 <P><LI>Include an <B>E</B> instruction in the template file to create a
 322 one-line file that has the format of a local password file entry.
 323 <P><LI>Incorporate the one-line file into the common source version of the local
 324 password file. It makes sense to store this file in AFS. See the
 325 following two example scripts for automating this step.
 326 <P><LI>Distribute the common password file to each client machine, perhaps by
 327 using the AFS <B>package</B> utility as described in <A HREF="auagd016.htm#HDRWQ419">Configuring Client Machines with the package Program</A>.
 328 </OL>
 329 <P>As an example, the template file used by the ABC Corporation includes the
 330 following <B>E</B> instruction to create a file called
 331 <B>passwd_</B><VAR>username</VAR> in the directory
 332 <B>/afs/.abc.com/common/etc/newaccts</B> (the entire
 333 contents of the template file appear in <A HREF="#HDRWQ471">Example uss Templates</A> and a full description of the <B>E</B> instruction
 334 appears in <A HREF="#HDRWQ476">Creating One-Line Files with the E Instruction</A>):
 335 <PRE>   E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root \
 336         "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
 337 </PRE>
 338 <P>For the user Joe L. Smith with username <B>smith</B>, this
 339 instruction creates a file called <B>passwd_smith</B> which contains the
 340 following line:
 341 <PRE>   smith:X:1205:11:Joe L. Smith:/afs/abc.com/usr/usr1/smith:/bin/csh
 342 </PRE>
 343 <P>A shell script is probably the easiest way to incorporate a set of files
 344 created in this manner into a common source password file, and two sample
 345 shell scripts appear here. To automate the process even further, you
 346 can create a <B>cron</B> process in a file server machine's
 347 <B>/usr/afs/local/BosConfig</B> directory to execute the shell script,
 348 perhaps each day at a given time; for details, see <A HREF="auagd009.htm#HDRWQ162">To create and start a new process</A>.
 349 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">The following example scripts are suggestions only. If you choose to
 350 use them, or to model similar scripts on them, you must test that your script
 351 has the desired result, preferably in a test environment.
 352 </TD></TR></TABLE>
 353 <P><B>Example C Shell Script</B>
 354 <P>The first example is a simple C shell script suitable for the ABC
 355 Corporation cell. It incorporates the individual files found in the
 356 <B>/afs/.abc.com/common/uss/newaccts</B> directory into a
 357 new version of the global password file found in the
 358 <B>/afs/.abc.com/common/etc</B> directory, sorting the files
 359 into alphabetical order. It takes care to save the current version with
 360 a <B>.old</B> extension, then removes the individual files when
 361 done.
 362 <PRE>   set  dir = /afs/.abc.com/common
 363    cat  $dir/uss/newaccts/passwd_* $dir/etc/passwd  >!  $dir/etc/passwd.new
 364    mv  $dir/etc/passwd  $dir/etc/passwd.old
 365    sort  $dir/etc/passwd.new  >  $dir/etc/passwd
 366    rm  $dir/etc/passwd.new  $dir/uss/newaccts/passwd_*
 367 </PRE>
 368 <P><B>Example Bourne Shell Script</B>
 369 <P>The second, more elaborate, example is a Bourne shell script that first
 370 verifies that there are new <B>passwd_</B><VAR>username</VAR> files to be
 371 incorporated into the global password file. While running, it checks
 372 that each new entry does not already exist. Like the shorter C shell
 373 example, it incorporates the individual files found in the
 374 <B>/afs/.abc.com/common/uss/newaccts</B> directory into a
 375 new version of the global <B>passwd</B> file found in the
 376 <B>/afs/.abc.com/common/etc</B> directory.
 377 <PRE>   #!/bin/sh
 378    DESTDIR=/afs/.abc.com/common/uss/newaccts
 379    cd  $DESTDIR
 380    DEST=/afs/.abc.com/common/etc
 381    cp /afs/.abc.com/common/etc/passwd   /afs/.abc.com/common/uss/newaccts/passwd
 382    echo "copied in passwd file."
 383    PASSWD=/afs/.abc.com/common/uss/newaccts/passwd
 384    ENTRIES=`ls passwd_*`
 385    case $ENTRIES in
 386    "")
 387         echo No new entry found to be added to passwd file
 388         ;;
 389    *)
 390         echo  "Adding new users to passwd file."
 391         for  i  in  $ENTRIES
 392         do
 393            cat  $i  |  awk  -F:  '{print $1  >  "foo"}'
 394            USER=`cat foo`
 395            case  `egrep  -e  \^$USER\: $PASSWD` in
 396            "")
 397                    echo  adding  $USER
 398                    cat  $i  >>  $PASSWD
 399                    ;;
 400            *)
 401                    echo  $USER already in passwd file
 402                    ;;
 403            esac
 404            mv  $i  ../old.passdir/done_${i}
 405         done
 406         cd  /afs/.abc.com/common/uss/newaccts
 407         echo  "sorting password file"
 408         sort  ${PASSWD}  >  ${PASSWD}.sorted
 409         echo  "installing files"
 410         install  ${PASSWD}.sorted ${DEST}/passwd
 411         echo  "Password file is built, sorted and installed."
 412         ;;
 413    esac
 414 </PRE>
 415 <A NAME="IDX7617"></A>
 416 <A NAME="IDX7618"></A>
 417 <A NAME="IDX7619"></A>
 418 <HR><H2><A NAME="HDRWQ459" HREF="auagd002.htm#ToC_545">Converting Existing UNIX Accounts with uss</A></H2>
 419 <P>This section discusses the three main issues you need to
 420 consider if there are existing UNIX accounts to be converted to AFS
 421 accounts.
 422 <P><H3><A NAME="HDRWQ460" HREF="auagd002.htm#ToC_546">Making UNIX and AFS UIDs Match</A></H3>
 423 <P>As previously mentioned, AFS users must have an entry in the
 424 local password file on every client machine from which they access the AFS
 425 filespace as an authenticated user. Both administration and use are
 426 much simpler if the UNIX UID and AFS UID match. When converting
 427 existing UNIX accounts, you have two alternatives:
 428 <UL>
 429 <P><LI>Make the AFS UIDs match the existing UNIX UIDs. In this case, you
 430 need to assign the AFS UID yourself as you create an AFS account:
 431 <UL>
 432 <P><LI>If using the <B>uss add</B> command, include the <B>-uid</B>
 433 argument.
 434 <P><LI>If using the <B>uss bulk</B> command, specify the desired UID in the
 435 <VAR>uid</VAR> field of the <B>add</B> instruction in the bulk input
 436 file.
 437 </UL>
 438 <P>Because you are retaining the user's UNIX UID, you do not need to
 439 alter the UID in the local password file entry. However, if you are
 440 using an AFS-modified login utility, you possibly need to change the password
 441 field in the entry. For a discussion of how the value in the password
 442 field affects login with an AFS-modified login utility, see <A HREF="#HDRWQ455">Creating Local Password File Entries with uss</A>.
 443 <P>If now or in the future you need to create AFS accounts for users who do
 444 not have an existing UNIX UID, then you must guarantee that new AFS UIDs do
 445 not conflict with any existing UNIX UIDs. The simplest way is to set
 446 the <TT>max user id</TT> counter in the Protection Database to a value
 447 higher than the largest existing UNIX UID. See <A HREF="auagd019.htm#HDRWQ560">Displaying and Setting the AFS UID and GID Counters</A>.
 448 <P><LI>Change the existing UNIX UIDs to match the new AFS UIDs that the
 449 Protection Server assigns automatically.
 450 <P>Allow the Protection Server to allocate the AFS UIDs automatically as you
 451 create AFS accounts. For instructions on creating a new entry for the
 452 local password file during account creation, see <A HREF="#HDRWQ455">Creating Local Password File Entries with uss</A>.
 453 <P>There is one drawback to changing the UNIX UID: any files and
 454 directories that the user owned in the local file system before becoming an
 455 AFS user still have the former UID in their owner field. If you want
 456 the <B>ls -l</B> and <B>ls -ld</B> commands to display the correct
 457 owner, you must use the <B>chown</B> command to change the value to the
 458 user's new UID, whether you are leaving the file in the local file system
 459 or moving it to AFS. See <A HREF="#HDRWQ462">Moving Local Files into AFS</A>.
 460 </UL>
 461 <P><H3><A NAME="HDRWQ461" HREF="auagd002.htm#ToC_547">Setting the Password Field Appropriately</A></H3>
 462 <P>Existing UNIX accounts already have an entry in the local
 463 password file, probably with a (scrambled) password in the password
 464 field. You possibly need to change the value in the field, depending on
 465 the type of login utility you use:
 466 <UL>
 467 <P><LI>If the login utility is not modified for use with AFS, the actual password
 468 must appear (in scrambled form) in the password field of the local password
 469 file entry.
 470 <P><LI>If the login utility is modified for use with AFS, choose one of the
 471 acceptable values, each of which affects the login utility's behavior
 472 differently. See <A HREF="#HDRWQ455">Creating Local Password File Entries with uss</A>.
 473 </UL>
 474 <P>If you choose to place an actual password in a local password file entry,
 475 then you can define a dummy password when you use a template file <B>E</B>
 476 instruction to create the entry, as described in <A HREF="#HDRWQ476">Creating One-Line Files with the E Instruction</A>. Have the user issue the UNIX password-setting
 477 command (<B>passwd</B> or equivalent) to replace the dummy with an actual
 478 secret password.
 479 <P><H3><A NAME="HDRWQ462" HREF="auagd002.htm#ToC_548">Moving Local Files into AFS</A></H3>
 480 <P>New AFS users with existing UNIX accounts probably already
 481 own files and directories stored in a machine's local file system, and it
 482 usually makes sense to transfer them into the new home volume. The
 483 easiest method is to move them onto the local disk of an AFS client machine,
 484 and then use the UNIX <B>mv</B> command to transfer them into the
 485 user's new AFS home directory.
 486 <P>As you move files and directories into AFS, keep in mind that the meaning
 487 of their mode bits changes. AFS ignores the second and third sets of
 488 mode bits (group and other), and does not use the first set (the owner bits)
 489 directly, but only in conjunction with entries on the ACL (for details, see <A HREF="auagd020.htm#HDRWQ580">How AFS Interprets the UNIX Mode Bits</A>). Be sure that the ACL protects the file or directory
 490 at least as securely as the mode bits.
 491 <P>If you have chosen to change a user's UNIX UID to match a new AFS UID,
 492 you must change the ownership of UNIX files and directories as well.
 493 Only members of the <B>system:administrators</B> group can issue the
 494 <B>chown</B> command on files and directories once they reside in
 495 AFS.
 496 <A NAME="IDX7620"></A>
 497 <A NAME="IDX7621"></A>
 498 <A NAME="IDX7622"></A>
 499 <HR><H2><A NAME="HDRWQ463" HREF="auagd002.htm#ToC_549">Constructing a uss Template File</A></H2>
 500 <P>Creating user accounts with <B>uss</B> commands is
 501 generally more convenient than using individual commands. You control
 502 the account creation process just as closely, but the <B>uss</B> template
 503 file enables you to predefine many aspects of account configuration.
 504 Because you construct the template before issuing <B>uss</B> commands, you
 505 have time to consider configuration details carefully and correct syntax
 506 errors. The following list summarizes some further advantages of using
 507 a template:
 508 <UL>
 509 <P><LI>You do not have to remember the correct order in which to create or delete
 510 account components, or the order of each command's arguments, which
 511 reduces the likelihood of errors.
 512 <P><LI>You do not have to type the same information multiple times.
 513 Instead, you can place constants and variables in the template file that
 514 enable you to type as little on the command line as possible. See <A HREF="#HDRWQ465">Using Constants and Variables in the Template File</A>.
 515 <P><LI>You can create different templates for different types of users.
 516 Instead of having to remember which components differ for a given user,
 517 specify the appropriate template when issuing the <B>uss add</B> or
 518 <B>uss bulk</B> command.
 519 <P><LI>You can create any of the three types of AFS account (authentication-only,
 520 basic, or full) by including or omitting certain information in the template,
 521 as described in <A HREF="#HDRWQ464">Creating the Three Types of User Accounts</A>.
 522 </UL>
 523 <P>The following list briefly describes the instructions that can appear in a
 524 template file and points you to a later section for more details. It
 525 lists them in the order that is usually optimal for correct handling of
 526 dependencies between the different types of instruction.
 527 <DL>
 528 <P><DT><B><B>G</B>
 529 </B><DD>Defines a directory that is one of a set of parent directories into which
 530 the <B>uss</B> command interpreter evenly distributes newly created home
 531 directories. Place the corresponding template file variable, $AUTO, in
 532 the <VAR>mount_point</VAR> field of the <B>V</B> instruction. See <A HREF="#HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</A> and <A HREF="#HDRWQ473">Creating a Volume with the V Instruction</A>.
 533 <P><DT><B><B>V</B>
 534 </B><DD>Creates a volume, mounts it as the user's home directory at a
 535 specified location in the AFS filespace, sets the volume's quota, and
 536 defines the owner and ACL for the directory. This instruction must
 537 appear in any template that is not empty (zero-length). See <A HREF="#HDRWQ473">Creating a Volume with the V Instruction</A>.
 538 <P><DT><B><B>D</B>
 539 </B><DD>Creates a directory, generally a subdirectory of the new home directory,
 540 and sets its mode bits, owner, and ACL. See <A HREF="#HDRWQ474">Creating a Directory with the D Instruction</A>.
 541 <P><DT><B><B>F</B>
 542 </B><DD>Creates a file by copying a prototype and sets its mode bits and
 543 owner. See <A HREF="#HDRWQ475">Creating a File from a Prototype with the F Instruction</A>.
 544 <P><DT><B><B>E</B>
 545 </B><DD>Creates a single-line file by copying in the contents of the instruction
 546 itself, then sets the file's mode bits and owner. See <A HREF="#HDRWQ476">Creating One-Line Files with the E Instruction</A>.
 547 <P><DT><B><B>L</B>
 548 </B><DD>Creates a hard link. See <A HREF="#HDRWQ477">Creating Links with the L and S Instructions</A>.
 549 <P><DT><B><B>S</B>
 550 </B><DD>Creates a symbolic link. See <A HREF="#HDRWQ477">Creating Links with the L and S Instructions</A>.
 551 <P><DT><B><B>A</B>
 552 </B><DD>Improves account security by imposing restrictions on passwords and
 553 authentication attempts. See <A HREF="#HDRWQ478">Increasing Account Security with the A Instruction</A>.
 554 <P><DT><B><B>X</B>
 555 </B><DD>Executes a command. See <A HREF="#HDRWQ479">Executing Commands with the X Instruction</A>.
 556 </DL>
 557 <A NAME="IDX7623"></A>
 558 <A NAME="IDX7624"></A>
 559 <A NAME="IDX7625"></A>
 560 <P><H3><A NAME="HDRWQ464" HREF="auagd002.htm#ToC_550">Creating the Three Types of User Accounts</A></H3>
 561 <P>Using the <B>uss add</B> and <B>uss bulk</B>
 562 commands, you can create three types of accounts that differ in their levels
 563 of functionality. For a description of the types, see <A HREF="auagd007.htm#HDRWQ57">Configuring AFS User Accounts</A>. The following list explains how to construct a
 564 template for each type:
 565 <UL>
 566 <P><LI>To create an authentication-only account, create an empty (zero-length)
 567 template file. Such an account has only two components: entries
 568 in the Authentication Database and Protection Database.
 569 <P><LI>To create a basic account, include a <B>V</B> instruction, and
 570 <B>G</B> instructions if you want to distribute home directories evenly as
 571 described in <A HREF="#HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</A>. In addition to Authentication Database and
 572 Protection Database entries, this type of account includes a volume mounted at
 573 the home directory with owner and ACL set appropriately.
 574 <P><LI>To create a full account, include <B>D</B>, <B>E</B>,
 575 <B>F</B>, <B>L</B>, and <B>S</B> instructions as appropriate, in
 576 addition to the <B>V</B> and <B>G</B> instructions. This type
 577 of account includes configuration files for basic functions such as logging
 578 in, printing, and mail delivery. For a discussion of some useful types
 579 of configuration files, see <A HREF="auagd007.htm#HDRWQ60">Creating Standard Files in New AFS Accounts</A>.
 580 </UL>
 581 <A NAME="IDX7626"></A>
 582 <A NAME="IDX7627"></A>
 583 <A NAME="IDX7628"></A>
 584 <A NAME="IDX7629"></A>
 585 <P><H3><A NAME="HDRWQ465" HREF="auagd002.htm#ToC_551">Using Constants and Variables in the Template File</A></H3>
 586 <P>Each instruction in the <B>uss</B> template file has
 587 several fields that define the characteristics of the element that it
 588 creates. The <B>D</B> instruction's fields, for instance,
 589 define a directory's pathname, owner, mode bits, and ACL.
 590 <P>You can place three types of values in a field: a variable, a
 591 constant, or a combination of the two. The appropriate value depends on
 592 the desired configuration, and determines which arguments you provide to the
 593 <B>uss add</B> command or which fields you include in a bulk input file
 594 <B>add</B> instruction.
 595 <P>If an aspect of account configuration is the same for every user, define a
 596 constant value in the appropriate field by inserting a character
 597 string. For example, to assign a space quota of 10,000 KB to every user
 598 volume, place the string <B>10000</B> in the <B>V</B>
 599 instruction's <VAR>quota</VAR> field.
 600 <P>If, on the other hand, an aspect of account configuration varies for each
 601 user, put a variable in the appropriate field. When creating each
 602 account, provide a value for the variable by providing either the
 603 corresponding argument to the <B>uss add</B> command or a value in the
 604 corresponding field of the <B>add</B> instruction in the bulk input
 605 file.
 606 <P>The <B>uss</B> command suite defines a set of template variables, each
 607 of which has a corresponding source for its value, as summarized in <A HREF="#TBLWQ466">Table 3</A>. For a discussion of their intended uses, see the
 608 following sections about each template instruction (<A HREF="#HDRWQ473">Creating a Volume with the V Instruction</A> through <A HREF="#HDRWQ479">Executing Commands with the X Instruction</A>).
 609 <BR>
 610 <P><B><A NAME="TBLWQ466" HREF="auagd004.htm#FT_TBLWQ466">Table 3. Source for values of uss template variables</A></B><BR>
 611 <TABLE WIDTH="100%" BORDER>
 612 <TR>
 613 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>Variable</B>
 614 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>Source for value</B>
 615 </TD></TR><TR>
 616 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$AUTO
 617 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">Previous <B>G</B> instructions in template
 618 </TD></TR><TR>
 619 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$MTPT
 620 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-mount</B> argument to <B>uss add</B> command or
 621 <VAR>mount_point</VAR> field of bulk input file <B>add</B> instruction, when
 622 in <B>V</B> instruction; <B>V</B> instruction's
 623 <VAR>mount_point</VAR> field when in subsequent instructions
 624 </TD></TR><TR>
 625 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$NAME
 626 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-realname</B> argument to <B>uss add</B> command or
 627 <VAR>mount_point</VAR> field of bulk input file <B>add</B> instruction, if
 628 provided; otherwise, <B>-user</B> argument to <B>uss add</B>
 629 command or <VAR>username</VAR> field of in bulk input file <B>add</B>
 630 instruction
 631 </TD></TR><TR>
 632 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$PART
 633 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-partition</B> argument to <B>uss add</B> command or
 634 <VAR>partition</VAR> field of bulk input file <B>add</B> instruction
 635 </TD></TR><TR>
 636 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$PWEXPIRES
 637 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-pwexpires</B> argument to <B>uss add</B> command or
 638 <VAR>password_expires</VAR> field of bulk input file <B>add</B> instruction
 639 </TD></TR><TR>
 640 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$SERVER
 641 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-server</B> argument to <B>uss add</B> command or
 642 <VAR>file_server</VAR> field of bulk input file <B>add</B> instruction
 643 </TD></TR><TR>
 644 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$UID
 645 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-uid</B> argument to <B>uss add</B> command or <VAR>uid</VAR>
 646 field of bulk input file <B>add</B> instruction, if provided;
 647 otherwise, allocated automatically by Protection Server
 648 </TD></TR><TR>
 649 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$USER
 650 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-user</B> argument to <B>uss add</B> command or
 651 <VAR>username</VAR> field of bulk input file <B>add</B> instruction
 652 </TD></TR><TR>
 653 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$1 through $9
 654 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-var</B> argument to <B>uss add</B> command or <VAR>var1</VAR>
 655 through <VAR>var9</VAR> fields of bulk input file <B>add</B> instruction
 656 </TD></TR></TABLE>
 657 <P>A common use of variables is to define the file server machine and
 658 partition that house the user's volume, which often vary from user to
 659 user. Place the $SERVER variable in the <B>V</B> instruction's
 660 <VAR>server</VAR> field, and the $PART variable in its <VAR>partition</VAR>
 661 field. If using the <B>uss add</B> command, provide the desired
 662 value with the <B>-server</B> and <B>-partition</B> arguments.
 663 If using the <B>uss bulk</B> command, provide the desired values in the
 664 <VAR>file_server</VAR> and <VAR>partition</VAR> fields of each user's
 665 <B>add</B> instruction in the bulk input file.
 666 <A NAME="IDX7630"></A>
 667 <A NAME="IDX7631"></A>
 668 <P>The variables $1 through $9 can be used to customize other aspects of the
 669 account. Provide a value for these variables with the <B>-var</B>
 670 argument to the <B>uss add</B> command or in the appropriate field of the
 671 bulk input file <B>add</B> instruction. The <B>-var</B>
 672 argument is unusual in that each instance for it has two parts: the
 673 number index and the value, separated by a space. For examples of the
 674 use of a number variable, see the discussions of the <VAR>mount_point</VAR> and
 675 <VAR>quota</VAR> fields in <A HREF="#HDRWQ473">Creating a Volume with the V Instruction</A>.
 676 <P>If some aspect of account configuration is partly constant and partly
 677 variable, you can combine variables and constants in an instruction
 678 field. For example, suppose that the ABC Corporation mounts user
 679 volumes in the <B>/afs/abc.com/usr</B> directory. That part
 680 of the pathname is constant, but the name of the mount point and home
 681 directory is the user's username, which corresponds to the $USER
 682 variable. To configure accounts in this way, combine a constant string
 683 and a variable in the <B>V</B> instruction's <VAR>mount_point</VAR>
 684 field as follows:
 685 <PRE>   /afs/abc.com/usr/$USER
 686 </PRE>
 687 <P>Then provide the value for the $USER variable with the <B>-user</B>
 688 argument to the <B>uss add</B> command, or in the <VAR>username</VAR> field
 689 of each user's <B>add</B> instruction in the bulk input file.
 690 <A NAME="IDX7632"></A>
 691 <A NAME="IDX7633"></A>
 692 <P><H3><A NAME="HDRWQ468" HREF="auagd002.htm#ToC_552">Where to Place Template Files</A></H3>
 693 <P>A template must be available to the <B>uss</B> command
 694 interpreter as it executes a <B>uss add</B> or <B>uss bulk</B>
 695 command, even if it is the zero-length file appropriate for creating an
 696 authentication-only account.
 697 <P>If you do not provide the <B>-template</B> argument to the <B>uss
 698 add</B> or <B>uss bulk</B> command, then the command interpreter
 699 searches for a template file called <B>uss.template</B> in each of
 700 the following directories in turn:
 701 <OL TYPE=1>
 702 <P><LI>The current working directory
 703 <P><LI><B>/afs/<VAR>cellname</VAR>/common/uss</B>, where <VAR>cellname</VAR> is
 704 the local cell
 705 <P><LI><B>/etc</B>
 706 </OL>
 707 <P>To use a template file with a different name or stored in a different
 708 directory, include the <B>-template</B> argument to the <B>uss add</B>
 709 or <B>uss bulk</B> command. If you provide a filename only, the
 710 command interpreter looks for it in the directories listed just
 711 previously. If you provide a pathname and filename, it looks only in
 712 the specified directory, interpreting a partial pathname relative to the
 713 current working directory.
 714 <A NAME="IDX7634"></A>
 715 <A NAME="IDX7635"></A>
 716 <P><H3><A NAME="HDRWQ469" HREF="auagd002.htm#ToC_553">Some General Rules for Constructing a Template</A></H3>
 717 <P>This section summarizes some general rules to follow when
 718 constructing a template file. For each instruction's syntax
 719 definition, see the following sections (<A HREF="#HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</A> through <A HREF="#HDRWQ479">Executing Commands with the X Instruction</A>).
 720 <UL>
 721 <P><LI>If a variable takes its value from an element elsewhere within the
 722 template, the definition must precede the reference. Putting the
 723 instruction lines in the following order usually results in correct resolution
 724 of variables:
 725 <P><B>G  V  D  F  E  L  S  A X</B>
 726 <P><LI>The fields in each instruction must appear in the order specified by the
 727 instruction's syntax definition, which appear in the following sections
 728 about each instruction. You cannot omit a field. Separate each
 729 field from its neighbors with one or more spaces.
 730 <P><LI>When specifying a pathname, provide a full one. Partial pathnames
 731 are interpreted relative to the current working directory (the one in which
 732 the <B>uss</B> command is issued), with possibly unintended
 733 results.
 734 <P><LI>Each instruction must appear on a single line in the template file, with a
 735 newline character (<B>&lt;Return></B>) only at the end of the
 736 instruction. Some example instructions appear in this document on more
 737 than one line, but that is only for legibility.
 738 <P><LI>Provide a value for every variable that appears in the template by
 739 including the corresponding argument to the <B>uss add</B> command or
 740 placing a value in the corresponding field of the bulk input file
 741 <B>add</B> instruction. A missing value halts the entire creation
 742 operation. If a variable does not appear in the template file, the
 743 command interpreter ignores the corresponding command-line argument or field
 744 in the bulk input file, even if you provide it.
 745 <P><LI>You can use blank lines in the template file to increase its
 746 legibility. If you place comments in the file, begin each comment line
 747 with the number sign (<B>#</B>).
 748 </UL>
 749 <P><H3><A NAME="HDRWQ470" HREF="auagd002.htm#ToC_554">About Creating Local Disk Directories and Files</A></H3>
 750 <P>It is possible to use the <B>D</B>, <B>E</B>, and
 751 <B>F</B> instructions to create directories or files in the local file
 752 system of the machine on which you are issuing the <B>uss</B> command, but
 753 that usage is not recommended. It introduces two potential
 754 complications:
 755 <UL>
 756 <P><LI>The local file system automatically assigns ownership of a new local disk
 757 directory or file to its creator. Because you are the issuer of the
 758 <B>uss</B> command that is creating the object, it records your current
 759 UNIX UID. If that is not appropriate and you want to designate another
 760 owner as the object is created, then you must be logged in as the local
 761 superuser <B>root</B> (the local file system allows only the
 762 <B>root</B> user to issue the UNIX <B>chown</B> command, which the
 763 <B>uss</B> command interpreter invokes to change the owner from the
 764 default value). You must also use the <B>-admin</B> argument to the
 765 <B>uss add</B> or <B>uss bulk</B> command to authenticate as a
 766 privileged AFS administrator. Only an administrator can create
 767 Authentication Database and Protection Database entries, which the
 768 <B>uss</B> command interpreter always creates as part of a new
 769 account.
 770 <P>The alternative is to become the local superuser <B>root</B> after the
 771 <B>uss</B> operation completes, and issue the necessary <B>chown</B>
 772 command then. However, that makes the account creation process that
 773 much less automated.
 774 <P><LI>Creating a local disk directory always generates an error message because
 775 the <B>uss</B> command interpreter cannot successfully set a local
 776 directory's ACL. The directory is created nevertheless, and a
 777 value still must appear in the <B>D</B> instruction's <VAR>ACL</VAR>
 778 field.
 779 </UL>
 780 <P>The recommended method for configuring a machine's local disk is to
 781 use the AFS <B>package</B> utility instead; see <A HREF="auagd016.htm#HDRWQ419">Configuring Client Machines with the package Program</A>.
 782 <A NAME="IDX7636"></A>
 783 <A NAME="IDX7637"></A>
 784 <P><H3><A NAME="HDRWQ471" HREF="auagd002.htm#ToC_555">Example uss Templates</A></H3>
 785 <P>This section describes example templates for the basic and
 786 full account types (the template for an authentication-only account is
 787 empty).
 788 <P>The first example creates a basic account. It contains two
 789 <B>G</B> instructions and a <B>V</B> instruction that defines the
 790 volume name, file server machine, partition, quota in kilobytes, mount point,
 791 home directory owner, and home directory access control list. In the
 792 ABC Corporation cell, a suitable template is:
 793 <PRE>   G /afs/.abc.com/usr1
 794    G /afs/.abc.com/usr2
 795    V  user.$USER  $SERVER.abc.com  /vicep$PART  5000  $AUTO/$USER   $UID  \
 796         $USER all staff rl
 797 </PRE>
 798 <P>When issuing the <B>uss add</B> command with this type of template,
 799 provide the following arguments:
 800 <UL>
 801 <P><LI><B>-user</B> to specify the username for the $USER variable
 802 <P><LI><B>-server</B> to specify the unique part of the file server machine
 803 name for the $SERVER variable
 804 <P><LI><B>-partition</B> to specify the unique part of the partition name for
 805 the $PART variable
 806 </UL>
 807 <P>The Protection Server automatically assigns an AFS UID for the $UID
 808 variable, and the <B>G</B> instructions provide a value for the $AUTO
 809 variable.
 810 <P>The following example template file creates a full account in the ABC
 811 Corporation cell. The following sections about each type of instruction
 812 describe the effect of the examples. Note that the <B>V</B> and
 813 <B>E</B> instructions appear on two lines each only for the sake of
 814 legibility.
 815 <PRE>   #
 816    # Specify the available grouping directories
 817    #
 818    G /afs/.abc.com/usr1
 819    G /afs/.abc.com/usr2
 820    #
 821    # Create the user's home volume
 822    #
 823    V user.$USER $SERVER.abc.com /vicep$PART 5000 /afs/.abc.com/$AUTO/$USER \
 824         $UID $USER all abc:staff rl
 825    #
 826    # Create directories and files for mail
 827    #
 828    D $MTPT/.MESSAGES 0700 $UID $USER all abc:staff none
 829    D $MTPT/.Outgoing 0700 $UID $USER rlidwk postman rlidwk
 830    D $MTPT/Mailbox 0700 $UID $USER all abc:staff none system:anyuser lik
 831    #
 832    # Here are some useful scripts for login etc.
 833    #
 834    F $MTPT/.Xbiff 0755 $UID /afs/abc.com/admin/user/proto
 835    F $MTPT/.Xresources 0644 $UID /afs/abc.com/admin/user/proto
 836    F $MTPT/.Xsession 0755 $UID /afs/abc.com/admin/user/proto
 837    F $MTPT/.cshrc 0755 $UID /afs/abc.com/admin/user/proto
 838    F $MTPT/.login 0755 $UID /afs/abc.com/admin/user/proto
 839    F $MTPT/.logout 0755 $UID /afs/abc.com/admin/user/proto
 840    F $MTPT/.twmrc 0644 $UID /afs/abc.com/admin/user/proto
 841    F $MTPT/preferences 0644 $UID /afs/abc.com/admin/user/proto
 842    #
 843    # Make a passwd entry
 844    #
 845    E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root \
 846         "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
 847    #
 848    # Put in the standard password/authentication checks
 849    #
 850    A $USER 250 noreuse 9 25
 851    #
 852    # Create and mount a public volume for the user
 853    #
 854    X "create_public_vol $USER $1 $2"
 855    #
 856    # Here we set up the symbolic link to public directory
 857    #
 858    S /afs/abc.com/public/$USER $MTPT/public
 859 </PRE>
 860 <A NAME="IDX7638"></A>
 861 <A NAME="IDX7639"></A>
 862 <A NAME="IDX7640"></A>
 863 <A NAME="IDX7641"></A>
 864 <A NAME="IDX7642"></A>
 865 <P><H3><A NAME="HDRWQ472" HREF="auagd002.htm#ToC_556">Evenly Distributing User Home Directories with the G Instruction</A></H3>
 866 <P>In cells with thousands of user accounts, it often makes
 867 sense to distribute the mount points for user volumes into multiple parent
 868 directories, because placing them all in one directory noticeably slows down
 869 directory lookup when a user home directory is accessed. A possible
 870 solution is to create parent directories that group user home directories
 871 alphabetically, or that reflect divisions like academic or corporate
 872 departments. However, in a really large cell, some such groups can
 873 still be large enough to slow directory lookup, and users who belong to those
 874 groups are unfairly penalized every time they access their home
 875 directory. Another drawback to groupings that reflect workplace
 876 divisions is that you must move mount points when users change departmental
 877 affiliation.
 878 <P>An alternative is an even distribution of user home directories into
 879 multiple parent directories that do not represent workplace divisions.
 880 The <B>uss</B> command suite enables you to define a list of directories
 881 by placing a <B>G</B> instruction for each one at the top of the template
 882 file, and then using the $AUTO variable in the <B>V</B> instruction's
 883 <VAR>mount_point</VAR> field. When the <B>uss</B> command interpreter
 884 encounters the $AUTO variable, it substitutes the directory named by a
 885 <B>G</B> instruction that currently has the fewest entries.
 886 (Actually, the $AUTO variable can appear in any field that includes a
 887 pathname, in any type of instruction. In all cases, the command
 888 interpreter substitutes the directory that currently has the fewest
 889 entries.)
 890 <P>The <B>G</B> instruction's syntax is as follows:
 891 <PRE>   G  <VAR>directory</VAR>
 892 </PRE>
 893 <P>where <VAR>directory</VAR> specifies either a complete directory pathname or
 894 only the final element (the directory itself). The choice determines
 895 the appropriate value to place in the <B>V</B> instruction's
 896 <VAR>mount_point</VAR> field.
 897 <P>Specify the read/write path to each directory, to avoid the failure that
 898 results when you attempt to create a new mount point in a read-only
 899 volume. By convention, you indicate the read/write path by placing a
 900 period before the cell name at the pathname's second level (for example,
 901 <B>/afs/.abc.com</B>). For further discussion of the
 902 concept of read/write and read-only paths through the filespace, see <A HREF="auagd010.htm#HDRWQ208">Mounting Volumes</A>.
 903 <P>For example, the ABC Corporation example template for a full account in <A HREF="#HDRWQ471">Example uss Templates</A> defines two directories:
 904 <PRE>   G /afs/.abc.com/usr1
 905    G /afs/.abc.com/usr2
 906 </PRE>
 907 <P>and puts the value <B>$AUTO/$USER</B> in the <B>V</B>
 908 instruction's <VAR>mount_point</VAR> field. An alternative with the
 909 same result is to define the directories as follows:
 910 <PRE>   G usr1
 911    G usr2
 912 </PRE>
 913 <P>and specify a more complete pathname in the <B>V</B> instruction's
 914 <VAR>mount_point</VAR> field:
 915 <B>/afs/.abc.com/$AUTO/$USER</B>.
 916 <A NAME="IDX7643"></A>
 917 <A NAME="IDX7644"></A>
 918 <A NAME="IDX7645"></A>
 919 <A NAME="IDX7646"></A>
 920 <A NAME="IDX7647"></A>
 921 <A NAME="IDX7648"></A>
 922 <P><H3><A NAME="HDRWQ473" HREF="auagd002.htm#ToC_557">Creating a Volume with the V Instruction</A></H3>
 923 <P>Unless the template file is empty (zero-length), one and
 924 only one <B>V</B> instruction must appear in it. (To create other
 925 volumes for a user as part of a <B>uss</B> account-creation operation, use
 926 the <B>X</B> instruction to invoke the <B>vos create</B> command or a
 927 script that invokes that command along with others, such as the <B>fs
 928 mkmount</B> command. For an example, see <A HREF="#HDRWQ479">Executing Commands with the X Instruction</A>.)
 929 <P>The <B>V</B> instruction defines the following AFS entities:
 930 <UL>
 931 <P><LI>A volume and associated VLDB entry
 932 <P><LI>The volume's site (file server machine and partition)
 933 <P><LI>The volume's mount point in the AFS filespace, which becomes the
 934 user's home directory
 935 <P><LI>The volume's space quota
 936 <P><LI>The home directory's owner, usually the new user
 937 <P><LI>The home directory's ACL, which normally at least grants all
 938 permissions to the user
 939 </UL>
 940 <P>The following discussion of the fields in a <B>V</B> instruction refers
 941 to the example in the full account template from <A HREF="#HDRWQ471">Example uss Templates</A> (the instruction appears here on two lines only for
 942 legibility):
 943 <PRE>   V  user.$USER  $SERVER.abc.com  /vicep$PART  5000  \
 944        /afs/.abc.com/$AUTO/$USER  $UID  $USER all abc:staff rl
 945 </PRE>
 946 <P>The <B>V</B> instruction's syntax is as follows:
 947 <PRE>   V  <VAR>volume_name</VAR>  <VAR>server</VAR>  <VAR>partition</VAR>  <VAR>quota</VAR>  <VAR>mount_point</VAR> <VAR>owner</VAR>  <VAR>ACL</VAR>
 948 </PRE>
 949 <P>where
 950 <DL>
 951 <P><DT><B><B>V</B>
 952 </B><DD>Indicates a volume creation instruction.
 953 <P><DT><B><VAR>volume_name</VAR>
 954 </B><DD>Specifies the volume's name as recorded in the VLDB.
 955 <P>To follow the convention of including the user's name as part of the
 956 volume name, include the $USER variable in this field. The variable
 957 takes its value from the <B>-user</B> argument to the <B>uss add</B>
 958 command or from the bulk input file <B>add</B> instruction's
 959 <VAR>username</VAR> field.
 960 <P>The ABC Corporation example uses the value <B>user.$USER</B> to
 961 assign the conventional volume name,
 962 <B>user.</B><VAR>username</VAR>. When creating an account for
 963 user <B>smith</B>, for example, you then include <B>-user smith</B> as
 964 an argument to the <B>uss add</B> command, or place the value
 965 <B>smith</B> in the bulk input file <B>add</B> instruction's
 966 <VAR>username</VAR> field.
 967 <P><DT><B><VAR>server</VAR>
 968 </B><DD>Names the file server machine on which to create the new volume. It
 969 is best to provide a fully qualified host name (for example,
 970 <B>fs1.abc.com</B>), but an abbreviated form is acceptable
 971 if the cell's naming service is available to resolve it at the time the
 972 volume is created.
 973 <P>To place different users' volumes on different file server machines,
 974 use the $SERVER variable in this field, and provide a value for it either with
 975 the <B>-server</B> argument to the <B>uss add</B> command or in the
 976 <VAR>server</VAR> field of the bulk input file <B>add</B>
 977 instruction. One easy way to specify a fully qualified hostname without
 978 having to type it completely on the command line is to combine a constant and
 979 the $SERVER variable. Specifically, the constant specifies the
 980 domain-name suffix common to all the file server machines.
 981 <P>In the ABC Corporation example, all of the file server machines in the cell
 982 share the <B>abc.com</B> domain name suffix, so the <VAR>server</VAR>
 983 field combines a variable and constant:
 984 <B>$SERVER.abc.com</B>. To place the new volume on
 985 the machine <B>fs1.abc.com</B>, you then include
 986 <B>-server fs1</B> as an argument to the <B>uss add</B> command, or
 987 place the value <B>fs1</B> in the bulk input file <B>add</B>
 988 instruction's <VAR>server</VAR> field.
 989 <P><DT><B><VAR>partition</VAR>
 990 </B><DD>Specifies the partition on which to create the user's volume; it
 991 must be on the file server machine named in the <VAR>server</VAR> field.
 992 Identify the partition by its complete name (for example, <B>/vicepa</B>)
 993 or use one of the abbreviations listed in <A HREF="auagd023.htm#HDRWQ615">Rules for Using Abbreviations and Aliases</A>.
 994 <P>To place different users' volumes on different partitions, use the
 995 $PART variable in this field, and provide a value for it either with the
 996 <B>-partition</B> argument to the <B>uss add</B> command or in the
 997 <VAR>partition</VAR> field of the bulk input file <B>add</B>
 998 instruction. Because all full partition names start with the
 999 <B>/vicep</B> string, it is convenient to combine that string as a
1000 constant with the $PART variable.
1001 <P>The ABC Corporation example template combines the constant string
1002 <B>/vicep</B> and the $PART variable in this way, as
1003 <B>/vicep$PART</B>.
1004 <A NAME="IDX7649"></A>
1005 <A NAME="IDX7650"></A>
1006 <A NAME="IDX7651"></A>
1007 <A NAME="IDX7652"></A>
1008 <P><DT><B><VAR>quota</VAR>
1009 </B><DD>Sets the maximum number of kilobyte blocks the volume can occupy on the
1010 file server machine's disk. It must be an integer. If you
1011 assign the same quota to all user volumes, specify a constant value. To
1012 assign different quotas to different volumes, place one of the number
1013 variables ($1 through $9) in this field, and provide a value for it either
1014 with the <B>-var</B> argument to the <B>uss add</B> command or in the
1015 appropriate field of the bulk input file <B>add</B> instruction.
1016 <P>The ABC Corporation example grants a 5000 KB initial quota to every new
1017 user.
1018 <A NAME="IDX7653"></A>
1019 <A NAME="IDX7654"></A>
1020 <A NAME="IDX7655"></A>
1021 <A NAME="IDX7656"></A>
1022 <P><DT><B><VAR>mount_point</VAR>
1023 </B><DD>Creates a mount point for the volume, which serves as the volume's
1024 root directory and the user's home directory. By convention, user
1025 home directory names include the username, which you can read in by including
1026 the $USER variable in this field.
1027 <P>Specify the read/write path to the mount point, to avoid the failure that
1028 results when you attempt to create the new mount point in a read-only
1029 volume. By convention, you indicate the read/write path by placing a
1030 period before the cell name at the pathname's second level (for example,
1031 <B>/afs/.abc.com</B>). If you use the $AUTO variable
1032 in this field, the directories named by each <B>G</B> instruction possibly
1033 already indicate the read/write path. For further discussion of the
1034 concept of read/write and read-only paths through the filespace, see <A HREF="auagd010.htm#HDRWQ208">Mounting Volumes</A>.
1035 <P>If other parts of the mount point name also vary from user to user, you can
1036 use the $MTPT variable in this field, and provide a value with the <B>uss
1037 add</B> command's <B>-mount</B> argument or in the
1038 <VAR>mount_point</VAR> field of a bulk input file <B>add</B>
1039 instruction. Note, however, that when the $MTPT variable appears in
1040 subsequent instructions in the template (usually, in <B>D</B>,
1041 <B>E</B>, or <B>F</B> instructions), it instead takes as its value the
1042 complete contents of this field.
1043 <P>Combine constants and variables based on how you have decided to group home
1044 directories together in one or more parent directories. Note that the
1045 parent directories must already exist before you run a <B>uss add</B> or
1046 <B>uss bulk</B> command that references the template. Possibilities
1047 for grouping home directories include the following:
1048 <A NAME="IDX7657"></A>
1049 <P>
1050 <UL>
1051 <P><LI>Placing all user home directories in a single parent directory; the
1052 name <B>/afs/</B><VAR>cellname</VAR><B>/usr</B> is an AFS-appropriate
1053 variation on the UNIX <B>/usr</B> convention. This choice is most
1054 appropriate for a cell with a small number of user accounts. The
1055 simplest way to implement this choice is to combine a constant string and the
1056 $USER variable, as in <B>/afs/.abc.com/usr/$USER</B>.
1057 <P><LI>Distributing home directories evenly into a set of parent directories that
1058 do not correspond to workplace divisions. This choice is appropriate in
1059 cells with tens of thousands of accounts, where the number of home directories
1060 is large enough to slow directory lookup significantly if they all reside
1061 together in one parent directory, but distribution according to workplace
1062 divisions is not feasible.
1063 <P>The $AUTO variable is designed to distribute home directories evenly in
1064 this manner. As explained in <A HREF="#HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</A>, the <B>uss</B> command interpreter substitutes the
1065 directory that is defined by a preceding <B>G</B> template instruction and
1066 that currently has the fewest entries. The example ABC Corporation
1067 template illustrates this choice by using the value
1068 <B>/afs/.abc.com/$AUTO/$USER</B>.
1069 <P><LI>Distributing home directories into multiple directories that reflect
1070 divisions like academic or corporate departments. Perhaps the simplest
1071 way to implement this scheme is to use the $MTPT variable to represent the
1072 department, as in
1073 <B>/afs/.ghi.com/usr/$MTPT/$USER</B>. You then
1074 provide <B>-user smith</B> and <B>-mount acctg</B> arguments to the
1075 <B>uss add</B> command to create the mount point
1076 <B>/afs/.ghi.com/usr/acctg/smith</B>.
1077 <P><LI>Distributing home directories into alphabetic subdirectories of
1078 <B>usr</B> (<B>usr/a</B>, <B>usr/b</B> and so on), based on the
1079 first letter or letters in the username. The advantage is that knowing
1080 the username enables you easily to locate a home directory. A potential
1081 drawback is that the distribution is not likely to be even, and if there are a
1082 large number of accounts, then slowed directory lookup unfairly affects users
1083 whose names begins with popular letters.
1084 <P>Perhaps the simplest way to implement this scheme is to use the $MTPT
1085 variable to represent the letter or letters, as in
1086 <B>/afs/.jkl.com/usr/$MTPT/$USER</B>. Then provide
1087 the <B>-user smith</B> and <B>-mount s/m</B> arguments to the <B>uss
1088 add</B> command to create the mount point
1089 <B>/afs/.jkl.com/usr/s/m/smith</B>.
1090 </UL>
1091 <P><DT><B><VAR>owner</VAR>
1092 </B><DD>Specifies the username or UID of the user to be designated the mount
1093 point's owner in the output from the UNIX <B>ls -ld</B>
1094 command. To follow the standard convention for home directory
1095 ownership, use the $UID variable in this field, as in the ABC Corporation
1096 example template. The Protection Server then automatically assigns an
1097 AFS UID unless you provide the <B>-uid</B> argument to the <B>uss
1098 add</B> command or fill in the <VAR>uid</VAR> field in the bulk input file
1099 <B>add</B> instruction. (If you are converting existing UNIX
1100 accounts, see the discussion of additional considerations in <A HREF="#HDRWQ459">Converting Existing UNIX Accounts with uss</A>.)
1101 <A NAME="IDX7658"></A>
1102 <A NAME="IDX7659"></A>
1103 <A NAME="IDX7660"></A>
1104 <A NAME="IDX7661"></A>
1105 <P><DT><B><VAR>ACL</VAR>
1106 </B><DD>Sets the ACL on the new home directory. Provide one or more paired
1107 values, each pair consisting of an AFS username or group name and the desired
1108 permissions, in that order (a group name must already exist in the Protection
1109 Database to be used). Separate the two parts of the pair, and each
1110 pair, with a space. For a discussion of the available permissions, see <A HREF="auagd020.htm#HDRWQ567">The AFS ACL Permissions</A>.
1111 <P>At minimum, grant all permissions to the new user by including the value
1112 <B>$USER all</B> in this field. The File Server automatically
1113 grants all permissions to the <B>system:administrators</B> group as
1114 well. You cannot grant permissions to the issuer of the <B>uss</B>
1115 command, because as the last step in account creation the <B>uss</B>
1116 command interpreter automatically deletes that user from any ACLs set during
1117 the creation process.
1118 <P>The ABC Corporation example uses the following value to grant all
1119 permissions to the new user and <B>r</B> (<B>read</B>) and
1120 <B>l</B> (<B>lookup</B>) permissions to the members of the
1121 <B>abc:staff</B> group:
1122 <P><B>$USER all abc:staff rl</B>
1123 </DL>
1124 <A NAME="IDX7662"></A>
1125 <A NAME="IDX7663"></A>
1126 <A NAME="IDX7664"></A>
1127 <A NAME="IDX7665"></A>
1128 <A NAME="IDX7666"></A>
1129 <A NAME="IDX7667"></A>
1130 <P><H3><A NAME="HDRWQ474" HREF="auagd002.htm#ToC_558">Creating a Directory with the D Instruction</A></H3>
1131 <P>Each <B>D</B> instruction in the template file creates a
1132 directory; there is no limit on the number of them in the
1133 template. If a <B>D</B> instruction creates a subdirectory in a new
1134 user's home directory (its intended use), then it must follow the
1135 <B>V</B> instruction. Creating a directory on the local disk of the
1136 machine where the <B>uss</B> command runs is not recommended for the
1137 reasons outlined in <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1138 <P>The following discussion of the fields in a <B>D</B> instruction refers
1139 to one of the examples in the full account template in <A HREF="#HDRWQ471">Example uss Templates</A>:
1140 <PRE>   D $MTPT/Mailbox 0700 $UID $USER all abc:staff none  system:anyuser lik
1141 </PRE>
1142 <P>The <B>D</B> instruction's syntax is as follows:
1143 <PRE>   D  <VAR>pathname</VAR>  <VAR>mode_bits</VAR>  <VAR>owner</VAR>  <VAR>ACL</VAR>
1144 </PRE>
1145 <P>where
1146 <DL>
1147 <P><DT><B><B>D</B>
1148 </B><DD>Indicates a directory creation instruction.
1149 <P><DT><B><VAR>pathname</VAR>
1150 </B><DD>Specifies the directory's full pathname. If it is a
1151 subdirectory of the user's home directory, it is simplest to use the
1152 $MTPT variable to specify the home directory pathname. When the $MTPT
1153 variable appears in a <B>D</B> instruction, it takes its value from the
1154 preceding <B>V</B> instruction's <VAR>mount_point</VAR> field (this
1155 dependency is why a <B>D</B> instruction must follow the <B>V</B>
1156 instruction).
1157 <P>Specify the read/write pathname to the directory, to avoid the failure that
1158 results when you attempt to create a new directory in a read-only
1159 volume. By convention, you indicate the read/write path by placing a
1160 period before the cell name at the pathname's second level (for example,
1161 <B>/afs/.abc.com</B>). If you use the $MTPT variable
1162 in this field, the value in the <B>V</B> instruction's
1163 <VAR>mount_point</VAR> field possibly already indicates the read/write
1164 path. For further discussion of the concept of read/write and read-only
1165 paths through the filespace, see <A HREF="auagd010.htm#HDRWQ208">Mounting Volumes</A>.
1166 <P>The ABC Corporation example uses the value <B>$MTPT/Mailbox</B> to
1167 place the <B>Mailbox</B> subdirectory in the user's home
1168 directory.
1169 <P><DT><B><VAR>mode_bits</VAR>
1170 </B><DD>Defines the directory's UNIX mode bits. Acceptable values are
1171 the standard three- or four-digit numbers corresponding to a combination of
1172 permissions. Examples: <B>0755</B> corresponds to
1173 <B>rwxr-xr-x</B>, and <B>0644</B> to <B>rw-r--r--</B>. The
1174 first (owner) <B>x</B> bit must be turned on to enable access to a
1175 directory.
1176 <P>The ABC Corporation example uses the value <B>0700</B> to set the mode
1177 bits on the <B>Mailbox</B> subdirectory to <B>rwxr-----</B>.
1178 <P><DT><B><VAR>owner</VAR>
1179 </B><DD>Specifies the username or UID of the user to be designated the
1180 directory's owner in the output from the UNIX <B>ls -ld</B>
1181 command.
1182 <P>If the directory resides in AFS, place the $UID variable in this field, as
1183 in the ABC Corporation example template. The Protection Server then
1184 automatically assigns an AFS UID unless you provide the <B>-uid</B>
1185 argument to the <B>uss add</B> command or fill in the <VAR>uid</VAR> field
1186 in the bulk input file <B>add</B> instruction. (If you are
1187 converting existing UNIX accounts, see the discussion of additional
1188 considerations in <A HREF="#HDRWQ459">Converting Existing UNIX Accounts with uss</A>.)
1189 <P>If the directory resides on the local disk, it is simplest to specify the
1190 username or UNIX UID under which you are issuing the <B>uss</B>
1191 command. For a discussion of the complications that arise from
1192 designating another user, see <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1193 <A NAME="IDX7668"></A>
1194 <A NAME="IDX7669"></A>
1195 <A NAME="IDX7670"></A>
1196 <A NAME="IDX7671"></A>
1197 <P><DT><B><VAR>ACL</VAR>
1198 </B><DD>Sets the ACL on the new directory. Provide one or more paired
1199 values, each pair consisting of an AFS username or group name and the desired
1200 permissions, in that order (a group name must already exist in the Protection
1201 Database to be used). Separate the two parts of the pair, and each
1202 pair, with a space. For a description of the available permissions, see
1203 <A HREF="auagd020.htm#HDRWQ567">The AFS ACL Permissions</A>.
1204 <P>At minimum, grant all permissions to the new user by including the value
1205 <B>$USER all</B>. You cannot grant permissions to the issuer of the
1206 <B>uss</B> command, because as the last step in account creation the
1207 <B>uss</B> command interpreter automatically deletes that user from any
1208 ACLs set during the creation process. An error message always appears
1209 if the directory is on the local disk, as detailed in <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1210 <P>The ABC Corporation example uses the following value to grant all
1211 permissions to the new user, no permissions to the members of the
1212 <B>abc:staff</B> group, and the <B>l</B> (<B>lookup</B>),
1213 <B>i</B> (<B>insert</B>), and <B>k</B> (<B>lock</B>)
1214 permissions to the members of the <B>system:anyuser</B> group:
1215 <P><B>$USER all abc:staff none system:anyuser lik</B>
1216 <P>It grants such extensive permissions to the <B>system:anyuser</B>
1217 group to enable any system user (including a mail-delivery daemon) to insert
1218 mail into the <B>Mailbox</B> directory. The absence of the
1219 <B>r</B> (<B>read</B>) permission prevents members of the
1220 <B>system:anyuser</B> group from reading the mail files.
1221 </DL>
1222 <A NAME="IDX7672"></A>
1223 <A NAME="IDX7673"></A>
1224 <A NAME="IDX7674"></A>
1225 <A NAME="IDX7675"></A>
1226 <A NAME="IDX7676"></A>
1227 <A NAME="IDX7677"></A>
1228 <P><H3><A NAME="HDRWQ475" HREF="auagd002.htm#ToC_559">Creating a File from a Prototype with the F Instruction</A></H3>
1229 <P>Each <B>F</B> instruction in the template file creates a
1230 file by copying the contents of an existing prototype file; there is no
1231 limit on the number of them in the template, and each can refer to a different
1232 prototype. If an <B>F</B> instruction creates a file in a new
1233 user's home directory or a subdirectory of it (the intended use), then it
1234 must follow the <B>V</B> or <B>D</B> instruction that creates the
1235 parent directory. Creating a file on the local disk of the machine
1236 where the <B>uss</B> command runs is not recommended for the reasons
1237 detailed in <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1238 <P>The <B>E</B> instruction also creates a file, but the two types of
1239 instruction have complementary advantages. Files created with an
1240 <B>E</B> instruction can be customized for each user, because variables
1241 can appear in the field that specifies the contents of the file. In
1242 contrast, the contents of a file created using the <B>F</B> instruction
1243 are the same for every user. An <B>E</B> file can be only a single
1244 line, however, whereas an <B>F</B> file can be any length.
1245 <P>The following discussion of the fields in a <B>F</B> instruction refers
1246 to one of the examples in the full account template in <A HREF="#HDRWQ471">Example uss Templates</A>:
1247 <PRE>   F $MTPT/.login 0755 $UID /afs/abc.com/admin/user/proto
1248 </PRE>
1249 <P>The <B>F</B> instruction's syntax is as follows:
1250 <PRE>   F  <VAR>pathname</VAR>  <VAR>mode_bits</VAR>  <VAR>owner</VAR>  <VAR>prototype_file</VAR>
1251 </PRE>
1252 <P>where
1253 <DL>
1254 <P><DT><B><B>F</B>
1255 </B><DD>Indicates a file creation instruction.
1256 <P><DT><B><VAR>pathname</VAR>
1257 </B><DD>Specifies the full pathname of the file to create, including the
1258 filename. If it resides in the user's home directory or a
1259 subdirectory of it, it is simplest to use the $MTPT variable to specify the
1260 home directory pathname. When the $MTPT variable appears in an
1261 <B>F</B> instruction, it takes its value from the preceding <B>V</B>
1262 instruction's <VAR>mount_point</VAR> field (this dependency is why an
1263 <B>F</B> instruction must follow the <B>V</B> instruction).
1264 <P>Specify the read/write path to the file, to avoid the failure that results
1265 when you attempt to create a new file in a read-only volume. By
1266 convention, you indicate the read/write path by placing a period before the
1267 cell name at the pathname's second level (for example,
1268 <B>/afs/.abc.com</B>). If you use the $MTPT variable
1269 in this field, the value in the <B>V</B> instruction's
1270 <VAR>mount_point</VAR> field possibly already indicates the read/write
1271 path. For further discussion of the concept of read/write and read-only
1272 paths through the filespace, see <A HREF="auagd010.htm#HDRWQ208">Mounting Volumes</A>.
1273 <P>The ABC Corporation example uses the value <B>$MTPT/.login</B>
1274 to place a file called <B>.login</B> in the user's home
1275 directory.
1276 <P><DT><B><VAR>mode_bits</VAR>
1277 </B><DD>Defines the file's UNIX mode bits. Acceptable values are the
1278 standard three- or four-digit numbers corresponding to a combination of
1279 permissions. Examples: <B>0755</B> corresponds to
1280 <B>rwxr-xr-x</B>, and <B>0644</B> to <B>rw-r--r--</B>.
1281 <P>The ABC Corporation example uses the value <B>0755</B> to set the mode
1282 bits on the <B>.login</B> file to <B>rwxr-xr-x</B>.
1283 <P><DT><B><VAR>owner</VAR>
1284 </B><DD>Specifies the username or UID of the user to be designated the file's
1285 owner in the output from the UNIX <B>ls -l</B> command.
1286 <P>If the file resides in AFS, place the $UID variable in this field, as in
1287 the ABC Corporation example template. The Protection Server then
1288 automatically assigns an AFS UID unless you provide the <B>-uid</B>
1289 argument to the <B>uss add</B> command or fill in the <VAR>uid</VAR> field
1290 in the bulk input file <B>add</B> instruction. (If you are
1291 converting existing UNIX accounts, see the discussion of additional
1292 considerations in <A HREF="#HDRWQ459">Converting Existing UNIX Accounts with uss</A>.)
1293 <P>If the file resides on the local disk, it is simplest to specify the
1294 username or UNIX UID under which you are issuing the <B>uss</B>
1295 command. For a discussion of the complications that arise from
1296 designating another user, see <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1297 <P><DT><B><VAR>prototype_file</VAR>
1298 </B><DD>Names the AFS or local directory that houses the prototype file to
1299 copy. The prototype file's name must match the final element in
1300 the <VAR>pathname</VAR> field.
1301 <P>The ABC Corporation example references a prototype file called
1302 <B>.login</B> in the directory
1303 <B>/afs/abc.com/admin/user/proto</B>.
1304 </DL>
1305 <A NAME="IDX7678"></A>
1306 <A NAME="IDX7679"></A>
1307 <A NAME="IDX7680"></A>
1308 <A NAME="IDX7681"></A>
1309 <A NAME="IDX7682"></A>
1310 <A NAME="IDX7683"></A>
1311 <P><H3><A NAME="HDRWQ476" HREF="auagd002.htm#ToC_560">Creating One-Line Files with the E Instruction</A></H3>
1312 <P>Each <B>E</B> instruction in the template file creates a
1313 file by echoing a specified single line into it; there is no limit on the
1314 number of them in the template. If an <B>E</B> instruction creates
1315 a file in a new user's home directory or a subdirectory of it (the
1316 intended use), then it must follow the <B>V</B> or <B>D</B>
1317 instruction that creates the parent directory. Creating a file on the
1318 local disk of the machine where the <B>uss</B> command runs is not
1319 recommended for the reasons detailed in <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1320 <P>The <B>F</B> instruction also creates a file, but the two types of
1321 instruction have complementary advantages. Files created with an
1322 <B>E</B> instruction can be customized for each user, because variables
1323 can appear in the field that specifies the contents of the file. The
1324 command interpreter replaces the variables with appropriate values before
1325 creating the file. In contrast, the contents of a file created using
1326 the <B>F</B> instruction are the same for every user. An
1327 <B>E</B> file can be only a single line, however, whereas an <B>F</B>
1328 file can be any length.
1329 <P>The <B>E</B> instruction is particularly suited to creating an entry
1330 for the new user in the cell's common source password file, which is then
1331 copied to client machines to serve as the local password file
1332 (<B>/etc/passwd</B> or equivalent). The following discussion of the
1333 fields refers to an example of this type of use, from the ABC
1334 Corporation's full account template shown in <A HREF="#HDRWQ471">Example uss Templates</A>. For further discussion of how to
1335 incorporate the files created in this way into a common source password file,
1336 see <A HREF="#HDRWQ458">Creating a Common Source Password File</A>.
1337 <PRE>   E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root  \
1338       "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
1339 </PRE>
1340 <P>The <B>E</B> instruction's syntax is as follows:
1341 <PRE>   E  <VAR>pathname</VAR>  <VAR>mode_bits</VAR>  <VAR>owner</VAR>  "<VAR>contents</VAR>"
1342 </PRE>
1343 <P>where
1344 <DL>
1345 <P><DT><B><B>E</B>
1346 </B><DD>Indicates a file creation instruction.
1347 <P><DT><B><VAR>pathname</VAR>
1348 </B><DD>Specifies the full pathname of the file to create, including the
1349 filename. It can include variables. If it resides in the
1350 user's home directory or a subdirectory of it, it is simplest to use the
1351 $MTPT variable to specify the home directory pathname. When the $MTPT
1352 variable appears in an <B>E</B> instruction, it takes its value from the
1353 preceding <B>V</B> instruction's <VAR>mount_point</VAR> field (this
1354 dependency is why an <B>E</B> instruction must follow the <B>V</B>
1355 instruction.)
1356 <P>Specify the read/write path to the file, to avoid the failure that results
1357 when you attempt to create a new file in a read-only volume. By
1358 convention, you indicate the read/write path by placing a period before the
1359 cell name at the pathname's second level (for example,
1360 <B>/afs/.abc.com</B>). If you use the $MTPT variable
1361 in this field, the value in the <B>V</B> instruction's
1362 <VAR>mount_point</VAR> field possibly already indicates the read/write
1363 path. For further discussion of the concept of read/write and read-only
1364 paths through the filespace, see <A HREF="auagd010.htm#HDRWQ208">Mounting Volumes</A>.
1365 <P>The ABC Corporation example writes the file created by the <B>E</B>
1366 instruction to <B>/afs/.abc.com/common/etc/newaccts</B>
1367 directory, naming it after the new user:
1368 <PRE>   /afs/.abc.com/common/etc/newaccts/passwd_$USER
1369 </PRE>
1370 <P><DT><B><VAR>mode_bits</VAR>
1371 </B><DD>Defines the file's UNIX mode bits. Acceptable values are the
1372 standard three- or four-digit numbers corresponding to a combination of
1373 permissions. Examples: <B>0755</B> corresponds to
1374 <B>rwxr-xr-x</B>, and <B>0644</B> to <B>rw-r--r--</B>.
1375 <P>The ABC Corporation example uses the value <B>0644</B> to set the mode
1376 bits on the <B>passwd_</B><VAR>user</VAR> file to
1377 <B>r-xr--r--</B>.
1378 <P><DT><B><VAR>owner</VAR>
1379 </B><DD>Specifies the username or UID of the user to be designated the file's
1380 owner in the output from the UNIX <B>ls -l</B> command.
1381 <P>If the file resides in AFS and is to be owned by the user, place the $UID
1382 variable in this field. The Protection Server then automatically
1383 assigns an AFS UID unless you provide the <B>-uid</B> argument to the
1384 <B>uss add</B> command or fill in the <VAR>uid</VAR> field in the bulk input
1385 file <B>add</B> instruction. (If you are converting existing UNIX
1386 accounts, see the discussion of additional considerations in <A HREF="#HDRWQ459">Converting Existing UNIX Accounts with uss</A>.)
1387 <P>If the file resides on the local disk, specify the username or UNIX UID
1388 under which you are issuing the <B>uss</B> command. For a
1389 discussion of the complications that arise from designating another user, see <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1390 <P>The ABC Corporation example is creating an AFS file intended for
1391 incorporation into the common password file, rather than for direct use by the
1392 new user. It therefore designates the local superuser <B>root</B>
1393 as the owner of the new file. Designating an alternate owner on an AFS
1394 file does not introduce complications: issuing the <B>chown</B>
1395 command on AFS files requires membership in the
1396 <B>system:administrators</B> group, but the issuer of the
1397 <B>uss</B> command is necessarily authenticated as a member of that
1398 group.
1399 <P><DT><B><VAR>contents</VAR>
1400 </B><DD>Specifies the one-line character string to write into the new file.
1401 Surround it with double quotes if it contains one or more spaces. It
1402 cannot contain the newline character, but can contain any of the standard
1403 variables, which the command interpreter resolves as it creates the
1404 file.
1405 <P>The ABC Corporation example has the following value in the
1406 <VAR>contents</VAR> field, to create a password file entry:
1407 <PRE>   $USER:X:$UID:10:$NAME:$MTPT:/bin/csh
1408 </PRE>
1409 </DL>
1410 <A NAME="IDX7684"></A>
1411 <A NAME="IDX7685"></A>
1412 <A NAME="IDX7686"></A>
1413 <A NAME="IDX7687"></A>
1414 <A NAME="IDX7688"></A>
1415 <A NAME="IDX7689"></A>
1416 <A NAME="IDX7690"></A>
1417 <A NAME="IDX7691"></A>
1418 <A NAME="IDX7692"></A>
1419 <A NAME="IDX7693"></A>
1420 <A NAME="IDX7694"></A>
1421 <P><H3><A NAME="HDRWQ477" HREF="auagd002.htm#ToC_561">Creating Links with the L and S Instructions</A></H3>
1422 <P>Each <B>L</B> instruction in the template file creates a
1423 hard link between two files, as achieved by the standard UNIX <B>ln</B>
1424 command. The <B>S</B> instruction creates a symbolic link between
1425 two files, as achieved by the standard UNIX <B>ln -s</B> command.
1426 An explanation of links is beyond the scope of this document, but the basic
1427 effect in both cases is to create a second name for an existing file, so that
1428 it can be accessed via either name. Creating a link does not create a
1429 second copy of the file.
1430 <P>There is no limit on the number of <B>L</B> or <B>S</B>
1431 instructions in a template file. If the link is in a new user's
1432 home directory or a subdirectory of it (the intended use), then it must follow
1433 the <B>V</B> or <B>D</B> instruction that creates the parent
1434 directory, and the <B>F</B>, <B>E</B>, or <B>X</B> instruction
1435 that creates the file being linked to. Creating a file on the local
1436 disk of the machine where the <B>uss</B> command runs is not recommended,
1437 for the reasons detailed in <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1438 <P>Note that AFS allows hard links only between files that reside in the same
1439 directory. This restriction is necessary to eliminate the confusion
1440 that results from associating two potentially different ACLs (those of the two
1441 directories) with the same file. Symbolic links are legal between two
1442 files that reside in different directories and even in different
1443 volumes. The ACL on the actual file applies to the link as well.
1444 <P>You do not set the owner or mode bits on a link created with an
1445 <B>L</B> or <B>S</B> instruction, as you do for directories or
1446 files. The <B>uss</B> command interpreter automatically records the
1447 UNIX UID of the <B>uss</B> command's issuer as the owner, and sets
1448 the mode bits to <B>lrwxrwxrwx</B> (777).
1449 <P>The following discussion of the fields in an <B>L</B> or <B>S</B>
1450 instruction refers to an example in the full account template from <A HREF="#HDRWQ471">Example uss Templates</A>, namely
1451 <PRE>   S /afs/abc.com/public/$USER $MTPT/public
1452 </PRE>
1453 <P>The <B>L</B> and <B>S</B> instructions' syntax is as
1454 follows:
1455 <PRE>   L  <VAR>existing_file</VAR>  <VAR>link</VAR>
1456    S  <VAR>existing_file</VAR>  <VAR>link</VAR>
1457 </PRE>
1458 <P>where
1459 <DL>
1460 <P><DT><B><B>L</B>
1461 </B><DD>Indicates a hard link creation instruction.
1462 <P><DT><B><B>S</B>
1463 </B><DD>Indicates a symbolic link creation instruction.
1464 <P><DT><B><VAR>existing_file</VAR>
1465 </B><DD>Specifies the complete pathname of the existing file. If it resides
1466 in the user's home directory or a subdirectory of it, it is simplest to
1467 use the $MTPT variable to specify the home directory pathname. When the
1468 $MTPT variable appears in an <B>L</B> or <B>S</B> instruction, it
1469 takes its value from the preceding <B>V</B> instruction's
1470 <VAR>mount_point</VAR> field (this dependency is why the instruction must follow
1471 the <B>V</B> instruction).
1472 <P>Do not create a symbolic link to a file whose name begins with the number
1473 sign (<B>#</B>) or percent sign (<B>%</B>). When the Cache
1474 Manager reads a symbolic link whose contents begin with one of those
1475 characters, it interprets it as a regular or read/write mount point,
1476 respectively.
1477 <P>The ABC Corporation example creates a link to the publicly readable volume
1478 created and mounted by a preceding <B>X</B> instruction, by specifying the
1479 path to its mount point:
1480 <PRE>   /afs/abc.com/public/$USER
1481 </PRE>
1482 <P><DT><B><VAR>link</VAR>
1483 </B><DD>Specifies the complete pathname of the second name for the file. If
1484 it resides in the user's home directory or a subdirectory of it, it is
1485 simplest to use the $MTPT variable to specify the home directory
1486 pathname.
1487 <P>Specify the read/write path to the link, to avoid the failure that results
1488 when you attempt to create a new link in a read-only volume. By
1489 convention, you indicate the read/write path by placing a period before the
1490 cell name at the pathname's second level (for example,
1491 <B>/afs/.abc.com</B>). If you use the $MTPT variable
1492 in this field, the value in the <B>V</B> instruction's
1493 <VAR>mount_point</VAR> field possibly already indicates the read/write
1494 path. For further discussion of the concept of read/write and read-only
1495 paths through the filespace, see <A HREF="auagd010.htm#HDRWQ208">Mounting Volumes</A>.
1496 <P>The ABC Corporation example creates a link called <B>public</B> in the
1497 user's home directory:
1498 <PRE>   $MTPT/public
1499 </PRE>
1500 </DL>
1501 <A NAME="IDX7695"></A>
1502 <A NAME="IDX7696"></A>
1503 <A NAME="IDX7697"></A>
1504 <A NAME="IDX7698"></A>
1505 <P><H3><A NAME="HDRWQ478" HREF="auagd002.htm#ToC_562">Increasing Account Security with the A Instruction</A></H3>
1506 <P>The <B>A</B> instruction in the template file enhances
1507 cell security by imposing the following restrictions on users' password
1508 choice and authentication attempts.
1509 <UL>
1510 <P><LI>Limiting the user's password lifetime. When the lifetime
1511 expires, the user can no longer use the password to authenticate and must
1512 change it.
1513 <P><LI>Prohibiting the reuse of the user's 20 most-recently used
1514 passwords.
1515 <P><LI>Limiting the number of consecutive times that a user can provide an
1516 incorrect password during authentication, and for how long the Authentication
1517 Server refuses further authentication attempts after the limit is exceeded
1518 (referred to as an <I>account lockout</I>). For regular user
1519 accounts in most cells, the recommended limit is nine and lockout time is 25
1520 minutes.
1521 </UL>
1522 <P>The following discussion of the fields in an <B>A</B> instruction
1523 refers to the example in the full account template from <A HREF="#HDRWQ471">Example uss Templates</A>, which sets a password lifetime of 250 days, prohibits reuse
1524 of passwords, limits the number of failed authentication attempts to nine, and
1525 creates a lockout time of 25 minutes if the authentication limit is
1526 exceeded:
1527 <PRE>   A $USER 250 noreuse 9 25
1528 </PRE>
1529 <P>The <B>A</B> instruction's syntax is as follows:
1530 <PRE>   A  <VAR>username</VAR>  <VAR>password_lifetime</VAR>  <VAR>password_reuse</VAR>  <VAR>failures</VAR>  <VAR>locktime</VAR>
1531 </PRE>
1532 <P>where
1533 <DL>
1534 <P><DT><B><B>A</B>
1535 </B><DD>Indicates a security enhancing instruction.
1536 <P><DT><B><VAR>username</VAR>
1537 </B><DD>Names the Authentication Database entry on which to impose security
1538 restrictions. Use the $USER variable to read in the username from the
1539 <B>uss add</B> command's <B>-user</B> argument, or from the
1540 <VAR>username</VAR> field of an <B>add</B> instruction in the bulk input
1541 file. The ABC Corporation example uses this value.
1542 <P><DT><B><VAR>password_lifetime</VAR>
1543 </B><DD>Sets the number of days after the user's password is changed that it
1544 remains valid. When the password becomes invalid (expires), the user is
1545 unable to authenticate, but has 30 more days in which to issue the
1546 <B>kpasswd</B> command to change the password (after that, only an
1547 administrator can change it).
1548 <P>Specify an integer from the range <B>1</B> through <B>254</B> to
1549 specify the number of days until expiration, the value <B>0</B> to
1550 indicate that the password never expires, or the value $PWEXPIRES to read in
1551 the number of days from the <B>uss add</B> or <B>uss bulk</B>
1552 command's <B>-pwexpires</B> argument. If the <B>A</B>
1553 instruction does not appear in the template file, by default the user's
1554 password never expires.
1555 <P>The ABC Corporation example sets a password lifetime of 250 days.
1556 <P><DT><B><VAR>password_reuse</VAR>
1557 </B><DD>Determines whether or not the user can change his or her password (using
1558 the <B>kpasswd</B> or <B>kas setpassword</B> command) to one that is
1559 similar to any of his or her last 20 passwords. The acceptable values
1560 are <B>reuse</B> to allow reuse and <B>noreuse</B> to prohibit
1561 it. If the <B>A</B> instruction does not appear in the template
1562 file, the default is to allow password reuse.
1563 <P>The ABC Corporation example prohibits password reuse.
1564 <P><DT><B><VAR>failures</VAR>
1565 </B><DD>Sets the number of consecutive times the user can provide an incorrect
1566 password during authentication (using the <B>klog</B> command or a login
1567 utility that grants AFS tokens). When the user exceeds the limit, the
1568 Authentication Server rejects further authentication attempts for the amount
1569 of time specified in the <VAR>locktime</VAR> field.
1570 <P>Specify an integer from the range <B>1</B> through <B>254</B> to
1571 specify the number of failures permitted, or the value <B>0</B> to
1572 indicate that there is no limit to the number of unsuccessful attempts.
1573 If the <B>A</B> instruction does not appear in the template file, the
1574 default is to allow an unlimited number of failures.
1575 <P>The ABC Corporation example sets the limit to nine failed attempts.
1576 <P><DT><B><VAR>locktime</VAR>
1577 </B><DD>Specifies how long the Authentication Server refuses authentication
1578 attempts from a user who has exceeded the failure limit set in the
1579 <VAR>failures</VAR> field.
1580 <P>Specify a number of hours and minutes (<VAR>hh</VAR>:<VAR>mm</VAR>) or
1581 minutes only (<VAR>mm</VAR>), from the range <B>01</B> (one minute) through
1582 <B>36:00</B> (36 hours). The Authentication Server
1583 automatically reduces any larger value to <B>36:00</B> and also
1584 rounds up any nonzero value to the next highest multiple of 8.5
1585 minutes. A value of <B>0</B> (zero) sets an infinite lockout time,
1586 in which case an administrator must always issue the <B>kas unlock</B>
1587 command to unlock the account.
1588 <P>The ABC Corporation example sets the lockout time to 25 minutes, which is
1589 rounded up to 25 minutes 30 seconds (the next highest multiple of 8.5
1590 minutes).
1591 </DL>
1592 <A NAME="IDX7699"></A>
1593 <A NAME="IDX7700"></A>
1594 <A NAME="IDX7701"></A>
1595 <A NAME="IDX7702"></A>
1596 <A NAME="IDX7703"></A>
1597 <A NAME="IDX7704"></A>
1598 <P><H3><A NAME="HDRWQ479" HREF="auagd002.htm#ToC_563">Executing Commands with the X Instruction</A></H3>
1599 <P>The <B>X</B> instruction in the template file executes a
1600 command, which can be a standard UNIX command, a shell script or program, or
1601 an AFS command. The command string can include standard template
1602 variables, and any number of <B>X</B> instructions can appear in a
1603 template file. If an instruction manipulates an element created by
1604 another instruction, it must appear after that instruction.
1605 <P>The following discussion of the field in an <B>X</B> instruction refers
1606 to the example in the full account template from <A HREF="#HDRWQ471">Example uss Templates</A>:
1607 <PRE>   X "create_public_vol $USER $1 $2"
1608 </PRE>
1609 <P>The <B>X</B> instruction's syntax is as follows:
1610 <PRE>   X "<VAR>command</VAR>"
1611 </PRE>
1612 <P>where <VAR>command</VAR> specifies the command to execute. Surround it
1613 with double quotes if it contains spaces. The command string can
1614 contain any of the standard variables, which the <B>uss</B> command
1615 interpreter resolves before passing the command on to the appropriate other
1616 command interpreter, but it cannot contain newline characters.
1617 <P>The ABC Corporation example invokes a script called
1618 <B>create_public_vol</B>, which creates another volume associated with the
1619 new user and mounts it in a publicly readable part of the ABC
1620 Corporation's filespace:
1621 <PRE>   "create_public_vol $USER $1 $2"
1622 </PRE>
1623 <P>It uses the $USER variable to read in the username and make it part of both
1624 the volume name and mount point name. The <B>uss</B> command issuer
1625 supplies a file server machine name for the $1 variable and a partition name
1626 for the $2 variable, to specify the site for the new volume.
1627 <A NAME="IDX7705"></A>
1628 <A NAME="IDX7706"></A>
1629 <A NAME="IDX7707"></A>
1630 <A NAME="IDX7708"></A>
1631 <A NAME="IDX7709"></A>
1632 <A NAME="IDX7710"></A>
1633 <A NAME="IDX7711"></A>
1634 <A NAME="IDX7712"></A>
1635 <A NAME="IDX7713"></A>
1636 <A NAME="IDX7714"></A>
1637 <A NAME="IDX7715"></A>
1638 <HR><H2><A NAME="HDRWQ480" HREF="auagd002.htm#ToC_564">Creating Individual Accounts with the uss add Command</A></H2>
1639 <P>After you have created a template file, you can create an
1640 individual account by issuing the <B>uss add</B> command (for template
1641 creation instructions see <A HREF="#HDRWQ463">Constructing a uss Template File</A>). When you issue the command, the <B>uss</B>
1642 command interpreter contacts various AFS servers to perform the following
1643 actions:
1644 <UL>
1645 <P><LI>Create a Protection Database entry. By default, the Protection
1646 Server assigns an AFS UID which becomes the value of the $UID variable used in
1647 the template.
1648 <P><LI>Create an Authentication Database entry, recording an encrypted version of
1649 the initial password.
1650 <P><LI>Create the account components defined in the indicated template file,
1651 contacting the File Server, Volume Server, and Volume Location (VL) Server as
1652 necessary.
1653 </UL>
1654 <P>To review which types of instructions to include in a template to create
1655 different file system objects, see <A HREF="#HDRWQ463">Constructing a uss Template File</A>. If the template is empty, the <B>uss add</B>
1656 command creates an authentication-only account consisting of Protection
1657 Database and Authentication Database entries.
1658 <P>When you issue the <B>uss add</B> command, provide a value for each
1659 variable in the template file by including the corresponding command-line
1660 argument. If you fail to supply a value for a variable, the
1661 <B>uss</B> command interpreter substitutes a null string, which usually
1662 causes the account creation to fail. If you include a command line
1663 argument for which the corresponding variable does not appear in the template,
1664 it is ignored.
1665 <P><A HREF="#TBLWQ481">Table 4</A> summarizes the mappings between variables and the arguments
1666 to the <B>uss add</B> command. It is adapted from <A HREF="#TBLWQ466">Table 3</A>, but includes only those variables that take their value
1667 from command line arguments.
1668 <BR>
1669 <P><B><A NAME="TBLWQ481" HREF="auagd004.htm#FT_TBLWQ481">Table 4. Command-line argument sources for uss template variables</A></B><BR>
1670 <TABLE WIDTH="100%" BORDER>
1671 <TR>
1672 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>Variable</B>
1673 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>Command-line Argument</B>
1674 </TD></TR><TR>
1675 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$MTPT
1676 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-mount</B> (for occurrence in <B>V</B> instruction)
1677 </TD></TR><TR>
1678 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$NAME
1679 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-realname</B> if provided; otherwise <B>-user</B>
1680 </TD></TR><TR>
1681 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$PART
1682 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-partition</B>
1683 </TD></TR><TR>
1684 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$PWEXPIRES
1685 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-pwexpires</B>
1686 </TD></TR><TR>
1687 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$SERVER
1688 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-server</B>
1689 </TD></TR><TR>
1690 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$UID
1691 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-uid</B> if provided; otherwise allocated by Protection
1692 Server
1693 </TD></TR><TR>
1694 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$USER
1695 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-user</B>
1696 </TD></TR><TR>
1697 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">$1 through $9
1698 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%"><B>-var</B>
1699 </TD></TR></TABLE>
1700 <P><H3><A NAME="HDRWQ483" HREF="auagd002.htm#ToC_565">To create an AFS account with the uss add command</A></H3>
1701 <OL TYPE=1>
1702 <P><LI>Authenticate as an AFS identity with all of the following
1703 privileges. In the conventional configuration, the <B>admin</B>
1704 user account has them, or you possibly have a personal administrative
1705 account. (To increase cell security, it is best to create special
1706 privileged accounts for use only while performing administrative
1707 procedures; for further discussion, see <A HREF="auagd021.htm#HDRWQ584">An Overview of Administrative Privilege</A>.) If necessary, issue the <B>klog</B>
1708 command to authenticate.
1709 <PRE>   % <B>klog</B> <VAR>admin_user</VAR>
1710    Password: <VAR>admin_password</VAR>
1711 </PRE>
1712 <P>The following list specifies the necessary privileges and indicates how to
1713 check that you have them.
1714 <UL>
1715 <P><LI>Membership in the <B>system:administrators</B> group. If
1716 necessary, issue the <B>pts membership</B> command, which is fully
1717 described in <A HREF="auagd021.htm#HDRWQ587">To display the members of the system:administrators group</A>.
1718 <PRE>   % <B>pts membership system:administrators</B>
1719
1720 </PRE>
1721 <P><LI>Inclusion in the <B>/usr/afs/etc/UserList</B> file. If
1722 necessary, issue the <B>bos listusers</B> command, which is fully
1723 described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1724 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1725 </PRE>
1726 <P><LI>The <TT>ADMIN</TT> flag on the Authentication Database entry.
1727 However, the Authentication Server always prompts you for a password in order
1728 to perform its own authentication. The following instructions direct
1729 you to specify the administrative identity on the <B>uss</B> command line
1730 itself.
1731 <P><LI>The <B>i</B> (<B>insert</B>) and <B>l</B> (<B>lookup</B>)
1732 permissions on the ACL of the directory in which you are mounting the
1733 user's volume. If necessary, issue the <B>fs listacl</B>
1734 command, which is fully described in <A HREF="auagd020.htm#HDRWQ572">Displaying ACLs</A>.
1735 <PRE>   % <B>fs listacl</B> [&lt;<VAR>dir/file path</VAR>>]
1736 </PRE>
1737 <P>Members of the <B>system:administrators</B> group always
1738 implicitly have the <B>a</B> (<B>administer</B>) and by default also
1739 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
1740 <B>fs setacl</B> command to grant other rights as necessary.
1741 </UL>
1742 <P><LI><B>(Optional)</B> Log in as the local superuser
1743 <B>root</B>. This is necessary only if you are creating new files
1744 or directories in the local file system and want to designate an alternate
1745 owner as the object is created. For a discussion of the issues
1746 involved, see <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
1747 <P><LI>Verify the location and functionality of the template file you are
1748 using. For a description of where the <B>uss</B> command
1749 interpreter expects to find the template, see <A HREF="#HDRWQ468">Where to Place Template Files</A>. You can always provide an alternate pathname if you
1750 wish. Also note the variables used in the template, to be sure that you
1751 provide the corresponding arguments on the <B>uss</B> command line.
1752 <P><LI><A NAME="LIWQ484"></A><B>(Optional)</B> Change to the directory where the
1753 template resides. This affects the type of pathname you must type in
1754 Step <A HREF="#LIWQ485">6</A>.
1755 <PRE>   % <B>cd</B> <VAR>template_directory</VAR>
1756 </PRE>
1757 <P><LI><B>(Optional)</B> Run the <B>uss add</B> command with the
1758 <B>-dryrun</B> flag to preview the creation of the account. Note
1759 any error messages and correct the cause before reissuing the command without
1760 the <B>-dryrun</B> flag. The next step describes the <B>uss
1761 add</B> command's syntax. For more information on the
1762 <B>-dryrun</B> flag, see <A HREF="#HDRWQ454">Avoiding and Recovering from Errors and Interrupted Operations</A>.
1763 <A NAME="IDX7716"></A>
1764 <A NAME="IDX7717"></A>
1765 <P><LI><A NAME="LIWQ485"></A>Issue the <B>uss add</B> command to create the
1766 account. Enter the command on a single line; it appears here on
1767 multiple lines only for legibility.
1768 <P>The <B>uss add</B> operation creates an Authentication Database
1769 entry. The Authentication Server performs its own authentication rather
1770 than accepting your existing AFS token. By default, it authenticates
1771 your local (UNIX) identity, which possibly does not correspond to an
1772 AFS-privileged administrator. Include the <B>-admin</B> argument to
1773 name an identity that has the <TT>ADMIN</TT> flag on its Authentication
1774 Database entry. To verify that an entry has the flag, issue the
1775 <B>kas examine</B> command as described in <A HREF="auagd021.htm#HDRWQ590">To check if the ADMIN flag is set</A>.
1776 <PRE>   % <B>uss add</B> <B>-user</B> &lt;<VAR>login&nbsp;name</VAR>>  <B>-admin</B> &lt;<VAR>administrator&nbsp;to&nbsp;authenticate</VAR>>   \
1777              [<B>-realname</B> &lt;<VAR>full&nbsp;name&nbsp;in&nbsp;quotes</VAR>>] [<B>-pass</B> &lt;<VAR>initial&nbsp;passwd</VAR>>]   \
1778              [<B>-pwexpires</B> &lt;<VAR>password&nbsp;expires&nbsp;in&nbsp;[0..254]&nbsp;days&nbsp;(0&nbsp;=>&nbsp;never)</VAR>>]  \
1779              [<B>-server</B> &lt;<VAR>FileServer&nbsp;for&nbsp;home&nbsp;volume</VAR>>]  \
1780              [<B>-partition</B> &lt;<VAR>FileServer's&nbsp;disk&nbsp;partition&nbsp;for&nbsp;home&nbsp;volume</VAR>>]  \
1781              [<B>-mount</B> &lt;<VAR>home&nbsp;directory&nbsp;mount&nbsp;point</VAR>>]  \
1782              [<B>-uid</B> &lt;<VAR>uid&nbsp;to&nbsp;assign&nbsp;the&nbsp;user</VAR>>]  \
1783              [<B>-template</B> &lt;<VAR>pathname&nbsp;of&nbsp;template&nbsp;file</VAR>>]  \
1784              [<B>-var</B> &lt;<VAR>auxiliary&nbsp;argument&nbsp;pairs&nbsp;(Numval)</VAR>><SUP>+</SUP>] [<B>-dryrun</B>] \
1785              [<B>-overwrite</B>]
1786    Administrator's (<VAR>admin_user</VAR>) password: <VAR>admin_password</VAR>
1787 </PRE>
1788 <P>where
1789 <DL>
1790 <P><DT><B>ad
1791 </B><DD>Is the shortest acceptable abbreviation of <B>add</B>.
1792 <P><DT><B>-user
1793 </B><DD>Names the user's Authentication Database and Protection Database
1794 entries. Because it becomes the username (the name under which a user
1795 logs in), it must obey the restrictions that many operating systems impose on
1796 usernames (usually, to contain no more than eight lowercase letters).
1797 Also avoid the following characters: colon (<B>:</B>),
1798 semicolon (<B>;</B>), comma (<B>,</B>), at sign (<B>@</B>),
1799 space, newline, and the period (<B>.</B>), which is conventionally
1800 used only in special administrative names.
1801 <P>This argument provides the value for the $USER variable in the template
1802 file. For suggestions on standardizing usernames, see <A HREF="auagd007.htm#HDRWQ58">Choosing Usernames and Naming Other Account Components</A>.
1803 <P><DT><B>-admin
1804 </B><DD>Names an administrative account that has the <TT>ADMIN</TT> flag on its
1805 Authentication Database entry, such as <B>admin</B>. The password
1806 prompt echoes it as <VAR>admin_user</VAR>. Enter the appropriate password
1807 as <VAR>admin_password</VAR>.
1808 <P><DT><B>-realname
1809 </B><DD>Specifies the user's actual full name. If it contains spaces
1810 or punctuation, surround it with double quotes. If you do not provide
1811 it, it defaults to the username provided with the <B>-user</B>
1812 argument.
1813 <P>This argument provides the value for the $NAME variable in the template
1814 file. For information about using this argument and variable as part of
1815 an automated process for creating entries in a local password file such as
1816 <B>/etc/passwd</B>, see <A HREF="#HDRWQ458">Creating a Common Source Password File</A>.
1817 <P><DT><B>-pass
1818 </B><DD>Specifies the user's initial password. Although the AFS
1819 commands that handle passwords accept strings of virtually unlimited length,
1820 it is best to use a password of eight characters or less, which is the maximum
1821 length that many applications and utilities accept.
1822 <P>Possible choices for initial passwords include the username, a string of
1823 digits such as those from a Social Security number, or a standard string such
1824 as <B>changeme</B>, which is the default if you do not provide this
1825 argument. There is no corresponding variable in the template
1826 file.
1827 <P>Instruct users to change their passwords to a truly secret string as soon
1828 as they authenticate with AFS for the first time. The <I>IBM AFS User
1829 Guide</I> explains how to use the <B>kpasswd</B> command to change an
1830 AFS password.
1831 <P><DT><B>-pwexpires
1832 </B><DD>Sets the number of days after a user's password is changed that it
1833 remains valid. Provide an integer from the range <B>1</B> through
1834 <B>254</B> to specify the number of days until expiration, or the value
1835 <B>0</B> to indicate that the password never expires (the default if you
1836 do not provide this argument). When the password becomes invalid
1837 (expires), the user is unable to authenticate, but has 30 more days in which
1838 to issue the <B>kpasswd</B> command to change the password; after
1839 that, only an administrator can change it.
1840 <P>This argument provides the value for the $PWEXPIRES variable in the
1841 template file.
1842 <P><DT><B>-server
1843 </B><DD>Names the file server machine on which to create the new user's home
1844 volume. It is best to provide a fully qualified hostname (for example,
1845 <B>fs1.abc.com</B>), but an abbreviated form is acceptable
1846 provided that the cell's naming service is available to resolve it when
1847 you issue the <B>uss add</B> command.
1848 <P>This argument provides the value for the $SERVER variable in the template
1849 file. To avoid having to type a fully qualified hostname on the command
1850 line, combine the $SERVER variable with a constant (for example, the
1851 cell's domain name) in the <VAR>server</VAR> field of the <B>V</B>
1852 instruction in the template file. For an example, see <A HREF="#HDRWQ473">Creating a Volume with the V Instruction</A>.
1853 <P><DT><B>-partition
1854 </B><DD>Specifies the partition on which to create the user's home
1855 volume; it must be on the file server machine named by the
1856 <B>-server</B> argument. Identify the partition by its complete
1857 name (for example, <B>/vicepa</B>), or use one of the abbreviations listed
1858 in <A HREF="auagd023.htm#HDRWQ615">Rules for Using Abbreviations and Aliases</A>.
1859 <P>This argument provides the value for the $PART variable in the template
1860 file.
1861 <P><DT><B>-mount
1862 </B><DD>Specifies the pathname for the user's home directory in the
1863 cell's read/write filespace. Partial pathnames are interpreted
1864 relative to the current working directory.
1865 <P>This argument provides the value for the $MTPT variable in the template
1866 file, but only when it appears in the <B>V</B> instruction's
1867 <VAR>mount_point</VAR> field. When the $MTPT variable appears in any
1868 subsequent instructions, it takes its value from the <B>V</B>
1869 instruction's <VAR>mount_point</VAR> field, rather than directly from this
1870 argument. For more details, and for suggestions about how to use this
1871 argument and the $MTPT variable, see <A HREF="#HDRWQ473">Creating a Volume with the V Instruction</A>.
1872 <P><DT><B>-uid
1873 </B><DD>Specifies a positive integer other than <B>0</B> (zero) to assign as
1874 the user's AFS UID. It is best to omit this argument and allow the
1875 Protection Server to assign an AFS UID that is one greater than the current
1876 value of the <TT>max user id</TT> counter. (To display the counter,
1877 use the <B>pts listmax</B> command as described in <A HREF="auagd019.htm#HDRWQ561">To display the AFS ID counters</A>.)
1878 <P>If you have a reason to use this argument (perhaps because the user already
1879 has a UNIX UID), first use the <B>pts examine</B> command to verify that
1880 there is no existing account with the desired AFS UID; if there is, the
1881 account creation process terminates with an error.
1882 <P>This argument provides the value for the $UID variable in the template
1883 file.
1884 <P><DT><B>-template
1885 </B><DD>Specifies the pathname of the template file. If you omit this
1886 argument, the command interpreter searches for a template file called
1887 <B>uss.template</B> in each of the following directories in
1888 turn:
1889 <OL TYPE=a>
1890 <P><LI>The current working directory
1891 <P><LI><B>/afs/</B><VAR>cellname</VAR><B>/common/uss</B>, where
1892 <VAR>cellname</VAR> names the local cell
1893 <P><LI><B>/etc</B>
1894 </OL>
1895 <P>If you specify a filename other than <B>uss.template</B> but
1896 without a pathname, the command interpreter searches for it in the indicated
1897 directories. If you provide a full or partial pathname, the command
1898 interpreter consults the specified file only; it interprets partial
1899 pathnames relative to the current working directory.
1900 <P>If the specified template file is empty (zero-length), the command creates
1901 Protection and Authentication Database entries only.
1902 <P>To learn how to construct a template file, see <A HREF="#HDRWQ463">Constructing a uss Template File</A>.
1903 <P><DT><B>-var
1904 </B><DD>Specifies values for each of the number variables $1 through $9 that can
1905 appear in the template file. You can use the number variables to assign
1906 values to variables in the <B>uss</B> template file that are not part of
1907 the standard set.
1908 <P>For each instance of this argument, provide two parts in the indicated
1909 order, separated by a space:
1910 <UL>
1911 <P><LI>The integer from the range <B>1</B> through <B>9</B> that matches
1912 the variable in the template file. Do not precede it with a dollar
1913 sign.
1914 <P><LI>A string of alphanumeric characters to assign as the value of the
1915 variable.
1916 </UL>
1917 <P>To learn about suggested uses for the number variables, see the description
1918 of the <B>V</B> instruction's <VAR>quota</VAR> field in <A HREF="#HDRWQ473">Creating a Volume with the V Instruction</A>.
1919 <P><DT><B>-dryrun
1920 </B><DD>Reports actions that the command interpreter needs to perform to run the
1921 command, without actually performing them.
1922 <P><DT><B>-overwrite
1923 </B><DD>Overwrites any directories, files, and links that exist in the file system
1924 and for which there are definitions in <B>D</B>, <B>E</B>,
1925 <B>F</B>, <B>L</B>, or <B>S</B> instructions in the template file
1926 named by the <B>-template</B> argument. If you omit this flag, the
1927 command interpreter prompts you once for confirmation that you want to
1928 overwrite all such elements.
1929 </DL>
1930 <P><LI>If the new user home directory resides in a replicated volume, use the
1931 <B>vos release</B> command to release the volume, as described in <A HREF="auagd010.htm#HDRWQ194">To replicate a read/write volume (create a read-only volume)</A>.
1932 <PRE>
1933    % <B>vos release</B> &lt;<VAR>volume&nbsp;name&nbsp;or&nbsp;ID</VAR>>
1934
1935 </PRE>
1936 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">This step can be necessary even if the home directory's parent directory
1937 is not itself a mount point for a replicated volume (and is easier to overlook
1938 in that case). For example, the ABC Corporation template puts the mount
1939 points for user volumes in the <B>/afs/abc.com/usr</B>
1940 directory. Because that is a regular directory rather than a mount
1941 point, it resides in the <B>root.cell</B> volume mounted at the
1942 <B>/afs/abc.com</B> directory. That volume is replicated, so
1943 after changing it by creating a new mount point the administrator must issue
1944 the <B>vos release</B> command.
1945 </TD></TR></TABLE>
1946 <P><LI>Create an entry for the new user in the local password file
1947 (<B>/etc/passwd</B> or equivalent) on each AFS client machine that he or
1948 she can log into. For suggestions on automating this step, see <A HREF="#HDRWQ458">Creating a Common Source Password File</A>.
1949 <P>Even if you do not use the automated method, set the user's UNIX UID
1950 to match the AFS UID assigned automatically by the Protection Server or
1951 assigned with the <B>-uid</B> argument. The new user's AFS UID
1952 appears in the trace produced by the <B>uss add</B> output, or you can use
1953 the <B>pts examine</B> command to display it, as described in <A HREF="auagd019.htm#HDRWQ537">To display a Protection Database entry</A>.
1954 </OL>
1955 <A NAME="IDX7718"></A>
1956 <A NAME="IDX7719"></A>
1957 <A NAME="IDX7720"></A>
1958 <A NAME="IDX7721"></A>
1959 <A NAME="IDX7722"></A>
1960 <A NAME="IDX7723"></A>
1961 <A NAME="IDX7724"></A>
1962 <HR><H2><A NAME="HDRWQ486" HREF="auagd002.htm#ToC_566">Deleting Individual Accounts with the uss delete Command</A></H2>
1963 <P>The <B>uss delete</B> command deletes an AFS user
1964 account according to the arguments you provide on the command line;
1965 unlike the <B>uss add</B> command, it does not use a template file.
1966 When you issue the command, the <B>uss</B> command interpreter contacts
1967 various AFS servers to perform the following actions:
1968 <UL>
1969 <P><LI>Remove the mount point for the user's home volume
1970 <P><LI>Remove the user's home volume and delete the associated VLDB entry,
1971 unless you include the <B>-savevolume</B> flag
1972 <P><LI>Delete the user's Authentication Database entry
1973 <P><LI>Delete the user's Protection Database entry
1974 </UL>
1975 <P>Before issuing the <B>uss delete</B> command, you can also perform the
1976 following optional tasks:
1977 <UL>
1978 <P><LI>Copy the user's home volume to tape or another permanent medium and
1979 record the username and UID on a reserved list. This information
1980 enables you to restore the user's account easily if he or she returns to
1981 your cell. For information about using the AFS Backup System to back up
1982 volumes, see <A HREF="auagd011.htm#HDRWQ248">Configuring the AFS Backup System</A> and <A HREF="auagd012.htm#HDRWQ283">Backing Up and Restoring AFS Data</A>.
1983 <P><LI>If the user has exclusive use of any other volumes (such as a volume for
1984 storing project-related data), make a backup copy of each one and then remove
1985 it and its mount point as instructed in <A HREF="auagd010.htm#HDRWQ235">Removing Volumes and their Mount Points</A>.
1986 <P><LI>Use the <B>pts listowned</B> command to display any groups that the
1987 user owns; instructions appear in <A HREF="auagd019.htm#HDRWQ540">To list the groups that a user or group owns</A>. Decide whether to use the <B>pts delete</B>
1988 command to remove the groups or the <B>pts chown</B> command to transfer
1989 ownership to another user or group. Instructions appear in <A HREF="auagd019.htm#HDRWQ553">To delete Protection Database entries</A> and <A HREF="auagd019.htm#HDRWQ555">To change a group's owner</A>. Alternatively, you can have the
1990 user remove or transfer ownership of the groups before leaving. A group
1991 that remains in the Protection Database after its owner is removed is
1992 considered <VAR>orphaned</VAR>, and only members of the
1993 <B>system:administrators</B> group can administer it.
1994 </UL>
1995 <P>You can automate some of these tasks by including <B>exec</B>
1996 instructions in the bulk input file and using the <B>uss bulk</B> command
1997 to delete the account. See <A HREF="#HDRWQ488">Creating and Deleting Multiple Accounts with the uss bulk Command</A>.
1998 <P><H3><A NAME="HDRWQ487" HREF="auagd002.htm#ToC_567">To delete an AFS account</A></H3>
1999 <OL TYPE=1>
2000 <P><LI>Authenticate as an AFS identity with all of the following
2001 privileges. In the conventional configuration, the <B>admin</B>
2002 user account has them, or you possibly have a personal administrative
2003 account. (To increase cell security, it is best to create special
2004 privileged accounts for use only while performing administrative
2005 procedures; for further discussion, see <A HREF="auagd021.htm#HDRWQ584">An Overview of Administrative Privilege</A>.) If necessary, issue the <B>klog</B>
2006 command to authenticate.
2007 <PRE>   % <B>klog</B> <VAR>admin_user</VAR>
2008    Password: <VAR>admin_password</VAR>
2009 </PRE>
2010 <P>The following list specifies the necessary privileges and indicates how to
2011 check that you have them.
2012 <UL>
2013 <P><LI>Membership in the <B>system:administrators</B> group. If
2014 necessary, issue the <B>pts membership</B> command, which is fully
2015 described in <A HREF="auagd021.htm#HDRWQ587">To display the members of the system:administrators group</A>.
2016 <PRE>   % <B>pts membership system:administrators</B>
2017
2018 </PRE>
2019 <P><LI>Inclusion in the <B>/usr/afs/etc/UserList</B> file. If
2020 necessary, issue the <B>bos listusers</B> command, which is fully
2021 described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2022 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2023 </PRE>
2024 <P><LI>The <TT>ADMIN</TT> flag on the Authentication Database entry.
2025 However, the Authentication Server always prompts you for a password in order
2026 to perform its own authentication. The following instructions direct
2027 you to specify the administrative identity on the <B>uss</B> command line
2028 itself.
2029 <P><LI>The <B>d</B> (<B>delete</B>) permission on the ACL of the
2030 directory that houses the user's home directory. If necessary,
2031 issue the <B>fs listacl</B> command, which is fully described in <A HREF="auagd020.htm#HDRWQ572">Displaying ACLs</A>.
2032 <PRE>   % <B>fs listacl</B> [&lt;<VAR>dir/file path</VAR>>]
2033 </PRE>
2034 <P>Members of the <B>system:administrators</B> group always
2035 implicitly have the <B>a</B> (<B>administer</B>) and by default also
2036 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
2037 <B>fs setacl</B> command to grant other rights as necessary.
2038 </UL>
2039 <P><LI>Consider and resolve the issues discussed in the introduction to this
2040 section concerning the continued maintenance of a deleted user's account
2041 information, owned groups, and volumes.
2042 <P><LI><B>(Optional)</B> Run the <B>uss delete</B> command with the
2043 <B>-dryrun</B> flag to preview the deletion of the account. Note
2044 any error messages and correct the cause before reissuing the command without
2045 the <B>-dryrun</B> flag. The next step describes the <B>uss
2046 delete</B> command's syntax.
2047 <A NAME="IDX7725"></A>
2048 <A NAME="IDX7726"></A>
2049 <P><LI>Issue the <B>uss delete</B> command to delete the account.
2050 Enter the command on a single line; it appears here on multiple lines
2051 only for legibility.
2052 <P>The delete operation always removes the user's entry from the
2053 Authentication Database. The Authentication Server performs its own
2054 authentication rather than accepting your existing AFS token. By
2055 default, it authenticates your local (UNIX) identity, which possibly does not
2056 correspond to an AFS-privileged administrator. Include the
2057 <B>-admin</B> argument to name an identity that has the <TT>ADMIN</TT>
2058 flag on its Authentication Database entry. To verify that an entry has
2059 the flag, issue the <B>kas examine</B> command as described in <A HREF="auagd021.htm#HDRWQ590">To check if the ADMIN flag is set</A>.
2060 <PRE>   % <B>uss delete</B> <B>-user</B> &lt;<VAR>login&nbsp;name</VAR>>  \
2061                 <B>-mountpoint</B> &lt;<VAR>mountpoint&nbsp;for&nbsp;user's&nbsp;volume</VAR>>  \
2062                 [<B>-savevolume</B>]  <B>-admin </B> &lt;<VAR>administrator&nbsp;to&nbsp;authenticate</VAR>>  \
2063                 [<B>-dryrun</B>]
2064    Administrator's (<VAR>admin_user</VAR>) password: <VAR>admin_password</VAR>
2065 </PRE>
2066 <P>where
2067 <DL>
2068 <P><DT><B>d
2069 </B><DD>Is the shortest acceptable abbreviation of <B>delete</B>.
2070 <P><DT><B>-user
2071 </B><DD>Names the entry to delete from the Protection and Authentication
2072 Databases.
2073 <P><DT><B>-mountpoint
2074 </B><DD>Specifies the pathname of the mount point to delete (the user's home
2075 directory). Unless the <B>-savevolume</B> argument is included, the
2076 volume mounted there is also deleted from the file server machine where it
2077 resides, as is its record from the VLDB. Partial pathnames are
2078 interpreted relative to the current working directory.
2079 <P>Specify the read/write path to the mount point, to avoid the failure that
2080 results when you attempt to delete a mount point from a read-only
2081 volume. By convention, you indicate the read/write path by placing a
2082 period before the cell name at the pathname's second level (for example,
2083 <B>/afs/.abc.com</B>). For further discussion of the
2084 concept of read/write and read-only paths through the filespace, see <A HREF="auagd010.htm#HDRWQ208">Mounting Volumes</A>.
2085 <P><DT><B>-savevolume
2086 </B><DD>Retains the user's volume and VLDB entry.
2087 <P><DT><B>-admin
2088 </B><DD>Names an administrative account that has the <TT>ADMIN</TT> flag on its
2089 Authentication Database entry, such as <B>admin</B>. The password
2090 prompt echoes it as <VAR>admin_user</VAR>. Enter the appropriate password
2091 as <VAR>admin_password</VAR>.
2092 <P><DT><B>-dryrun
2093 </B><DD>Reports actions that the command interpreter needs to perform to run the
2094 command, without actually performing them.
2095 </DL>
2096 <P><LI>If the deleted user home directory resided in a replicated volume, use the
2097 <B>vos release</B> command to release the volume, as described in <A HREF="auagd010.htm#HDRWQ194">To replicate a read/write volume (create a read-only volume)</A>.
2098 <PRE>
2099    % <B>vos release</B> &lt;<VAR>volume&nbsp;name&nbsp;or&nbsp;ID</VAR>>
2100
2101 </PRE>
2102 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">This step can be necessary even if the home directory's parent directory
2103 is not itself a mount point for a replicated volume (and is easier to overlook
2104 in that case). For example, the ABC Corporation template puts the mount
2105 points for user volumes in the <B>/afs/abc.com/usr</B>
2106 directory. Because that is a regular directory rather than a mount
2107 point, it resides in the <B>root.cell</B> volume mounted at the
2108 <B>/afs/abc.com</B> directory. That volume is replicated, so
2109 after changing it by deleting a mount point the administrator must issue the
2110 <B>vos release</B> command.
2111 </TD></TR></TABLE>
2112 <P><LI>Delete the user's entry from the local password file
2113 (<B>/etc/passwd</B> or equivalent) of each client machine. If you
2114 use the AFS <B>package</B> utility, it is sufficient to remove the entry
2115 from the common source version of the file. If you intend to reactivate
2116 the user's account in the future, it is simpler to comment out the entry
2117 or place an asterisk (*) in the password field.
2118 </OL>
2119 <A NAME="IDX7727"></A>
2120 <A NAME="IDX7728"></A>
2121 <A NAME="IDX7729"></A>
2122 <A NAME="IDX7730"></A>
2123 <A NAME="IDX7731"></A>
2124 <HR><H2><A NAME="HDRWQ488" HREF="auagd002.htm#ToC_568">Creating and Deleting Multiple Accounts with the uss bulk Command</A></H2>
2125 <P>The <B>uss bulk</B> command allows you to create and
2126 delete many accounts at once. Before executing the command, you must
2127 <UL>
2128 <P><LI>Construct a template if you plan to create any accounts, just as you must
2129 do before running the <B>uss add</B> command. The same template
2130 applies to all accounts created by a single <B>uss bulk</B>
2131 command.
2132 <P><LI>Construct a bulk input file of instructions that create and delete
2133 accounts and execute any related commands, as described in <A HREF="#HDRWQ489">Constructing a Bulk Input File</A>.
2134 </UL>
2135 <A NAME="IDX7732"></A>
2136 <A NAME="IDX7733"></A>
2137 <P><H3><A NAME="HDRWQ489" HREF="auagd002.htm#ToC_569">Constructing a Bulk Input File</A></H3>
2138 <P>You can include five types of instructions in a bulk input
2139 file: <B>add</B>, <B>delete</B>, <B>exec</B>,
2140 <B>savevolume</B>, and <B>delvolume</B>. The following sections
2141 discuss their uses.
2142 <P><B>Creating a User Account with the add Instruction</B>
2143 <P>Each <B>add</B> instruction creates a single user account, and so is
2144 basically the equivalent of issuing one <B>uss add</B> command.
2145 There is no limit to the number of <B>add</B> instructions in the bulk
2146 input file.
2147 <P>As indicated by the following syntax statement, the order of the
2148 instruction's fields matches the order of arguments to the <B>uss
2149 add</B> command (though some of the command's arguments do not have a
2150 corresponding field). Like the <B>uss add</B> command's
2151 arguments, many of the fields provide a value for a variable in the
2152 <B>uss</B> template file. Each instruction must be a single line in
2153 the file (have a newline character only at its end); it appears on
2154 multiple lines here only for legibility.
2155 <PRE>   <B>add</B> <VAR>username</VAR>[<B>:</B><VAR>full_name</VAR>][<B>:</B><VAR>initial_password</VAR>][<B>:</B><VAR>password_expires</VAR>]
2156    [<B>:</B><VAR>file_server</VAR>][<B>:</B><VAR>partition</VAR>][<B>:</B><VAR>mount_point</VAR>][<B>:</B><VAR>uid</VAR>]
2157    [<B>:</B><VAR>var1</VAR>][<B>:</B><VAR>var2</VAR>][<B>:</B><VAR>var3</VAR>][<B>:</B><VAR>var4</VAR>][<B>:</B><VAR>var5</VAR>][<B>:</B><VAR>var6</VAR>][<B>:</B><VAR>var7</VAR>][<B>:</B><VAR>var8</VAR>][<B>:</B><VAR>var9</VAR>][<B>:</B>]
2158 </PRE>
2159 <P>For a complete description of the acceptable values in each field, see the
2160 <B>uss Bulk Input File</B> reference page in the <I>IBM AFS
2161 Administration Reference</I>, or the description of the corresponding
2162 arguments to the <B>uss add</B> command, in <A HREF="#HDRWQ483">To create an AFS account with the uss add command</A>. Following are some basic notes:
2163 <UL>
2164 <P><LI>Begin the line with the string <B>add</B> only, not <B>uss
2165 add</B>.
2166 <P><LI>Only the first argument, <VAR>username</VAR>, is required. It
2167 corresponds to the <B>-user</B> argument to the <B>uss add</B>
2168 command.
2169 <P><LI>Do not surround the <VAR>full_name</VAR> value with double quotes, even
2170 though you must use them around the value for the <B>-realname</B>
2171 argument to the <B>uss add</B> command.
2172 <P><LI>If you want to omit a value for an argument, indicate an empty field by
2173 using two colons with nothing between them. Leaving a field empty is
2174 acceptable if the corresponding command line argument is optional or if the
2175 corresponding variable does not appear in the template file. For every
2176 field that precedes the last one to which you assign an actual value, you must
2177 either provide a value or indicate an empty field. It is acceptable,
2178 but not necessary, to indicate empty fields after the last one in which you
2179 assign a value.
2180 <P><LI>After the last field, end the line with either a colon and newline
2181 character (<B>&lt;Return></B>), or a newline alone.
2182 <P><LI>The final nine fields are for assigning values to the number variables ($1
2183 through $9), with the fields listed in increasing numerical order.
2184 Specify the value only, not the variable number.
2185 </UL>
2186 <P><B>Deleting a User Account with the delete Instruction</B>
2187 <P>Each <B>delete</B> instruction deletes a single user account, and so is
2188 basically the equivalent of issuing one <B>uss delete</B> command.
2189 There is no limit to the number of <B>delete</B> instructions in the bulk
2190 input file.
2191 <P>Like all instructions in the bulk input file, each <B>delete</B>
2192 instruction must be a single line in the file (have a newline character only
2193 at its end), even though it can cover multiple lines on a display
2194 screen. The curly braces (<B>{  }</B>) indicate two mutually
2195 exclusive choices.
2196 <PRE>   <B>delete</B> <VAR>username</VAR><B>:</B><VAR>mount_point_path</VAR>[:{ <B>savevolume</B> | <B>delvolume</B> }][<B>:</B>]
2197 </PRE>
2198 <P>For a complete description of the acceptable values in each field, see the
2199 <B>uss Bulk Input File</B> reference page in the <I>IBM AFS
2200 Administration Reference</I> or the description of the corresponding
2201 arguments to the <B>uss delete</B> command, in <A HREF="#HDRWQ487">To delete an AFS account</A>. Following are some basic notes:
2202 <UL>
2203 <P><LI>Begin the line with the string <B>delete</B> only, not <B>uss
2204 delete</B>.
2205 <P><LI>The first two arguments, <VAR>username</VAR> and <VAR>mount_point_path</VAR>,
2206 are required. They correspond to the <B>-user</B> and
2207 <B>-mountpoint</B> arguments to the <B>uss delete</B> command.
2208 <P><LI>The third field, which is optional, controls whether the user's home
2209 volume is removed from the file server where it resides, along with the
2210 corresponding VLDB entry. There are three possible values:
2211 <UL>
2212 <P><LI>No value treats the volume and VLDB entry according to the prevailing
2213 default, which is established by a preceding <B>savevolume</B> or
2214 <B>delvolume</B> instruction in the template file. See the
2215 following discussion of those instructions to learn how the default is
2216 set.
2217 <P><LI>The string <B>savevolume</B> preserves the volume and VLDB entry,
2218 overriding the default.
2219 <P><LI>The string <B>delvolume</B> removes the volume and VLDB entry,
2220 overriding the default.
2221 </UL>
2222 <P><LI>After the last field, end the line with either a colon and newline
2223 character (<B>&lt;Return></B>), or a newline alone.
2224 </UL>
2225 <P><B>Running a Command or Script with the exec Instruction</B>
2226 <P>The <B>exec</B> instruction runs the indicated AFS command, compiled
2227 program, or UNIX shell script or command. The command processor assumes
2228 the AFS and local identities of the issuer of the <B>uss bulk</B> command,
2229 who must have the privileges required to run the command.
2230 <P>The instruction's syntax is as follows:
2231 <PRE>   <B>exec</B> <VAR>command</VAR>
2232 </PRE>
2233 <P>It is not necessary to surround the <VAR>command</VAR> string with double
2234 quotes (" ") or other delimiters.
2235 <P><B>Setting the Default Treatment of Volumes with the delvolume and
2236 savevolume Instructions</B>
2237 <P>The <B>savevolume</B> and <B>delvolume</B> instructions set the
2238 default treatment of volumes referenced by the <B>delete</B> instructions
2239 that follow them in the bulk input file. Their syntax is as
2240 follows:
2241 <PRE>   <B>savevolume</B>
2242    <B>delvolume</B>
2243 </PRE>
2244 <P>Both instructions are optional and take no arguments. If neither
2245 appears in the bulk input file, then by default all volumes and VLDB entries
2246 referenced by <B>delete</B> instructions are removed. If the
2247 <B>savevolume</B> instruction appears in the file, it prevents the removal
2248 of the volume and VLDB entry referenced by all subsequent <B>delete</B>
2249 instructions in the file. The <B>delvolume</B> instruction
2250 explicitly establishes the default (which is deletion) for subsequent
2251 <B>delete</B> instructions.
2252 <P>The effect of either instruction lasts until the end of the bulk input
2253 file, or until its opposite appears. To override the prevailing default
2254 for a particular <B>delete</B> instruction, put the <B>savevolume</B>
2255 or <B>delvolume</B> string in the instruction's third field.
2256 (You can also use multiple instances of the <B>savevolume</B> and
2257 <B>delvolume</B> instructions to toggle back and forth between default
2258 preservation and deletion of volumes.)
2259 <P><H3><A NAME="Header_570" HREF="auagd002.htm#ToC_570">Example Bulk Input File Instructions</A></H3>
2260 <P>To create an authentication-only account, use an <B>add</B>
2261 instruction like the following example, which includes only the first
2262 (<VAR>username</VAR>) argument. The user's real name is set to match
2263 the username (<B>anderson</B>) and her initial password is set to the
2264 string <B>changeme</B>.
2265 <PRE>   add anderson
2266 </PRE>
2267 <P>The following example also creates an authentication-only account, but sets
2268 nondefault values for the real name and initial password.
2269 <PRE>   add smith:John Smith:js_pswd
2270 </PRE>
2271 <P>The next two example <B>add</B> instructions require that the
2272 administrator of the ABC Corporation cell (<B>abc.com</B>) has
2273 written a <B>uss</B> template file with the following <B>V</B>
2274 instruction in it:
2275 <PRE>   V user.$USER $SERVER.abc.com /vicep$PART 10000 /afs/.abc.com/usr/$3/$USER \
2276        $UID $USER all
2277 </PRE>
2278 <P>To create accounts for users named John Smith from the Marketing Department
2279 and Pat Jones from the Finance Department, the appropriate <B>add</B>
2280 instructions in the bulk input file are as follows:
2281 <PRE>   add smith:John Smith:::fs1:a:::::marketing
2282    add jones:Pat Jones:::fs3:c:::::finance
2283 </PRE>
2284 <P>The new account for Smith consists of Protection and Authentication
2285 Database entries called <B>smith</B>. His initial password is the
2286 default string <B>changeme</B>, and the Protection Server generates his
2287 AFS UID. His home volume, called <B>user.smith</B>, has a
2288 10,000 KB quota, resides on partition <B>/vicepa</B> of file server
2289 machine <B>fs1.abc.com</B>, and is mounted at
2290 <B>/afs/.abc.com/usr/marketing/smith</B>. The final
2291 <B>$UID $USER all</B> part of the <B>V</B> instruction gives him
2292 ownership of his home directory and all permissions on its ACL. The
2293 account for <B>jones</B> is similar, except that it resides on partition
2294 <B>/vicepc</B> of file server machine <B>fs3.abc.com</B>
2295 and is mounted at
2296 <B>/afs/.abc.com/usr/finance/jones</B>.
2297 <P>Notice that the fields corresponding to <VAR>mount_point</VAR>, <VAR>uid</VAR>,
2298 <VAR>var1</VAR>, and <VAR>var2</VAR> are empty (between the values <TT>a</TT>
2299 and <TT>marketing</TT> on the first example line) because the corresponding
2300 variables do not appear in the <B>V</B> instruction in the template
2301 file. The <VAR>initial_passwd</VAR> and <VAR>password_expires</VAR> fields
2302 are also empty.
2303 <P>If you wish, you can specify values or empty fields for all nine number
2304 variables in an <B>add</B> instruction. In that case, the bulk
2305 input file instructions are as follows:
2306 <PRE>   add smith:John Smith:::fs1:a:::::marketing::::::
2307    add jones:Pat Jones:::fs3:c:::::finance::::::
2308 </PRE>
2309 <P>The following example is a section of a bulk input file with a number of
2310 <B>delete</B> instructions and a <B>savevolume</B> instruction.
2311 Because the first three instructions appear before the <B>savevolume</B>
2312 instruction and their third field is blank, the corresponding volumes and VLDB
2313 entries are removed. The <B>delete</B> instruction for user
2314 <B>terry</B> follows the <B>savevolume</B> instruction, so her volume
2315 is not removed, but the volume for user <B>johnson</B> is, because the
2316 <B>delvolume</B> string in the third field of the <B>delete</B>
2317 instruction overrides the current default.
2318 <PRE>   delete smith:/afs/abc.com/usr/smith
2319    delete pat:/afs/abc.com/usr/pat
2320    delete rogers:/afs/abc.com/usr/rogers
2321    savevolume
2322    delete terry:/afs/abc.com/usr/terry
2323    delete johnson:/afs/abc.com/usr/johnson:delvolume
2324 </PRE>
2325 <P>The following example <B>exec</B> instruction is useful as a separator
2326 between a set of <B>add</B> instructions and a set of <B>delete</B>
2327 instructions. It generates a message on the standard output stream that
2328 informs you of the <B>uss bulk</B> command's progress.
2329 <PRE>   exec echo "Additions completed; beginning deletions..."
2330 </PRE>
2331 <P><H3><A NAME="Header_571" HREF="auagd002.htm#ToC_571">To create and delete multiple AFS user accounts</A></H3>
2332 <OL TYPE=1>
2333 <P><LI>Authenticate as an AFS identity with all of the following
2334 privileges. In the conventional configuration, the <B>admin</B>
2335 user account has them, or you possibly have a personal administrative
2336 account. (To increase cell security, it is best to create special
2337 privileged accounts for use only while performing administrative
2338 procedures; for further discussion, see <A HREF="auagd021.htm#HDRWQ584">An Overview of Administrative Privilege</A>.) If necessary, issue the <B>klog</B>
2339 command to authenticate.
2340 <PRE>   % <B>klog</B> <VAR>admin_user</VAR>
2341    Password: <VAR>admin_password</VAR>
2342 </PRE>
2343 <P>The following list specifies the necessary privileges and indicates how to
2344 check that you have them.
2345 <UL>
2346 <P><LI>Membership in the <B>system:administrators</B> group. If
2347 necessary, issue the <B>pts membership</B> command, which is fully
2348 described in <A HREF="auagd021.htm#HDRWQ587">To display the members of the system:administrators group</A>.
2349 <PRE>   % <B>pts membership system:administrators</B>
2350
2351 </PRE>
2352 <P><LI>Inclusion in the <B>/usr/afs/etc/UserList</B> file. If
2353 necessary, issue the <B>bos listusers</B> command, which is fully
2354 described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2355 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2356 </PRE>
2357 <P><LI>The <TT>ADMIN</TT> flag on the Authentication Database entry.
2358 However, the Authentication Server always prompts you for a password in order
2359 to perform its own authentication. The following instructions direct
2360 you to specify the administrative identity on the <B>uss</B> command line
2361 itself.
2362 <P><LI>The <B>d</B> (<B>delete</B>), <B>i</B> (<B>insert</B>) and
2363 <B>l</B> (<B>lookup</B>) permissions on the ACL of the parent
2364 directory for each volume mount point. If necessary, issue the <B>fs
2365 listacl</B> command, which is fully described in <A HREF="auagd020.htm#HDRWQ572">Displaying ACLs</A>.
2366 <PRE>   % <B>fs listacl</B> [&lt;<VAR>dir/file path</VAR>>]
2367 </PRE>
2368 <P>Members of the <B>system:administrators</B> group always
2369 implicitly have the <B>a</B> (<B>administer</B>) and by default also
2370 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
2371 <B>fs setacl</B> command to grant other rights as necessary.
2372 </UL>
2373 <P><LI><B>(Optional.)</B> Log in as the local superuser
2374 <B>root</B>. This is necessary only if you are creating new files
2375 or directories in the local file system and want to designate an alternate
2376 owner as the object is created. For a discussion of the issues
2377 involved, see <A HREF="#HDRWQ470">About Creating Local Disk Directories and Files</A>.
2378 <P><LI>If the bulk input file includes <B>add</B> instructions, verify the
2379 location and functionality of the template you are using. For a
2380 description of where the <B>uss</B> command interpreter expects to find
2381 the template, see <A HREF="#HDRWQ468">Where to Place Template Files</A>. You can always provide an alternate pathname if you
2382 wish. Also note which variables appear in the template, to be sure that
2383 you provide the corresponding arguments in the <B>add</B> instruction or
2384 on the <B>uss bulk</B> command line.
2385 <P><LI>Create a bulk input file that complies with the rules listed in <A HREF="#HDRWQ489">Constructing a Bulk Input File</A>. It is simplest to put the file in the same directory
2386 as the template file you are using.
2387 <P><LI><B>(Optional.)</B> Change to the directory where the bulk input
2388 file and template file reside.
2389 <PRE>   % <B>cd</B> <VAR>template_directory</VAR>
2390 </PRE>
2391 <A NAME="IDX7734"></A>
2392 <A NAME="IDX7735"></A>
2393 <P><LI><A NAME="LIWQ490"></A>Issue the <B>uss bulk</B> command to create or delete
2394 accounts, or both. Enter the command on a single line; it appears
2395 here on multiple lines only for legibility.
2396 <P>The bulk operation always manipulates user entries in the Authentication
2397 Database. The Authentication Server performs its own authentication
2398 rather than accepting your existing AFS token. By default, it
2399 authenticates your local (UNIX) identity, which possibly does not correspond
2400 to an AFS-privileged administrator. Include the <B>-admin</B>
2401 argument to name an identity that has the <TT>ADMIN</TT> flag on its
2402 Authentication Database entry. To verify that an entry has the flag,
2403 issue the <B>kas examine</B> command as described in <A HREF="auagd021.htm#HDRWQ590">To check if the ADMIN flag is set</A>.
2404 <PRE>   % <B>uss bulk</B> &lt;<VAR>bulk&nbsp;input&nbsp;file</VAR>>  \
2405               [<B>-template</B> &lt;<VAR>pathname&nbsp;of&nbsp;template&nbsp;file</VAR>>]  \
2406               <B>-admin</B> &lt;<VAR>administrator&nbsp;to&nbsp;authenticate</VAR>>  \
2407               [<B>-dryrun</B>] [<B>-overwrite</B>]  \
2408               [<B>-pwexpires</B> &lt;<VAR>password&nbsp;expires&nbsp;in&nbsp;[0..254]&nbsp;days&nbsp;(0&nbsp;=>&nbsp;never)></VAR>]  \
2409               [<B>-pipe</B>]
2410    Administrator's (<VAR>admin_user</VAR>) password: <VAR>admin_password</VAR>
2411 </PRE>
2412 <P>where
2413 <DL>
2414 <P><DT><B><B>b</B>
2415 </B><DD>Is the shortest acceptable abbreviation of <B>bulk</B>.
2416 <P><DT><B><VAR>bulk input file</VAR>
2417 </B><DD>Specifies the pathname of the bulk input file. Partial pathnames
2418 are interpreted relative to the current working directory. For a
2419 discussion of the required file format, see <A HREF="#HDRWQ489">Constructing a Bulk Input File</A>.
2420 <P><DT><B>-template
2421 </B><DD>Specifies the pathname of the template file for any <B>uss add</B>
2422 commands that appear in the bulk input file. Partial pathnames are
2423 interpreted relative to the current working directory. For a discussion
2424 of the required file format, see <A HREF="#HDRWQ463">Constructing a uss Template File</A>.
2425 <P><DT><B>-admin
2426 </B><DD>Names an administrative account that has the <TT>ADMIN</TT> flag on its
2427 Authentication Database entry, such as the <B>admin</B> account.
2428 The password prompt echoes it as <VAR>admin_user</VAR>. Enter the
2429 appropriate password as <VAR>admin_password</VAR>.
2430 <P><DT><B>-dryrun
2431 </B><DD>Reports actions that the command interpreter needs to perform to run the
2432 command, without actually performing them.
2433 <P><DT><B><B>-overwrite</B>
2434 </B><DD>Overwrites any directories, files and links that exist in the file system
2435 and for which there are also <B>D</B>, <B>E</B>, <B>F</B>,
2436 <B>L</B>, or <B>S</B> instructions in the template file named by the
2437 <B>-template</B> argument. If this flag is omitted, the command
2438 interpreter prompts, once for each <B>add</B> instruction in the bulk
2439 input file, for confirmation that it is to overwrite such elements. Do
2440 not include this flag if there are no <B>add</B> instructions in the bulk
2441 input file.
2442 <P><DT><B><B>-pwexpires</B>
2443 </B><DD>Sets the number of days after a user's password is changed that it
2444 remains valid, for each user named by an <B>add</B> instruction in the
2445 bulk input file. Provide an integer from the range <B>1</B> through
2446 <B>254</B> to specify the number of days until expiration, or the value
2447 <B>0</B> to indicate that the password never expires (the default).
2448 <P>When the password becomes invalid (expires), the user is unable to
2449 authenticate, but has 30 more days in which to issue the <B>kpasswd</B>
2450 command to change the password (after that, only an administrator can change
2451 it).
2452 <P><DT><B><B>-pipe</B>
2453 </B><DD>Suppresses the Authentication Server's prompt for the password of the
2454 issuer or the user named by the <B>-admin</B> argument (the Authentication
2455 Server always separately authenticates the user who is creating or deleting an
2456 entry in the Authentication Database). Instead, the command interpreter
2457 accepts the password as piped input from another program, enabling you to run
2458 the <B>uss bulk</B> command in unattended batch jobs.
2459 </DL>
2460 <P><LI>If a newly created or deleted user home directory resides in a replicated
2461 volume, use the <B>vos release</B> command to release the volume, as
2462 described in <A HREF="auagd010.htm#HDRWQ194">To replicate a read/write volume (create a read-only volume)</A>.
2463 <PRE>
2464    % <B>vos release</B> &lt;<VAR>volume&nbsp;name&nbsp;or&nbsp;ID</VAR>>
2465
2466 </PRE>
2467 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">This step can be necessary even if the home directory's parent directory
2468 is not itself a mount point for a replicated volume (and is easier to overlook
2469 in that case). For example, the ABC Corporation template puts the mount
2470 points for user volumes in the <B>/afs/abc.com/usr</B>
2471 directory. Because that is a regular directory rather than a mount
2472 point, it resides in the <B>root.cell</B> volume mounted at the
2473 <B>/afs/abc.com</B> directory. That volume is replicated, so
2474 after changing it by creating or deleting a mount point, the administrator
2475 must issue the <B>vos release</B> command.
2476 </TD></TR></TABLE>
2477 <P><LI>If you are creating accounts, create an entry for the new user in the
2478 local password file (<B>/etc/passwd</B> or equivalent) on each AFS client
2479 machine that he or she can log into. For suggestions on automating this
2480 step, see <A HREF="#HDRWQ458">Creating a Common Source Password File</A>.
2481 <P>Even if you do not use the automated method, set the user's UNIX UID
2482 to match the AFS UID assigned automatically by the Protection Server or
2483 assigned with the <B>-uid</B> argument. The new user's AFS UID
2484 appears in the trace produced by the <B>uss add</B> output or you can use
2485 the <B>pts examine</B> command to display it, as described in <A HREF="auagd019.htm#HDRWQ537">To display a Protection Database entry</A>.
2486 <P><LI>If you are deleting accounts, delete the user's entry from the local
2487 password file (<B>/etc/passwd</B> or equivalent) of each client
2488 machine. If you use the AFS <B>package</B> utility, it is
2489 sufficient to remove the entry from the common source version of the
2490 file. If you intend to reactivate the user's account in the
2491 future, it is simpler to comment out the entry or place an asterisk (*) in the
2492 password field.
2493 </OL>
2494 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd016.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auagd018.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
2495 <!-- Begin Footer Records  ========================================== -->
2496 <P><HR><B>
2497 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
2498 </B>
2499 <!-- End Footer Records  ============================================ -->
2500 <A NAME="Bot_Of_Page"></A>
2501 </BODY></HTML>