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