doc: replace hostnames with IETF example hostnames
[openafs.git] / doc / xml / AdminGuide / auagd017.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ449">
3   <title>Creating and Deleting User Accounts with the uss Command Suite</title>
4
5   <para><indexterm>
6       <primary>user account</primary>
7
8       <secondary>two methods for creating and deleting</secondary>
9     </indexterm></para>
10
11   <para>The <emphasis role="bold">uss</emphasis> command suite helps you create and delete AFS user accounts quickly and easily. You
12   can create a single account with the <emphasis role="bold">uss add</emphasis> command, delete a single account with the <emphasis
13   role="bold">uss delete</emphasis> command, or create and delete multiple accounts with the <emphasis role="bold">uss
14   bulk</emphasis> command.</para>
15
16   <para>A single <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command can create a complete
17   AFS user account because the <emphasis role="bold">uss</emphasis> command interpreter refers to a template file in which you
18   predefine the configuration of many account components. The <emphasis role="bold">uss delete</emphasis> command deletes most of
19   the components of a user account, but does not use a template file.</para>
20
21   <para>The <emphasis role="bold">uss</emphasis> suite also easily incorporates shell scripts or other programs that you write to
22   perform parts of account creation and deletion unique to your site. To invoke a script or program automatically as a <emphasis
23   role="bold">uss</emphasis> command runs, use the appropriate instructions in the template file or bulk input file. Various
24   sections of this chapter discuss possible uses for scripts.</para>
25
26   <para>Using the <emphasis role="bold">uss</emphasis> commands to create and delete accounts is the recommended method because it
27   automates and correctly orders most of the necessary steps. The alternative is to issue a series of separate commands to the
28   various AFS servers, which requires more careful record keeping. For instructions, see <link linkend="HDRWQ491">Administering User
29   Accounts</link>.</para>
30
31   <sect1 id="HDRWQ450">
32     <title>Summary of Instructions</title>
33
34     <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
35
36     <informaltable frame="none">
37       <tgroup cols="2">
38         <colspec colwidth="80*" />
39
40         <colspec colwidth="20*" />
41
42         <tbody>
43           <row>
44             <entry>Add a single user account</entry>
45
46             <entry><emphasis role="bold">uss add</emphasis></entry>
47           </row>
48
49           <row>
50             <entry>Delete a single user account</entry>
51
52             <entry><emphasis role="bold">uss delete</emphasis></entry>
53           </row>
54
55           <row>
56             <entry>Add and delete multiple accounts</entry>
57
58             <entry><emphasis role="bold">uss bulk</emphasis></entry>
59           </row>
60         </tbody>
61       </tgroup>
62     </informaltable>
63   </sect1>
64
65   <sect1 id="HDRWQ452">
66     <title>Overview of the uss Command Suite</title>
67
68     <para>The commands in the <emphasis role="bold">uss</emphasis> suite help you to automate the creation and deletion of AFS user
69     accounts: <itemizedlist>
70         <listitem>
71           <para>The <emphasis role="bold">uss add</emphasis> command creates all of the components of an account, one account at a
72           time. It consults a template file that defines account configuration.</para>
73         </listitem>
74
75         <listitem>
76           <para>The <emphasis role="bold">uss delete</emphasis> command deletes the major components of an account, one account at a
77           time. It does not use a template file, so you possibly need to perform additional tasks manually.</para>
78         </listitem>
79
80         <listitem>
81           <para>The <emphasis role="bold">uss bulk</emphasis> command can create and delete multiple accounts. It refers to a bulk
82           input file that can contain any number of account-creation and deletion instructions, along with other instructions for
83           further automating the process.</para>
84         </listitem>
85       </itemizedlist></para>
86
87     <indexterm>
88       <primary>user account</primary>
89
90       <secondary>components</secondary>
91     </indexterm>
92
93     <indexterm>
94       <primary>user</primary>
95
96       <secondary>account</secondary>
97
98       <see>user account</see>
99     </indexterm>
100
101     <sect2 id="Header_538">
102       <title>The Components of an AFS User Account</title>
103
104       <para>An AFS user account can have many components. The only two required components are entries in the Protection Database
105       and Authentication Database, but the other components add functionality and usability. The following information also appears
106       in a corresponding section of <link linkend="HDRWQ491">Administering User Accounts</link>, but is repeated here for your
107       convenience. <itemizedlist>
108           <listitem>
109             <para>A <emphasis>Protection Database entry</emphasis> defines the username (the name provided when authenticating with
110             AFS), and maps it to an AFS user ID (AFS UID), a number that the AFS servers use internally when referencing users. The
111             Protection Database also tracks the groups to which the user belongs. For details, see <link
112             linkend="HDRWQ531">Administering the Protection Database</link>.</para>
113           </listitem>
114
115           <listitem>
116             <para>An <emphasis>Authentication Database entry</emphasis> records the user's AFS password in a scrambled form suitable
117             for use as an encryption key.</para>
118           </listitem>
119
120           <listitem>
121             <para>A home <emphasis>volume</emphasis> stores all the files in the user's home directory together on a single
122             partition of a file server machine. The volume has an associated quota that limits its size. For a complete discussion
123             of volumes, see <link linkend="HDRWQ174">Managing Volumes</link>.</para>
124           </listitem>
125
126           <listitem>
127             <para>A <emphasis>mount point</emphasis> makes the contents of the user's volume visible and accessible in the AFS
128             filespace, and acts as the user's home directory. For more details about mount points, see <link
129             linkend="HDRWQ183">About Mounting Volumes</link>.</para>
130           </listitem>
131
132           <listitem>
133             <para>Full access permissions on the home directory's <emphasis>access control list (ACL)</emphasis> and ownership of
134             the directory (as displayed by the UNIX <emphasis role="bold">ls -ld</emphasis> command) enable the user to manage his
135             or her files. For details on AFS file protection, see <link linkend="HDRWQ562">Managing Access Control
136             Lists</link>.</para>
137           </listitem>
138
139           <listitem>
140             <para>A <emphasis>local password file entry</emphasis> (in the <emphasis role="bold">/etc/passwd</emphasis> file or
141             equivalent) of each AFS client machine enables the user to log in and access AFS files through the Cache Manager. A
142             subsequent section in this chapter further discusses local password file entries.</para>
143           </listitem>
144
145           <listitem>
146             <para>Other optional <emphasis>configuration files</emphasis> make the account more convenient to use. Such files help
147             the user log in and log out more easily, receive electronic mail, print, and so on.</para>
148           </listitem>
149         </itemizedlist></para>
150
151       <indexterm>
152         <primary>uss commands</primary>
153
154         <secondary>privilege required</secondary>
155       </indexterm>
156
157       <indexterm>
158         <primary>privilege</primary>
159
160         <secondary>required for uss commands</secondary>
161       </indexterm>
162     </sect2>
163
164     <sect2 id="HDRWQ453">
165       <title>Privilege Requirements for the uss Commands</title>
166
167       <para>To issue <emphasis role="bold">uss</emphasis> commands successfully, you usually need all of the standard AFS
168       administrative privileges: membership in the <emphasis role="bold">system:administrators</emphasis> group, inclusion in the
169       <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on every relevant server machine, and the
170       <computeroutput>ADMIN</computeroutput> flag on your Authentication Database entry. For details on administrative privilege,
171       see <link linkend="HDRWQ581">Managing Administrative Privilege</link>. <indexterm>
172           <primary>uss commands</primary>
173
174           <secondary>add</secondary>
175
176           <tertiary>avoiding interruption</tertiary>
177         </indexterm> <indexterm>
178           <primary>uss commands</primary>
179
180           <secondary>delete</secondary>
181
182           <tertiary>avoiding interruption</tertiary>
183         </indexterm> <indexterm>
184           <primary>previewing</primary>
185
186           <secondary>user account creation/deletion with uss</secondary>
187         </indexterm> <indexterm>
188           <primary>user account</primary>
189
190           <secondary>uss commands to create/delete</secondary>
191
192           <tertiary>previewing</tertiary>
193         </indexterm> <indexterm>
194           <primary>user account</primary>
195
196           <secondary>creation using uss</secondary>
197
198           <tertiary>previewing</tertiary>
199         </indexterm> <indexterm>
200           <primary>user account</primary>
201
202           <secondary>deletion using uss</secondary>
203
204           <tertiary>previewing</tertiary>
205         </indexterm> <indexterm>
206           <primary>uss</primary>
207
208           <secondary>previewing effect of command</secondary>
209         </indexterm></para>
210     </sect2>
211
212     <sect2 id="HDRWQ454">
213       <title>Avoiding and Recovering from Errors and Interrupted Operations</title>
214
215       <para>As for any complex operation, there are a number of possible reasons that an account-creation or deletion operation can
216       halt before it completes. You can easily avoid several of the common reasons by making the following checks before issuing a
217       <emphasis role="bold">uss</emphasis> command: <itemizedlist>
218           <listitem>
219             <para>Verify that you have all of the administrative privileges you need to complete an operation, as described in <link
220             linkend="HDRWQ453">Privilege Requirements for the uss Commands</link>. The instructions for using the <emphasis
221             role="bold">uss add</emphasis>, <emphasis role="bold">uss delete</emphasis>, and <emphasis role="bold">uss
222             bulk</emphasis> commands include this check as a step.</para>
223           </listitem>
224
225           <listitem>
226             <para>Proofread the template and bulk input files for correct syntax and acceptable values. For discussion, see <link
227             linkend="HDRWQ463">Constructing a uss Template File</link> and <link linkend="HDRWQ489">Constructing a Bulk Input
228             File</link>.</para>
229           </listitem>
230
231           <listitem>
232             <para>Do not issue <emphasis role="bold">uss</emphasis> commands when you are aware of network, server machine, or
233             server process outages. Because <emphasis role="bold">uss</emphasis> operations affect so many components of AFS, it is
234             unlikely that the command can succeed when there are outages.</para>
235           </listitem>
236         </itemizedlist></para>
237
238       <para>Another way to avoid errors that halt an operation is to preview the <emphasis role="bold">uss</emphasis> command by
239       combining the <emphasis role="bold">-dryrun</emphasis> flag with the other arguments to be used on the actual command. The
240       <emphasis role="bold">uss</emphasis> command interpreter generates a screen trace of the actions to be performed by the actual
241       command, without performing them.</para>
242
243       <para>Using the <emphasis role="bold">-dryrun</emphasis> flag reveals many basic errors that can halt an operation,
244       particularly the ones due to incorrect syntax in the command line, template file, or bulk input file. It does not catch all
245       possible errors, however, because the command interpreter is not actually attempting to perform the actions it is tracing. For
246       example, a Volume Server outage does not necessarily halt the volume creation step when the <emphasis
247       role="bold">-dryrun</emphasis> flag is included, because the command interpreter is not actually contacting the server; such
248       an outage halts the actual creation operation. <indexterm>
249           <primary>failure</primary>
250
251           <secondary>of uss account creation</secondary>
252
253           <tertiary>recovering from</tertiary>
254         </indexterm> <indexterm>
255           <primary>uss</primary>
256
257           <secondary>account</secondary>
258
259           <tertiary>recovering from account creation failure</tertiary>
260         </indexterm> <indexterm>
261           <primary>uss</primary>
262
263           <secondary>command</secondary>
264
265           <tertiary>reissuing, effect of</tertiary>
266         </indexterm></para>
267
268       <para>When the <emphasis role="bold">uss</emphasis> command interpreter encounters error conditions minor enough that they do
269       not require halting the operation, it usually generates a message that begins with the string <computeroutput>uss:
270       Warning:</computeroutput> and describes the action it is taking to avoid halting. For example, if a user's Protection Database
271       entry already exists, the following message appears on the standard output stream:</para>
272
273       <programlisting>
274    uss: Warning: User 'user' already in the protection database
275    The uid for user 'user' is AFS UID
276 </programlisting>
277
278       <para>If an error is more serious, the word <computeroutput>Warning</computeroutput> does not appear in the message, which
279       instead describes why the command interpreter cannot perform the requested action. Not all of these errors cause the <emphasis
280       role="bold">uss</emphasis> operation to halt, but they still require you to take corrective action. For example, attempting to
281       create a mount point fails if you lack the necessary permissions on the parent directory's ACL, or if the mount point pathname
282       in the <emphasis role="bold">V</emphasis> instruction's mount_point field is malformed. However, this error does not cause the
283       creation operation to halt until later instructions in the template attempt to install subdirectories or files under the
284       nonexistent mount point.</para>
285
286       <para>If the command shell prompts returns directly after an error message, then the error generally was serious enough to
287       halt the operation. When an error halts account creation or deletion, the best way to recover is to find and fix the cause,
288       and then reissue the same <emphasis role="bold">uss</emphasis> command. <indexterm>
289           <primary>uss commands</primary>
290
291           <secondary>overwriting existing account components</secondary>
292         </indexterm> <indexterm>
293           <primary>overwriting</primary>
294
295           <secondary>existing directories/files/links with uss</secondary>
296         </indexterm> <indexterm>
297           <primary>directory</primary>
298
299           <secondary>overwritten by uss if exists</secondary>
300         </indexterm> <indexterm>
301           <primary>file</primary>
302
303           <secondary>overwritten by uss if exists</secondary>
304         </indexterm> <indexterm>
305           <primary>hard link</primary>
306
307           <secondary>overwritten by uss if exists</secondary>
308         </indexterm> <indexterm>
309           <primary>symbolic link</primary>
310
311           <secondary>overwritten by uss if exists</secondary>
312         </indexterm></para>
313
314       <para>The following list describes what happens when components of a user's account already exist when you reissue an
315       account-creation command (the <emphasis role="bold">uss add</emphasis> command, or the <emphasis role="bold">uss
316       bulk</emphasis> command when the bulk input file contains <emphasis role="bold">add</emphasis> instructions): <itemizedlist>
317           <listitem>
318             <para>If the Protection Database entry already exists, a message confirms its existence and specifies the associated AFS
319             UID.</para>
320           </listitem>
321
322           <listitem>
323             <para>If the Authentication Database entry already exists, a message confirms its existence.</para>
324           </listitem>
325
326           <listitem>
327             <para>If the volume and associated Volume Location Database (VLDB) entry already exist, a message confirms their
328             existence. However, the <emphasis role="bold">uss</emphasis> command interpreter does alter the volume's quota, mount
329             point, or ACL if any of the relevant fields in the template <emphasis role="bold">V</emphasis> instruction have changed
330             since the command last ran. If the value in the mount_point field has changed, the command interpreter creates the new
331             mount point but does not remove any existing mount points.</para>
332           </listitem>
333
334           <listitem>
335             <para>If any of the fields in the template <emphasis role="bold">A</emphasis> instruction have changed, the <emphasis
336             role="bold">uss</emphasis> command interpreter makes the changes without comment.</para>
337           </listitem>
338
339           <listitem>
340             <para>If a directory, file, or link defined by a template file <emphasis role="bold">D</emphasis>, <emphasis
341             role="bold">E</emphasis>, <emphasis role="bold">F</emphasis>, <emphasis role="bold">L</emphasis>, or <emphasis
342             role="bold">S</emphasis> instruction already exists, the <emphasis role="bold">uss</emphasis> command interpreter
343             replaces the existing element with one that conforms to the template definition. To control whether the <emphasis
344             role="bold">uss</emphasis> command interpreter prompts for confirmation that you wish to overwrite a given element, use
345             the <emphasis role="bold">-overwrite</emphasis> flag to the <emphasis role="bold">uss add</emphasis> or <emphasis
346             role="bold">uss bulk</emphasis> command: <itemizedlist>
347                 <listitem>
348                   <para>If you include the <emphasis role="bold">-overwrite</emphasis> flag, the command interpreter automatically
349                   overwrites all elements without asking for confirmation.</para>
350                 </listitem>
351
352                 <listitem>
353                   <para>If you omit the flag, the command interpreter prompts once for each account to ask if you want to overwrite
354                   all elements associated with it.</para>
355                 </listitem>
356               </itemizedlist></para>
357           </listitem>
358
359           <listitem>
360             <para>The command interpreter always reexecutes <emphasis role="bold">X</emphasis> instructions in the template file. If
361             a command's result already holds, reissuing it has the same effect as reissuing it outside the context of the <emphasis
362             role="bold">uss</emphasis> commands.</para>
363           </listitem>
364         </itemizedlist></para>
365
366       <para>The following describes what happens when a <emphasis role="bold">uss delete</emphasis> command references account
367       components that have already been deleted. <itemizedlist>
368           <listitem>
369             <para>If the volume and VLDB entry no longer exist, a message confirms their absence.</para>
370           </listitem>
371
372           <listitem>
373             <para>If the Authentication Database entry no longer exists, a message confirms its absence.</para>
374           </listitem>
375         </itemizedlist></para>
376
377       <indexterm>
378         <primary>local password file</primary>
379
380         <secondary>creating entry for AFS user</secondary>
381
382         <tertiary>with uss</tertiary>
383       </indexterm>
384     </sect2>
385   </sect1>
386
387   <sect1 id="HDRWQ455">
388     <title>Creating Local Password File Entries with uss</title>
389
390     <para>To obtain authenticated access to a cell's AFS filespace, a user must not only have a valid AFS token, but also an entry
391     in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of the AFS client machine. This section
392     discusses why it is important for the user's AFS UID to match to the UNIX UID listed in the local password file, the appropriate
393     value to put in the file's password field, and outlines a method for creating a single source password file.</para>
394
395     <para>For instructions on using the template file's <emphasis role="bold">E</emphasis> instruction to generate local password
396     file entries automatically as part of account creation, see <link linkend="HDRWQ458">Creating a Common Source Password
397     File</link>.</para>
398
399     <para>The following information also appears in a corresponding section of <link linkend="HDRWQ491">Administering User
400     Accounts</link>, but is repeated here for your convenience. <indexterm>
401         <primary>AFS UID</primary>
402
403         <secondary>matching with UNIX UID</secondary>
404       </indexterm> <indexterm>
405         <primary>user account</primary>
406
407         <secondary>matching AFS and UNIX UIDs</secondary>
408       </indexterm> <indexterm>
409         <primary>uss</primary>
410
411         <secondary>AFS UID, assigning</secondary>
412       </indexterm> <indexterm>
413         <primary>assigning</primary>
414
415         <secondary>AFS UID with uss</secondary>
416       </indexterm> <indexterm>
417         <primary>UNIX UID</primary>
418
419         <secondary>matching with AFS UID</secondary>
420       </indexterm></para>
421
422     <sect2 id="HDRWQ456">
423       <title>Assigning AFS and UNIX UIDs that Match</title>
424
425       <para>A user account is easiest to administer and use if the AFS user ID number (AFS UID) and UNIX UID match. All instructions
426       in the AFS documentation assume that they do.</para>
427
428       <para>The most basic reason to make AFS and UNIX UIDs the same is so that the owner name reported by the UNIX <emphasis
429       role="bold">ls -l</emphasis> and <emphasis role="bold">ls -ld</emphasis> commands makes sense for AFS files and directories.
430       Following standard UNIX practice, the File Server records a number rather than a username in an AFS file or directory's owner
431       field: the owner's AFS UID. When you issue the <emphasis role="bold">ls -l</emphasis> command, it translates the UID to a
432       username according to the mapping in the local password file, not the AFS Protection Database. If the AFS and UNIX UIDs do not
433       match, the <emphasis role="bold">ls -l</emphasis> command reports an unexpected (and incorrect) owner. The output can even
434       vary on different client machines if their local password files map the same UNIX UID to different names.</para>
435
436       <para>Follow the recommendations in the indicated sections to make AFS and UNIX UIDs match when you are creating accounts for
437       various types of users: <itemizedlist>
438           <listitem>
439             <para>If creating an AFS account for a user who already has a UNIX UID, see <link linkend="HDRWQ459">Converting Existing
440             UNIX Accounts with uss</link>.</para>
441           </listitem>
442
443           <listitem>
444             <para>If some users in your cell have existing UNIX accounts but the user for whom you are creating an AFS account does
445             not, then it is best to allow the Protection Server to allocate an AFS UID automatically. To avoid overlap of AFS UIDs
446             with existing UNIX UIDs, set the Protection Database's <computeroutput>max user id</computeroutput> counter higher than
447             the largest UNIX UID, using the instructions in <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID
448             Counters</link>.</para>
449           </listitem>
450
451           <listitem>
452             <para>If none of your users have existing UNIX accounts, allow the Protection Server to allocate AFS UIDs automatically,
453             starting either at its default or at the value you have set for the <computeroutput>max user id</computeroutput>
454             counter.</para>
455           </listitem>
456         </itemizedlist></para>
457
458       <indexterm>
459         <primary>password</primary>
460
461         <secondary>setting in local password file</secondary>
462
463         <tertiary>with uss</tertiary>
464       </indexterm>
465
466       <indexterm>
467         <primary>local password file</primary>
468
469         <secondary>setting password in</secondary>
470
471         <tertiary>with uss</tertiary>
472       </indexterm>
473     </sect2>
474
475     <sect2 id="HDRWQ457">
476       <title>Specifying Passwords in the Local Password File</title>
477
478       <para>Authenticating with AFS is easiest for your users if you install and configure an AFS-modified login utility, which logs
479       a user into the local file system and obtains an AFS token in one step. In this case, the local password file no longer
480       controls a user's ability to login in most circumstances, because the AFS-modified login utility does not consult the local
481       password file if the user provides the correct AFS password. You can nonetheless use a password file entry's password field
482       (usually, the second field) in the following ways to control login and authentication: <itemizedlist>
483           <listitem>
484             <para>To prevent both local login and AFS authentication, place an asterisk ( * ) in the field. This is useful mainly in
485             emergencies, when you want to prevent a certain user from logging into the machine.</para>
486           </listitem>
487
488           <listitem>
489             <para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
490             string of any length other than the standard thirteen characters in the field. This is appropriate if you want to allow
491             only people with local AFS accounts to log into to your machines. A single <emphasis role="bold">X</emphasis> or other
492             character is the most easily recognizable way to do this.</para>
493           </listitem>
494
495           <listitem>
496             <para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
497             standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
498             role="bold">passwd</emphasis> or equivalent).</para>
499           </listitem>
500         </itemizedlist></para>
501
502       <para>If you do not use an AFS-modified login utility, you must place a standard UNIX password in the local password file of
503       every client machine the user will use. The user logs into the local file system only, and then must issue the <emphasis
504       role="bold">klog</emphasis> command to authenticate with AFS. It is simplest if the passwords in the local password file and
505       the Authentication Database are the same, but this is not required. <indexterm>
506           <primary>creating</primary>
507
508           <secondary>common local password file with uss</secondary>
509         </indexterm> <indexterm>
510           <primary>local password file</primary>
511
512           <secondary>creating common source version with uss</secondary>
513         </indexterm> <indexterm>
514           <primary>uss commands</primary>
515
516           <secondary>local password file</secondary>
517
518           <tertiary>creating common source version</tertiary>
519         </indexterm> <indexterm>
520           <primary>passwd file</primary>
521
522           <secondary></secondary>
523
524           <see>local password file</see>
525         </indexterm></para>
526     </sect2>
527
528     <sect2 id="HDRWQ458">
529       <title>Creating a Common Source Password File</title>
530
531       <para>This section explains how to create a common source version of the local password file when using <emphasis
532       role="bold">uss</emphasis> commands to create user accounts. The sequence of steps is as follows: <orderedlist>
533           <listitem>
534             <para>Include an <emphasis role="bold">E</emphasis> instruction in the template file to create a one-line file that has
535             the format of a local password file entry.</para>
536           </listitem>
537
538           <listitem>
539             <para>Incorporate the one-line file into the common source version of the local password file. It makes sense to store
540             this file in AFS. See the following two example scripts for automating this step.</para>
541           </listitem>
542
543           <listitem>
544             <para>Distribute the common password file to each client machine, perhaps by using the AFS <emphasis
545             role="bold">package</emphasis> utility as described in <link linkend="HDRWQ419">Configuring Client Machines with the
546             package Program</link>.</para>
547           </listitem>
548         </orderedlist></para>
549
550       <para>As an example, the template file used by the Example Corporation includes the following <emphasis role="bold">E</emphasis>
551       instruction to create a file called <emphasis role="bold">passwd_</emphasis>username in the directory <emphasis
552       role="bold">/afs/.example.com/common/etc/newaccts</emphasis> (the entire contents of the template file appear in <link
553       linkend="HDRWQ471">Example uss Templates</link> and a full description of the <emphasis role="bold">E</emphasis> instruction
554       appears in <link linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>):</para>
555
556       <programlisting>
557    E /afs/.example.com/common/etc/newaccts/passwd_$USER 0644 root \
558         "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
559 </programlisting>
560
561       <para>For the user Joe L. Smith with username <emphasis role="bold">smith</emphasis>, this instruction creates a file called
562       <emphasis role="bold">passwd_smith</emphasis> which contains the following line:</para>
563
564       <programlisting>
565    smith:X:1205:11:Joe L. Smith:/afs/example.com/usr/usr1/smith:/bin/csh
566 </programlisting>
567
568       <para>A shell script is probably the easiest way to incorporate a set of files created in this manner into a common source
569       password file, and two sample shell scripts appear here. To automate the process even further, you can create a <emphasis
570       role="bold">cron</emphasis> process in a file server machine's <emphasis role="bold">/usr/afs/local/BosConfig</emphasis>
571       directory to execute the shell script, perhaps each day at a given time; for details, see <link linkend="HDRWQ162">To create
572       and start a new process</link>.</para>
573
574       <note>
575         <para>The following example scripts are suggestions only. If you choose to use them, or to model similar scripts on them,
576         you must test that your script has the desired result, preferably in a test environment.</para>
577       </note>
578
579       <para><emphasis role="bold">Example C Shell Script</emphasis></para>
580
581       <para>The first example is a simple C shell script suitable for the Example Corporation cell. It incorporates the individual files
582       found in the <emphasis role="bold">/afs/.example.com/common/uss/newaccts</emphasis> directory into a new version of the global
583       password file found in the <emphasis role="bold">/afs/.example.com/common/etc</emphasis> directory, sorting the files into
584       alphabetical order. It takes care to save the current version with a <emphasis role="bold">.old</emphasis> extension, then
585       removes the individual files when done.</para>
586
587       <programlisting>
588    set  dir = /afs/.example.com/common
589    cat  $dir/uss/newaccts/passwd_* $dir/etc/passwd  &gt;!  $dir/etc/passwd.new
590    mv  $dir/etc/passwd  $dir/etc/passwd.old
591    sort  $dir/etc/passwd.new  &gt;  $dir/etc/passwd
592    rm  $dir/etc/passwd.new  $dir/uss/newaccts/passwd_*
593 </programlisting>
594
595       <para><emphasis role="bold">Example Bourne Shell Script</emphasis></para>
596
597       <para>The second, more elaborate, example is a Bourne shell script that first verifies that there are new <emphasis
598       role="bold">passwd_</emphasis>username files to be incorporated into the global password file. While running, it checks that
599       each new entry does not already exist. Like the shorter C shell example, it incorporates the individual files found in the
600       <emphasis role="bold">/afs/.example.com/common/uss/newaccts</emphasis> directory into a new version of the global <emphasis
601       role="bold">passwd</emphasis> file found in the <emphasis role="bold">/afs/.example.com/common/etc</emphasis> directory.</para>
602
603       <programlisting>
604    #!/bin/sh
605    DESTDIR=/afs/.example.com/common/uss/newaccts
606    cd  $DESTDIR
607    DEST=/afs/.example.com/common/etc
608    cp /afs/.example.com/common/etc/passwd   /afs/.example.com/common/uss/newaccts/passwd
609    echo "copied in passwd file."
610    PASSWD=/afs/.example.com/common/uss/newaccts/passwd
611    ENTRIES=`ls passwd_*`
612    case $ENTRIES in 
613    "")
614         echo No new entry found to be added to passwd file
615         ;;
616    *)
617         echo  "Adding new users to passwd file."
618         for  i  in  $ENTRIES
619         do
620            cat  $i  |  awk  -F:  '{print $1  &gt;  "foo"}'
621            USER=`cat foo`
622            case  `egrep  -e  \^$USER\: $PASSWD` in 
623            "")
624                    echo  adding  $USER
625                    cat  $i  &gt;&gt;  $PASSWD
626                    ;;
627            *)
628                    echo  $USER already in passwd file
629                    ;;
630            esac
631            mv  $i  ../old.passdir/done_${i}
632         done
633         cd  /afs/.example.com/common/uss/newaccts
634         echo  "sorting password file"
635         sort  ${PASSWD}  &gt;  ${PASSWD}.sorted
636         echo  "installing files"     
637         install  ${PASSWD}.sorted ${DEST}/passwd
638         echo  "Password file is built, sorted and installed."
639         ;;
640    esac
641 </programlisting>
642
643       <indexterm>
644         <primary>uss commands</primary>
645
646         <secondary>converting existing UNIX accounts</secondary>
647       </indexterm>
648
649       <indexterm>
650         <primary>converting</primary>
651
652         <secondary>existing UNIX accounts to AFS accounts</secondary>
653
654         <tertiary>with uss</tertiary>
655       </indexterm>
656
657       <indexterm>
658         <primary>user account</primary>
659
660         <secondary>converting existing UNIX to AFS</secondary>
661
662         <tertiary>with uss</tertiary>
663       </indexterm>
664     </sect2>
665   </sect1>
666
667   <sect1 id="HDRWQ459">
668     <title>Converting Existing UNIX Accounts with uss</title>
669
670     <para>This section discusses the three main issues you need to consider if there are existing UNIX accounts to be converted to
671     AFS accounts.</para>
672
673     <sect2 id="HDRWQ460">
674       <title>Making UNIX and AFS UIDs Match</title>
675
676       <para>As previously mentioned, AFS users must have an entry in the local password file on every client machine from which they
677       access the AFS filespace as an authenticated user. Both administration and use are much simpler if the UNIX UID and AFS UID
678       match. When converting existing UNIX accounts, you have two alternatives: <itemizedlist>
679           <listitem>
680             <para>Make the AFS UIDs match the existing UNIX UIDs. In this case, you need to assign the AFS UID yourself as you
681             create an AFS account: <itemizedlist>
682                 <listitem>
683                   <para>If using the <emphasis role="bold">uss add</emphasis> command, include the <emphasis
684                   role="bold">-uid</emphasis> argument.</para>
685                 </listitem>
686
687                 <listitem>
688                   <para>If using the <emphasis role="bold">uss bulk</emphasis> command, specify the desired UID in the uid field of
689                   the <emphasis role="bold">add</emphasis> instruction in the bulk input file.</para>
690                 </listitem>
691               </itemizedlist></para>
692
693             <para>Because you are retaining the user's UNIX UID, you do not need to alter the UID in the local password file entry.
694             However, if you are using an AFS-modified login utility, you possibly need to change the password field in the entry.
695             For a discussion of how the value in the password field affects login with an AFS-modified login utility, see <link
696             linkend="HDRWQ455">Creating Local Password File Entries with uss</link>.</para>
697
698             <para>If now or in the future you need to create AFS accounts for users who do not have an existing UNIX UID, then you
699             must guarantee that new AFS UIDs do not conflict with any existing UNIX UIDs. The simplest way is to set the
700             <computeroutput>max user id</computeroutput> counter in the Protection Database to a value higher than the largest
701             existing UNIX UID. See <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID Counters</link>.</para>
702           </listitem>
703
704           <listitem>
705             <para>Change the existing UNIX UIDs to match the new AFS UIDs that the Protection Server assigns automatically.</para>
706
707             <para>Allow the Protection Server to allocate the AFS UIDs automatically as you create AFS accounts. For instructions on
708             creating a new entry for the local password file during account creation, see <link linkend="HDRWQ455">Creating Local
709             Password File Entries with uss</link>.</para>
710
711             <para>There is one drawback to changing the UNIX UID: any files and directories that the user owned in the local file
712             system before becoming an AFS user still have the former UID in their owner field. If you want the <emphasis
713             role="bold">ls -l</emphasis> and <emphasis role="bold">ls -ld</emphasis> commands to display the correct owner, you must
714             use the <emphasis role="bold">chown</emphasis> command to change the value to the user's new UID, whether you are
715             leaving the file in the local file system or moving it to AFS. See <link linkend="HDRWQ462">Moving Local Files into
716             AFS</link>.</para>
717           </listitem>
718         </itemizedlist></para>
719     </sect2>
720
721     <sect2 id="HDRWQ461">
722       <title>Setting the Password Field Appropriately</title>
723
724       <para>Existing UNIX accounts already have an entry in the local password file, probably with a (scrambled) password in the
725       password field. You possibly need to change the value in the field, depending on the type of login utility you use:
726       <itemizedlist>
727           <listitem>
728             <para>If the login utility is not modified for use with AFS, the actual password must appear (in scrambled form) in the
729             password field of the local password file entry.</para>
730           </listitem>
731
732           <listitem>
733             <para>If the login utility is modified for use with AFS, choose one of the acceptable values, each of which affects the
734             login utility's behavior differently. See <link linkend="HDRWQ455">Creating Local Password File Entries with
735             uss</link>.</para>
736           </listitem>
737         </itemizedlist></para>
738
739       <para>If you choose to place an actual password in a local password file entry, then you can define a dummy password when you
740       use a template file <emphasis role="bold">E</emphasis> instruction to create the entry, as described in <link
741       linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>. Have the user issue the UNIX password-setting
742       command (<emphasis role="bold">passwd</emphasis> or equivalent) to replace the dummy with an actual secret password.</para>
743     </sect2>
744
745     <sect2 id="HDRWQ462">
746       <title>Moving Local Files into AFS</title>
747
748       <para>New AFS users with existing UNIX accounts probably already own files and directories stored in a machine's local file
749       system, and it usually makes sense to transfer them into the new home volume. The easiest method is to move them onto the
750       local disk of an AFS client machine, and then use the UNIX <emphasis role="bold">mv</emphasis> command to transfer them into
751       the user's new AFS home directory.</para>
752
753       <para>As you move files and directories into AFS, keep in mind that the meaning of their mode bits changes. AFS ignores the
754       second and third sets of mode bits (group and other), and does not use the first set (the owner bits) directly, but only in
755       conjunction with entries on the ACL (for details, see <link linkend="HDRWQ580">How AFS Interprets the UNIX Mode Bits</link>).
756       Be sure that the ACL protects the file or directory at least as securely as the mode bits.</para>
757
758       <para>If you have chosen to change a user's UNIX UID to match a new AFS UID, you must change the ownership of UNIX files and
759       directories as well. Only members of the <emphasis role="bold">system:administrators</emphasis> group can issue the <emphasis
760       role="bold">chown</emphasis> command on files and directories once they reside in AFS. <indexterm>
761           <primary>uss commands</primary>
762
763           <secondary>advantages over individual account-creation commands</secondary>
764         </indexterm> <indexterm>
765           <primary>uss template file</primary>
766
767           <secondary>advantages</secondary>
768         </indexterm> <indexterm>
769           <primary>uss template file</primary>
770
771           <secondary>instructions summarized</secondary>
772         </indexterm></para>
773     </sect2>
774   </sect1>
775
776   <sect1 id="HDRWQ463">
777     <title>Constructing a uss Template File</title>
778
779     <para>Creating user accounts with <emphasis role="bold">uss</emphasis> commands is generally more convenient than using
780     individual commands. You control the account creation process just as closely, but the <emphasis role="bold">uss</emphasis>
781     template file enables you to predefine many aspects of account configuration. Because you construct the template before issuing
782     <emphasis role="bold">uss</emphasis> commands, you have time to consider configuration details carefully and correct syntax
783     errors. The following list summarizes some further advantages of using a template: <itemizedlist>
784         <listitem>
785           <para>You do not have to remember the correct order in which to create or delete account components, or the order of each
786           command's arguments, which reduces the likelihood of errors.</para>
787         </listitem>
788
789         <listitem>
790           <para>You do not have to type the same information multiple times. Instead, you can place constants and variables in the
791           template file that enable you to type as little on the command line as possible. See <link linkend="HDRWQ465">Using
792           Constants and Variables in the Template File</link>.</para>
793         </listitem>
794
795         <listitem>
796           <para>You can create different templates for different types of users. Instead of having to remember which components
797           differ for a given user, specify the appropriate template when issuing the <emphasis role="bold">uss add</emphasis> or
798           <emphasis role="bold">uss bulk</emphasis> command.</para>
799         </listitem>
800
801         <listitem>
802           <para>You can create any of the three types of AFS account (authentication-only, basic, or full) by including or omitting
803           certain information in the template, as described in <link linkend="HDRWQ464">Creating the Three Types of User
804           Accounts</link>.</para>
805         </listitem>
806       </itemizedlist></para>
807
808     <para>The following list briefly describes the instructions that can appear in a template file and points you to a later section
809     for more details. It lists them in the order that is usually optimal for correct handling of dependencies between the different
810     types of instruction. <variablelist>
811         <varlistentry>
812           <term><emphasis role="bold">G</emphasis></term>
813
814           <listitem>
815             <para>Defines a directory that is one of a set of parent directories into which the <emphasis role="bold">uss</emphasis>
816             command interpreter evenly distributes newly created home directories. Place the corresponding template file variable,
817             $AUTO, in the mount_point field of the <emphasis role="bold">V</emphasis> instruction. See <link
818             linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link> and <link
819             linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
820           </listitem>
821         </varlistentry>
822
823         <varlistentry>
824           <term><emphasis role="bold">V</emphasis></term>
825
826           <listitem>
827             <para>Creates a volume, mounts it as the user's home directory at a specified location in the AFS filespace, sets the
828             volume's quota, and defines the owner and ACL for the directory. This instruction must appear in any template that is
829             not empty (zero-length). See <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
830           </listitem>
831         </varlistentry>
832
833         <varlistentry>
834           <term><emphasis role="bold">D</emphasis></term>
835
836           <listitem>
837             <para>Creates a directory, generally a subdirectory of the new home directory, and sets its mode bits, owner, and ACL.
838             See <link linkend="HDRWQ474">Creating a Directory with the D Instruction</link>.</para>
839           </listitem>
840         </varlistentry>
841
842         <varlistentry>
843           <term><emphasis role="bold">F</emphasis></term>
844
845           <listitem>
846             <para>Creates a file by copying a prototype and sets its mode bits and owner. See <link linkend="HDRWQ475">Creating a
847             File from a Prototype with the F Instruction</link>.</para>
848           </listitem>
849         </varlistentry>
850
851         <varlistentry>
852           <term><emphasis role="bold">E</emphasis></term>
853
854           <listitem>
855             <para>Creates a single-line file by copying in the contents of the instruction itself, then sets the file's mode bits
856             and owner. See <link linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>.</para>
857           </listitem>
858         </varlistentry>
859
860         <varlistentry>
861           <term><emphasis role="bold">L</emphasis></term>
862
863           <listitem>
864             <para>Creates a hard link. See <link linkend="HDRWQ477">Creating Links with the L and S Instructions</link>.</para>
865           </listitem>
866         </varlistentry>
867
868         <varlistentry>
869           <term><emphasis role="bold">S</emphasis></term>
870
871           <listitem>
872             <para>Creates a symbolic link. See <link linkend="HDRWQ477">Creating Links with the L and S Instructions</link>.</para>
873           </listitem>
874         </varlistentry>
875
876         <varlistentry>
877           <term><emphasis role="bold">A</emphasis></term>
878
879           <listitem>
880             <para>Improves account security by imposing restrictions on passwords and authentication attempts. See <link
881             linkend="HDRWQ478">Increasing Account Security with the A Instruction</link>.</para>
882           </listitem>
883         </varlistentry>
884
885         <varlistentry>
886           <term><emphasis role="bold">X</emphasis></term>
887
888           <listitem>
889             <para>Executes a command. See <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>.</para>
890           </listitem>
891         </varlistentry>
892       </variablelist></para>
893
894     <indexterm>
895       <primary>uss template file</primary>
896
897       <secondary>instructions for different account types</secondary>
898     </indexterm>
899
900     <indexterm>
901       <primary>user account</primary>
902
903       <secondary>creating different types with uss</secondary>
904     </indexterm>
905
906     <indexterm>
907       <primary>creating</primary>
908
909       <secondary>user account types with uss</secondary>
910     </indexterm>
911
912     <sect2 id="HDRWQ464">
913       <title>Creating the Three Types of User Accounts</title>
914
915       <para>Using the <emphasis role="bold">uss add</emphasis> and <emphasis role="bold">uss bulk</emphasis> commands, you can
916       create three types of accounts that differ in their levels of functionality. For a description of the types, see <link
917       linkend="HDRWQ57">Configuring AFS User Accounts</link>. The following list explains how to construct a template for each type:
918       <itemizedlist>
919           <listitem>
920             <para>To create an authentication-only account, create an empty (zero-length) template file. Such an account has only
921             two components: entries in the Authentication Database and Protection Database.</para>
922           </listitem>
923
924           <listitem>
925             <para>To create a basic account, include a <emphasis role="bold">V</emphasis> instruction, and <emphasis
926             role="bold">G</emphasis> instructions if you want to distribute home directories evenly as described in <link
927             linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link>. In addition to
928             Authentication Database and Protection Database entries, this type of account includes a volume mounted at the home
929             directory with owner and ACL set appropriately.</para>
930           </listitem>
931
932           <listitem>
933             <para>To create a full account, include <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>,
934             <emphasis role="bold">F</emphasis>, <emphasis role="bold">L</emphasis>, and <emphasis role="bold">S</emphasis>
935             instructions as appropriate, in addition to the <emphasis role="bold">V</emphasis> and <emphasis
936             role="bold">G</emphasis> instructions. This type of account includes configuration files for basic functions such as
937             logging in, printing, and mail delivery. For a discussion of some useful types of configuration files, see <link
938             linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>.</para>
939           </listitem>
940         </itemizedlist></para>
941
942       <indexterm>
943         <primary>constants</primary>
944
945         <secondary>uss template file</secondary>
946       </indexterm>
947
948       <indexterm>
949         <primary>uss template file</primary>
950
951         <secondary>constants</secondary>
952       </indexterm>
953
954       <indexterm>
955         <primary>variables</primary>
956
957         <secondary>in uss template file</secondary>
958       </indexterm>
959
960       <indexterm>
961         <primary>uss template file</primary>
962
963         <secondary>variables</secondary>
964       </indexterm>
965     </sect2>
966
967     <sect2 id="HDRWQ465">
968       <title>Using Constants and Variables in the Template File</title>
969
970       <para>Each instruction in the <emphasis role="bold">uss</emphasis> template file has several fields that define the
971       characteristics of the element that it creates. The <emphasis role="bold">D</emphasis> instruction's fields, for instance,
972       define a directory's pathname, owner, mode bits, and ACL.</para>
973
974       <para>You can place three types of values in a field: a variable, a constant, or a combination of the two. The appropriate
975       value depends on the desired configuration, and determines which arguments you provide to the <emphasis role="bold">uss
976       add</emphasis> command or which fields you include in a bulk input file <emphasis role="bold">add</emphasis>
977       instruction.</para>
978
979       <para>If an aspect of account configuration is the same for every user, define a constant value in the appropriate field by
980       inserting a character string. For example, to assign a space quota of 10,000 KB to every user volume, place the string
981       <emphasis role="bold">10000</emphasis> in the <emphasis role="bold">V</emphasis> instruction's quota field.</para>
982
983       <para>If, on the other hand, an aspect of account configuration varies for each user, put a variable in the appropriate field.
984       When creating each account, provide a value for the variable by providing either the corresponding argument to the <emphasis
985       role="bold">uss add</emphasis> command or a value in the corresponding field of the <emphasis role="bold">add</emphasis>
986       instruction in the bulk input file.</para>
987
988       <para>The <emphasis role="bold">uss</emphasis> command suite defines a set of template variables, each of which has a
989       corresponding source for its value, as summarized in <link linkend="TBLWQ466">Table 3</link>. For a discussion of their
990       intended uses, see the following sections about each template instruction (<link linkend="HDRWQ473">Creating a Volume with the
991       V Instruction</link> through <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>).</para>
992
993       <table id="TBLWQ466" label="3">
994         <title>Source for values of uss template variables</title>
995
996         <tgroup cols="2">
997           <colspec colwidth="20*" />
998
999           <colspec colwidth="80*" />
1000
1001           <thead>
1002             <row>
1003               <entry><emphasis role="bold">Variable</emphasis></entry>
1004
1005               <entry><emphasis role="bold">Source for value</emphasis></entry>
1006             </row>
1007           </thead>
1008
1009           <tbody>
1010             <row>
1011               <entry>$AUTO</entry>
1012
1013               <entry>Previous <emphasis role="bold">G</emphasis> instructions in template</entry>
1014             </row>
1015
1016             <row>
1017               <entry>$MTPT</entry>
1018
1019               <entry><emphasis role="bold">-mount</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
1020               mount_point field of bulk input file <emphasis role="bold">add</emphasis> instruction, when in <emphasis
1021               role="bold">V</emphasis> instruction; <emphasis role="bold">V</emphasis> instruction's mount_point field when in
1022               subsequent instructions</entry>
1023             </row>
1024
1025             <row>
1026               <entry>$NAME</entry>
1027
1028               <entry><emphasis role="bold">-realname</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
1029               mount_point field of bulk input file <emphasis role="bold">add</emphasis> instruction, if provided; otherwise,
1030               <emphasis role="bold">-user</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or username field
1031               of in bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
1032             </row>
1033
1034             <row>
1035               <entry>$PART</entry>
1036
1037               <entry><emphasis role="bold">-partition</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
1038               partition field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
1039             </row>
1040
1041             <row>
1042               <entry>$PWEXPIRES</entry>
1043
1044               <entry><emphasis role="bold">-pwexpires</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
1045               password_expires field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
1046             </row>
1047
1048             <row>
1049               <entry>$SERVER</entry>
1050
1051               <entry><emphasis role="bold">-server</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
1052               file_server field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
1053             </row>
1054
1055             <row>
1056               <entry>$UID</entry>
1057
1058               <entry><emphasis role="bold">-uid</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or uid field
1059               of bulk input file <emphasis role="bold">add</emphasis> instruction, if provided; otherwise, allocated automatically
1060               by Protection Server</entry>
1061             </row>
1062
1063             <row>
1064               <entry>$USER</entry>
1065
1066               <entry><emphasis role="bold">-user</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or username
1067               field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
1068             </row>
1069
1070             <row>
1071               <entry>$1 through $9</entry>
1072
1073               <entry><emphasis role="bold">-var</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or var1
1074               through var9 fields of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
1075             </row>
1076           </tbody>
1077         </tgroup>
1078       </table>
1079
1080       <para>A common use of variables is to define the file server machine and partition that house the user's volume, which often
1081       vary from user to user. Place the $SERVER variable in the <emphasis role="bold">V</emphasis> instruction's server field, and
1082       the $PART variable in its partition field. If using the <emphasis role="bold">uss add</emphasis> command, provide the desired
1083       value with the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. If using
1084       the <emphasis role="bold">uss bulk</emphasis> command, provide the desired values in the file_server and partition fields of
1085       each user's <emphasis role="bold">add</emphasis> instruction in the bulk input file. <indexterm>
1086           <primary>number variables</primary>
1087
1088           <secondary>uss template file</secondary>
1089         </indexterm> <indexterm>
1090           <primary>uss template file</primary>
1091
1092           <secondary>number variables</secondary>
1093         </indexterm></para>
1094
1095       <para>The variables $1 through $9 can be used to customize other aspects of the account. Provide a value for these variables
1096       with the <emphasis role="bold">-var</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or in the
1097       appropriate field of the bulk input file <emphasis role="bold">add</emphasis> instruction. The <emphasis
1098       role="bold">-var</emphasis> argument is unusual in that each instance for it has two parts: the number index and the value,
1099       separated by a space. For examples of the use of a number variable, see the discussions of the mount_point and quota fields in
1100       <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
1101
1102       <para>If some aspect of account configuration is partly constant and partly variable, you can combine variables and constants
1103       in an instruction field. For example, suppose that the Example Corporation mounts user volumes in the <emphasis
1104       role="bold">/afs/example.com/usr</emphasis> directory. That part of the pathname is constant, but the name of the mount point and
1105       home directory is the user's username, which corresponds to the $USER variable. To configure accounts in this way, combine a
1106       constant string and a variable in the <emphasis role="bold">V</emphasis> instruction's mount_point field as follows:</para>
1107
1108       <programlisting>
1109    /afs/example.com/usr/$USER
1110 </programlisting>
1111
1112       <para>Then provide the value for the $USER variable with the <emphasis role="bold">-user</emphasis> argument to the <emphasis
1113       role="bold">uss add</emphasis> command, or in the username field of each user's <emphasis role="bold">add</emphasis>
1114       instruction in the bulk input file. <indexterm>
1115           <primary>location</primary>
1116
1117           <secondary>standard for uss template file</secondary>
1118         </indexterm> <indexterm>
1119           <primary>uss template file</primary>
1120
1121           <secondary>standard locations</secondary>
1122         </indexterm></para>
1123     </sect2>
1124
1125     <sect2 id="HDRWQ468">
1126       <title>Where to Place Template Files</title>
1127
1128       <para>A template must be available to the <emphasis role="bold">uss</emphasis> command interpreter as it executes a <emphasis
1129       role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command, even if it is the zero-length file
1130       appropriate for creating an authentication-only account.</para>
1131
1132       <para>If you do not provide the <emphasis role="bold">-template</emphasis> argument to the <emphasis role="bold">uss
1133       add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command, then the command interpreter searches for a template file
1134       called <emphasis role="bold">uss.template</emphasis> in each of the following directories in turn: <orderedlist>
1135           <listitem>
1136             <para>The current working directory</para>
1137           </listitem>
1138
1139           <listitem>
1140             <para><emphasis role="bold">/afs/cellname/common/uss</emphasis>, where cellname is the local cell</para>
1141           </listitem>
1142
1143           <listitem>
1144             <para><emphasis role="bold">/etc</emphasis></para>
1145           </listitem>
1146         </orderedlist></para>
1147
1148       <para>To use a template file with a different name or stored in a different directory, include the <emphasis
1149       role="bold">-template</emphasis> argument to the <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss
1150       bulk</emphasis> command. If you provide a filename only, the command interpreter looks for it in the directories listed just
1151       previously. If you provide a pathname and filename, it looks only in the specified directory, interpreting a partial pathname
1152       relative to the current working directory. <indexterm>
1153           <primary>rules</primary>
1154
1155           <secondary>uss template file</secondary>
1156         </indexterm> <indexterm>
1157           <primary>uss template file</primary>
1158
1159           <secondary>rules for constructing</secondary>
1160         </indexterm></para>
1161     </sect2>
1162
1163     <sect2 id="HDRWQ469">
1164       <title>Some General Rules for Constructing a Template</title>
1165
1166       <para>This section summarizes some general rules to follow when constructing a template file. For each instruction's syntax
1167       definition, see the following sections (<link linkend="HDRWQ472">Evenly Distributing User Home Directories with the G
1168       Instruction</link> through <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>). <itemizedlist>
1169           <listitem>
1170             <para>If a variable takes its value from an element elsewhere within the template, the definition must precede the
1171             reference. Putting the instruction lines in the following order usually results in correct resolution of
1172             variables:</para>
1173
1174             <para><emphasis role="bold">G V D F E L S A X</emphasis></para>
1175           </listitem>
1176
1177           <listitem>
1178             <para>The fields in each instruction must appear in the order specified by the instruction's syntax definition, which
1179             appear in the following sections about each instruction. You cannot omit a field. Separate each field from its neighbors
1180             with one or more spaces.</para>
1181           </listitem>
1182
1183           <listitem>
1184             <para>When specifying a pathname, provide a full one. Partial pathnames are interpreted relative to the current working
1185             directory (the one in which the <emphasis role="bold">uss</emphasis> command is issued), with possibly unintended
1186             results.</para>
1187           </listitem>
1188
1189           <listitem>
1190             <para>Each instruction must appear on a single line in the template file, with a newline character (<emphasis
1191             role="bold">&lt;Return&gt;</emphasis>) only at the end of the instruction. Some example instructions appear in this
1192             document on more than one line, but that is only for legibility.</para>
1193           </listitem>
1194
1195           <listitem>
1196             <para>Provide a value for every variable that appears in the template by including the corresponding argument to the
1197             <emphasis role="bold">uss add</emphasis> command or placing a value in the corresponding field of the bulk input file
1198             <emphasis role="bold">add</emphasis> instruction. A missing value halts the entire creation operation. If a variable
1199             does not appear in the template file, the command interpreter ignores the corresponding command-line argument or field
1200             in the bulk input file, even if you provide it.</para>
1201           </listitem>
1202
1203           <listitem>
1204             <para>You can use blank lines in the template file to increase its legibility. If you place comments in the file, begin
1205             each comment line with the number sign (<emphasis role="bold">#</emphasis>).</para>
1206           </listitem>
1207         </itemizedlist></para>
1208     </sect2>
1209
1210     <sect2 id="HDRWQ470">
1211       <title>About Creating Local Disk Directories and Files</title>
1212
1213       <para>It is possible to use the <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, and <emphasis
1214       role="bold">F</emphasis> instructions to create directories or files in the local file system of the machine on which you are
1215       issuing the <emphasis role="bold">uss</emphasis> command, but that usage is not recommended. It introduces two potential
1216       complications: <itemizedlist>
1217           <listitem>
1218             <para>The local file system automatically assigns ownership of a new local disk directory or file to its creator.
1219             Because you are the issuer of the <emphasis role="bold">uss</emphasis> command that is creating the object, it records
1220             your current UNIX UID. If that is not appropriate and you want to designate another owner as the object is created, then
1221             you must be logged in as the local superuser <emphasis role="bold">root</emphasis> (the local file system allows only
1222             the <emphasis role="bold">root</emphasis> user to issue the UNIX <emphasis role="bold">chown</emphasis> command, which
1223             the <emphasis role="bold">uss</emphasis> command interpreter invokes to change the owner from the default value). You
1224             must also use the <emphasis role="bold">-admin</emphasis> argument to the <emphasis role="bold">uss add</emphasis> or
1225             <emphasis role="bold">uss bulk</emphasis> command to authenticate as a privileged AFS administrator. Only an
1226             administrator can create Authentication Database and Protection Database entries, which the <emphasis
1227             role="bold">uss</emphasis> command interpreter always creates as part of a new account.</para>
1228
1229             <para>The alternative is to become the local superuser <emphasis role="bold">root</emphasis> after the <emphasis
1230             role="bold">uss</emphasis> operation completes, and issue the necessary <emphasis role="bold">chown</emphasis> command
1231             then. However, that makes the account creation process that much less automated.</para>
1232           </listitem>
1233
1234           <listitem>
1235             <para>Creating a local disk directory always generates an error message because the <emphasis role="bold">uss</emphasis>
1236             command interpreter cannot successfully set a local directory's ACL. The directory is created nevertheless, and a value
1237             still must appear in the <emphasis role="bold">D</emphasis> instruction's ACL field.</para>
1238           </listitem>
1239         </itemizedlist></para>
1240
1241       <para>The recommended method for configuring a machine's local disk is to use the AFS <emphasis role="bold">package</emphasis>
1242       utility instead; see <link linkend="HDRWQ419">Configuring Client Machines with the package Program</link>. <indexterm>
1243           <primary>examples</primary>
1244
1245           <secondary>uss template file</secondary>
1246         </indexterm> <indexterm>
1247           <primary>uss template file</primary>
1248
1249           <secondary>examples</secondary>
1250         </indexterm></para>
1251     </sect2>
1252
1253     <sect2 id="HDRWQ471">
1254       <title>Example uss Templates</title>
1255
1256       <para>This section describes example templates for the basic and full account types (the template for an authentication-only
1257       account is empty).</para>
1258
1259       <para>The first example creates a basic account. It contains two <emphasis role="bold">G</emphasis> instructions and a
1260       <emphasis role="bold">V</emphasis> instruction that defines the volume name, file server machine, partition, quota in
1261       kilobytes, mount point, home directory owner, and home directory access control list. In the Example Corporation cell, a suitable
1262       template is:</para>
1263
1264       <programlisting>
1265    G /afs/.example.com/usr1
1266    G /afs/.example.com/usr2
1267    V  user.$USER  $SERVER.example.com  /vicep$PART  5000  $AUTO/$USER   $UID  \
1268         $USER all staff rl
1269 </programlisting>
1270
1271       <para>When issuing the <emphasis role="bold">uss add</emphasis> command with this type of template, provide the following
1272       arguments: <itemizedlist>
1273           <listitem>
1274             <para><emphasis role="bold">-user</emphasis> to specify the username for the $USER variable</para>
1275           </listitem>
1276
1277           <listitem>
1278             <para><emphasis role="bold">-server</emphasis> to specify the unique part of the file server machine name for the
1279             $SERVER variable</para>
1280           </listitem>
1281
1282           <listitem>
1283             <para><emphasis role="bold">-partition</emphasis> to specify the unique part of the partition name for the $PART
1284             variable</para>
1285           </listitem>
1286         </itemizedlist></para>
1287
1288       <para>The Protection Server automatically assigns an AFS UID for the $UID variable, and the <emphasis role="bold">G</emphasis>
1289       instructions provide a value for the $AUTO variable.</para>
1290
1291       <para>The following example template file creates a full account in the Example Corporation cell. The following sections about
1292       each type of instruction describe the effect of the examples. Note that the <emphasis role="bold">V</emphasis> and <emphasis
1293       role="bold">E</emphasis> instructions appear on two lines each only for the sake of legibility.</para>
1294
1295       <programlisting>
1296    #
1297    # Specify the available grouping directories
1298    #
1299    G /afs/.example.com/usr1
1300    G /afs/.example.com/usr2
1301    #
1302    # Create the user's home volume
1303    #
1304    V user.$USER $SERVER.example.com /vicep$PART 5000 /afs/.example.com/$AUTO/$USER \
1305         $UID $USER all abc:staff rl
1306    #
1307    # Create directories and files for mail
1308    #
1309    D $MTPT/.MESSAGES 0700 $UID $USER all abc:staff none 
1310    D $MTPT/.Outgoing 0700 $UID $USER rlidwk postman rlidwk 
1311    D $MTPT/Mailbox 0700 $UID $USER all abc:staff none system:anyuser lik
1312    #
1313    # Here are some useful scripts for login etc.
1314    #
1315    F $MTPT/.Xbiff 0755 $UID /afs/example.com/admin/user/proto
1316    F $MTPT/.Xresources 0644 $UID /afs/example.com/admin/user/proto
1317    F $MTPT/.Xsession 0755 $UID /afs/example.com/admin/user/proto
1318    F $MTPT/.cshrc 0755 $UID /afs/example.com/admin/user/proto
1319    F $MTPT/.login 0755 $UID /afs/example.com/admin/user/proto
1320    F $MTPT/.logout 0755 $UID /afs/example.com/admin/user/proto
1321    F $MTPT/.twmrc 0644 $UID /afs/example.com/admin/user/proto
1322    F $MTPT/preferences 0644 $UID /afs/example.com/admin/user/proto
1323    #
1324    # Make a passwd entry
1325    #
1326    E /afs/.example.com/common/etc/newaccts/passwd_$USER 0644 root \
1327         "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
1328    #
1329    # Put in the standard password/authentication checks
1330    #
1331    A $USER 250 noreuse 9 25
1332    #
1333    # Create and mount a public volume for the user
1334    #
1335    X "create_public_vol $USER $1 $2"
1336    #
1337    # Here we set up the symbolic link to public directory
1338    #
1339    S /afs/example.com/public/$USER $MTPT/public
1340 </programlisting>
1341
1342       <indexterm>
1343         <primary>uss commands</primary>
1344
1345         <secondary>directory</secondary>
1346
1347         <tertiary>distributing evenly with G instruction</tertiary>
1348       </indexterm>
1349
1350       <indexterm>
1351         <primary>defining</primary>
1352
1353         <secondary>directory for even distribution of accounts with uss</secondary>
1354       </indexterm>
1355
1356       <indexterm>
1357         <primary>directory</primary>
1358
1359         <secondary>defining for even distribution of accounts with uss</secondary>
1360       </indexterm>
1361
1362       <indexterm>
1363         <primary>uss template file</primary>
1364
1365         <secondary>G instruction</secondary>
1366       </indexterm>
1367
1368       <indexterm>
1369         <primary>uss template file</primary>
1370
1371         <secondary>directory</secondary>
1372
1373         <tertiary>G instruction for even distribution</tertiary>
1374       </indexterm>
1375     </sect2>
1376
1377     <sect2 id="HDRWQ472">
1378       <title>Evenly Distributing User Home Directories with the G Instruction</title>
1379
1380       <para>In cells with thousands of user accounts, it often makes sense to distribute the mount points for user volumes into
1381       multiple parent directories, because placing them all in one directory noticeably slows down directory lookup when a user home
1382       directory is accessed. A possible solution is to create parent directories that group user home directories alphabetically, or
1383       that reflect divisions like academic or corporate departments. However, in a really large cell, some such groups can still be
1384       large enough to slow directory lookup, and users who belong to those groups are unfairly penalized every time they access
1385       their home directory. Another drawback to groupings that reflect workplace divisions is that you must move mount points when
1386       users change departmental affiliation.</para>
1387
1388       <para>An alternative is an even distribution of user home directories into multiple parent directories that do not represent
1389       workplace divisions. The <emphasis role="bold">uss</emphasis> command suite enables you to define a list of directories by
1390       placing a <emphasis role="bold">G</emphasis> instruction for each one at the top of the template file, and then using the
1391       $AUTO variable in the <emphasis role="bold">V</emphasis> instruction's mount_point field. When the <emphasis
1392       role="bold">uss</emphasis> command interpreter encounters the $AUTO variable, it substitutes the directory named by a
1393       <emphasis role="bold">G</emphasis> instruction that currently has the fewest entries. (Actually, the $AUTO variable can appear
1394       in any field that includes a pathname, in any type of instruction. In all cases, the command interpreter substitutes the
1395       directory that currently has the fewest entries.)</para>
1396
1397       <para>The <emphasis role="bold">G</emphasis> instruction's syntax is as follows:</para>
1398
1399       <programlisting>
1400    G  directory
1401 </programlisting>
1402
1403       <para>where directory specifies either a complete directory pathname or only the final element (the directory itself). The
1404       choice determines the appropriate value to place in the <emphasis role="bold">V</emphasis> instruction's mount_point
1405       field.</para>
1406
1407       <para>Specify the read/write path to each directory, to avoid the failure that results when you attempt to create a new mount
1408       point in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
1409       pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For further discussion of the concept
1410       of read/write and read-only paths through the filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
1411
1412       <para>For example, the Example Corporation example template for a full account in <link linkend="HDRWQ471">Example uss
1413       Templates</link> defines two directories:</para>
1414
1415       <programlisting>
1416    G /afs/.example.com/usr1
1417    G /afs/.example.com/usr2
1418 </programlisting>
1419
1420       <para>and puts the value <emphasis role="bold">$AUTO/$USER</emphasis> in the <emphasis role="bold">V</emphasis> instruction's
1421       mount_point field. An alternative with the same result is to define the directories as follows:</para>
1422
1423       <programlisting>
1424    G usr1
1425    G usr2
1426 </programlisting>
1427
1428       <para>and specify a more complete pathname in the <emphasis role="bold">V</emphasis> instruction's mount_point field:
1429       <emphasis role="bold">/afs/.example.com/$AUTO/$USER</emphasis>. <indexterm>
1430           <primary>uss commands</primary>
1431
1432           <secondary>volume</secondary>
1433
1434           <tertiary>creating with V instruction</tertiary>
1435         </indexterm> <indexterm>
1436           <primary>creating</primary>
1437
1438           <secondary>volume with uss</secondary>
1439         </indexterm> <indexterm>
1440           <primary>volume</primary>
1441
1442           <secondary>creating with uss</secondary>
1443         </indexterm> <indexterm>
1444           <primary>uss template file</primary>
1445
1446           <secondary>V instruction</secondary>
1447         </indexterm> <indexterm>
1448           <primary>uss template file</primary>
1449
1450           <secondary>volume</secondary>
1451
1452           <tertiary>creating with V instruction</tertiary>
1453         </indexterm> <indexterm>
1454           <primary>uss template file</primary>
1455
1456           <secondary>zero-length</secondary>
1457         </indexterm></para>
1458     </sect2>
1459
1460     <sect2 id="HDRWQ473">
1461       <title>Creating a Volume with the V Instruction</title>
1462
1463       <para>Unless the template file is empty (zero-length), one and only one <emphasis role="bold">V</emphasis> instruction must
1464       appear in it. (To create other volumes for a user as part of a <emphasis role="bold">uss</emphasis> account-creation
1465       operation, use the <emphasis role="bold">X</emphasis> instruction to invoke the <emphasis role="bold">vos create</emphasis>
1466       command or a script that invokes that command along with others, such as the <emphasis role="bold">fs mkmount</emphasis>
1467       command. For an example, see <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>.)</para>
1468
1469       <para>The <emphasis role="bold">V</emphasis> instruction defines the following AFS entities:</para>
1470
1471       <itemizedlist>
1472         <listitem>
1473           <para>A volume and associated VLDB entry</para>
1474         </listitem>
1475
1476         <listitem>
1477           <para>The volume's site (file server machine and partition)</para>
1478         </listitem>
1479
1480         <listitem>
1481           <para>The volume's mount point in the AFS filespace, which becomes the user's home directory</para>
1482         </listitem>
1483
1484         <listitem>
1485           <para>The volume's space quota</para>
1486         </listitem>
1487
1488         <listitem>
1489           <para>The home directory's owner, usually the new user</para>
1490         </listitem>
1491
1492         <listitem>
1493           <para>The home directory's ACL, which normally at least grants all permissions to the user</para>
1494         </listitem>
1495       </itemizedlist>
1496
1497       <para>The following discussion of the fields in a <emphasis role="bold">V</emphasis> instruction refers to the example in the
1498       full account template from <link linkend="HDRWQ471">Example uss Templates</link> (the instruction appears here on two lines
1499       only for legibility):</para>
1500
1501       <programlisting>
1502    V  user.$USER  $SERVER.example.com  /vicep$PART  5000  \
1503        /afs/.example.com/$AUTO/$USER  $UID  $USER all abc:staff rl
1504 </programlisting>
1505
1506       <para>The <emphasis role="bold">V</emphasis> instruction's syntax is as follows:</para>
1507
1508       <programlisting>
1509    V  volume_name  server  partition  quota  mount_point owner  ACL
1510 </programlisting>
1511
1512       <para>where <variablelist>
1513           <varlistentry>
1514             <term><emphasis role="bold">V</emphasis></term>
1515
1516             <listitem>
1517               <para>Indicates a volume creation instruction.</para>
1518             </listitem>
1519           </varlistentry>
1520
1521           <varlistentry>
1522             <term><emphasis role="bold">volume_name</emphasis></term>
1523
1524             <listitem>
1525               <para>Specifies the volume's name as recorded in the VLDB.</para>
1526
1527               <para>To follow the convention of including the user's name as part of the volume name, include the $USER variable in
1528               this field. The variable takes its value from the <emphasis role="bold">-user</emphasis> argument to the <emphasis
1529               role="bold">uss add</emphasis> command or from the bulk input file <emphasis role="bold">add</emphasis> instruction's
1530               username field.</para>
1531
1532               <para>The Example Corporation example uses the value <emphasis role="bold">user.$USER</emphasis> to assign the
1533               conventional volume name, <emphasis role="bold">user.</emphasis>username. When creating an account for user <emphasis
1534               role="bold">smith</emphasis>, for example, you then include <emphasis role="bold">-user smith</emphasis> as an
1535               argument to the <emphasis role="bold">uss add</emphasis> command, or place the value <emphasis
1536               role="bold">smith</emphasis> in the bulk input file <emphasis role="bold">add</emphasis> instruction's username
1537               field.</para>
1538             </listitem>
1539           </varlistentry>
1540
1541           <varlistentry>
1542             <term><emphasis role="bold">server</emphasis></term>
1543
1544             <listitem>
1545               <para>Names the file server machine on which to create the new volume. It is best to provide a fully qualified host
1546               name (for example, <emphasis role="bold">fs1.example.com</emphasis>), but an abbreviated form is acceptable if the cell's
1547               naming service is available to resolve it at the time the volume is created.</para>
1548
1549               <para>To place different users' volumes on different file server machines, use the $SERVER variable in this field, and
1550               provide a value for it either with the <emphasis role="bold">-server</emphasis> argument to the <emphasis
1551               role="bold">uss add</emphasis> command or in the server field of the bulk input file <emphasis
1552               role="bold">add</emphasis> instruction. One easy way to specify a fully qualified hostname without having to type it
1553               completely on the command line is to combine a constant and the $SERVER variable. Specifically, the constant specifies
1554               the domain-name suffix common to all the file server machines.</para>
1555
1556               <para>In the Example Corporation example, all of the file server machines in the cell share the <emphasis
1557               role="bold">example.com</emphasis> domain name suffix, so the server field combines a variable and constant: <emphasis
1558               role="bold">$SERVER.example.com</emphasis>. To place the new volume on the machine <emphasis
1559               role="bold">fs1.example.com</emphasis>, you then include <emphasis role="bold">-server fs1</emphasis> as an argument to
1560               the <emphasis role="bold">uss add</emphasis> command, or place the value <emphasis role="bold">fs1</emphasis> in the
1561               bulk input file <emphasis role="bold">add</emphasis> instruction's server field.</para>
1562             </listitem>
1563           </varlistentry>
1564
1565           <varlistentry>
1566             <term><emphasis role="bold">partition</emphasis></term>
1567
1568             <listitem>
1569               <para>Specifies the partition on which to create the user's volume; it must be on the file server machine named in the
1570               server field. Identify the partition by its complete name (for example, <emphasis role="bold">/vicepa</emphasis>) or
1571               use one of the abbreviations listed in <link linkend="HDRWQ615">Rules for Using Abbreviations and
1572               Aliases</link>.</para>
1573
1574               <para>To place different users' volumes on different partitions, use the $PART variable in this field, and provide a
1575               value for it either with the <emphasis role="bold">-partition</emphasis> argument to the <emphasis role="bold">uss
1576               add</emphasis> command or in the partition field of the bulk input file <emphasis role="bold">add</emphasis>
1577               instruction. Because all full partition names start with the <emphasis role="bold">/vicep</emphasis> string, it is
1578               convenient to combine that string as a constant with the $PART variable.</para>
1579
1580               <para>The Example Corporation example template combines the constant string <emphasis role="bold">/vicep</emphasis> and
1581               the $PART variable in this way, as <emphasis role="bold">/vicep$PART</emphasis>. <indexterm>
1582                   <primary>uss commands</primary>
1583
1584                   <secondary>volume</secondary>
1585
1586                   <tertiary>setting quota</tertiary>
1587                 </indexterm> <indexterm>
1588                   <primary>volume quota</primary>
1589
1590                   <secondary>setting</secondary>
1591
1592                   <tertiary>with uss</tertiary>
1593                 </indexterm> <indexterm>
1594                   <primary>uss template file</primary>
1595
1596                   <secondary>quota on volume, setting with V instruction</secondary>
1597                 </indexterm> <indexterm>
1598                   <primary>setting</primary>
1599
1600                   <secondary>volume quota with uss</secondary>
1601                 </indexterm></para>
1602             </listitem>
1603           </varlistentry>
1604
1605           <varlistentry>
1606             <term><emphasis role="bold">quota</emphasis></term>
1607
1608             <listitem>
1609               <para>Sets the maximum number of kilobyte blocks the volume can occupy on the file server machine's disk. It must be
1610               an integer. If you assign the same quota to all user volumes, specify a constant value. To assign different quotas to
1611               different volumes, place one of the number variables ($1 through $9) in this field, and provide a value for it either
1612               with the <emphasis role="bold">-var</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or in
1613               the appropriate field of the bulk input file <emphasis role="bold">add</emphasis> instruction.</para>
1614
1615               <para>The Example Corporation example grants a 5000 KB initial quota to every new user. <indexterm>
1616                   <primary>uss commands</primary>
1617
1618                   <secondary>volume</secondary>
1619
1620                   <tertiary>mounting</tertiary>
1621                 </indexterm> <indexterm>
1622                   <primary>creating</primary>
1623
1624                   <secondary>mount point with uss</secondary>
1625                 </indexterm> <indexterm>
1626                   <primary>uss template file</primary>
1627
1628                   <secondary>mount point, creating with V instruction</secondary>
1629                 </indexterm> <indexterm>
1630                   <primary>mount point</primary>
1631
1632                   <secondary>creating with uss</secondary>
1633                 </indexterm></para>
1634             </listitem>
1635           </varlistentry>
1636
1637           <varlistentry>
1638             <term><emphasis role="bold">mount_point</emphasis></term>
1639
1640             <listitem>
1641               <para>Creates a mount point for the volume, which serves as the volume's root directory and the user's home directory.
1642               By convention, user home directory names include the username, which you can read in by including the $USER variable
1643               in this field.</para>
1644
1645               <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create the
1646               new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period before the
1647               cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the
1648               $AUTO variable in this field, the directories named by each <emphasis role="bold">G</emphasis> instruction possibly
1649               already indicate the read/write path. For further discussion of the concept of read/write and read-only paths through
1650               the filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
1651
1652               <para>If other parts of the mount point name also vary from user to user, you can use the $MTPT variable in this
1653               field, and provide a value with the <emphasis role="bold">uss add</emphasis> command's <emphasis
1654               role="bold">-mount</emphasis> argument or in the mount_point field of a bulk input file <emphasis
1655               role="bold">add</emphasis> instruction. Note, however, that when the $MTPT variable appears in subsequent instructions
1656               in the template (usually, in <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, or <emphasis
1657               role="bold">F</emphasis> instructions), it instead takes as its value the complete contents of this field.</para>
1658
1659               <para>Combine constants and variables based on how you have decided to group home directories together in one or more
1660               parent directories. Note that the parent directories must already exist before you run a <emphasis role="bold">uss
1661               add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command that references the template. Possibilities for
1662               grouping home directories include the following: <indexterm>
1663                   <primary>user account</primary>
1664
1665                   <secondary>methods for grouping</secondary>
1666                 </indexterm> <itemizedlist>
1667                   <listitem>
1668                     <para>Placing all user home directories in a single parent directory; the name <emphasis
1669                     role="bold">/afs/</emphasis>cellname<emphasis role="bold">/usr</emphasis> is an AFS-appropriate variation on the
1670                     UNIX <emphasis role="bold">/usr</emphasis> convention. This choice is most appropriate for a cell with a small
1671                     number of user accounts. The simplest way to implement this choice is to combine a constant string and the $USER
1672                     variable, as in <emphasis role="bold">/afs/.example.com/usr/$USER</emphasis>.</para>
1673                   </listitem>
1674
1675                   <listitem>
1676                     <para>Distributing home directories evenly into a set of parent directories that do not correspond to workplace
1677                     divisions. This choice is appropriate in cells with tens of thousands of accounts, where the number of home
1678                     directories is large enough to slow directory lookup significantly if they all reside together in one parent
1679                     directory, but distribution according to workplace divisions is not feasible.</para>
1680
1681                     <para>The $AUTO variable is designed to distribute home directories evenly in this manner. As explained in <link
1682                     linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link>, the <emphasis
1683                     role="bold">uss</emphasis> command interpreter substitutes the directory that is defined by a preceding
1684                     <emphasis role="bold">G</emphasis> template instruction and that currently has the fewest entries. The example
1685                     Example Corporation template illustrates this choice by using the value <emphasis
1686                     role="bold">/afs/.example.com/$AUTO/$USER</emphasis>.</para>
1687                   </listitem>
1688
1689                   <listitem>
1690                     <para>Distributing home directories into multiple directories that reflect divisions like academic or corporate
1691                     departments. Perhaps the simplest way to implement this scheme is to use the $MTPT variable to represent the
1692                     department, as in <emphasis role="bold">/afs/.example.com/usr/$MTPT/$USER</emphasis>. You then provide <emphasis
1693                     role="bold">-user smith</emphasis> and <emphasis role="bold">-mount acctg</emphasis> arguments to the <emphasis
1694                     role="bold">uss add</emphasis> command to create the mount point <emphasis
1695                     role="bold">/afs/.example.com/usr/acctg/smith</emphasis>.</para>
1696                   </listitem>
1697
1698                   <listitem>
1699                     <para>Distributing home directories into alphabetic subdirectories of <emphasis role="bold">usr</emphasis>
1700                     (<emphasis role="bold">usr/a</emphasis>, <emphasis role="bold">usr/b</emphasis> and so on), based on the first
1701                     letter or letters in the username. The advantage is that knowing the username enables you easily to locate a
1702                     home directory. A potential drawback is that the distribution is not likely to be even, and if there are a large
1703                     number of accounts, then slowed directory lookup unfairly affects users whose names begins with popular
1704                     letters.</para>
1705
1706                     <para>Perhaps the simplest way to implement this scheme is to use the $MTPT variable to represent the letter or
1707                     letters, as in <emphasis role="bold">/afs/.example.com/usr/$MTPT/$USER</emphasis>. Then provide the <emphasis
1708                     role="bold">-user smith</emphasis> and <emphasis role="bold">-mount s/m</emphasis> arguments to the <emphasis
1709                     role="bold">uss add</emphasis> command to create the mount point <emphasis
1710                     role="bold">/afs/.example.com/usr/s/m/smith</emphasis>.</para>
1711                   </listitem>
1712                 </itemizedlist></para>
1713             </listitem>
1714           </varlistentry>
1715
1716           <varlistentry>
1717             <term><emphasis role="bold">owner</emphasis></term>
1718
1719             <listitem>
1720               <para>Specifies the username or UID of the user to be designated the mount point's owner in the output from the UNIX
1721               <emphasis role="bold">ls -ld</emphasis> command. To follow the standard convention for home directory ownership, use
1722               the $UID variable in this field, as in the Example Corporation example template. The Protection Server then automatically
1723               assigns an AFS UID unless you provide the <emphasis role="bold">-uid</emphasis> argument to the <emphasis
1724               role="bold">uss add</emphasis> command or fill in the uid field in the bulk input file <emphasis
1725               role="bold">add</emphasis> instruction. (If you are converting existing UNIX accounts, see the discussion of
1726               additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link>.) <indexterm>
1727                   <primary>uss commands</primary>
1728
1729                   <secondary>ACL, setting on home directory</secondary>
1730                 </indexterm> <indexterm>
1731                   <primary>ACL</primary>
1732
1733                   <secondary>setting on user home directory with uss</secondary>
1734                 </indexterm> <indexterm>
1735                   <primary>uss template file</primary>
1736
1737                   <secondary>ACL, setting</secondary>
1738
1739                   <tertiary>user home directory with V instruction</tertiary>
1740                 </indexterm> <indexterm>
1741                   <primary>setting</primary>
1742
1743                   <secondary>ACL on home directory with uss</secondary>
1744                 </indexterm></para>
1745             </listitem>
1746           </varlistentry>
1747
1748           <varlistentry>
1749             <term><emphasis role="bold">ACL</emphasis></term>
1750
1751             <listitem>
1752               <para>Sets the ACL on the new home directory. Provide one or more paired values, each pair consisting of an AFS
1753               username or group name and the desired permissions, in that order (a group name must already exist in the Protection
1754               Database to be used). Separate the two parts of the pair, and each pair, with a space. For a discussion of the
1755               available permissions, see <link linkend="HDRWQ567">The AFS ACL Permissions</link>.</para>
1756
1757               <para>At minimum, grant all permissions to the new user by including the value <emphasis role="bold">$USER
1758               all</emphasis> in this field. The File Server automatically grants all permissions to the <emphasis
1759               role="bold">system:administrators</emphasis> group as well. You cannot grant permissions to the issuer of the
1760               <emphasis role="bold">uss</emphasis> command, because as the last step in account creation the <emphasis
1761               role="bold">uss</emphasis> command interpreter automatically deletes that user from any ACLs set during the creation
1762               process.</para>
1763
1764               <para>The Example Corporation example uses the following value to grant all permissions to the new user and <emphasis
1765               role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis
1766               role="bold">lookup</emphasis>) permissions to the members of the <emphasis role="bold">abc:staff</emphasis>
1767               group:</para>
1768
1769               <para><emphasis role="bold">$USER all abc:staff rl</emphasis></para>
1770             </listitem>
1771           </varlistentry>
1772         </variablelist></para>
1773
1774       <indexterm>
1775         <primary>uss template file</primary>
1776
1777         <secondary>D instruction</secondary>
1778       </indexterm>
1779
1780       <indexterm>
1781         <primary>uss commands</primary>
1782
1783         <secondary>directory</secondary>
1784
1785         <tertiary>creating</tertiary>
1786       </indexterm>
1787
1788       <indexterm>
1789         <primary>uss template file</primary>
1790
1791         <secondary>directory</secondary>
1792
1793         <tertiary>creating with D instruction</tertiary>
1794       </indexterm>
1795
1796       <indexterm>
1797         <primary>creating</primary>
1798
1799         <secondary>directory with uss</secondary>
1800       </indexterm>
1801
1802       <indexterm>
1803         <primary>directory</primary>
1804
1805         <secondary>creating with uss</secondary>
1806       </indexterm>
1807
1808       <indexterm>
1809         <primary>D instruction</primary>
1810
1811         <secondary>uss template file</secondary>
1812       </indexterm>
1813     </sect2>
1814
1815     <sect2 id="HDRWQ474">
1816       <title>Creating a Directory with the D Instruction</title>
1817
1818       <para>Each <emphasis role="bold">D</emphasis> instruction in the template file creates a directory; there is no limit on the
1819       number of them in the template. If a <emphasis role="bold">D</emphasis> instruction creates a subdirectory in a new user's
1820       home directory (its intended use), then it must follow the <emphasis role="bold">V</emphasis> instruction. Creating a
1821       directory on the local disk of the machine where the <emphasis role="bold">uss</emphasis> command runs is not recommended for
1822       the reasons outlined in <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
1823
1824       <para>The following discussion of the fields in a <emphasis role="bold">D</emphasis> instruction refers to one of the examples
1825       in the full account template in <link linkend="HDRWQ471">Example uss Templates</link>:</para>
1826
1827       <programlisting>
1828    D $MTPT/Mailbox 0700 $UID $USER all abc:staff none  system:anyuser lik
1829 </programlisting>
1830
1831       <para>The <emphasis role="bold">D</emphasis> instruction's syntax is as follows:</para>
1832
1833       <programlisting>
1834    D  pathname  mode_bits  owner  ACL
1835 </programlisting>
1836
1837       <para>where <variablelist>
1838           <varlistentry>
1839             <term><emphasis role="bold">D</emphasis></term>
1840
1841             <listitem>
1842               <para>Indicates a directory creation instruction.</para>
1843             </listitem>
1844           </varlistentry>
1845
1846           <varlistentry>
1847             <term><emphasis role="bold">pathname</emphasis></term>
1848
1849             <listitem>
1850               <para>Specifies the directory's full pathname. If it is a subdirectory of the user's home directory, it is simplest to
1851               use the $MTPT variable to specify the home directory pathname. When the $MTPT variable appears in a <emphasis
1852               role="bold">D</emphasis> instruction, it takes its value from the preceding <emphasis role="bold">V</emphasis>
1853               instruction's mount_point field (this dependency is why a <emphasis role="bold">D</emphasis> instruction must follow
1854               the <emphasis role="bold">V</emphasis> instruction).</para>
1855
1856               <para>Specify the read/write pathname to the directory, to avoid the failure that results when you attempt to create a
1857               new directory in a read-only volume. By convention, you indicate the read/write path by placing a period before the
1858               cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the
1859               $MTPT variable in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field
1860               possibly already indicates the read/write path. For further discussion of the concept of read/write and read-only
1861               paths through the filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
1862
1863               <para>The Example Corporation example uses the value <emphasis role="bold">$MTPT/Mailbox</emphasis> to place the <emphasis
1864               role="bold">Mailbox</emphasis> subdirectory in the user's home directory.</para>
1865             </listitem>
1866           </varlistentry>
1867
1868           <varlistentry>
1869             <term><emphasis role="bold">mode_bits</emphasis></term>
1870
1871             <listitem>
1872               <para>Defines the directory's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers
1873               corresponding to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to
1874               <emphasis role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
1875               role="bold">rw-r--r--</emphasis>. The first (owner) <emphasis role="bold">x</emphasis> bit must be turned on to enable
1876               access to a directory.</para>
1877
1878               <para>The Example Corporation example uses the value <emphasis role="bold">0700</emphasis> to set the mode bits on the
1879               <emphasis role="bold">Mailbox</emphasis> subdirectory to <emphasis role="bold">rwxr-----</emphasis>.</para>
1880             </listitem>
1881           </varlistentry>
1882
1883           <varlistentry>
1884             <term><emphasis role="bold">owner</emphasis></term>
1885
1886             <listitem>
1887               <para>Specifies the username or UID of the user to be designated the directory's owner in the output from the UNIX
1888               <emphasis role="bold">ls -ld</emphasis> command.</para>
1889
1890               <para>If the directory resides in AFS, place the $UID variable in this field, as in the Example Corporation example
1891               template. The Protection Server then automatically assigns an AFS UID unless you provide the <emphasis
1892               role="bold">-uid</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or fill in the uid field
1893               in the bulk input file <emphasis role="bold">add</emphasis> instruction. (If you are converting existing UNIX
1894               accounts, see the discussion of additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX
1895               Accounts with uss</link>.)</para>
1896
1897               <para>If the directory resides on the local disk, it is simplest to specify the username or UNIX UID under which you
1898               are issuing the <emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from
1899               designating another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.
1900               <indexterm>
1901                   <primary>ACL</primary>
1902
1903                   <secondary>setting for directory with uss</secondary>
1904                 </indexterm> <indexterm>
1905                   <primary>setting</primary>
1906
1907                   <secondary>ACL for directory with uss</secondary>
1908                 </indexterm> <indexterm>
1909                   <primary>uss template file</primary>
1910
1911                   <secondary>ACL, setting</secondary>
1912
1913                   <tertiary>directory created by D instruction</tertiary>
1914                 </indexterm> <indexterm>
1915                   <primary>uss commands</primary>
1916
1917                   <secondary>ACL, setting for directory</secondary>
1918                 </indexterm></para>
1919             </listitem>
1920           </varlistentry>
1921
1922           <varlistentry>
1923             <term><emphasis role="bold">ACL</emphasis></term>
1924
1925             <listitem>
1926               <para>Sets the ACL on the new directory. Provide one or more paired values, each pair consisting of an AFS username or
1927               group name and the desired permissions, in that order (a group name must already exist in the Protection Database to
1928               be used). Separate the two parts of the pair, and each pair, with a space. For a description of the available
1929               permissions, see <link linkend="HDRWQ567">The AFS ACL Permissions</link>.</para>
1930
1931               <para>At minimum, grant all permissions to the new user by including the value <emphasis role="bold">$USER
1932               all</emphasis>. You cannot grant permissions to the issuer of the <emphasis role="bold">uss</emphasis> command,
1933               because as the last step in account creation the <emphasis role="bold">uss</emphasis> command interpreter
1934               automatically deletes that user from any ACLs set during the creation process. An error message always appears if the
1935               directory is on the local disk, as detailed in <link linkend="HDRWQ470">About Creating Local Disk Directories and
1936               Files</link>.</para>
1937
1938               <para>The Example Corporation example uses the following value to grant all permissions to the new user, no permissions to
1939               the members of the <emphasis role="bold">abc:staff</emphasis> group, and the <emphasis role="bold">l</emphasis>
1940               (<emphasis role="bold">lookup</emphasis>), <emphasis role="bold">i</emphasis> (<emphasis
1941               role="bold">insert</emphasis>), and <emphasis role="bold">k</emphasis> (<emphasis role="bold">lock</emphasis>)
1942               permissions to the members of the <emphasis role="bold">system:anyuser</emphasis> group:</para>
1943
1944               <para><emphasis role="bold">$USER all abc:staff none system:anyuser lik</emphasis></para>
1945
1946               <para>It grants such extensive permissions to the <emphasis role="bold">system:anyuser</emphasis> group to enable any
1947               system user (including a mail-delivery daemon) to insert mail into the <emphasis role="bold">Mailbox</emphasis>
1948               directory. The absence of the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission
1949               prevents members of the <emphasis role="bold">system:anyuser</emphasis> group from reading the mail files.</para>
1950             </listitem>
1951           </varlistentry>
1952         </variablelist></para>
1953
1954       <indexterm>
1955         <primary>uss commands</primary>
1956
1957         <secondary>file, creating from prototype</secondary>
1958       </indexterm>
1959
1960       <indexterm>
1961         <primary>creating</primary>
1962
1963         <secondary>file with uss</secondary>
1964       </indexterm>
1965
1966       <indexterm>
1967         <primary>file</primary>
1968
1969         <secondary>creating with uss</secondary>
1970       </indexterm>
1971
1972       <indexterm>
1973         <primary>uss template file</primary>
1974
1975         <secondary>F instruction</secondary>
1976       </indexterm>
1977
1978       <indexterm>
1979         <primary>uss template file</primary>
1980
1981         <secondary>file</secondary>
1982
1983         <tertiary>creating from prototype</tertiary>
1984       </indexterm>
1985
1986       <indexterm>
1987         <primary>F instruction</primary>
1988
1989         <secondary>uss template file</secondary>
1990       </indexterm>
1991     </sect2>
1992
1993     <sect2 id="HDRWQ475">
1994       <title>Creating a File from a Prototype with the F Instruction</title>
1995
1996       <para>Each <emphasis role="bold">F</emphasis> instruction in the template file creates a file by copying the contents of an
1997       existing prototype file; there is no limit on the number of them in the template, and each can refer to a different prototype.
1998       If an <emphasis role="bold">F</emphasis> instruction creates a file in a new user's home directory or a subdirectory of it
1999       (the intended use), then it must follow the <emphasis role="bold">V</emphasis> or <emphasis role="bold">D</emphasis>
2000       instruction that creates the parent directory. Creating a file on the local disk of the machine where the <emphasis
2001       role="bold">uss</emphasis> command runs is not recommended for the reasons detailed in <link linkend="HDRWQ470">About Creating
2002       Local Disk Directories and Files</link>.</para>
2003
2004       <para>The <emphasis role="bold">E</emphasis> instruction also creates a file, but the two types of instruction have
2005       complementary advantages. Files created with an <emphasis role="bold">E</emphasis> instruction can be customized for each
2006       user, because variables can appear in the field that specifies the contents of the file. In contrast, the contents of a file
2007       created using the <emphasis role="bold">F</emphasis> instruction are the same for every user. An <emphasis
2008       role="bold">E</emphasis> file can be only a single line, however, whereas an <emphasis role="bold">F</emphasis> file can be
2009       any length.</para>
2010
2011       <para>The following discussion of the fields in a <emphasis role="bold">F</emphasis> instruction refers to one of the examples
2012       in the full account template in <link linkend="HDRWQ471">Example uss Templates</link>:</para>
2013
2014       <programlisting>
2015    F $MTPT/.login 0755 $UID /afs/example.com/admin/user/proto
2016 </programlisting>
2017
2018       <para>The <emphasis role="bold">F</emphasis> instruction's syntax is as follows:</para>
2019
2020       <programlisting>
2021    F  pathname  mode_bits  owner  prototype_file
2022 </programlisting>
2023
2024       <para>where <variablelist>
2025           <varlistentry>
2026             <term><emphasis role="bold">F</emphasis></term>
2027
2028             <listitem>
2029               <para>Indicates a file creation instruction.</para>
2030             </listitem>
2031           </varlistentry>
2032
2033           <varlistentry>
2034             <term><emphasis role="bold">pathname</emphasis></term>
2035
2036             <listitem>
2037               <para>Specifies the full pathname of the file to create, including the filename. If it resides in the user's home
2038               directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname.
2039               When the $MTPT variable appears in an <emphasis role="bold">F</emphasis> instruction, it takes its value from the
2040               preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency is why an <emphasis
2041               role="bold">F</emphasis> instruction must follow the <emphasis role="bold">V</emphasis> instruction).</para>
2042
2043               <para>Specify the read/write path to the file, to avoid the failure that results when you attempt to create a new file
2044               in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
2045               pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the $MTPT variable
2046               in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
2047               indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
2048               filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
2049
2050               <para>The Example Corporation example uses the value <emphasis role="bold">$MTPT/.login</emphasis> to place a file called
2051               <emphasis role="bold">.login</emphasis> in the user's home directory.</para>
2052             </listitem>
2053           </varlistentry>
2054
2055           <varlistentry>
2056             <term><emphasis role="bold">mode_bits</emphasis></term>
2057
2058             <listitem>
2059               <para>Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding
2060               to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to <emphasis
2061               role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
2062               role="bold">rw-r--r--</emphasis>.</para>
2063
2064               <para>The Example Corporation example uses the value <emphasis role="bold">0755</emphasis> to set the mode bits on the
2065               <emphasis role="bold">.login</emphasis> file to <emphasis role="bold">rwxr-xr-x</emphasis>.</para>
2066             </listitem>
2067           </varlistentry>
2068
2069           <varlistentry>
2070             <term><emphasis role="bold">owner</emphasis></term>
2071
2072             <listitem>
2073               <para>Specifies the username or UID of the user to be designated the file's owner in the output from the UNIX
2074               <emphasis role="bold">ls -l</emphasis> command.</para>
2075
2076               <para>If the file resides in AFS, place the $UID variable in this field, as in the Example Corporation example template.
2077               The Protection Server then automatically assigns an AFS UID unless you provide the <emphasis
2078               role="bold">-uid</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or fill in the uid field
2079               in the bulk input file <emphasis role="bold">add</emphasis> instruction. (If you are converting existing UNIX
2080               accounts, see the discussion of additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX
2081               Accounts with uss</link>.)</para>
2082
2083               <para>If the file resides on the local disk, it is simplest to specify the username or UNIX UID under which you are
2084               issuing the <emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from
2085               designating another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
2086             </listitem>
2087           </varlistentry>
2088
2089           <varlistentry>
2090             <term><emphasis role="bold">prototype_file</emphasis></term>
2091
2092             <listitem>
2093               <para>Names the AFS or local directory that houses the prototype file to copy. The prototype file's name must match
2094               the final element in the pathname field.</para>
2095
2096               <para>The Example Corporation example references a prototype file called <emphasis role="bold">.login</emphasis> in the
2097               directory <emphasis role="bold">/afs/example.com/admin/user/proto</emphasis>.</para>
2098             </listitem>
2099           </varlistentry>
2100         </variablelist></para>
2101
2102       <indexterm>
2103         <primary>uss commands</primary>
2104
2105         <secondary>file, creating by echoing one line</secondary>
2106       </indexterm>
2107
2108       <indexterm>
2109         <primary>creating</primary>
2110
2111         <secondary>file with uss</secondary>
2112       </indexterm>
2113
2114       <indexterm>
2115         <primary>file</primary>
2116
2117         <secondary>creating with uss</secondary>
2118       </indexterm>
2119
2120       <indexterm>
2121         <primary>uss template file</primary>
2122
2123         <secondary>E instruction</secondary>
2124       </indexterm>
2125
2126       <indexterm>
2127         <primary>uss template file</primary>
2128
2129         <secondary>file</secondary>
2130
2131         <tertiary>creating by echoing one line</tertiary>
2132       </indexterm>
2133
2134       <indexterm>
2135         <primary>E instruction</primary>
2136
2137         <secondary>uss template file</secondary>
2138       </indexterm>
2139     </sect2>
2140
2141     <sect2 id="HDRWQ476">
2142       <title>Creating One-Line Files with the E Instruction</title>
2143
2144       <para>Each <emphasis role="bold">E</emphasis> instruction in the template file creates a file by echoing a specified single
2145       line into it; there is no limit on the number of them in the template. If an <emphasis role="bold">E</emphasis> instruction
2146       creates a file in a new user's home directory or a subdirectory of it (the intended use), then it must follow the <emphasis
2147       role="bold">V</emphasis> or <emphasis role="bold">D</emphasis> instruction that creates the parent directory. Creating a file
2148       on the local disk of the machine where the <emphasis role="bold">uss</emphasis> command runs is not recommended for the
2149       reasons detailed in <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
2150
2151       <para>The <emphasis role="bold">F</emphasis> instruction also creates a file, but the two types of instruction have
2152       complementary advantages. Files created with an <emphasis role="bold">E</emphasis> instruction can be customized for each
2153       user, because variables can appear in the field that specifies the contents of the file. The command interpreter replaces the
2154       variables with appropriate values before creating the file. In contrast, the contents of a file created using the <emphasis
2155       role="bold">F</emphasis> instruction are the same for every user. An <emphasis role="bold">E</emphasis> file can be only a
2156       single line, however, whereas an <emphasis role="bold">F</emphasis> file can be any length.</para>
2157
2158       <para>The <emphasis role="bold">E</emphasis> instruction is particularly suited to creating an entry for the new user in the
2159       cell's common source password file, which is then copied to client machines to serve as the local password file (<emphasis
2160       role="bold">/etc/passwd</emphasis> or equivalent). The following discussion of the fields refers to an example of this type of
2161       use, from the Example Corporation's full account template shown in <link linkend="HDRWQ471">Example uss Templates</link>. For
2162       further discussion of how to incorporate the files created in this way into a common source password file, see <link
2163       linkend="HDRWQ458">Creating a Common Source Password File</link>.</para>
2164
2165       <programlisting>
2166    E /afs/.example.com/common/etc/newaccts/passwd_$USER 0644 root  \
2167       "$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
2168 </programlisting>
2169
2170       <para>The <emphasis role="bold">E</emphasis> instruction's syntax is as follows:</para>
2171
2172       <programlisting>
2173    E  pathname  mode_bits  owner  "contents"
2174 </programlisting>
2175
2176       <para>where <variablelist>
2177           <varlistentry>
2178             <term><emphasis role="bold">E</emphasis></term>
2179
2180             <listitem>
2181               <para>Indicates a file creation instruction.</para>
2182             </listitem>
2183           </varlistentry>
2184
2185           <varlistentry>
2186             <term><emphasis role="bold">pathname</emphasis></term>
2187
2188             <listitem>
2189               <para>Specifies the full pathname of the file to create, including the filename. It can include variables. If it
2190               resides in the user's home directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the
2191               home directory pathname. When the $MTPT variable appears in an <emphasis role="bold">E</emphasis> instruction, it
2192               takes its value from the preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency
2193               is why an <emphasis role="bold">E</emphasis> instruction must follow the <emphasis role="bold">V</emphasis>
2194               instruction.)</para>
2195
2196               <para>Specify the read/write path to the file, to avoid the failure that results when you attempt to create a new file
2197               in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
2198               pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the $MTPT variable
2199               in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
2200               indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
2201               filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
2202
2203               <para>The Example Corporation example writes the file created by the <emphasis role="bold">E</emphasis> instruction to
2204               <emphasis role="bold">/afs/.example.com/common/etc/newaccts</emphasis> directory, naming it after the new user:</para>
2205
2206               <programlisting>
2207    /afs/.example.com/common/etc/newaccts/passwd_$USER
2208 </programlisting>
2209             </listitem>
2210           </varlistentry>
2211
2212           <varlistentry>
2213             <term><emphasis role="bold">mode_bits</emphasis></term>
2214
2215             <listitem>
2216               <para>Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding
2217               to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to <emphasis
2218               role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
2219               role="bold">rw-r--r--</emphasis>.</para>
2220
2221               <para>The Example Corporation example uses the value <emphasis role="bold">0644</emphasis> to set the mode bits on the
2222               <emphasis role="bold">passwd_</emphasis>user file to <emphasis role="bold">r-xr--r--</emphasis>.</para>
2223             </listitem>
2224           </varlistentry>
2225
2226           <varlistentry>
2227             <term><emphasis role="bold">owner</emphasis></term>
2228
2229             <listitem>
2230               <para>Specifies the username or UID of the user to be designated the file's owner in the output from the UNIX
2231               <emphasis role="bold">ls -l</emphasis> command.</para>
2232
2233               <para>If the file resides in AFS and is to be owned by the user, place the $UID variable in this field. The Protection
2234               Server then automatically assigns an AFS UID unless you provide the <emphasis role="bold">-uid</emphasis> argument to
2235               the <emphasis role="bold">uss add</emphasis> command or fill in the uid field in the bulk input file <emphasis
2236               role="bold">add</emphasis> instruction. (If you are converting existing UNIX accounts, see the discussion of
2237               additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link>.)</para>
2238
2239               <para>If the file resides on the local disk, specify the username or UNIX UID under which you are issuing the
2240               <emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from designating
2241               another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
2242
2243               <para>The Example Corporation example is creating an AFS file intended for incorporation into the common password file,
2244               rather than for direct use by the new user. It therefore designates the local superuser <emphasis
2245               role="bold">root</emphasis> as the owner of the new file. Designating an alternate owner on an AFS file does not
2246               introduce complications: issuing the <emphasis role="bold">chown</emphasis> command on AFS files requires membership
2247               in the <emphasis role="bold">system:administrators</emphasis> group, but the issuer of the <emphasis
2248               role="bold">uss</emphasis> command is necessarily authenticated as a member of that group.</para>
2249             </listitem>
2250           </varlistentry>
2251
2252           <varlistentry>
2253             <term><emphasis role="bold">contents</emphasis></term>
2254
2255             <listitem>
2256               <para>Specifies the one-line character string to write into the new file. Surround it with double quotes if it
2257               contains one or more spaces. It cannot contain the newline character, but can contain any of the standard variables,
2258               which the command interpreter resolves as it creates the file.</para>
2259
2260               <para>The Example Corporation example has the following value in the contents field, to create a password file
2261               entry:</para>
2262
2263               <programlisting>
2264    $USER:X:$UID:10:$NAME:$MTPT:/bin/csh
2265 </programlisting>
2266             </listitem>
2267           </varlistentry>
2268         </variablelist></para>
2269
2270       <indexterm>
2271         <primary>L instruction</primary>
2272
2273         <secondary>uss template file</secondary>
2274       </indexterm>
2275
2276       <indexterm>
2277         <primary>S instruction</primary>
2278
2279         <secondary>uss template file</secondary>
2280       </indexterm>
2281
2282       <indexterm>
2283         <primary>uss</primary>
2284
2285         <secondary>hard link, creating</secondary>
2286       </indexterm>
2287
2288       <indexterm>
2289         <primary>creating</primary>
2290
2291         <secondary>link (hard or symbolic) with uss</secondary>
2292       </indexterm>
2293
2294       <indexterm>
2295         <primary>hard link</primary>
2296
2297         <secondary>creating with uss</secondary>
2298       </indexterm>
2299
2300       <indexterm>
2301         <primary>uss template file</primary>
2302
2303         <secondary>L instruction</secondary>
2304       </indexterm>
2305
2306       <indexterm>
2307         <primary>uss template file</primary>
2308
2309         <secondary>hard link, creating</secondary>
2310       </indexterm>
2311
2312       <indexterm>
2313         <primary>uss</primary>
2314
2315         <secondary>symbolic link, creating</secondary>
2316       </indexterm>
2317
2318       <indexterm>
2319         <primary>symbolic link</primary>
2320
2321         <secondary>creating with uss</secondary>
2322       </indexterm>
2323
2324       <indexterm>
2325         <primary>uss template file</primary>
2326
2327         <secondary>S instruction</secondary>
2328       </indexterm>
2329
2330       <indexterm>
2331         <primary>uss template file</primary>
2332
2333         <secondary>symbolic link, creating</secondary>
2334       </indexterm>
2335     </sect2>
2336
2337     <sect2 id="HDRWQ477">
2338       <title>Creating Links with the L and S Instructions</title>
2339
2340       <para>Each <emphasis role="bold">L</emphasis> instruction in the template file creates a hard link between two files, as
2341       achieved by the standard UNIX <emphasis role="bold">ln</emphasis> command. The <emphasis role="bold">S</emphasis> instruction
2342       creates a symbolic link between two files, as achieved by the standard UNIX <emphasis role="bold">ln -s</emphasis> command. An
2343       explanation of links is beyond the scope of this document, but the basic effect in both cases is to create a second name for
2344       an existing file, so that it can be accessed via either name. Creating a link does not create a second copy of the
2345       file.</para>
2346
2347       <para>There is no limit on the number of <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis> instructions
2348       in a template file. If the link is in a new user's home directory or a subdirectory of it (the intended use), then it must
2349       follow the <emphasis role="bold">V</emphasis> or <emphasis role="bold">D</emphasis> instruction that creates the parent
2350       directory, and the <emphasis role="bold">F</emphasis>, <emphasis role="bold">E</emphasis>, or <emphasis
2351       role="bold">X</emphasis> instruction that creates the file being linked to. Creating a file on the local disk of the machine
2352       where the <emphasis role="bold">uss</emphasis> command runs is not recommended, for the reasons detailed in <link
2353       linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
2354
2355       <para>Note that AFS allows hard links only between files that reside in the same directory. This restriction is necessary to
2356       eliminate the confusion that results from associating two potentially different ACLs (those of the two directories) with the
2357       same file. Symbolic links are legal between two files that reside in different directories and even in different volumes. The
2358       ACL on the actual file applies to the link as well.</para>
2359
2360       <para>You do not set the owner or mode bits on a link created with an <emphasis role="bold">L</emphasis> or <emphasis
2361       role="bold">S</emphasis> instruction, as you do for directories or files. The <emphasis role="bold">uss</emphasis> command
2362       interpreter automatically records the UNIX UID of the <emphasis role="bold">uss</emphasis> command's issuer as the owner, and
2363       sets the mode bits to <emphasis role="bold">lrwxrwxrwx</emphasis> (777).</para>
2364
2365       <para>The following discussion of the fields in an <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis>
2366       instruction refers to an example in the full account template from <link linkend="HDRWQ471">Example uss Templates</link>,
2367       namely</para>
2368
2369       <programlisting>
2370    S /afs/example.com/public/$USER $MTPT/public
2371 </programlisting>
2372
2373       <para>The <emphasis role="bold">L</emphasis> and <emphasis role="bold">S</emphasis> instructions' syntax is as follows:</para>
2374
2375       <programlisting>
2376    L  existing_file  link
2377    S  existing_file  link
2378 </programlisting>
2379
2380       <para>where <variablelist>
2381           <varlistentry>
2382             <term><emphasis role="bold">L</emphasis></term>
2383
2384             <listitem>
2385               <para>Indicates a hard link creation instruction.</para>
2386             </listitem>
2387           </varlistentry>
2388
2389           <varlistentry>
2390             <term><emphasis role="bold">S</emphasis></term>
2391
2392             <listitem>
2393               <para>Indicates a symbolic link creation instruction.</para>
2394             </listitem>
2395           </varlistentry>
2396
2397           <varlistentry>
2398             <term><emphasis role="bold">existing_file</emphasis></term>
2399
2400             <listitem>
2401               <para>Specifies the complete pathname of the existing file. If it resides in the user's home directory or a
2402               subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname. When the $MTPT
2403               variable appears in an <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis> instruction, it takes
2404               its value from the preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency is
2405               why the instruction must follow the <emphasis role="bold">V</emphasis> instruction).</para>
2406
2407               <para>Do not create a symbolic link to a file whose name begins with the number sign (<emphasis
2408               role="bold">#</emphasis>) or percent sign (<emphasis role="bold">%</emphasis>). When the Cache Manager reads a
2409               symbolic link whose contents begin with one of those characters, it interprets it as a regular or read/write mount
2410               point, respectively.</para>
2411
2412               <para>The Example Corporation example creates a link to the publicly readable volume created and mounted by a preceding
2413               <emphasis role="bold">X</emphasis> instruction, by specifying the path to its mount point:</para>
2414
2415               <programlisting>
2416    /afs/example.com/public/$USER
2417 </programlisting>
2418             </listitem>
2419           </varlistentry>
2420
2421           <varlistentry>
2422             <term><emphasis role="bold">link</emphasis></term>
2423
2424             <listitem>
2425               <para>Specifies the complete pathname of the second name for the file. If it resides in the user's home directory or a
2426               subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname.</para>
2427
2428               <para>Specify the read/write path to the link, to avoid the failure that results when you attempt to create a new link
2429               in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
2430               pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). If you use the $MTPT variable
2431               in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
2432               indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
2433               filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
2434
2435               <para>The Example Corporation example creates a link called <emphasis role="bold">public</emphasis> in the user's home
2436               directory:</para>
2437
2438               <programlisting>
2439    $MTPT/public
2440 </programlisting>
2441             </listitem>
2442           </varlistentry>
2443         </variablelist></para>
2444
2445       <indexterm>
2446         <primary>A instruction</primary>
2447
2448         <secondary>uss template file</secondary>
2449       </indexterm>
2450
2451       <indexterm>
2452         <primary>uss commands</primary>
2453
2454         <secondary>password/authentication security, setting with A instruction</secondary>
2455       </indexterm>
2456
2457       <indexterm>
2458         <primary>uss template file</primary>
2459
2460         <secondary>A instruction</secondary>
2461       </indexterm>
2462
2463       <indexterm>
2464         <primary>uss template file</primary>
2465
2466         <secondary>password/authentication security, setting with A instruction</secondary>
2467       </indexterm>
2468     </sect2>
2469
2470     <sect2 id="HDRWQ478">
2471       <title>Increasing Account Security with the A Instruction</title>
2472
2473       <para>The <emphasis role="bold">A</emphasis> instruction in the template file enhances cell security by imposing the following
2474       restrictions on users' password choice and authentication attempts. <itemizedlist>
2475           <listitem>
2476             <para>Limiting the user's password lifetime. When the lifetime expires, the user can no longer use the password to
2477             authenticate and must change it.</para>
2478           </listitem>
2479
2480           <listitem>
2481             <para>Prohibiting the reuse of the user's 20 most-recently used passwords.</para>
2482           </listitem>
2483
2484           <listitem>
2485             <para>Limiting the number of consecutive times that a user can provide an incorrect password during authentication, and
2486             for how long the Authentication Server refuses further authentication attempts after the limit is exceeded (referred to
2487             as an <emphasis>account lockout</emphasis>). For regular user accounts in most cells, the recommended limit is nine and
2488             lockout time is 25 minutes.</para>
2489           </listitem>
2490         </itemizedlist></para>
2491
2492       <para>The following discussion of the fields in an <emphasis role="bold">A</emphasis> instruction refers to the example in the
2493       full account template from <link linkend="HDRWQ471">Example uss Templates</link>, which sets a password lifetime of 250 days,
2494       prohibits reuse of passwords, limits the number of failed authentication attempts to nine, and creates a lockout time of 25
2495       minutes if the authentication limit is exceeded:</para>
2496
2497       <programlisting>
2498    A $USER 250 noreuse 9 25
2499 </programlisting>
2500
2501       <para>The <emphasis role="bold">A</emphasis> instruction's syntax is as follows:</para>
2502
2503       <programlisting>
2504    A  username  password_lifetime  password_reuse  failures  locktime
2505 </programlisting>
2506
2507       <para>where <variablelist>
2508           <varlistentry>
2509             <term><emphasis role="bold">A</emphasis></term>
2510
2511             <listitem>
2512               <para>Indicates a security enhancing instruction.</para>
2513             </listitem>
2514           </varlistentry>
2515
2516           <varlistentry>
2517             <term><emphasis role="bold">username</emphasis></term>
2518
2519             <listitem>
2520               <para>Names the Authentication Database entry on which to impose security restrictions. Use the $USER variable to read
2521               in the username from the <emphasis role="bold">uss add</emphasis> command's <emphasis role="bold">-user</emphasis>
2522               argument, or from the username field of an <emphasis role="bold">add</emphasis> instruction in the bulk input file.
2523               The Example Corporation example uses this value.</para>
2524             </listitem>
2525           </varlistentry>
2526
2527           <varlistentry>
2528             <term><emphasis role="bold">password_lifetime</emphasis></term>
2529
2530             <listitem>
2531               <para>Sets the number of days after the user's password is changed that it remains valid. When the password becomes
2532               invalid (expires), the user is unable to authenticate, but has 30 more days in which to issue the <emphasis
2533               role="bold">kpasswd</emphasis> command to change the password (after that, only an administrator can change
2534               it).</para>
2535
2536               <para>Specify an integer from the range <emphasis role="bold">1</emphasis> through <emphasis
2537               role="bold">254</emphasis> to specify the number of days until expiration, the value <emphasis
2538               role="bold">0</emphasis> to indicate that the password never expires, or the value $PWEXPIRES to read in the number of
2539               days from the <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command's
2540               <emphasis role="bold">-pwexpires</emphasis> argument. If the <emphasis role="bold">A</emphasis> instruction does not
2541               appear in the template file, by default the user's password never expires.</para>
2542
2543               <para>The Example Corporation example sets a password lifetime of 250 days.</para>
2544             </listitem>
2545           </varlistentry>
2546
2547           <varlistentry>
2548             <term><emphasis role="bold">password_reuse</emphasis></term>
2549
2550             <listitem>
2551               <para>Determines whether or not the user can change his or her password (using the <emphasis
2552               role="bold">kpasswd</emphasis> or <emphasis role="bold">kas setpassword</emphasis> command) to one that is similar to
2553               any of his or her last 20 passwords. The acceptable values are <emphasis role="bold">reuse</emphasis> to allow reuse
2554               and <emphasis role="bold">noreuse</emphasis> to prohibit it. If the <emphasis role="bold">A</emphasis> instruction
2555               does not appear in the template file, the default is to allow password reuse.</para>
2556
2557               <para>The Example Corporation example prohibits password reuse.</para>
2558             </listitem>
2559           </varlistentry>
2560
2561           <varlistentry>
2562             <term><emphasis role="bold">failures</emphasis></term>
2563
2564             <listitem>
2565               <para>Sets the number of consecutive times the user can provide an incorrect password during authentication (using the
2566               <emphasis role="bold">klog</emphasis> command or a login utility that grants AFS tokens). When the user exceeds the
2567               limit, the Authentication Server rejects further authentication attempts for the amount of time specified in the
2568               locktime field.</para>
2569
2570               <para>Specify an integer from the range <emphasis role="bold">1</emphasis> through <emphasis
2571               role="bold">254</emphasis> to specify the number of failures permitted, or the value <emphasis
2572               role="bold">0</emphasis> to indicate that there is no limit to the number of unsuccessful attempts. If the <emphasis
2573               role="bold">A</emphasis> instruction does not appear in the template file, the default is to allow an unlimited number
2574               of failures.</para>
2575
2576               <para>The Example Corporation example sets the limit to nine failed attempts.</para>
2577             </listitem>
2578           </varlistentry>
2579
2580           <varlistentry>
2581             <term><emphasis role="bold">locktime</emphasis></term>
2582
2583             <listitem>
2584               <para>Specifies how long the Authentication Server refuses authentication attempts from a user who has exceeded the
2585               failure limit set in the failures field.</para>
2586
2587               <para>Specify a number of hours and minutes (hh:mm) or minutes only (mm), from the range <emphasis
2588               role="bold">01</emphasis> (one minute) through <emphasis role="bold">36:00</emphasis> (36 hours). The Authentication
2589               Server automatically reduces any larger value to <emphasis role="bold">36:00</emphasis> and also rounds up any nonzero
2590               value to the next highest multiple of 8.5 minutes. A value of <emphasis role="bold">0</emphasis> (zero) sets an
2591               infinite lockout time, in which case an administrator must always issue the <emphasis role="bold">kas
2592               unlock</emphasis> command to unlock the account.</para>
2593
2594               <para>The Example Corporation example sets the lockout time to 25 minutes, which is rounded up to 25 minutes 30 seconds
2595               (the next highest multiple of 8.5 minutes).</para>
2596             </listitem>
2597           </varlistentry>
2598         </variablelist></para>
2599
2600       <indexterm>
2601         <primary>uss commands</primary>
2602
2603         <secondary>command, executing with X instruction</secondary>
2604       </indexterm>
2605
2606       <indexterm>
2607         <primary>executing</primary>
2608
2609         <secondary>command using uss template line</secondary>
2610       </indexterm>
2611
2612       <indexterm>
2613         <primary>commands</primary>
2614
2615         <secondary>executing from uss template file</secondary>
2616       </indexterm>
2617
2618       <indexterm>
2619         <primary>uss template file</primary>
2620
2621         <secondary>X instruction</secondary>
2622       </indexterm>
2623
2624       <indexterm>
2625         <primary>uss template file</primary>
2626
2627         <secondary>command, executing with X instruction</secondary>
2628       </indexterm>
2629
2630       <indexterm>
2631         <primary>X instruction</primary>
2632
2633         <secondary>uss template file</secondary>
2634       </indexterm>
2635     </sect2>
2636
2637     <sect2 id="HDRWQ479">
2638       <title>Executing Commands with the X Instruction</title>
2639
2640       <para>The <emphasis role="bold">X</emphasis> instruction in the template file executes a command, which can be a standard UNIX
2641       command, a shell script or program, or an AFS command. The command string can include standard template variables, and any
2642       number of <emphasis role="bold">X</emphasis> instructions can appear in a template file. If an instruction manipulates an
2643       element created by another instruction, it must appear after that instruction.</para>
2644
2645       <para>The following discussion of the field in an <emphasis role="bold">X</emphasis> instruction refers to the example in the
2646       full account template from <link linkend="HDRWQ471">Example uss Templates</link>:</para>
2647
2648       <programlisting>
2649    X "create_public_vol $USER $1 $2"
2650 </programlisting>
2651
2652       <para>The <emphasis role="bold">X</emphasis> instruction's syntax is as follows:</para>
2653
2654       <programlisting>
2655    X "command"
2656 </programlisting>
2657
2658       <para>where command specifies the command to execute. Surround it with double quotes if it contains spaces. The command string
2659       can contain any of the standard variables, which the <emphasis role="bold">uss</emphasis> command interpreter resolves before
2660       passing the command on to the appropriate other command interpreter, but it cannot contain newline characters.</para>
2661
2662       <para>The Example Corporation example invokes a script called <emphasis role="bold">create_public_vol</emphasis>, which creates
2663       another volume associated with the new user and mounts it in a publicly readable part of the Example Corporation's
2664       filespace:</para>
2665
2666       <programlisting>
2667    "create_public_vol $USER $1 $2"
2668 </programlisting>
2669
2670       <para>It uses the $USER variable to read in the username and make it part of both the volume name and mount point name. The
2671       <emphasis role="bold">uss</emphasis> command issuer supplies a file server machine name for the $1 variable and a partition
2672       name for the $2 variable, to specify the site for the new volume. <indexterm>
2673           <primary>creating</primary>
2674
2675           <secondary>user account</secondary>
2676
2677           <tertiary>with uss</tertiary>
2678         </indexterm> <indexterm>
2679           <primary>user</primary>
2680
2681           <secondary>account</secondary>
2682
2683           <see>user account</see>
2684         </indexterm> <indexterm>
2685           <primary>user account</primary>
2686
2687           <secondary>creating</secondary>
2688
2689           <tertiary>with uss</tertiary>
2690         </indexterm> <indexterm>
2691           <primary>username</primary>
2692
2693           <secondary>assigning</secondary>
2694
2695           <tertiary>with uss</tertiary>
2696         </indexterm> <indexterm>
2697           <primary>creating</primary>
2698
2699           <secondary>Protection Database user entry</secondary>
2700
2701           <tertiary>with uss</tertiary>
2702         </indexterm> <indexterm>
2703           <primary>creating</primary>
2704
2705           <secondary>Authentication Database entry</secondary>
2706
2707           <tertiary>with uss</tertiary>
2708         </indexterm> <indexterm>
2709           <primary>Protection Database</primary>
2710
2711           <secondary>user entry</secondary>
2712
2713           <tertiary>creating with uss</tertiary>
2714         </indexterm> <indexterm>
2715           <primary>Authentication Database</primary>
2716
2717           <secondary>entry</secondary>
2718
2719           <tertiary>creating with uss</tertiary>
2720         </indexterm> <indexterm>
2721           <primary>uss commands</primary>
2722
2723           <secondary>creating individual user account</secondary>
2724         </indexterm> <indexterm>
2725           <primary>AFS UID</primary>
2726
2727           <secondary>assigning</secondary>
2728
2729           <tertiary>with uss</tertiary>
2730         </indexterm> <indexterm>
2731           <primary>user</primary>
2732
2733           <secondary>AFS UID, assigning</secondary>
2734         </indexterm></para>
2735     </sect2>
2736   </sect1>
2737
2738   <sect1 id="HDRWQ480">
2739     <title>Creating Individual Accounts with the uss add Command</title>
2740
2741     <para>After you have created a template file, you can create an individual account by issuing the <emphasis role="bold">uss
2742     add</emphasis> command (for template creation instructions see <link linkend="HDRWQ463">Constructing a uss Template
2743     File</link>). When you issue the command, the <emphasis role="bold">uss</emphasis> command interpreter contacts various AFS
2744     servers to perform the following actions: <itemizedlist>
2745         <listitem>
2746           <para>Create a Protection Database entry. By default, the Protection Server assigns an AFS UID which becomes the value of
2747           the $UID variable used in the template.</para>
2748         </listitem>
2749
2750         <listitem>
2751           <para>Create an Authentication Database entry, recording an encrypted version of the initial password.</para>
2752         </listitem>
2753
2754         <listitem>
2755           <para>Create the account components defined in the indicated template file, contacting the File Server, Volume Server, and
2756           Volume Location (VL) Server as necessary.</para>
2757         </listitem>
2758       </itemizedlist></para>
2759
2760     <para>To review which types of instructions to include in a template to create different file system objects, see <link
2761     linkend="HDRWQ463">Constructing a uss Template File</link>. If the template is empty, the <emphasis role="bold">uss
2762     add</emphasis> command creates an authentication-only account consisting of Protection Database and Authentication Database
2763     entries.</para>
2764
2765     <para>When you issue the <emphasis role="bold">uss add</emphasis> command, provide a value for each variable in the template
2766     file by including the corresponding command-line argument. If you fail to supply a value for a variable, the <emphasis
2767     role="bold">uss</emphasis> command interpreter substitutes a null string, which usually causes the account creation to fail. If
2768     you include a command line argument for which the corresponding variable does not appear in the template, it is ignored.</para>
2769
2770     <para><link linkend="TBLWQ481">Table 4</link> summarizes the mappings between variables and the arguments to the <emphasis
2771     role="bold">uss add</emphasis> command. It is adapted from <link linkend="TBLWQ466">Table 3</link>, but includes only those
2772     variables that take their value from command line arguments.</para>
2773
2774     <table id="TBLWQ481" label="4">
2775       <title>Command-line argument sources for uss template variables</title>
2776
2777       <tgroup cols="2">
2778         <colspec colwidth="20*" />
2779
2780         <colspec colwidth="80*" />
2781
2782         <thead>
2783           <row>
2784             <entry><emphasis role="bold">Variable</emphasis></entry>
2785
2786             <entry><emphasis role="bold">Command-line Argument</emphasis></entry>
2787           </row>
2788         </thead>
2789
2790         <tbody>
2791           <row>
2792             <entry>$MTPT</entry>
2793
2794             <entry><emphasis role="bold">-mount</emphasis> (for occurrence in <emphasis role="bold">V</emphasis>
2795             instruction)</entry>
2796           </row>
2797
2798           <row>
2799             <entry>$NAME</entry>
2800
2801             <entry><emphasis role="bold">-realname</emphasis> if provided; otherwise <emphasis role="bold">-user</emphasis></entry>
2802           </row>
2803
2804           <row>
2805             <entry>$PART</entry>
2806
2807             <entry><emphasis role="bold">-partition</emphasis></entry>
2808           </row>
2809
2810           <row>
2811             <entry>$PWEXPIRES</entry>
2812
2813             <entry><emphasis role="bold">-pwexpires</emphasis></entry>
2814           </row>
2815
2816           <row>
2817             <entry>$SERVER</entry>
2818
2819             <entry><emphasis role="bold">-server</emphasis></entry>
2820           </row>
2821
2822           <row>
2823             <entry>$UID</entry>
2824
2825             <entry><emphasis role="bold">-uid</emphasis> if provided; otherwise allocated by Protection Server</entry>
2826           </row>
2827
2828           <row>
2829             <entry>$USER</entry>
2830
2831             <entry><emphasis role="bold">-user</emphasis></entry>
2832           </row>
2833
2834           <row>
2835             <entry>$1 through $9</entry>
2836
2837             <entry><emphasis role="bold">-var</emphasis></entry>
2838           </row>
2839         </tbody>
2840       </tgroup>
2841     </table>
2842
2843     <sect2 id="HDRWQ483">
2844       <title>To create an AFS account with the uss add command</title>
2845
2846       <orderedlist>
2847         <listitem>
2848           <para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
2849           <emphasis role="bold">admin</emphasis> user account has them, or you possibly have a personal administrative account. (To
2850           increase cell security, it is best to create special privileged accounts for use only while performing administrative
2851           procedures; for further discussion, see <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
2852           necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
2853    % <emphasis role="bold">klog</emphasis> admin_user
2854    Password: &lt;<replaceable>admin_password</replaceable>&gt;
2855 </programlisting></para>
2856
2857           <para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>
2858
2859           <itemizedlist>
2860             <listitem>
2861               <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
2862               <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
2863               display the members of the system:administrators group</link>. <programlisting>
2864    % <emphasis role="bold">pts membership system:administrators</emphasis>
2865 </programlisting></para>
2866             </listitem>
2867
2868             <listitem>
2869               <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
2870               role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
2871               users in the UserList file</link>. <programlisting>
2872    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2873 </programlisting></para>
2874             </listitem>
2875
2876             <listitem>
2877               <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. However, the
2878               Authentication Server always prompts you for a password in order to perform its own authentication. The following
2879               instructions direct you to specify the administrative identity on the <emphasis role="bold">uss</emphasis> command
2880               line itself.</para>
2881             </listitem>
2882
2883             <listitem>
2884               <para>The <emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) and <emphasis
2885               role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions on the ACL of the directory in which
2886               you are mounting the user's volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which
2887               is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
2888    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
2889 </programlisting></para>
2890
2891               <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
2892               role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
2893               role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
2894               role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
2895             </listitem>
2896           </itemizedlist>
2897         </listitem>
2898
2899         <listitem>
2900           <para><emphasis role="bold">(Optional)</emphasis> Log in as the local superuser <emphasis role="bold">root</emphasis>.
2901           This is necessary only if you are creating new files or directories in the local file system and want to designate an
2902           alternate owner as the object is created. For a discussion of the issues involved, see <link linkend="HDRWQ470">About
2903           Creating Local Disk Directories and Files</link>.</para>
2904         </listitem>
2905
2906         <listitem>
2907           <para>Verify the location and functionality of the template file you are using. For a description of where the <emphasis
2908           role="bold">uss</emphasis> command interpreter expects to find the template, see <link linkend="HDRWQ468">Where to Place
2909           Template Files</link>. You can always provide an alternate pathname if you wish. Also note the variables used in the
2910           template, to be sure that you provide the corresponding arguments on the <emphasis role="bold">uss</emphasis> command
2911           line.</para>
2912         </listitem>
2913
2914         <listitem>
2915           <para><emphasis role="bold">(Optional)</emphasis> Change to the directory where the template
2916           resides. This affects the type of pathname you must type in Step <link linkend="LIWQ485">6</link>. <programlisting>
2917    % <emphasis role="bold">cd</emphasis> template_directory
2918 </programlisting></para>
2919         </listitem>
2920
2921         <listitem>
2922           <para><emphasis role="bold">(Optional)</emphasis> Run the <emphasis role="bold">uss add</emphasis> command with the
2923           <emphasis role="bold">-dryrun</emphasis> flag to preview the creation of the account. Note any error messages and correct
2924           the cause before reissuing the command without the <emphasis role="bold">-dryrun</emphasis> flag. The next step describes
2925           the <emphasis role="bold">uss add</emphasis> command's syntax. For more information on the <emphasis
2926           role="bold">-dryrun</emphasis> flag, see <link linkend="HDRWQ454">Avoiding and Recovering from Errors and Interrupted
2927           Operations</link>. <indexterm>
2928               <primary>uss commands</primary>
2929
2930               <secondary>add</secondary>
2931             </indexterm><indexterm>
2932               <primary>commands</primary>
2933
2934               <secondary>uss add</secondary>
2935             </indexterm></para>
2936         </listitem>
2937
2938         <listitem id="LIWQ485">
2939           <para>Issue the <emphasis role="bold">uss add</emphasis> command to create the account. Enter the
2940           command on a single line; it appears here on multiple lines only for legibility.</para>
2941
2942           <para>The <emphasis role="bold">uss add</emphasis> operation creates an Authentication Database entry. The Authentication
2943           Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your
2944           local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the <emphasis
2945           role="bold">-admin</emphasis> argument to name an identity that has the <computeroutput>ADMIN</computeroutput> flag on its
2946           Authentication Database entry. To verify that an entry has the flag, issue the <emphasis role="bold">kas
2947           examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the ADMIN flag is set</link>.</para>
2948
2949           <programlisting>
2950    % <emphasis role="bold">uss add</emphasis> <emphasis role="bold">-user</emphasis> &lt;<replaceable>login name</replaceable>&gt;  <emphasis
2951               role="bold">-admin</emphasis> &lt;<replaceable>administrator to authenticate</replaceable>&gt;   \
2952              [<emphasis role="bold">-realname</emphasis> &lt;<replaceable>full name in quotes</replaceable>&gt;] [<emphasis
2953               role="bold">-pass</emphasis> &lt;<replaceable>initial passwd</replaceable>&gt;]   \
2954              [<emphasis role="bold">-pwexpires</emphasis> &lt;<replaceable>password expires in [0..254] days (0 =</replaceable>&gt; never)&gt;]  \
2955              [<emphasis role="bold">-server</emphasis> &lt;<replaceable>FileServer for home volume</replaceable>&gt;]  \
2956              [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>FileServer's disk partition for home volume</replaceable>&gt;]  \
2957              [<emphasis role="bold">-mount</emphasis> &lt;<replaceable>home directory mount point</replaceable>&gt;]  \
2958              [<emphasis role="bold">-uid</emphasis> &lt;<replaceable>uid to assign the user</replaceable>&gt;]  \
2959              [<emphasis role="bold">-template</emphasis> &lt;<replaceable>pathname of template file</replaceable>&gt;]  \
2960              [<emphasis role="bold">-var</emphasis> &lt;<replaceable>auxiliary argument pairs (Numval)</replaceable>&gt;+] [<emphasis
2961               role="bold">-dryrun</emphasis>] \
2962              [<emphasis role="bold">-overwrite</emphasis>] 
2963    Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
2964 </programlisting>
2965
2966           <para>where <variablelist>
2967               <varlistentry>
2968                 <term><emphasis role="bold">ad</emphasis></term>
2969
2970                 <listitem>
2971                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">add</emphasis>.</para>
2972                 </listitem>
2973               </varlistentry>
2974
2975               <varlistentry>
2976                 <term><emphasis role="bold">-user</emphasis></term>
2977
2978                 <listitem>
2979                   <para>Names the user's Authentication Database and Protection Database entries. Because it becomes the username
2980                   (the name under which a user logs in), it must obey the restrictions that many operating systems impose on
2981                   usernames (usually, to contain no more than eight lowercase letters). Also avoid the following characters: colon
2982                   (<emphasis role="bold">:</emphasis>), semicolon (<emphasis role="bold">;</emphasis>), comma (<emphasis
2983                   role="bold">,</emphasis>), at sign (<emphasis role="bold">@</emphasis>), space, newline, and the period (<emphasis
2984                   role="bold">.</emphasis>), which is conventionally used only in special administrative names.</para>
2985
2986                   <para>This argument provides the value for the $USER variable in the template file. For suggestions on
2987                   standardizing usernames, see <link linkend="HDRWQ58">Choosing Usernames and Naming Other Account
2988                   Components</link>.</para>
2989                 </listitem>
2990               </varlistentry>
2991
2992               <varlistentry>
2993                 <term><emphasis role="bold">-admin</emphasis></term>
2994
2995                 <listitem>
2996                   <para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
2997                   Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
2998                   admin_user. Enter the appropriate password as admin_password.</para>
2999                 </listitem>
3000               </varlistentry>
3001
3002               <varlistentry>
3003                 <term><emphasis role="bold">-realname</emphasis></term>
3004
3005                 <listitem>
3006                   <para>Specifies the user's actual full name. If it contains spaces or punctuation, surround it with double quotes.
3007                   If you do not provide it, it defaults to the username provided with the <emphasis role="bold">-user</emphasis>
3008                   argument.</para>
3009
3010                   <para>This argument provides the value for the $NAME variable in the template file. For information about using
3011                   this argument and variable as part of an automated process for creating entries in a local password file such as
3012                   <emphasis role="bold">/etc/passwd</emphasis>, see <link linkend="HDRWQ458">Creating a Common Source Password
3013                   File</link>.</para>
3014                 </listitem>
3015               </varlistentry>
3016
3017               <varlistentry>
3018                 <term><emphasis role="bold">-pass</emphasis></term>
3019
3020                 <listitem>
3021                   <para>Specifies the user's initial password. Although the AFS commands that handle passwords accept strings of
3022                   virtually unlimited length, it is best to use a password of eight characters or less, which is the maximum length
3023                   that many applications and utilities accept.</para>
3024
3025                   <para>Possible choices for initial passwords include the username, a string of digits such as those from a Social
3026                   Security number, or a standard string such as <emphasis role="bold">changeme</emphasis>, which is the default if
3027                   you do not provide this argument. There is no corresponding variable in the template file.</para>
3028
3029                   <para>Instruct users to change their passwords to a truly secret string as soon as they authenticate with AFS for
3030                   the first time. The <emphasis>OpenAFS User Guide</emphasis> explains how to use the <emphasis
3031                   role="bold">kpasswd</emphasis> command to change an AFS password.</para>
3032                 </listitem>
3033               </varlistentry>
3034
3035               <varlistentry>
3036                 <term><emphasis role="bold">-pwexpires</emphasis></term>
3037
3038                 <listitem>
3039                   <para>Sets the number of days after a user's password is changed that it remains valid. Provide an integer from
3040                   the range <emphasis role="bold">1</emphasis> through <emphasis role="bold">254</emphasis> to specify the number of
3041                   days until expiration, or the value <emphasis role="bold">0</emphasis> to indicate that the password never expires
3042                   (the default if you do not provide this argument). When the password becomes invalid (expires), the user is unable
3043                   to authenticate, but has 30 more days in which to issue the <emphasis role="bold">kpasswd</emphasis> command to
3044                   change the password; after that, only an administrator can change it.</para>
3045
3046                   <para>This argument provides the value for the $PWEXPIRES variable in the template file.</para>
3047                 </listitem>
3048               </varlistentry>
3049
3050               <varlistentry>
3051                 <term><emphasis role="bold">-server</emphasis></term>
3052
3053                 <listitem>
3054                   <para>Names the file server machine on which to create the new user's home volume. It is best to provide a fully
3055                   qualified hostname (for example, <emphasis role="bold">fs1.example.com</emphasis>), but an abbreviated form is
3056                   acceptable provided that the cell's naming service is available to resolve it when you issue the <emphasis
3057                   role="bold">uss add</emphasis> command.</para>
3058
3059                   <para>This argument provides the value for the $SERVER variable in the template file. To avoid having to type a
3060                   fully qualified hostname on the command line, combine the $SERVER variable with a constant (for example, the
3061                   cell's domain name) in the server field of the <emphasis role="bold">V</emphasis> instruction in the template
3062                   file. For an example, see <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
3063                 </listitem>