Updated chapter 2, sections 1-3 of the Admin Guide
[openafs.git] / doc / xml / AdminGuide / auagd007.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ29">
3   <title>Issues in Cell Configuration and Administration</title>
4
5   <para>This chapter discusses many of the issues to consider when configuring and administering a cell, and directs you to detailed
6   related information available elsewhere in this guide. It is assumed you are already familiar with the material in <link
7   linkend="HDRWQ5">An Overview of OpenAFS Administration</link>.</para>
8
9   <para>It is best to read this chapter before installing your cell's first file server machine or performing any other
10   administrative task.</para>
11
12   <indexterm>
13     <primary>AFS</primary>
14
15     <secondary>differences from UNIX summarized</secondary>
16   </indexterm>
17
18   <indexterm>
19     <primary>UNIX</primary>
20
21     <secondary>differences from AFS summarized</secondary>
22   </indexterm>
23
24   <indexterm>
25     <primary>differences</primary>
26
27     <secondary>between AFS and UNIX, summarized</secondary>
28   </indexterm>
29
30   <sect1 id="HDRWQ30">
31     <title>Differences between AFS and UNIX: A Summary</title>
32
33     <para>AFS behaves like a standard UNIX file system in most respects, while also making file sharing easy within and between
34     cells. This section describes some differences between AFS and the UNIX file system, referring you to more detailed information
35     as appropriate.</para>
36
37     <indexterm>
38       <primary>protection</primary>
39
40       <secondary>AFS compared to UNIX</secondary>
41     </indexterm>
42
43     <sect2 id="Header_35">
44       <title>Differences in File and Directory Protection</title>
45
46       <para>AFS augments the standard UNIX file protection mechanism in two ways: it associates an <emphasis>access control list
47       (ACL)</emphasis> with each directory, and it enables users to define a large number of their own groups, which can be placed
48       on ACLs.</para>
49
50       <para>AFS uses ACLs to protect files and directories, rather than relying exclusively on the mode bits. This has several
51       implications, which are discussed further in the indicated sections: <itemizedlist>
52           <listitem>
53             <para>AFS ACLs use seven access permissions rather than the three UNIX mode bits. See <link linkend="HDRWQ567">The AFS
54             ACL Permissions</link>.</para>
55           </listitem>
56
57           <listitem>
58             <para>For directories, AFS ignores the UNIX mode bits. For files, AFS uses only the first set of mode bits (the
59             <emphasis role="bold">owner</emphasis> bits) , and their meaning interacts with permissions on the directory's ACL. See
60             <link linkend="HDRWQ580">How AFS Interprets the UNIX Mode Bits</link>.</para>
61           </listitem>
62
63           <listitem>
64             <para>A directory's ACL protects all of the files in a directory in the same manner. To apply a more restrictive set of
65             AFS permissions to certain file, place it in directory with a different ACL.</para>
66           </listitem>
67
68           <listitem>
69             <para>Moving a file to a different directory changes its protection. See <link linkend="HDRWQ566">Differences Between
70             UFS and AFS Data Protection</link>.</para>
71           </listitem>
72
73           <listitem>
74             <para>An ACL can include about 20 entries granting different combinations of permissions to different users or groups,
75             rather than only the three UNIX entities represented by the three sets of mode bits. See <link
76             linkend="HDRWQ566">Differences Between UFS and AFS Data Protection</link>.</para>
77           </listitem>
78
79           <listitem>
80             <para>You can designate an AFS file as write-only as in the UNIX file system, by setting only the <emphasis
81             role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit. You cannot designate an AFS directory as
82             write-only, because AFS ignores the mode bits on a directory. See <link linkend="HDRWQ580">How AFS Interprets the UNIX
83             Mode Bits</link>.</para>
84           </listitem>
85         </itemizedlist></para>
86
87       <para>AFS enables users to define the groups of other users. Placing these groups on ACLs extends the same permissions to a
88       number of exactly specified users at the same time, which is much more convenient than placing the individuals on the ACLs
89       directly. See <link linkend="HDRWQ531">Administering the Protection Database</link>.</para>
90
91       <para>There are also system-defined groups, <emphasis role="bold">system:anyuser</emphasis> and <emphasis
92       role="bold">system:authuser</emphasis>, whose presence on an ACL extends access to a wide range of users at once. See <link
93       linkend="HDRWQ535">The System Groups</link> and <link linkend="HDRWQ571">Using Groups on ACLs</link>.</para>
94
95       <indexterm>
96         <primary>authentication</primary>
97
98         <secondary>AFS compared to UNIX</secondary>
99       </indexterm>
100
101       <indexterm>
102         <primary>password</primary>
103
104         <secondary>AFS compared to UNIX</secondary>
105       </indexterm>
106     </sect2>
107
108     <sect2 id="HDRWQ31">
109       <title>Differences in Authentication</title>
110
111       <para>Just as the AFS filespace is distinct from each machine's local file system, AFS authentication is separate from local
112       login. This has two practical implications, which are discussed further in <link linkend="HDRWQ65">Using an AFS-modified login
113       Utility</link>. <itemizedlist>
114           <listitem>
115             <para>To access AFS files, users must both log into the local machine's UNIX file system and authenticate with the AFS
116             authentication service. (Logging into the local UNIX file system is necessary because the AFS filespace is accessed
117             through the Cache Manager, which resides in the local machine's kernel.)</para>
118
119             <para>AFS provides a modified login utility for each system type that accomplishes both local login and AFS
120             authentication in one step, based on a single password. If you choose not to use the AFS-modified login utility, your
121             users must login and authenticate in separate steps, as detailed in the <emphasis>OpenAFS User Guide</emphasis>.</para>
122           </listitem>
123
124           <listitem>
125             <para>Passwords may be stored in two separate places: the Kerberos Server and, optionally, each machine's local password
126             file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) for the UNIX file system. A user's passwords in the
127             two places can differ if desired, though the resulting behavior depends on whether and how the cell is using an
128             AFS-modified login utility.</para>
129           </listitem>
130         </itemizedlist></para>
131     </sect2>
132
133     <sect2 id="Header_37">
134       <title>Differences in the Semantics of Standard UNIX Commands</title>
135
136       <para>This section summarizes how AFS modifies the functionality of some UNIX commands. <variablelist>
137           <indexterm>
138             <primary>chmod command</primary>
139
140             <secondary>AFS compared to UNIX</secondary>
141           </indexterm>
142
143           <indexterm>
144             <primary>commands</primary>
145
146             <secondary>chmod (AFS compared to UNIX)</secondary>
147           </indexterm>
148
149           <indexterm>
150             <primary>setuid programs</primary>
151
152             <secondary>setting mode bits</secondary>
153           </indexterm>
154
155           <varlistentry>
156             <term><emphasis role="bold">The chmod command</emphasis></term>
157
158             <listitem>
159               <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can use this command to turn on
160               the setuid, setgid or sticky mode bits on AFS files. For more information, see <link linkend="HDRWQ409">Determining if
161               a Client Can Run Setuid Programs</link>.</para>
162
163               <indexterm>
164                 <primary>chown command</primary>
165
166                 <secondary>AFS compared to UNIX</secondary>
167               </indexterm>
168
169               <indexterm>
170                 <primary>commands</primary>
171
172                 <secondary>chown (AFS compared to UNIX)</secondary>
173               </indexterm>
174             </listitem>
175           </varlistentry>
176
177           <varlistentry>
178             <term><emphasis role="bold">The chown command</emphasis></term>
179
180             <listitem>
181               <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can issue this command on AFS
182               files.</para>
183
184               <indexterm>
185                 <primary>chgrp command</primary>
186
187                 <secondary>AFS compared to UNIX</secondary>
188               </indexterm>
189
190               <indexterm>
191                 <primary>commands</primary>
192
193                 <secondary>chgrp (AFS compared to UNIX)</secondary>
194               </indexterm>
195             </listitem>
196           </varlistentry>
197
198           <varlistentry>
199             <term><emphasis role="bold">The chgrp command</emphasis></term>
200
201             <listitem>
202               <para>Only members of the <emphasis role="bold">system:administrators</emphasis> can issue this command on AFS files
203               and directories.</para>
204
205               <indexterm>
206                 <primary>groups command</primary>
207
208                 <secondary>AFS compared to UNIX</secondary>
209               </indexterm>
210
211               <indexterm>
212                 <primary>commands</primary>
213
214                 <secondary>groups (AFS compared to UNIX)</secondary>
215               </indexterm>
216             </listitem>
217           </varlistentry>
218
219           <varlistentry>
220             <term><emphasis role="bold">The groups command</emphasis></term>
221
222             <listitem>
223               <para>If the user's AFS tokens are associated with a process authentication group (PAG), the output of this command
224               can include one or two large numbers. To learn about PAGs, see <link linkend="HDRWQ64">Identifying AFS Tokens by
225               PAG</link>.</para>
226
227               <indexterm>
228                 <primary>login utility</primary>
229
230                 <secondary>AFS compared to UNIX</secondary>
231               </indexterm>
232
233               <indexterm>
234                 <primary>commands</primary>
235
236                 <secondary>login (AFS compared to UNIX)</secondary>
237               </indexterm>
238               
239             </listitem>
240           </varlistentry>
241
242           <varlistentry>
243             <term><emphasis role="bold">The login utility</emphasis></term>
244
245             <listitem>
246               <para>AFS-modified login utilities both log the issuer into the local file system and authenticate the user with the
247               AFS authentication service. See <link linkend="HDRWQ65">Using an AFS-modified login Utility</link>.</para>
248
249               <indexterm>
250                 <primary>ln command</primary>
251
252                 <secondary>AFS compared to UNIX</secondary>
253               </indexterm>
254
255               <indexterm>
256                 <primary>commands</primary>
257
258                 <secondary>ln (AFS compared to UNIX)</secondary>
259               </indexterm>
260             </listitem>
261           </varlistentry>
262
263           <varlistentry>
264             <term><emphasis role="bold">The ln command</emphasis></term>
265
266             <listitem>
267               <para>This command cannot create hard links between files in different AFS directories. See <link
268               linkend="HDRWQ32">Creating Hard Links</link>.</para>
269
270               <indexterm>
271                 <primary>sshd command</primary>
272
273                 <secondary>AFS compared to UNIX</secondary>
274               </indexterm>
275
276               <indexterm>
277                 <primary>commands</primary>
278
279                 <secondary>sshd (AFS compared to UNIX)</secondary>
280               </indexterm>
281             </listitem>
282           </varlistentry>
283
284           <varlistentry>
285             <term><emphasis role="bold">The sshd daemon</emphasis></term>
286
287             <listitem>
288               <para>The <ulink url="http://www.openssh.org/">OpenSSH project</ulink> provides an sshd daemon that uses the GSSAPI protocol to pass Kerberos tickets between machines.</para>
289
290               <indexterm>
291                 <primary>ssh command</primary>
292
293                 <secondary>AFS compared to UNIX</secondary>
294               </indexterm>
295
296               <indexterm>
297                 <primary>commands</primary>
298
299                 <secondary>ssh (AFS compared to UNIX)</secondary>
300               </indexterm>
301             </listitem>
302           </varlistentry>
303         </variablelist></para>
304
305       <indexterm>
306         <primary>fsck command</primary>
307
308         <secondary>AFS compared to UNIX</secondary>
309       </indexterm>
310
311       <indexterm>
312         <primary>inode-based fileserver</primary>
313       </indexterm>
314
315       <indexterm>
316         <primary>namei-based fileserver</primary>
317       </indexterm>
318
319       <indexterm>
320         <primary>commands</primary>
321
322         <secondary>fsck (AFS compared to UNIX)</secondary>
323       </indexterm>
324
325       <indexterm>
326         <primary>fsck command</primary>
327
328         <secondary>AFS version</secondary>
329       </indexterm>
330
331       <indexterm>
332         <primary>commands</primary>
333
334         <secondary>fsck (AFS version)</secondary>
335       </indexterm>
336
337       <indexterm>
338         <primary>directories</primary>
339
340         <secondary>lost+found</secondary>
341       </indexterm>
342
343       <indexterm>
344         <primary>lost+found directory</primary>
345       </indexterm>
346     </sect2>
347
348     <sect2 id="Header_38">
349       <title>The AFS version of the fsck Command and inode-based fileservers</title>
350
351       <sidebar>
352         <para>The fileserver uses either of two formats for storing data
353         on disk. The inode format uses a combination of regular files and
354         extra fields stored in the inode data structures that are normally
355         reserved for use by the operating system. The namei interface uses
356         normal file storage and does not use special structures. The
357         choice of storage formats is chosen at compile time and the two
358         formats are incompatible. The storage format must be consistent
359         for the fileserver binaries and all vice partitions on a given
360         fileserver machine.</para>
361       </sidebar>
362       
363       <important><para>This section on fsck advice only applies to the inode-based fileserver binaries. On servers using namei-based binaries, the vendor-supplied fsck is required.</para></important>
364
365       <para>If you are using AFS fileserver binaries compiled with the inode-based format, never run the standard UNIX <emphasis role="bold">fsck</emphasis> command on an AFS file server machine. It does not
366       understand how the File Server organizes volume data on disk, and so moves all AFS data into the <emphasis
367       role="bold">lost+found</emphasis> directory on the partition.</para>
368
369       <para>Instead, use the version of the <emphasis role="bold">fsck</emphasis> program that is included in the AFS distribution.
370       The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to replace the vendor-supplied <emphasis
371       role="bold">fsck</emphasis> program with the AFS version as you install each server machine.</para>
372
373       <para>The AFS version functions like the standard <emphasis role="bold">fsck</emphasis> program on data stored on both UFS and
374       AFS partitions. The appearance of a banner like the following as the <emphasis role="bold">fsck</emphasis> program initializes
375       confirms that you are running the correct one:</para>
376
377       <programlisting>
378    --- AFS (R) version fsck---
379 </programlisting>
380
381       <para>where <emphasis>version</emphasis> is the AFS version. For correct results, it must match the AFS version of the server
382       binaries in use on the machine.</para>
383
384       <para>If you ever accidentally run the standard version of the program, contact your AFS support provider or refer to the <ulink url="http://www.openafs.org/support.html">OpenAFS support web page</ulink> for support options. It is
385       sometimes possible to recover volume data from the <emphasis role="bold">lost+found</emphasis> directory. If the data is not recoverabled, then restoring from backup is recommended.</para>
386
387       <warning><para>Running the fsck binary supplied by the operating system vendor on an fileserver using inode-based binaries will result in data corruption!</para></warning>
388       
389       <indexterm>
390         <primary>hard link</primary>
391
392         <secondary>AFS restrictions on</secondary>
393       </indexterm>
394
395       <indexterm>
396         <primary>restrictions</primary>
397
398         <secondary>on hard links in AFS</secondary>
399       </indexterm>
400     </sect2>
401
402     <sect2 id="HDRWQ32">
403       <title>Creating Hard Links</title>
404
405       <para>AFS does not allow hard links (created with the UNIX <emphasis role="bold">ln</emphasis> command) between files that
406       reside in different directories, because in that case it is unclear which of the directory's ACLs to associate with the
407       link.</para>
408
409       <para>AFS also does not allow hard links to directories, in order to keep the file system organized as a tree.</para>
410
411       <para>It is possible to create symbolic links (with the UNIX <emphasis role="bold">ln -s</emphasis> command) between elements
412       in two different AFS directories, or even between an element in AFS and one in a machine's local UNIX file system. Do not
413       create a symbolic link to a file whose name begins with either a number sign (<emphasis role="bold">#</emphasis>) or a percent
414       sign (<emphasis role="bold">%</emphasis>), however. The Cache Manager interprets such links as a mount point to a regular or
415       read/write volume, respectively.</para>
416
417       <indexterm>
418         <primary>fsync system call</primary>
419
420         <secondary>for files saved on AFS client</secondary>
421       </indexterm>
422
423       <indexterm>
424         <primary>close system call</primary>
425
426         <secondary>for files saved on AFS client</secondary>
427       </indexterm>
428
429       <indexterm>
430         <primary>write</primary>
431
432         <secondary>system call for files saved on AFS client</secondary>
433       </indexterm>
434     </sect2>
435
436     <sect2 id="HDRWQ33">
437       <title>AFS Implements Save on Close</title>
438
439       <para>When an application issues the UNIX <emphasis role="bold">close</emphasis> system call on a file, the Cache Manager
440       performs a synchronous write of the data to the File Server that maintains the central copy of the file. It does not return
441       control to the application until the File Server has acknowledged receipt of the data. For the <emphasis
442       role="bold">fsync</emphasis> system call, control does not return to the application until the File Server indicates that it
443       has written the data to non-volatile storage on the file server machine.</para>
444
445       <para>When an application issues the UNIX <emphasis role="bold">write</emphasis> system call, the Cache Manager writes
446       modifications to the local AFS client cache only. If the local machine crashes or an application program exits without issuing
447       the <emphasis role="bold">close</emphasis> system call, it is possible that the modifications are not recorded in the central
448       copy of the file maintained by the File Server. The Cache Manager does sometimes write this type of modified data from the
449       cache to the File Server without receiving the <emphasis role="bold">close</emphasis> or <emphasis
450       role="bold">fsync</emphasis> system call, for example if it needs to free cache chunks for new data. However, it is not
451       generally possible to predict when the Cache Manager transfers modified data to the File Server in this way.</para>
452
453       <para>The implication is that if an application's <emphasis role="bold">Save</emphasis> option invokes the <emphasis
454       role="bold">write</emphasis> system call rather than <emphasis role="bold">close</emphasis> or <emphasis
455       role="bold">fsync</emphasis>, the changes are not necessarily stored permanently on the File Server machine. Most application
456       programs issue the <emphasis role="bold">close</emphasis> system call for save operations, as well as when they finish
457       handling a file and when they exit.</para>
458     </sect2>
459
460     <sect2 id="Header_41">
461       <title>Setuid Programs</title>
462
463       <indexterm>
464         <primary>setuid programs</primary>
465
466         <secondary>restrictions on</secondary>
467       </indexterm>
468
469       <para>Set the UNIX setuid bit only for the local superuser <emphasis role="bold">root</emphasis>; this does not present an
470       automatic security risk: the local superuser has no special privilege in AFS, but only in the local machine's UNIX file system
471       and kernel.</para>
472
473       <para>Any file can be marked with the setuid bit, but only members of the <emphasis
474       role="bold">system:administrators</emphasis> group can issue the <emphasis role="bold">chown</emphasis> system call or the
475       <emphasis role="bold">chown</emphasis> command.</para>
476
477       <para>The <emphasis role="bold">fs setcell</emphasis> command determines whether setuid programs that originate in a foreign
478       cell can run on a given client machine. See <link linkend="HDRWQ409">Determining if a Client Can Run Setuid
479       Programs</link>.</para>
480
481       <indexterm>
482         <primary>cell</primary>
483
484         <secondary>name</secondary>
485
486         <tertiary>choosing</tertiary>
487       </indexterm>
488
489       <indexterm>
490         <primary>choosing</primary>
491
492         <secondary>name</secondary>
493
494         <tertiary>cell</tertiary>
495       </indexterm>
496
497       <indexterm>
498         <primary>conventions</primary>
499
500         <secondary>cell name</secondary>
501       </indexterm>
502
503       <indexterm>
504         <primary>Internet</primary>
505
506         <secondary>conventions for cell name</secondary>
507       </indexterm>
508     </sect2>
509   </sect1>
510
511   <sect1 id="HDRWQ34">
512     <title>Choosing a Cell Name</title>
513
514     <para>This section explains how to choose a cell name and explains why choosing an appropriate cell name is important.</para>
515
516     <para>Your cell name must distinguish your cell from all others in the AFS global namespace. By conventions, the cell name is
517     the second element in any AFS pathname; therefore, a unique cell name guarantees that every AFS pathname uniquely identifies a
518     file, even if cells use the same directory names at lower levels in their local AFS filespace. For example, both the ABC
519     Corporation cell and the State University cell can have a home directory for the user <emphasis role="bold">pat</emphasis>,
520     because the pathnames are distinct: <emphasis role="bold">/afs/abc.com/usr/pat</emphasis> and <emphasis
521     role="bold">/afs/stateu.edu/usr/pat</emphasis>.</para>
522
523     <para>By convention, cell names follow the ARPA Internet Domain System conventions for site names. If you are already an
524     Internet site, then it is simplest to choose your Internet domain name as the cellname.</para>
525
526     <para>If you are not an Internet site, it is best to choose a unique Internet-style name, particularly if you plan to connect to
527     the Internet in the future. There are a few
528     constraints on AFS cell names: <itemizedlist>
529         <listitem>
530           <para>It can contain as many as 64 characters, but shorter names are better because the cell name frequently is part of
531           machine and file names. If your cell name is long, you can reduce pathname length by creating a symbolic link to the
532           complete cell name, at the second level in your file tree. See <link linkend="HDRWQ42">The Second (Cellname)
533           Level</link>.</para>
534         </listitem>
535
536         <listitem>
537           <para>To guarantee it is suitable for different operating system types, the cell name can contain only lowercase
538           characters, numbers, underscores, dashes, and periods. Do not include command shell metacharacters.</para>
539         </listitem>
540
541         <listitem>
542           <para>It can include any number of fields, which are conventionally separated by periods (see the examples below).</para>
543         </listitem>
544
545         <listitem>
546           <para>It must end in a suffix that indicates the type of institution it is, or the country in which it is situated. The
547           following are some of the standard suffixes: <variablelist>
548               <varlistentry>
549                 <term><emphasis role="bold">.com</emphasis></term>
550
551                 <listitem>
552                   <para>For businesses and other commercial organizations. Example: <emphasis role="bold">abc.com</emphasis> for the
553                   ABC Corporation cell.</para>
554                 </listitem>
555               </varlistentry>
556
557               <varlistentry>
558                 <term><emphasis role="bold">.edu</emphasis></term>
559
560                 <listitem>
561                   <para>For educational institutions such as universities. Example: <emphasis role="bold">stateu.edu</emphasis> for
562                   the State University cell.</para>
563                 </listitem>
564               </varlistentry>
565
566               <varlistentry>
567                 <term><emphasis role="bold">.gov</emphasis></term>
568
569                 <listitem>
570                   <para>For United States government institutions.</para>
571                 </listitem>
572               </varlistentry>
573
574               <varlistentry>
575                 <term><emphasis role="bold">.mil</emphasis></term>
576
577                 <listitem>
578                   <para>For United States military installations.</para>
579                 </listitem>
580               </varlistentry>
581             </variablelist></para>
582         </listitem>
583       </itemizedlist></para>
584
585     <indexterm>
586       <primary>Internet</primary>
587
588       <secondary>Domain Registrar</secondary>
589     </indexterm>
590
591     <indexterm>
592       <primary>Domain Registrar</primary>
593     </indexterm>
594
595     <para>Other suffixes are available if none of these are
596     appropriate. Contact a domain registrar to purchase a domain name for
597     your cell.</para>
598
599     <indexterm>
600       <primary>setting</primary>
601
602       <secondary>cell name</secondary>
603     </indexterm>
604
605     <indexterm>
606       <primary>cell</primary>
607
608       <secondary>name</secondary>
609
610       <tertiary>setting</tertiary>
611     </indexterm>
612
613     <indexterm>
614       <primary>server machine</primary>
615
616       <secondary>setting home cell</secondary>
617     </indexterm>
618
619     <indexterm>
620       <primary>client machine</primary>
621
622       <secondary>setting home cell</secondary>
623     </indexterm>
624
625     <sect2 id="Header_43">
626       <title>How to Set the Cell Name</title>
627
628       <para>The cell name is recorded in two files on the local disk of each file server and client machine. Among other functions,
629       these files define the machine's cell membership and so affect how programs and processes run on the machine; see <link
630       linkend="HDRWQ35">Why Choosing the Appropriate Cell Name is Important</link>. The procedure for setting the cell name is
631       different for the two types of machines.</para>
632
633       <para>For file server machines, the two files that record the cell name are the <emphasis
634       role="bold">/usr/afs/etc/ThisCell</emphasis> and <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> files. As described
635       more explicitly in the <emphasis>OpenAFS Quick Beginnings</emphasis>, you set the cell name in both by issuing the <emphasis
636       role="bold">bos setcellname</emphasis> command on the first file server machine you install in your cell. It is not usually
637       necessary to issue the command again. If you use the Update Server, it distributes
638       its copy of the <emphasis role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files to additional
639       server machines that you install. If you do not use the Update Server, the <emphasis>OpenAFS Quick
640       Beginnings</emphasis> explains how to copy the files manually.</para>
641
642       <para>For client machines, the two files that record the cell name are the <emphasis
643       role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> files. You create
644       these files on a per-client basis, either with a text editor or by copying them onto the machine from a central source in AFS.
645       See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link> for details.</para>
646
647       <para>Change the cell name in these files only when you want to transfer the machine to a different cell (it can only belong
648       to one cell at a time). If the machine is a file server, follow the complete set of instructions in the <emphasis>OpenAFS
649       Quick Beginnings</emphasis> for configuring a new cell. If the machine is a client, all you need to do is change the files
650       appropriately and reboot the machine. The next section explains further the negative consequences of changing the name of an
651       existing cell.</para>
652
653       <para>To set the default cell name used by most AFS commands without changing the local <emphasis
654       role="bold">/usr/vice/etc/ThisCell</emphasis> file, set the AFSCELL environment variable in the command shell. It is worth
655       setting this variable if you need to complete significant administrative work in a foreign cell.</para>
656
657       <note>
658         <para>The <emphasis role="bold">fs checkservers</emphasis> and <emphasis role="bold">fs mkmount</emphasis> commands do not
659         use the AFSCELL variable. The <emphasis role="bold">fs checkservers</emphasis> command always defaults to the cell named in
660         the <emphasis role="bold">ThisCell</emphasis> file, unless the <emphasis role="bold">-cell</emphasis> argument is used. The
661         <emphasis role="bold">fs mkmount</emphasis> command defaults to the cell in which the parent directory of the new mount
662         point resides.</para>
663       </note>
664
665       <indexterm>
666         <primary>ThisCell file (client)</primary>
667
668         <secondary>how used by programs</secondary>
669       </indexterm>
670     </sect2>
671
672     <sect2 id="HDRWQ35">
673       <title>Why Choosing the Appropriate Cell Name is Important</title>
674
675       <para>Take care to select a cell name that is suitable for long-term use. Changing a cell name later is complicated. An
676       appropriate cell name is important because it is the second element in the pathname of all files in a cell's file tree.
677       Because each cell name is unique, its presence in an AFS pathname makes the pathname unique in the AFS global namespace, even
678       if multiple cells use similar filespace organization at lower levels. For instance, it means that every cell can have a home
679       directory called <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
680       role="bold">/usr/pat</emphasis> without causing a conflict. The presence of the cell name in pathnames also means that users
681       in every cell use the same pathname to access a file, whether the file resides in their local cell or in a foreign
682       cell.</para>
683
684       <para>Another reason to choose the correct cell name early in the process of installing your cell is that the cell membership
685       defined in each machine's <emphasis role="bold">ThisCell</emphasis> file affects the performance of many programs and
686       processes running on the machine. For instance, AFS commands (<emphasis role="bold">fs</emphasis>, <emphasis
687       role="bold">kas</emphasis>, <emphasis role="bold">pts</emphasis> and <emphasis role="bold">vos</emphasis> commands) by default
688       execute in the cell of the machine on which they are issued. The command interpreters check the <emphasis
689       role="bold">ThisCell</emphasis> file on the local disk and then contact the database server machines listed in the <emphasis
690       role="bold">CellServDB</emphasis> file for the indicated cell (the <emphasis role="bold">bos</emphasis> commands work
691       differently because the issuer always has to name of the machine on which to run the command).</para>
692       <para>The <emphasis role="bold">ThisCell</emphasis> file also determines the cell for which a
693 user receives an AFS token when
694       he or she logs in to a machine.</para> 
695       <para>This method of converting passwords into encryption keys means that the same password results in different keys in
696       different cells. Even if a user uses the same password in multiple cells, obtaining a user's token from one cell does not
697       enable unauthorized access to the user's account in another cell.</para>
698
699       <para>If you change the cell name, you must change the <emphasis role="bold">ThisCell</emphasis> and <emphasis
700       role="bold">CellServDB</emphasis> files on every server and client machine. Failure to change them all can prevent login,
701       because the encryption keys produced by the login utility do not match the keys stored in the Authentication Database. In
702       addition, many commands from the AFS suites do not work as expected.</para>
703
704       <indexterm>
705         <primary>participation</primary>
706
707         <secondary>in AFS global namespace</secondary>
708       </indexterm>
709
710       <indexterm>
711         <primary>AFS</primary>
712
713         <secondary>global namespace</secondary>
714       </indexterm>
715
716       <indexterm>
717         <primary>global namespace</primary>
718       </indexterm>
719     </sect2>
720   </sect1>
721
722   <sect1 id="HDRWQ36">
723     <title>Participating in the AFS Global Namespace</title>
724
725     <para>Participating in the AFS global namespace makes your cell's local file tree visible to AFS users in foreign cells and
726     makes other cells' file trees visible to your local users. It makes file sharing across cells just as easy as sharing within a
727     cell. This section outlines the procedures necessary for participating in the global namespace. <itemizedlist>
728         <listitem>
729           <para>Participation in the global namespace is not mandatory. Some cells use AFS primarily to facilitate file sharing
730           within the cell, and are not interested in providing their users with access to foreign cells.</para>
731         </listitem>
732
733         <listitem>
734           <para>Making your file tree visible does not mean making it vulnerable. You control how foreign users access your cell
735           using the same protection mechanisms that control local users' access. See <link linkend="HDRWQ40">Granting and Denying
736           Foreign Users Access to Your Cell</link>.</para>
737         </listitem>
738
739         <listitem>
740           <para>The two aspects of participation are independent. A cell can make its file tree visible without allowing its users
741           to see foreign cells' file trees, or can enable its users to see other file trees without advertising its own.</para>
742         </listitem>
743
744         <listitem>
745           <para>You make your cell visible to others by advertising your database server machines. See <link
746           linkend="HDRWQ38">Making Your Cell Visible to Others</link>.</para>
747         </listitem>
748
749         <listitem>
750           <para>You control access to foreign cells on a per-client machine basis. In other words, it is possible to make a foreign
751           cell accessible from one client machine in your cell but not another. See <link linkend="HDRWQ39">Making Other Cells
752           Visible in Your Cell</link>.</para>
753         </listitem>
754       </itemizedlist></para>
755
756     <indexterm>
757       <primary>conventions</primary>
758
759       <secondary>AFS pathnames</secondary>
760     </indexterm>
761
762     <indexterm>
763       <primary>AFS</primary>
764
765       <secondary>root directory (/afs)</secondary>
766
767       <tertiary>on client machine</tertiary>
768     </indexterm>
769
770     <indexterm>
771       <primary>directories</primary>
772
773       <secondary>/afs</secondary>
774     </indexterm>
775
776     <indexterm>
777       <primary>directories</primary>
778
779       <secondary>/afs/<emphasis>cellname</emphasis></secondary>
780     </indexterm>
781
782     <indexterm>
783       <primary>cell</primary>
784
785       <secondary>name</secondary>
786
787       <tertiary>at second level in file tree</tertiary>
788     </indexterm>
789
790     <sect2 id="HDRWQ37">
791       <title>What the Global Namespace Looks Like</title>
792
793       <para>The AFS global namespace appears the same to all AFS cells that participate in it, because they all agree to follow a
794       small set of conventions in constructing pathnames.</para>
795
796       <para>The first convention is that all AFS pathnames begin with the string <emphasis role="bold">/afs</emphasis> to indicate
797       that they belong to the AFS global namespace.</para>
798
799       <para>The second convention is that the cell name is the second element in an AFS pathname; it indicates where the file
800       resides (that is, the cell in which a file server machine houses the file). As noted, the presence of a cell name in pathnames
801       makes the global namespace possible, because it guarantees that all AFS pathnames are unique even if cells use the same
802       directory names at lower levels in their AFS filespace.</para>
803
804       <para>What appears at the third and lower levels in an AFS pathname depends on how a cell has chosen to arrange its filespace.
805       There are some suggested conventional directories at the third level; see <link linkend="HDRWQ43">The Third
806       Level</link>.</para>
807
808       <indexterm>
809         <primary>cell</primary>
810
811         <secondary>making local visible to foreign</secondary>
812       </indexterm>
813
814       <indexterm>
815         <primary>local cell</primary>
816
817         <secondary>making visible to foreign cells</secondary>
818       </indexterm>
819
820       <indexterm>
821         <primary>foreign cell</primary>
822
823         <secondary>making local cell visible</secondary>
824       </indexterm>
825     </sect2>
826
827     <sect2 id="HDRWQ38">
828       <title>Making Your Cell Visible to Others</title>
829
830       <para>You make your cell visible to others by advertising your cell name and database server machines. Just like client
831       machines in the local cell, the Cache Manager on machines in foreign cells use the information to reach your cell's Volume
832       Location (VL) Servers when they need volume and file location information. Similarly, client-side authentication programs
833       running in foreign cells use the information to contact your cell's authentication service.</para>
834
835       <para>There are two places you can make this information available: <itemizedlist>
836           <indexterm>
837             <primary>files</primary>
838
839             <secondary>global CellServDB</secondary>
840           </indexterm>
841
842           <indexterm>
843             <primary>CellServDB file maintained by AFS Product Support</primary>
844
845             <secondary>as global update source</secondary>
846           </indexterm>
847
848           <listitem>
849             <para>In the global <emphasis role="bold">CellServDB</emphasis> file maintained by the AFS Product Support group. This
850             file lists the name and database server machines of every cell that has agreed to make this information available to
851             other cells.</para>
852
853             <para>To add or change your cell's listing in this file, have the official support contact at your site call or write to
854             AFS Product Support. Changes to the file are frequent enough that AFS Product Support does not announce each one. It is
855             a good policy to check the file for changes on a regular schedule.</para>
856
857             <indexterm>
858               <primary>files</primary>
859
860               <secondary>CellServDB.local</secondary>
861             </indexterm>
862
863             <indexterm>
864               <primary>CellServDB.local file</primary>
865             </indexterm>
866           </listitem>
867
868           <listitem>
869             <para>A file called <emphasis role="bold">CellServDB.local</emphasis> in the <emphasis
870             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/service/etc</emphasis> directory
871             of your cell's filespace. List only your cell's database server machines.</para>
872           </listitem>
873         </itemizedlist></para>
874
875       <para>Update the files whenever you change the identity of your cell's database server machines. Also update the copies of the
876       <emphasis role="bold">CellServDB</emphasis> files on all of your server machines (in the <emphasis
877       role="bold">/usr/afs/etc</emphasis> directory) and client machines (in the <emphasis role="bold">/usr/vice/etc</emphasis>
878       directory). For instructions, see <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and <link
879       linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
880
881       <para>Once you have advertised your database server machines, it can be difficult to make your cell invisible again. You can
882       remove the <emphasis role="bold">CellServDB.local</emphasis> file and ask AFS Product Support to remove your entry from the
883       global <emphasis role="bold">CellServDB</emphasis> file, but other cells probably have an entry for your cell in their local
884       <emphasis role="bold">CellServDB</emphasis> files already. To make those entries invalid, you must change the names or IP
885       addresses of your database server machines.</para>
886
887       <para>Your cell does not have to be invisible to be inaccessible, however. To make your cell completely inaccessible to
888       foreign users, remove the <emphasis role="bold">system:anyuser</emphasis> group from all ACLs at the top three levels of your
889       filespace; see <link linkend="HDRWQ40">Granting and Denying Foreign Users Access to Your Cell</link>.</para>
890
891       <indexterm>
892         <primary>cell</primary>
893
894         <secondary>making foreign visible to local</secondary>
895       </indexterm>
896
897       <indexterm>
898         <primary>local cell</primary>
899
900         <secondary>making foreign cells visible in</secondary>
901       </indexterm>
902
903       <indexterm>
904         <primary>foreign cell</primary>
905
906         <secondary>making visible in local cell</secondary>
907       </indexterm>
908
909       <indexterm>
910         <primary>client machine</primary>
911
912         <secondary>making foreign cell visible</secondary>
913       </indexterm>
914     </sect2>
915
916     <sect2 id="HDRWQ39">
917       <title>Making Other Cells Visible in Your Cell</title>
918
919       <para>To make a foreign cell's filespace visible on a client machine in your cell, perform the following three steps:
920       <orderedlist>
921           <listitem>
922             <para>Mount the cell's <emphasis role="bold">root.cell</emphasis> volume at the second level in your cell's filespace
923             just below the <emphasis role="bold">/afs</emphasis> directory. Use the <emphasis role="bold">fs mkmount</emphasis>
924             command with the <emphasis role="bold">-cell</emphasis> argument as instructed in <link linkend="HDRWQ213">To create a
925             cellular mount point</link>.</para>
926           </listitem>
927
928           <listitem>
929             <para>Mount AFS at the <emphasis role="bold">/afs</emphasis> directory on the client machine. The <emphasis
930             role="bold">afsd</emphasis> program, which initializes the Cache Manager, performs the mount automatically at the
931             directory named in the first field of the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file or by the
932             command's <emphasis role="bold">-mountdir</emphasis> argument. Mounting AFS at an alternate location makes it impossible
933             to reach the filespace of any cell that mounts its <emphasis role="bold">root.afs</emphasis> and <emphasis
934             role="bold">root.cell</emphasis> volumes at the conventional locations. See <link linkend="HDRWQ395">Displaying and
935             Setting the Cache Size and Location</link>.</para>
936           </listitem>
937
938           <listitem>
939             <para>Create an entry for the cell in the list of database server machines which the Cache Manager maintains in kernel
940             memory.</para>
941
942             <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on every client machine's local disk lists the
943             database server machines for the local and foreign cells. The <emphasis role="bold">afsd</emphasis> program reads the
944             contents of the <emphasis role="bold">CellServDB</emphasis> file into kernel memory as it initializes the Cache Manager.
945             You can also use the <emphasis role="bold">fs newcell</emphasis> command to add or alter entries in kernel memory
946             directly between reboots of the machine. See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server
947             Machines</link>.</para>
948           </listitem>
949         </orderedlist></para>
950
951       <para>Note that making a foreign cell visible to client machines does not guarantee that your users can access its filespace.
952       The ACLs in the foreign cell must also grant them the necessary permissions.</para>
953
954       <indexterm>
955         <primary>cell</primary>
956
957         <secondary>granting local access to foreign users</secondary>
958       </indexterm>
959
960       <indexterm>
961         <primary>local cell</primary>
962
963         <secondary>granting foreign users access to</secondary>
964       </indexterm>
965     </sect2>
966
967     <sect2 id="HDRWQ40">
968       <title>Granting and Denying Foreign Users Access to Your Cell</title>
969
970       <para>Making your cell visible in the AFS global namespace does not take away your control over the way in which users from
971       foreign cells access your file tree.</para>
972
973       <para>By default, foreign users access your cell as the user <emphasis role="bold">anonymous</emphasis>, which means they have
974       only the permissions granted to the <emphasis role="bold">system:anyuser</emphasis> group on each directory's ACL. Normally
975       these permissions are limited to the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and
976       <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permissions.</para>
977
978       <para>There are two ways to grant wider access to foreign users: <itemizedlist>
979           <listitem>
980             <para>Grant additional permissions to the <emphasis role="bold">system:anyuser</emphasis> group on certain ACLs. Keep in
981             mind, however, that all users can then access that directory in the indicated way (not just specific foreign users you
982             have in mind).</para>
983           </listitem>
984
985           <listitem>
986             <para>Create a local authentication account for specific foreign users, by creating entries in the Protection and
987             Authentication Databases and local password file. It is not possible to place foreign usernames on ACLs, nor to
988             authenticate in a foreign cell without having an account in it.</para>
989           </listitem>
990         </itemizedlist></para>
991
992       <indexterm>
993         <primary>cell</primary>
994
995         <secondary>filespace configuration issues</secondary>
996       </indexterm>
997
998       <indexterm>
999         <primary>configuring</primary>
1000
1001         <secondary>filespace, issues</secondary>
1002       </indexterm>
1003
1004       <indexterm>
1005         <primary>file tree</primary>
1006
1007         <secondary>conventions</secondary>
1008
1009         <tertiary>for configuring</tertiary>
1010       </indexterm>
1011     </sect2>
1012   </sect1>
1013
1014   <sect1 id="HDRWQ41">
1015     <title>Configuring Your AFS Filespace</title>
1016
1017     <para>This section summarizes the issues to consider when configuring your AFS filespace. For a discussion of creating volumes
1018     that correspond most efficiently to the filespace's directory structure, see <link linkend="HDRWQ44">Creating Volumes to
1019     Simplify Administration</link>.</para>
1020
1021     <note>
1022       <para><emphasis role="bold">For Windows users:</emphasis> Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather
1023       than a forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname. The hierarchical
1024       organization of the filespace is however the same as on a UNIX machine.</para>
1025     </note>
1026
1027     <para>AFS pathnames must follow a few conventions so the AFS global namespace looks the same from any AFS client machine. There
1028     are corresponding conventions to follow in building your file tree, not just because pathnames reflect the structure of a file
1029     tree, but also because the AFS Cache Manager expects a certain configuration.</para>
1030
1031     <indexterm>
1032       <primary>AFS</primary>
1033
1034       <secondary>root directory (/afs)</secondary>
1035
1036       <tertiary>in cell filespace</tertiary>
1037     </indexterm>
1038
1039     <indexterm>
1040       <primary>directories</primary>
1041
1042       <secondary>/afs</secondary>
1043     </indexterm>
1044
1045     <sect2 id="Header_51">
1046       <title>The Top /afs Level</title>
1047
1048       <para>The first convention is that the top level in your file tree be called the <emphasis role="bold">/afs</emphasis>
1049       directory. If you name it something else, then you must use the <emphasis role="bold">-mountdir</emphasis> argument with the
1050       <emphasis role="bold">afsd</emphasis> program to get Cache Managers to mount AFS properly. You cannot participate in the AFS
1051       global namespace in that case.</para>
1052
1053       <indexterm>
1054         <primary>cell</primary>
1055
1056         <secondary>name</secondary>
1057
1058         <tertiary>at second level in file tree</tertiary>
1059       </indexterm>
1060
1061       <indexterm>
1062         <primary>directories</primary>
1063
1064         <secondary>/afs/<emphasis>cellname</emphasis></secondary>
1065       </indexterm>
1066
1067       <indexterm>
1068         <primary>symbolic link</primary>
1069
1070         <secondary>at second level of AFS pathname</secondary>
1071       </indexterm>
1072     </sect2>
1073
1074     <sect2 id="HDRWQ42">
1075       <title>The Second (Cellname) Level</title>
1076
1077       <para>The second convention is that just below the <emphasis role="bold">/afs</emphasis> directory you place directories
1078       corresponding to each cell whose file tree is visible and accessible from the local cell. Minimally, there must be a directory
1079       for the local cell. Each such directory is a mount point to the indicated cell's <emphasis role="bold">root.cell</emphasis>
1080       volume. For example, in the ABC Corporation cell, <emphasis role="bold">/afs/abc.com</emphasis> is a mount point for the
1081       cell's own <emphasis role="bold">root.cell</emphasis> volume and <emphasis role="bold">stateu.edu</emphasis> is a mount point
1082       for the State University cell's <emphasis role="bold">root.cell</emphasis> volume. The <emphasis role="bold">fs
1083       lsmount</emphasis> command displays the mount points.</para>
1084
1085       <programlisting>
1086    % <emphasis role="bold">fs lsmount /afs/abc.com</emphasis> 
1087    '/afs/abc.com' is a mount point for volume '#root.cell'
1088    % <emphasis role="bold">fs lsmount /afs/stateu.edu</emphasis>
1089    '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
1090 </programlisting>
1091
1092       <para>To reduce the amount of typing necessary in pathnames, you can create a symbolic link with an abbreviated name to the
1093       mount point of each cell your users frequently access (particularly the home cell). In the ABC Corporation cell, for instance,
1094       <emphasis role="bold">/afs/abc</emphasis> is a symbolic link to the <emphasis role="bold">/afs/abc.com</emphasis> mount point,
1095       as the <emphasis role="bold">fs lsmount</emphasis> command reveals.</para>
1096
1097       <programlisting>
1098    % <emphasis role="bold">fs lsmount /afs/abc</emphasis>
1099    '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
1100 </programlisting>
1101
1102       <indexterm>
1103         <primary>file tree</primary>
1104
1105         <secondary>conventions</secondary>
1106
1107         <tertiary>third level</tertiary>
1108       </indexterm>
1109
1110       <indexterm>
1111         <primary>directories</primary>
1112
1113         <secondary>conventional under /afs/cellname</secondary>
1114       </indexterm>
1115     </sect2>
1116
1117     <sect2 id="HDRWQ43">
1118       <title>The Third Level</title>
1119
1120       <para>You can organize the third level of your cell's file tree any way you wish. The following list describes directories
1121       that appear at this level in the conventional configuration: <variablelist>
1122           <varlistentry>
1123             <term><emphasis role="bold">common</emphasis></term>
1124
1125             <listitem>
1126               <para>This directory contains programs and files needed by users working on machines of all system types, such as text
1127               editors, online documentation files, and so on. Its <emphasis role="bold">/etc</emphasis> subdirectory is a logical
1128               place to keep the central update sources for files used on all of your cell's client machines, such as the <emphasis
1129               role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files.</para>
1130             </listitem>
1131           </varlistentry>
1132
1133           <varlistentry>
1134             <term><emphasis role="bold">public</emphasis></term>
1135
1136             <listitem>
1137               <para>A directory accessible to anyone who can access your filespace, because its ACL grants the <emphasis
1138               role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
1139               role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group. It is useful if
1140               you want to enable your users to make selected information available to everyone, but do not want to grant foreign
1141               users access to the contents of the <emphasis role="bold">usr</emphasis> directory which houses user home directories
1142               (and is also at this level). It is conventional to create a subdirectory for each of your cell's users.</para>
1143             </listitem>
1144           </varlistentry>
1145
1146           <varlistentry>
1147             <term><emphasis role="bold">service</emphasis></term>
1148
1149             <listitem>
1150               <para>This directory contains files and subdirectories that help cells coordinate resource sharing. For a list of the
1151               proposed standard files and subdirectories to create, call or write to AFS Product Support.</para>
1152
1153               <para>As an example, files that other cells expect to find in this directory's <emphasis role="bold">etc</emphasis>
1154               subdirectory can include the following: <itemizedlist>
1155                   <listitem>
1156                     <para><emphasis role="bold">CellServDB.export</emphasis>, a list of database server machines for many
1157                     cells</para>
1158                   </listitem>
1159
1160                   <listitem>
1161                     <para><emphasis role="bold">CellServDB.local</emphasis>, a list of the cell's own database server
1162                     machines</para>
1163                   </listitem>
1164
1165                   <listitem>
1166                     <para><emphasis role="bold">passwd</emphasis>, a copy of the local password file (<emphasis
1167                     role="bold">/etc/passwd</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
1168                   </listitem>
1169
1170                   <listitem>
1171                     <para><emphasis role="bold">group</emphasis>, a copy of the local groups file (<emphasis
1172                     role="bold">/etc/group</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
1173                   </listitem>
1174                 </itemizedlist></para>
1175             </listitem>
1176           </varlistentry>
1177
1178           <varlistentry>
1179             <term><emphasis>sys_type</emphasis></term>
1180
1181             <listitem>
1182               <para>A separate directory for storing the server and client binaries for each system type you use in the cell.
1183               Configuration is simplest if you use the system type names assigned in the AFS distribution, particularly if you wish
1184               to use the <emphasis role="bold">@sys</emphasis> variable in pathnames (see <link linkend="HDRWQ56">Using the @sys
1185               Variable in Pathnames</link>). The <emphasis>OpenAFS Release Notes</emphasis> lists the conventional name for each
1186               supported system type.</para>
1187
1188               <para>Within each such directory, create directories named <emphasis role="bold">bin</emphasis>, <emphasis
1189               role="bold">etc</emphasis>, <emphasis role="bold">usr</emphasis>, and so on, to store the programs normally kept in
1190               the <emphasis role="bold">/bin</emphasis>, <emphasis role="bold">/etc</emphasis> and <emphasis
1191               role="bold">/usr</emphasis> directories on a local disk. Then create symbolic links from the local directories on
1192               client machines into AFS; see <link linkend="HDRWQ55">Configuring the Local Disk</link>. Even if you do not choose to
1193               use symbolic links in this way, it can be convenient to have central copies of system binaries in AFS. If binaries are
1194               accidentally removed from a machine, you can recopy them onto the local disk from AFS rather than having to recover
1195               them from tape</para>
1196             </listitem>
1197           </varlistentry>
1198
1199           <varlistentry>
1200             <term><emphasis role="bold">usr</emphasis></term>
1201
1202             <listitem>
1203               <para>This directory contains home directories for your local users. As discussed in the previous entry for the
1204               <emphasis role="bold">public</emphasis> directory, it is often practical to protect this directory so that only
1205               locally authenticated users can access it. This keeps the contents of your user's home directories as secure as
1206               possible.</para>
1207
1208               <para>If your cell is quite large, directory lookup can be slowed if you put all home directories in a single
1209               <emphasis role="bold">usr</emphasis> directory. For suggestions on distributing user home directories among multiple
1210               grouping directories, see <link linkend="HDRWQ59">Grouping Home Directories</link>.</para>
1211             </listitem>
1212           </varlistentry>
1213
1214           <varlistentry>
1215             <term><emphasis role="bold">wsadmin</emphasis></term>
1216
1217             <listitem>
1218               <para>This directory contains prototype, configuration and library files for use with the <emphasis
1219               role="bold">package</emphasis> program. See <link linkend="HDRWQ419">Configuring Client Machines with the package
1220               Program</link>.</para>
1221             </listitem>
1222           </varlistentry>
1223         </variablelist></para>
1224
1225       <indexterm>
1226         <primary>volume name</primary>
1227
1228         <secondary>conventions for</secondary>
1229       </indexterm>
1230
1231       <indexterm>
1232         <primary>conventions</primary>
1233
1234         <secondary>volume names</secondary>
1235       </indexterm>
1236
1237       <indexterm>
1238         <primary>volume</primary>
1239
1240         <secondary>separate for each top level directory</secondary>
1241       </indexterm>
1242
1243       <indexterm>
1244         <primary>file tree</primary>
1245
1246         <secondary>creating volumes to match top level directories</secondary>
1247       </indexterm>
1248     </sect2>
1249   </sect1>
1250
1251   <sect1 id="HDRWQ44">
1252     <title>Creating Volumes to Simplify Administration</title>
1253
1254     <para>This section discusses how to create volumes in ways that make administering your system easier.</para>
1255
1256     <para>At the top levels of your file tree (at least through the third level), each directory generally corresponds to a separate
1257     volume. Some cells also configure the subdirectories of some third level directories as separate volumes. Common examples are
1258     the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/common</emphasis> and
1259     <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis>
1260     directories.</para>
1261
1262     <para>You do not have to create a separate volume for every directory level in a tree, but the advantage is that each volume
1263     tends to be smaller and easier to move for load balancing. The overhead for a mount point is no greater than for a standard
1264     directory, nor does the volume structure itself require much disk space. Most cells find that below the fourth level in the
1265     tree, using a separate volume for each directory is no longer efficient. For instance, while each user's home directory (at the
1266     fourth level in the tree) corresponds to a separate volume, all of the subdirectories in the home directory normally reside in
1267     the same volume.</para>
1268
1269     <para>Keep in mind that only one volume can be mounted at a given directory location in the tree. In contrast, a volume can be
1270     mounted at several locations, though this is not recommended because it distorts the hierarchical nature of the file tree,
1271     potentially causing confusion.</para>
1272
1273     <indexterm>
1274       <primary>volume name</primary>
1275
1276       <secondary>restrictions</secondary>
1277     </indexterm>
1278
1279     <indexterm>
1280       <primary>restrictions</primary>
1281
1282       <secondary>on volume names</secondary>
1283     </indexterm>
1284
1285     <indexterm>
1286       <primary>volume name</primary>
1287
1288       <secondary>two required</secondary>
1289     </indexterm>
1290
1291     <indexterm>
1292       <primary>volume</primary>
1293
1294       <secondary>root (root.afs and root.cell)</secondary>
1295     </indexterm>
1296
1297     <indexterm>
1298       <primary>root volumes (root.afs and root.cell)</primary>
1299     </indexterm>
1300
1301     <sect2 id="Header_55">
1302       <title>Assigning Volume Names</title>
1303
1304       <para>You can name your volumes anything you choose, subject to a few restrictions: <itemizedlist>
1305           <listitem>
1306             <para>Read/write volume names can be up to 22 characters in length. The maximum length for volume names is 31
1307             characters, and there must be room to add the <emphasis role="bold">.readonly</emphasis> extension on read-only
1308             volumes.</para>
1309           </listitem>
1310
1311           <listitem>
1312             <para>Do not add the <emphasis role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extensions
1313             to volume names yourself, even if they are appropriate. The Volume Server adds them automatically as it creates a
1314             read-only or backup version of a volume.</para>
1315           </listitem>
1316
1317           <listitem>
1318             <para>There must be volumes named <emphasis role="bold">root.afs</emphasis> and <emphasis
1319             role="bold">root.cell</emphasis>, mounted respectively at the top (<emphasis role="bold">/afs</emphasis>) level in the
1320             filespace and just below that level, at the cell's name (for example, at <emphasis role="bold">/afs/abc.com</emphasis>
1321             in the ABC Corporation cell).</para>
1322
1323             <para>Deviating from these names only creates confusion and extra work. Changing the name of the <emphasis
1324             role="bold">root.afs</emphasis> volume, for instance, means that you must use the <emphasis
1325             role="bold">-rootvol</emphasis> argument to the <emphasis role="bold">afsd</emphasis> program on every client machine,
1326             to name the alternate volume.</para>
1327
1328             <para>Similarly, changing the <emphasis role="bold">root.cell</emphasis> volume name prevents users in foreign cells
1329             from accessing your filespace, if the mount point for your cell in their filespace refers to the conventional <emphasis
1330             role="bold">root.cell</emphasis> name. Of course, this is one way to make your cell invisible to other cells.</para>
1331           </listitem>
1332         </itemizedlist></para>
1333
1334       <para>It is best to assign volume names that indicate the type of data they contain, and to use similar names for volumes with
1335       similar contents. It is also helpful if the volume name is similar to (or at least has elements in common with) the name of
1336       the directory at which it is mounted. Understanding the pattern then enables you accurately to guess what a volume contains
1337       and where it is mounted.</para>
1338
1339       <para>Many cells find that the most effective volume naming scheme puts a common prefix on the names of all related volumes.
1340       <link linkend="TBLVOL-PREFIX">Table 1</link> describes the recommended prefixing scheme.</para>
1341
1342       <table id="TBLVOL-PREFIX" label="1">
1343         <title>Suggested volume prefixes</title>
1344
1345         <tgroup cols="4">
1346           <colspec colwidth="14*" />
1347
1348           <colspec colwidth="28*" />
1349
1350           <colspec colwidth="22*" />
1351
1352           <colspec colwidth="36*" />
1353
1354           <thead>
1355             <row>
1356               <entry><emphasis role="bold">Prefix</emphasis></entry>
1357
1358               <entry><emphasis role="bold">Contents</emphasis></entry>
1359
1360               <entry><emphasis role="bold">Example Name</emphasis></entry>
1361
1362               <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
1363             </row>
1364           </thead>
1365
1366           <tbody>
1367             <row>
1368               <entry><emphasis role="bold">common.</emphasis></entry>
1369
1370               <entry>popular programs and files</entry>
1371
1372               <entry><emphasis role="bold">common.etc</emphasis></entry>
1373
1374               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1375               role="bold">/common/etc</emphasis></entry>
1376             </row>
1377
1378             <row>
1379               <entry><emphasis role="bold">src.</emphasis></entry>
1380
1381               <entry>source code</entry>
1382
1383               <entry><emphasis role="bold">src.afs</emphasis></entry>
1384
1385               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1386               role="bold">/src/afs</emphasis></entry>
1387             </row>
1388
1389             <row>
1390               <entry><emphasis role="bold">proj.</emphasis></entry>
1391
1392               <entry>project data</entry>
1393
1394               <entry><emphasis role="bold">proj.portafs</emphasis></entry>
1395
1396               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1397               role="bold">/proj/portafs</emphasis></entry>
1398             </row>
1399
1400             <row>
1401               <entry><emphasis role="bold">test.</emphasis></entry>
1402
1403               <entry>testing or other temporary data</entry>
1404
1405               <entry><emphasis role="bold">test.smith</emphasis></entry>
1406
1407               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1408               role="bold">/usr/smith/test</emphasis></entry>
1409             </row>
1410
1411             <row>
1412               <entry><emphasis role="bold">user.</emphasis></entry>
1413
1414               <entry>user home directory data</entry>
1415
1416               <entry><emphasis role="bold">user.terry</emphasis></entry>
1417
1418               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1419               role="bold">/usr/terry</emphasis></entry>
1420             </row>
1421
1422             <row>
1423               <entry>sys_type<emphasis role="bold">.</emphasis></entry>
1424
1425               <entry>programs compiled for an operating system type</entry>
1426
1427               <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
1428
1429               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1430               role="bold">/rs_aix42/bin</emphasis></entry>
1431             </row>
1432           </tbody>
1433         </tgroup>
1434       </table>
1435
1436       <para><link linkend="TBLPREFIX-EXAMPLE">Table 2</link> is a more specific example for a cell's <emphasis
1437       role="bold">rs_aix42</emphasis> system volumes and directories:</para>
1438
1439       <table id="TBLPREFIX-EXAMPLE" label="2">
1440         <title>Example volume-prefixing scheme</title>
1441
1442         <tgroup cols="2">
1443           <colspec colwidth="14*" />
1444
1445           <colspec colwidth="28*" />
1446
1447           <colspec colwidth="22*" />
1448
1449           <colspec colwidth="36*" />
1450
1451           <thead>
1452             <row>
1453               <entry><emphasis role="bold">Example Name</emphasis></entry>
1454
1455               <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
1456             </row>
1457           </thead>
1458
1459           <tbody>
1460             <row>
1461               <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
1462
1463               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1464               role="bold">/rs_aix42/bin</emphasis>, <emphasis
1465               role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/rs_aix42/bin</emphasis></entry>
1466             </row>
1467
1468             <row>
1469               <entry><emphasis role="bold">rs_aix42.etc</emphasis></entry>
1470
1471               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1472               role="bold">/rs_aix42/etc</emphasis></entry>
1473             </row>
1474
1475             <row>
1476               <entry><emphasis role="bold">rs_aix42.usr</emphasis></entry>
1477
1478               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1479               role="bold">/rs_aix42/usr</emphasis></entry>
1480             </row>
1481
1482             <row>
1483               <entry><emphasis role="bold">rs_aix42.usr.afsws</emphasis></entry>
1484
1485               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1486               role="bold">/rs_aix42/usr/afsws</emphasis></entry>
1487             </row>
1488
1489             <row>
1490               <entry><emphasis role="bold">rs_aix42.usr.lib</emphasis></entry>
1491
1492               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1493               role="bold">/rs_aix42/usr/lib</emphasis></entry>
1494             </row>
1495
1496             <row>
1497               <entry><emphasis role="bold">rs_aix42.usr.bin</emphasis></entry>
1498
1499               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1500               role="bold">/rs_aix42/usr/bin</emphasis></entry>
1501             </row>
1502
1503             <row>
1504               <entry><emphasis role="bold">rs_aix42.usr.etc</emphasis></entry>
1505
1506               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1507               role="bold">/rs_aix42/usr/etc</emphasis></entry>
1508             </row>
1509
1510             <row>
1511               <entry><emphasis role="bold">rs_aix42.usr.inc</emphasis></entry>
1512
1513               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1514               role="bold">/rs_aix42/usr/inc</emphasis></entry>
1515             </row>
1516
1517             <row>
1518               <entry><emphasis role="bold">rs_aix42.usr.man</emphasis></entry>
1519
1520               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1521               role="bold">/rs_aix42/usr/man</emphasis></entry>
1522             </row>
1523
1524             <row>
1525               <entry><emphasis role="bold">rs_aix42.usr.sys</emphasis></entry>
1526
1527               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1528               role="bold">/rs_aix42/usr/sys</emphasis></entry>
1529             </row>
1530
1531             <row>
1532               <entry><emphasis role="bold">rs_aix42.usr.local</emphasis></entry>
1533
1534               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1535               role="bold">/rs_aix42/usr/local</emphasis></entry>
1536             </row>
1537           </tbody>
1538         </tgroup>
1539       </table>
1540
1541       <para>There are several advantages to this scheme: <itemizedlist>
1542           <listitem>
1543             <para>The volume name is similar to the mount point name in the filespace. In all of the entries in <link
1544             linkend="TBLPREFIX-EXAMPLE">Table 2</link>, for example, the only difference between the volume and mount point name is
1545             that the former uses periods as separators and the latter uses slashes. Another advantage is that the volume name
1546             indicates the contents, or at least suggests the directory on which to issue the <emphasis role="bold">ls</emphasis>
1547             command to learn the contents.</para>
1548           </listitem>
1549
1550           <listitem>
1551             <para>It makes it easy to manipulate groups of related volumes at one time. In particular, the <emphasis role="bold">vos
1552             backupsys</emphasis> command's <emphasis role="bold">-prefix</emphasis> argument enables you to create a backup version
1553             of every volume whose name starts with the same string of characters. Making a backup version of each volume is one of
1554             the first steps in backing up a volume with the AFS Backup System, and doing it for many volumes with one command saves
1555             you a good deal of typing. For instructions for creating backup volumes, see <link linkend="HDRWQ201">Creating Backup
1556             Volumes</link>, For information on the AFS Backup System, see <link linkend="HDRWQ248">Configuring the AFS Backup
1557             System</link> and <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
1558           </listitem>
1559
1560           <listitem>
1561             <para>It makes it easy to group related volumes together on a partition. Grouping related volumes together has several
1562             advantages of its own, discussed in <link linkend="HDRWQ49">Grouping Related Volumes on a Partition</link>.</para>
1563           </listitem>
1564         </itemizedlist></para>
1565
1566       <indexterm>
1567         <primary>volume</primary>
1568
1569         <secondary>grouping related on same partition</secondary>
1570       </indexterm>
1571
1572       <indexterm>
1573         <primary>disk partition</primary>
1574
1575         <secondary>grouping related volumes on</secondary>
1576       </indexterm>
1577     </sect2>
1578
1579     <sect2 id="HDRWQ49">
1580       <title>Grouping Related Volumes on a Partition</title>
1581
1582       <para>If your cell is large enough to make it practical, consider grouping related volumes together on a partition. In
1583       general, you need at least three file server machines for volume grouping to be effective. Grouping has several advantages,
1584       which are most obvious when the file server machine becomes inaccessible: <itemizedlist>
1585           <listitem>
1586             <para>If you keep a hardcopy record of the volumes on a partition, you know which volumes are unavailable. You can keep
1587             such a record without grouping related volumes, but a list composed of unrelated volumes is much harder to maintain.
1588             Note that the record must be on paper, because the outage can prevent you from accessing an online copy or from issuing
1589             the <emphasis role="bold">vos listvol</emphasis> command, which gives you the same information.</para>
1590           </listitem>
1591
1592           <listitem>
1593             <para>The effect of an outage is more localized. For example, if all of the binaries for a given system type are on one
1594             partition, then only users of that system type are affected. If a partition houses binary volumes from several system
1595             types, then an outage can affect more people, particularly if the binaries that remain available are interdependent with
1596             those that are not available.</para>
1597           </listitem>
1598         </itemizedlist></para>
1599
1600       <para>The advantages of grouping related volumes on a partition do not necessarily extend to the grouping of all related
1601       volumes on one file server machine. For instance, it is probably unwise in a cell with two file server machines to put all
1602       system volumes on one machine and all user volumes on the other. An outage of either machine probably affects everyone.</para>
1603
1604       <para>Admittedly, the need to move volumes for load balancing purposes can limit the practicality of grouping related volumes.
1605       You need to weigh the complementary advantages case by case.</para>
1606
1607       <indexterm>
1608         <primary>replication</primary>
1609
1610         <secondary>appropriate volumes</secondary>
1611       </indexterm>
1612
1613       <indexterm>
1614         <primary>volume</primary>
1615
1616         <secondary>type to replicate</secondary>
1617       </indexterm>
1618
1619       <indexterm>
1620         <primary>volume</primary>
1621
1622         <secondary>where to place replicated</secondary>
1623       </indexterm>
1624
1625       <indexterm>
1626         <primary>read-only volume</primary>
1627
1628         <secondary>selecting site</secondary>
1629       </indexterm>
1630     </sect2>
1631
1632     <sect2 id="HDRWQ50">
1633       <title>When to Replicate Volumes</title>
1634
1635       <para>As discussed in <link linkend="HDRWQ15">Replication</link>, replication refers to making a copy, or clone, of a
1636       read/write source volume and then placing the copy on one or more additional file server machines. Replicating a volume can
1637       increase the availability of the contents. If one file server machine housing the volume becomes inaccessible, users can still
1638       access the copy of the volume stored on a different machine. No one machine is likely to become overburdened with requests for
1639       a popular file, either, because the file is available from several machines.</para>
1640
1641       <para>However, replication is not appropriate for all cells. If a cell does not have much disk space, replication can be
1642       unduly expensive, because each clone not on the same partition as the read/write source takes up as much disk space as its
1643       source volume did at the time the clone was made. Also, if you have only one file server machine, replication uses up disk
1644       space without increasing availability.</para>
1645
1646       <para>Replication is also not appropriate for volumes that change frequently. You must issue the <emphasis role="bold">vos
1647       release</emphasis> command every time you need to update a read-only volume to reflect changes in its read/write
1648       source.</para>
1649
1650       <para>For both of these reasons, replication is appropriate only for popular volumes whose contents do not change very often,
1651       such as system binaries and other volumes mounted at the upper levels of your filespace. User volumes usually exist only in a
1652       read/write version since they change so often.</para>
1653
1654       <para>If you are replicating any volumes, you must replicate the <emphasis role="bold">root.afs</emphasis> and <emphasis
1655       role="bold">root.cell</emphasis> volumes, preferably at two or three sites each (even if your cell only has two or three file
1656       server machines). The Cache Manager needs to pass through the directories corresponding to the <emphasis
1657       role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes as it interprets any pathname. The
1658       unavailability of these volumes makes all other volumes unavailable too, even if the file server machines storing the other
1659       volumes are still functioning.</para>
1660
1661       <para>Another reason to replicate the <emphasis role="bold">root.afs</emphasis> volume is that it can lessen the load on the
1662       File Server machine. The Cache Manager has a bias to access a read-only version of the <emphasis
1663       role="bold">root.afs</emphasis> volume if it is replicate, which puts the Cache Manager onto the <emphasis>read-only
1664       path</emphasis> through the AFS filespace. While on the read-only path, the Cache Manager attempts to access a read-only copy
1665       of replicated volumes. The File Server needs to track only one callback per Cache Manager for all of the data in a read-only
1666       volume, rather than the one callback per file it must track for read/write volumes. Fewer callbacks translate into a smaller
1667       load on the File Server.</para>
1668
1669       <para>If the <emphasis role="bold">root.afs</emphasis> volume is not replicated, the Cache Manager follows a read/write path
1670       through the filespace, accessing the read/write version of each volume. The File Server distributes and tracks a separate
1671       callback for each file in a read/write volume, imposing a greater load on it.</para>
1672
1673       <para>For more on read/write and read-only paths, see <link linkend="HDRWQ209">The Rules of Mount Point
1674       Traversal</link>.</para>
1675
1676       <para>It also makes sense to replicate system binary volumes in many cases, as well as the volume corresponding to the
1677       <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis> directory and
1678       the volumes corresponding to the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1679       role="bold">/common</emphasis> directory and its subdirectories.</para>
1680
1681       <para>It is a good idea to place a replica on the same partition as the read/write source. In this case, the read-only volume
1682       is a clone (like a backup volume): it is a copy of the source volume's vnode index, rather than a full copy of the volume
1683       contents. Only if the read/write volume moves to another partition or changes substantially does the read-only volume consume
1684       significant disk space. Read-only volumes kept on other partitions always consume the full amount of disk space that the
1685       read/write source consumed when the read-only volume was created.</para>
1686     </sect2>
1687
1688     <sect2 id="Header_58">
1689       <title>The Default Quota and ACL on a New Volume</title>
1690
1691       <para>Every AFS volume has associated with it a quota that limits the amount of disk space the volume is allowed to use. To
1692       set and change quota, use the commands described in <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current
1693       Size</link>.</para>
1694
1695       <para>By default, every new volume is assigned a space quota of 5000 KB blocks unless you include the <emphasis
1696       role="bold">-maxquota</emphasis> argument to the <emphasis role="bold">vos create</emphasis> command. Also by default, the ACL
1697       on the root directory of every new volume grants all permissions to the members of the <emphasis
1698       role="bold">system:administrators</emphasis> group. To learn how to change these values when creating an account with
1699       individual commands, see <link linkend="HDRWQ503">To create one user account with individual commands</link>. When using
1700       <emphasis role="bold">uss</emphasis> commands to create accounts, you can specify alternate ACL and quota values in the
1701       template file's <emphasis role="bold">V</emphasis> instruction; see <link linkend="HDRWQ473">Creating a Volume with the V
1702       Instruction</link>.</para>
1703
1704       <indexterm>
1705         <primary>server machine</primary>
1706
1707         <secondary>configuration issues</secondary>
1708       </indexterm>
1709
1710       <indexterm>
1711         <primary>configuring</primary>
1712
1713         <secondary>file server machine, issues</secondary>
1714       </indexterm>
1715
1716       <indexterm>
1717         <primary>roles for server machine</primary>
1718
1719         <secondary>summary</secondary>
1720       </indexterm>
1721
1722       <indexterm>
1723         <primary>server machine</primary>
1724
1725         <secondary>roles for</secondary>
1726
1727         <tertiary>summary</tertiary>
1728       </indexterm>
1729
1730       <indexterm>
1731         <primary>server machine</primary>
1732
1733         <secondary>first installed</secondary>
1734       </indexterm>
1735     </sect2>
1736   </sect1>
1737
1738   <sect1 id="HDRWQ51">
1739     <title>Configuring Server Machines</title>
1740
1741     <para>This section discusses some issues to consider when configuring server machines, which store AFS data, transfer it to
1742     client machines on request, and house the AFS administrative databases. To learn about client machines, see <link
1743     linkend="HDRWQ54">Configuring Client Machines</link>.</para>
1744
1745     <para>If your cell has more than one AFS server machine, you can configure them to perform specialized functions. A machine can
1746     assume one or more of the roles described in the following list. For more details, see <link linkend="HDRWQ90">The Four Roles
1747     for File Server Machines</link>. <itemizedlist>
1748         <listitem>
1749           <para>A <emphasis>simple file server</emphasis> machine runs only the processes that store and deliver AFS files to client
1750           machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
1751           requirements.</para>
1752         </listitem>
1753
1754         <listitem>
1755           <para>A <emphasis>database server machine</emphasis> runs the four database server processes that maintain AFS's
1756           replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
1757           processes.</para>
1758         </listitem>
1759
1760         <listitem>
1761           <para>A <emphasis>binary distribution machine</emphasis> distributes the AFS server binaries for its system type to all
1762           other server machines of that system type.</para>
1763         </listitem>
1764
1765         <listitem>
1766           <para>The single <emphasis>system control machine</emphasis> distributes common server configuration files to all other
1767           server machines in the cell, in a cell that runs the United States edition of AFS (cells that use the international
1768           edition of AFS must not use the system control machine for this purpose). The machine conventionally also serves as the
1769           time synchronization source for the cell, adjusting its clock according to a time source outside the cell.</para>
1770         </listitem>
1771       </itemizedlist></para>
1772
1773     <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to configure your cell's first file server machine to
1774     assume all four roles. The <emphasis>OpenAFS Quick Beginnings</emphasis> chapter on installing additional server machines also
1775     explains how to configure them to perform one or more roles.</para>
1776
1777     <indexterm>
1778       <primary>database server machine</primary>
1779
1780       <secondary>reason to run three</secondary>
1781     </indexterm>
1782
1783     <indexterm>
1784       <primary>distribution</primary>
1785
1786       <secondary>of databases</secondary>
1787     </indexterm>
1788
1789     <indexterm>
1790       <primary>databases, distributed</primary>
1791     </indexterm>
1792
1793     <indexterm>
1794       <primary>distributed databases</primary>
1795     </indexterm>
1796
1797     <sect2 id="HDRWQ52">
1798       <title>Replicating the OpenAFS Administrative Databases</title>
1799
1800       <para>The AFS administrative databases are housed on database server machines and store information that is crucial for
1801       correct cell functioning. Both server processes and Cache Managers access the information frequently: <itemizedlist>
1802           <listitem>
1803             <para>Every time a Cache Manager fetches a file from a directory that it has not previously accessed, it must look up
1804             the file's location in the Volume Location Database (VLDB).</para>
1805           </listitem>
1806
1807           <listitem>
1808             <para>Every time a user obtains an AFS token from the Authentication Server, the server looks up the user's password in
1809             the Authentication Database.</para>
1810           </listitem>
1811
1812           <listitem>
1813             <para>The first time that a user accesses a volume housed on a specific file server machine, the File Server contacts
1814             the Protection Server for a list of the user's group memberships as recorded in the Protection Database.</para>
1815           </listitem>
1816
1817           <listitem>
1818             <para>Every time you back up a volume using the AFS Backup System, the Backup Server creates records for it in the
1819             Backup Database.</para>
1820           </listitem>
1821         </itemizedlist></para>
1822
1823       <para>Maintaining your cell is simplest if the first machine has the lowest IP address of any machine you plan to use as a
1824       database server machine. If you later decide to use a machine with a lower IP address as a database server machine, you must
1825       update the <emphasis role="bold">CellServDB</emphasis> file on all clients before introducing the new machine.</para>
1826
1827       <para>If your cell has more than one server machine, it is best to run more than one as a database server machine (but more
1828       than three are rarely necessary). Replicating the administrative databases in this way yields the same benefits as replicating
1829       volumes: increased availability and reliability. If one database server machine or process stops functioning, the information
1830       in the database is still available from others. The load of requests for database information is spread across multiple
1831       machines, preventing any one from becoming overloaded.</para>
1832
1833       <para>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
1834       that all copies of the database always be identical, so it is not acceptable to record changes in only some of them. To
1835       synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <link
1836       linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
1837
1838       <para>If your cell has only one file server machine, it must also serve as a database server machine. If you cell has two file
1839       server machines, it is not always advantageous to run both as database server machines. If a server, process, or network
1840       failure interrupts communications between the database server processes on the two machines, it can become impossible to
1841       update the information in the database because neither of them can alone elect itself as the synchronization site.</para>
1842
1843       <indexterm>
1844         <primary>server machine</primary>
1845
1846         <secondary>protecting directories on local disk</secondary>
1847       </indexterm>
1848
1849       <indexterm>
1850         <primary>local disk</primary>
1851
1852         <secondary>protecting on file server machine</secondary>
1853       </indexterm>
1854     </sect2>
1855
1856     <sect2 id="HDRWQ53">
1857       <title>AFS Files on the Local Disk</title>
1858
1859       <para>It is generally simplest to store the binaries for all AFS server processes in the <emphasis
1860       role="bold">/usr/afs/bin</emphasis> directory on every file server machine, even if some processes do not actively run on the
1861       machine. This makes it easier to reconfigure a machine to fill a new role.</para>
1862
1863       <para>For security reasons, the <emphasis role="bold">/usr/afs</emphasis> directory on a file server machine and all of its
1864       subdirectories and files must be owned by the local superuser <emphasis role="bold">root</emphasis> and have only the first
1865       <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit turned on. Some files even have only the
1866       first <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) mode bit turned on (for example, the
1867       <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file, which lists the AFS server encryption keys). Each time the BOS
1868       Server starts, it checks that the mode bits on certain files and directories match the expected values. For a list, see the
1869       <emphasis>OpenAFS Quick Beginnings</emphasis> section about protecting sensitive AFS directories, or the discussion of the
1870       output from the <emphasis role="bold">bos status</emphasis> command in <link linkend="HDRWQ159">To display the status of
1871       server processes and their BosConfig entries</link>.</para>
1872
1873       <para>For a description of the contents of all AFS directories on a file server machine's local disk, see <link
1874       linkend="HDRWQ80">Administering Server Machines</link>.</para>
1875     </sect2>
1876
1877     <sect2 id="Header_62">
1878       <title>Configuring Partitions to Store AFS Data</title>
1879
1880       <para>The partitions that house AFS volumes on a file server machine must be mounted at directories named</para>
1881
1882       <para><emphasis role="bold">/vicep</emphasis><emphasis>index</emphasis></para>
1883
1884       <para>where <emphasis>index</emphasis> is one or two lowercase letters. By convention, the first AFS partition created is
1885       mounted at the <emphasis role="bold">/vicepa</emphasis> directory, the second at the <emphasis role="bold">/vicepb</emphasis>
1886       directory, and so on through the <emphasis role="bold">/vicepz</emphasis> directory. The names then continue with <emphasis
1887       role="bold">/vicepaa</emphasis> through <emphasis role="bold">/vicepaz</emphasis>, <emphasis role="bold">/vicepba</emphasis>
1888       through <emphasis role="bold">/vicepbz</emphasis>, and so on, up to the maximum supported number of server partitions, which
1889       is specified in the OpenAFS Release Notes.</para>
1890
1891       <para>Each <emphasis role="bold">/vicep</emphasis>x directory must correspond to an entire partition or logical volume, and
1892       must be a subdirectory of the root directory (/). It is not acceptable to configure part of (for example) the <emphasis
1893       role="bold">/usr</emphasis> partition as an AFS server partition and mount it on a directory called <emphasis
1894       role="bold">/usr/vicepa</emphasis>.</para>
1895
1896       <para>Also, do not store non-AFS files on AFS server partitions. The File Server and Volume Server expect to have available
1897       all of the space on the partition. Sharing space also creates competition between AFS and the local UNIX file system for
1898       access to the partition, particularly if the UNIX files are frequently used.</para>
1899
1900       <indexterm>
1901         <primary>server machine</primary>
1902
1903         <secondary>monitoring</secondary>
1904       </indexterm>
1905
1906       <indexterm>
1907         <primary>file server machine</primary>
1908
1909         <secondary>rebooting, about</secondary>
1910       </indexterm>
1911
1912       <indexterm>
1913         <primary>rebooting</primary>
1914
1915         <secondary>file server machine, limiting</secondary>
1916       </indexterm>
1917
1918       <indexterm>
1919         <primary>weekly restart of BOS Server (automatic)</primary>
1920
1921         <secondary>about</secondary>
1922       </indexterm>
1923
1924       <indexterm>
1925         <primary>restart times for BOS Server</primary>
1926
1927         <secondary>about</secondary>
1928       </indexterm>
1929     </sect2>
1930
1931     <sect2 id="Header_63">
1932       <title>Monitoring, Rebooting and Automatic Process Restarts</title>
1933
1934       <para>AFS provides several tools for monitoring the File Server, including the <emphasis role="bold">scout</emphasis> and
1935       <emphasis role="bold">afsmonitor</emphasis> programs. You can configure them to alert you when certain threshold values are
1936       exceeded, for example when a server partition is more than 95% full. See <link linkend="HDRWQ323">Monitoring and Auditing AFS
1937       Performance</link>.</para>
1938
1939       <para>Rebooting a file server machine requires shutting down the AFS processes and so inevitably causes a service outage.
1940       Reboot file server machines as infrequently as possible. For instructions, see <link linkend="HDRWQ139">Rebooting a Server
1941       Machine</link>.</para>
1942
1943       <para>By default, the BOS Server on each file server machine stops and immediately restarts all AFS server processes on the
1944       machine (including itself) once a week, at 4:00 a.m. on Sunday. This reduces the potential for the core leaks that can develop
1945       as any process runs for an extended time.</para>
1946
1947       <para>The BOS Server also checks each morning at 5:00 a.m. for any newly installed binary files in the <emphasis
1948       role="bold">/usr/afs/bin</emphasis> directory. It compares the timestamp on each binary file to the time at which the
1949       corresponding process last restarted. If the timestamp on the binary is later, the BOS Server restarts the corresponding
1950       process to start using it.</para>
1951
1952       <para>The default times are in the early morning hours when the outage that results from restarting a process is likely to
1953       disturb the fewest number of people. You can display the restart times for each machine with the <emphasis role="bold">bos
1954       getrestart</emphasis> command, and set them with the <emphasis role="bold">bos setrestart</emphasis> command. The latter
1955       command enables you to disable automatic restarts entirely, by setting the time to <emphasis role="bold">never</emphasis>. See
1956       <link linkend="HDRWQ171">Setting the BOS Server's Restart Times</link>.</para>
1957
1958       <indexterm>
1959         <primary>client machine</primary>
1960
1961         <secondary>configuration issues</secondary>
1962       </indexterm>
1963
1964       <indexterm>
1965         <primary>configuring</primary>
1966
1967         <secondary>client machine, issues</secondary>
1968       </indexterm>
1969     </sect2>
1970   </sect1>
1971
1972   <sect1 id="HDRWQ54">
1973     <title>Configuring Client Machines</title>
1974
1975     <para>This section summarizes issues to consider as you install and configure client machines in your cell.</para>
1976
1977     <indexterm>
1978       <primary>client machine</primary>
1979
1980       <secondary>files required on local disk</secondary>
1981     </indexterm>
1982
1983     <indexterm>
1984       <primary>local disk</primary>
1985
1986       <secondary>files required on client machine</secondary>
1987     </indexterm>
1988
1989     <indexterm>
1990       <primary>file</primary>
1991
1992       <secondary>required on client machine local disk</secondary>
1993     </indexterm>
1994
1995     <sect2 id="HDRWQ55">
1996       <title>Configuring the Local Disk</title>
1997
1998       <para>You can often free up significant amounts of local disk space on AFS client machines by storing standard UNIX files in
1999       AFS and creating symbolic links to them from the local disk. The <emphasis role="bold">@sys</emphasis> pathname variable can
2000       be useful in links to system-specific files; see <link linkend="HDRWQ56">Using the @sys Variable in Pathnames</link>.</para>
2001
2002       <para>There are two types of files that must actually reside on the local disk: boot sequence files needed before the
2003       <emphasis role="bold">afsd</emphasis> program is invoked, and files that can be helpful during file server machine
2004       outages.</para>
2005
2006       <para>During a reboot, AFS is inaccessible until the <emphasis role="bold">afsd</emphasis> program executes and initializes
2007       the Cache Manager. (In the conventional configuration, the AFS initialization file is included in the machine's initialization
2008       sequence and invokes the <emphasis role="bold">afsd</emphasis> program.) Files needed during reboot prior to that point must
2009       reside on the local disk. They include the following, but this list is not necessarily exhaustive. <itemizedlist>
2010           <listitem>
2011             <para>Standard UNIX utilities including the following or their equivalents: <itemizedlist>
2012                 <listitem>
2013                   <para>Machine initialization files (stored in the <emphasis role="bold">/etc</emphasis> or <emphasis
2014                   role="bold">/sbin</emphasis> directory on many system types)</para>
2015                 </listitem>
2016
2017                 <listitem>
2018                   <para>The <emphasis role="bold">fstab</emphasis> file</para>
2019                 </listitem>
2020
2021                 <listitem>
2022                   <para>The <emphasis role="bold">mount</emphasis> command binary</para>
2023                 </listitem>
2024
2025                 <listitem>
2026                   <para>The <emphasis role="bold">umount</emphasis> command binary</para>
2027                 </listitem>
2028               </itemizedlist></para>
2029           </listitem>
2030
2031           <listitem>
2032             <para>All subdirectories and files in the <emphasis role="bold">/usr/vice</emphasis> directory, including the following:
2033             <itemizedlist>
2034                 <listitem>
2035                   <para>The <emphasis role="bold">/usr/vice/cache</emphasis> directory</para>
2036                 </listitem>
2037
2038                 <listitem>
2039                   <para>The <emphasis role="bold">/usr/vice/etc/afsd</emphasis> command binary</para>
2040                 </listitem>
2041
2042                 <listitem>
2043                   <para>The <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file</para>
2044                 </listitem>
2045
2046                 <listitem>
2047                   <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file</para>
2048                 </listitem>
2049
2050                 <listitem>
2051                   <para>The <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file</para>
2052                 </listitem>
2053               </itemizedlist></para>
2054
2055             <para>For more information on these files, see <link linkend="HDRWQ391">Configuration and Cache-Related Files on the
2056             Local Disk</link>.</para>
2057           </listitem>
2058         </itemizedlist></para>
2059
2060       <para>The other type of files and programs to retain on the local disk are those you need when diagnosing and fixing problems
2061       caused by a file server outage, because the outage can make inaccessible the copies stored in AFS. Examples include the
2062       binaries for a text editor (such as <emphasis role="bold">ed</emphasis> or <emphasis role="bold">vi</emphasis>) and for the
2063       <emphasis role="bold">fs</emphasis> and <emphasis role="bold">bos</emphasis> commands. Store copies of AFS command binaries in
2064       the <emphasis role="bold">/usr/vice/etc</emphasis> directory as well as including them in the <emphasis
2065       role="bold">/usr/afsws</emphasis> directory, which is normally a link into AFS. Then place the <emphasis
2066       role="bold">/usr/afsws</emphasis> directory before the <emphasis role="bold">/usr/vice/etc</emphasis> directory in users'
2067       <envar>PATH</envar> environment variable definition. When AFS is functioning normally, users access the copy in the <emphasis
2068       role="bold">/usr/afsws</emphasis> directory, which is more likely to be current than a local copy.</para>
2069
2070       <para>You can automate the configuration of client machine local disks by using the <emphasis role="bold">package</emphasis>
2071       program, which updates the contents of the local disk to match a configuration file. See <link linkend="HDRWQ419">Configuring
2072       Client Machines with the package Program</link>.</para>
2073     </sect2>
2074
2075     <sect2 id="Header_66">
2076       <title>Enabling Access to Foreign Cells</title>
2077
2078       <indexterm>
2079         <primary>client machine</primary>
2080
2081         <secondary>enabling access to foreign cell</secondary>
2082       </indexterm>
2083
2084       <para>As detailed in <link linkend="HDRWQ39">Making Other Cells Visible in Your Cell</link>, you enable the Cache Manager to
2085       access a cell's AFS filespace by storing a list of the cell's database server machines in the local <emphasis
2086       role="bold">/usr/vice/etc/CellServDB</emphasis> file. The Cache Manager reads the list into kernel memory at reboot for faster
2087       retrieval. You can change the list in kernel memory between reboots by using the <emphasis role="bold">fs newcell</emphasis>
2088       command. It is often practical to store a central version of the <emphasis role="bold">CellServDB</emphasis> file in AFS and
2089       use the <emphasis role="bold">package</emphasis> program periodically to update each client's version with the source copy.
2090       See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
2091
2092       <para>Because each client machine maintains its own copy of the <emphasis role="bold">CellServDB</emphasis> file, you can in
2093       theory enable access to different foreign cells on different client machines. This is not usually practical, however,
2094       especially if users do not always work on the same machine.</para>
2095
2096       <indexterm>
2097         <primary>at-sys (@sys) variable in pathnames</primary>
2098       </indexterm>
2099
2100       <indexterm>
2101         <primary>sys (@sys) variable in pathnames</primary>
2102       </indexterm>
2103
2104       <indexterm>
2105         <primary>variables</primary>
2106
2107         <secondary>@sys in pathnames</secondary>
2108       </indexterm>
2109     </sect2>
2110
2111     <sect2 id="HDRWQ56">
2112       <title>Using the @sys Variable in Pathnames</title>
2113
2114       <para>When creating symbolic links into AFS on the local disk, it is often practical to use the @sys variable in pathnames.
2115       The Cache Manager automatically substitutes the local machine's AFS system name (CPU/operating system type) for the @sys
2116       variable. This means you can place the same links on machines of various system types and still have each machine access the
2117       binaries for its system type. For example, the Cache Manager on a machine running AIX 4.2 converts <emphasis
2118       role="bold">/afs/abc.com/@sys</emphasis> to <emphasis role="bold">/afs/abc.com/rs_aix42</emphasis>, whereas a machine running
2119       Solaris 7 converts it to <emphasis role="bold">/afs/abc.com/sun4x_57</emphasis>.</para>
2120
2121       <para>If you want to use the @sys variable, it is simplest to use the conventional AFS system type names as specified in the
2122       OpenAFS Release Notes. The Cache Manager records the local machine's system type name in kernel memory during initialization.
2123       If you do not use the conventional names, you must use the <emphasis role="bold">fs sysname</emphasis> command to change the
2124       value in kernel memory from its default just after Cache Manager initialization, on every client machine of the relevant
2125       system type. The <emphasis role="bold">fs sysname</emphasis> command also displays the current value; see <link
2126       linkend="HDRWQ417">Displaying and Setting the System Type Name</link>.</para>
2127
2128       <para>In pathnames in the AFS filespace itself, use the @sys variable carefully and sparingly, because it can lead to
2129       unexpected results. It is generally best to restrict its use to only one level in the filespace. The third level is a common
2130       choice, because that is where many cells store the binaries for different machine types.</para>
2131
2132       <para>Multiple instances of the @sys variable in a pathname are especially dangerous to people who must explicitly change
2133       directories (with the <emphasis role="bold">cd</emphasis> command, for example) into directories that store binaries for
2134       system types other than the machine on which they are working, such as administrators or developers who maintain those
2135       directories. After changing directories, it is recommended that such people verify they are in the desired directory.</para>
2136     </sect2>
2137
2138     <sect2 id="Header_68">
2139       <title>Setting Server Preferences</title>
2140
2141       <para>The Cache Manager stores a table of preferences for file server machines in kernel memory. A preference rank pairs a
2142       file server machine interface's IP address with an integer in the range from 1 to 65,534. When it needs to access a file, the
2143       Cache Manager compares the ranks for the interfaces of all machines that house the file, and first attempts to access the file
2144       via the interface with the best rank. As it initializes, the Cache Manager sets default ranks that bias it to access files via
2145       interfaces that are close to it in terms of network topology. You can adjust the preference ranks to improve performance if
2146       you wish.</para>
2147
2148       <para>The Cache Manager also uses similar preferences for Volume Location (VL) Server machines. Use the <emphasis
2149       role="bold">fs getserverprefs</emphasis> command to display preference ranks and the <emphasis role="bold">fs
2150       setserverprefs</emphasis> command to set them. See <link linkend="HDRWQ414">Maintaining Server Preference Ranks</link>.</para>
2151
2152       <indexterm>
2153         <primary>user account</primary>
2154
2155         <secondary>configuration issues</secondary>
2156       </indexterm>
2157     </sect2>
2158   </sect1>
2159
2160   <sect1 id="HDRWQ57">
2161     <title>Configuring AFS User Accounts</title>
2162
2163     <para>This section discusses some of the issues to consider when configuring AFS user accounts. Because AFS is separate from the
2164     UNIX file system, a user's AFS account is separate from her UNIX account.</para>
2165
2166     <para>The preferred method for creating a user account is with the <emphasis role="bold">uss</emphasis> suite of commands. With
2167     a single command, you can create all the components of one or many accounts, after you have prepared a template file that guides
2168     the account creation. See <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>.</para>
2169
2170     <para>Alternatively, you can issue the individual commands that create each component of an account. For instructions, along
2171     with instructions for removing user accounts and changing user passwords, user volume quotas and usernames, see <link
2172     linkend="HDRWQ491">Administering User Accounts</link>.</para>
2173
2174     <para>When users leave your system, it is often good policy to remove their accounts. Instructions appear in <link
2175     linkend="HDRWQ486">Deleting Individual Accounts with the uss delete Command</link> and <link linkend="HDRWQ524">Removing a User
2176     Account</link>.</para>
2177
2178     <para>An AFS user account consists of the following components, which are described in greater detail in <link
2179     linkend="HDRWQ494">The Components of an AFS User Account</link>. <itemizedlist>
2180         <listitem>
2181           <para>A Protection Database entry</para>
2182         </listitem>
2183
2184         <listitem>
2185           <para>An Authentication Database entry</para>
2186         </listitem>
2187
2188         <listitem>
2189           <para>A volume</para>
2190         </listitem>
2191
2192         <listitem>
2193           <para>A home directory at which the volume is mounted</para>
2194         </listitem>
2195
2196         <listitem>
2197           <para>Ownership of the home directory and full permissions on its ACL</para>
2198         </listitem>
2199
2200         <listitem>
2201           <para>An entry in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of each machine the
2202           user needs to log into</para>
2203         </listitem>
2204
2205         <listitem>
2206           <para>Optionally, standard files and subdirectories that make the account more useful</para>
2207         </listitem>
2208       </itemizedlist></para>
2209
2210     <para>By creating some components but not others, you can create accounts at different levels of functionality, using either
2211     <emphasis role="bold">uss</emphasis> commands as described in <link linkend="HDRWQ449">Creating and Deleting User Accounts with
2212     the uss Command Suite</link> or individual commands as described in <link linkend="HDRWQ491">Administering User Accounts</link>.
2213     The levels of functionality include the following <itemizedlist>
2214         <listitem>
2215           <para>An authentication-only account enables the user to obtain AFS tokens and so to access protected AFS data and to
2216           issue privileged commands. It consists only of entries in the Authentication and Protection Database. This type of account
2217           is suitable for administrative accounts and for users from foreign cells who need to access protected data. Local users
2218           generally also need a volume and home directory.</para>
2219         </listitem>
2220
2221         <listitem>
2222           <para>A basic user account includes a volume for the user, in addition to Authentication and Protection Database entries.
2223           The volume is mounted in the AFS filespace as the user's home directory, and provides a repository for the user's personal
2224           files.</para>
2225         </listitem>
2226
2227         <listitem>
2228           <para>A full account adds configuration files for basic functions such as logging in, printing, and mail delivery to a
2229           basic account, making it more convenient and useful. For a discussion of some useful types of configuration files, see
2230           <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>.</para>
2231         </listitem>
2232       </itemizedlist></para>
2233
2234     <para>If your users have UNIX user accounts that predate the introduction of AFS in the cell, you possibly want to convert them
2235     into AFS accounts. There are three main issues to consider: <itemizedlist>
2236         <listitem>
2237           <para>Making UNIX and AFS UIDs match</para>
2238         </listitem>
2239
2240         <listitem>
2241           <para>Setting the password field in the local password file appropriately</para>
2242         </listitem>
2243
2244         <listitem>
2245           <para>Moving files from the UNIX file system into AFS</para>
2246         </listitem>
2247       </itemizedlist></para>
2248
2249     <para>For further discussion, see <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link> or <link
2250     linkend="HDRWQ498">Converting Existing UNIX Accounts</link>.</para>
2251
2252     <indexterm>
2253       <primary>username</primary>
2254
2255       <secondary>choosing</secondary>
2256     </indexterm>
2257
2258     <indexterm>
2259       <primary>user</primary>
2260
2261       <secondary>name</secondary>
2262
2263       <see>username</see>
2264     </indexterm>
2265
2266     <indexterm>
2267       <primary>choosing</primary>
2268
2269       <secondary>name</secondary>
2270
2271       <tertiary>user</tertiary>
2272     </indexterm>
2273
2274     <indexterm>
2275       <primary>anonymous user</primary>
2276
2277       <secondary>AFS UID reserved</secondary>
2278     </indexterm>
2279
2280     <indexterm>
2281       <primary>AFS UID</primary>
2282
2283       <secondary>reserved</secondary>
2284
2285       <tertiary>anonymous user</tertiary>
2286     </indexterm>
2287
2288     <sect2 id="HDRWQ58">
2289       <title>Choosing Usernames and Naming Other Account Components</title>
2290
2291       <para>This section suggests schemes for choosing usernames, AFS UIDs, user volume names and mount point names, and also
2292       outlines some restrictions on your choices.</para>
2293
2294       <formalpara>
2295         <title>Usernames</title>
2296
2297         <para>AFS imposes very few restrictions on the form of usernames. It is best to keep usernames short, both because many
2298         utilities and applications can handle usernames of no more than eight characters and because by convention many components
2299         of and AFS account incorporate the name. These include the entries in the Protection and Authentication Databases, the
2300         volume, and the mount point. Depending on your electronic mail delivery system, the username can become part of the user's
2301         mailing address. The username is also the string that the user types when logging in to a client machine.</para>
2302       </formalpara>
2303
2304       <para>Some common choices for usernames are last names, first names, initials, or a combination, with numbers sometimes added.
2305       It is also best to avoid using the following characters, many of which have special meanings to the command shell.
2306       <itemizedlist>
2307           <listitem>
2308             <para>The comma (<emphasis role="bold">,</emphasis>)</para>
2309           </listitem>
2310
2311           <listitem>
2312             <para>The colon (<emphasis role="bold">:</emphasis>), because AFS reserves it as a field separator in protection group
2313             names; see <link linkend="HDRWQ62">The Two Types of User-Defined Groups</link></para>
2314           </listitem>
2315
2316           <listitem>
2317             <para>The semicolon (<emphasis role="bold">;</emphasis>)</para>
2318           </listitem>
2319
2320           <listitem>
2321             <para>The "at-sign" (<emphasis role="bold">@</emphasis>); this character is reserved for Internet mailing
2322             addresses</para>
2323           </listitem>
2324
2325           <listitem>
2326             <para>Spaces</para>
2327           </listitem>
2328
2329           <listitem>
2330             <para>The newline character</para>
2331           </listitem>
2332
2333           <listitem>
2334             <para>The period (<emphasis role="bold">.</emphasis>); it is conventional to use this character only in the special
2335             username that an administrator adopts while performing privileged tasks, such as <emphasis
2336             role="bold">pat.admin</emphasis></para>
2337           </listitem>
2338         </itemizedlist></para>
2339
2340       <formalpara>
2341         <title>AFS UIDs and UNIX UIDs</title>
2342
2343         <para>AFS associates a unique identification number, the AFS UID, with every username, recording the mapping in the user's
2344         Protection Database entry. The AFS UID functions within AFS much as the UNIX UID does in the local file system: the AFS
2345         server processes and the Cache Manager use it internally to identify a user, rather than the username.</para>
2346       </formalpara>
2347
2348       <para>Every AFS user also must have a UNIX UID recorded in the local password file (<emphasis
2349       role="bold">/etc/passwd</emphasis> or equivalent) of each client machine they log onto. Both administration and a user's AFS
2350       access are simplest if the AFS UID and UNIX UID match. One important consequence of matching UIDs is that the owner reported
2351       by the <emphasis role="bold">ls -l</emphasis> command matches the AFS username.</para>
2352
2353       <para>It is usually best to allow the Protection Server to allocate the AFS UID as it creates the Protection Database entry.
2354       However, both the <emphasis role="bold">pts createuser</emphasis> command and the <emphasis role="bold">uss</emphasis>
2355       commands that create user accounts enable you to assign AFS UIDs explicitly. This is appropriate in two cases: <itemizedlist>
2356           <listitem>
2357             <para>You wish to group together the AFS UIDs of related users</para>
2358           </listitem>
2359
2360           <listitem>
2361             <para>You are converting an existing UNIX account into an AFS account and want to make the AFS UID match the existing
2362             UNIX UID</para>
2363           </listitem>
2364         </itemizedlist></para>
2365
2366       <para>After the Protection Server initializes for the first time on a cell's first file server machine, it starts assigning
2367       AFS UIDs at a default value. To change the default before creating any user accounts, or at any time, use the <emphasis
2368       role="bold">pts setmax</emphasis> command to reset the <computeroutput>max user id counter</computeroutput>. To display the
2369       counter, use the <emphasis role="bold">pts listmax</emphasis> command. See <link linkend="HDRWQ560">Displaying and Setting the
2370       AFS UID and GID Counters</link>.</para>
2371
2372       <para>AFS reserves one AFS UID, 32766, for the user <emphasis role="bold">anonymous</emphasis>. The AFS server processes
2373       assign this identity and AFS UID to any user who does not possess a token for the local cell. Do not assign this AFS UID to
2374       any other user or hardcode its current value into any programs or a file's owner field, because it is subject to change in
2375       future releases.</para>
2376
2377       <indexterm>
2378         <primary>username</primary>
2379
2380         <secondary>part of volume name</secondary>
2381       </indexterm>
2382
2383       <indexterm>
2384         <primary>choosing</primary>
2385
2386         <secondary>name</secondary>
2387
2388         <tertiary>user volume</tertiary>
2389       </indexterm>
2390
2391       <formalpara>
2392         <title>User Volume Names</title>
2393
2394         <para>Like any volume name, a user volume's base (read/write) name cannot exceed 22 characters in length or include the
2395         <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension. See <link
2396         linkend="HDRWQ44">Creating Volumes to Simplify Administration</link>. By convention, user volume names have the format
2397         <emphasis role="bold">user.</emphasis>username. Using the <emphasis role="bold">user.</emphasis> prefix not only makes it
2398         easy to identify the volume's contents, but also to create a backup version of all user volumes by issuing a single
2399         <emphasis role="bold">vos backupsys</emphasis> command.</para>
2400       </formalpara>
2401
2402       <indexterm>
2403         <primary>mount point</primary>
2404
2405         <secondary>choosing name for user volume</secondary>
2406       </indexterm>
2407
2408       <indexterm>
2409         <primary>choosing</primary>
2410
2411         <secondary>name</secondary>
2412
2413         <tertiary>user volume mount point</tertiary>
2414       </indexterm>
2415
2416       <formalpara>
2417         <title>Mount Point Names</title>
2418
2419         <para>By convention, the mount point for a user's volume is named after the username. Many cells follow the convention of
2420         mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2421         role="bold">/usr</emphasis> directory, as discussed in <link linkend="HDRWQ43">The Third Level</link>. Very large cells
2422         sometimes find that mounting all user volumes in the same directory slows directory lookup, however; for suggested
2423         alternatives, see the following section.</para>
2424       </formalpara>
2425
2426       <indexterm>
2427         <primary>directories</primary>
2428
2429         <secondary>for grouping user home directories</secondary>
2430       </indexterm>
2431
2432       <indexterm>
2433         <primary>user account</primary>
2434
2435         <secondary>suggestions for grouping home directories</secondary>
2436       </indexterm>
2437     </sect2>
2438
2439     <sect2 id="HDRWQ59">
2440       <title>Grouping Home Directories</title>
2441
2442       <para>Mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2443       role="bold">/usr</emphasis> directory is an AFS-appropriate variation on the standard UNIX practice of putting user home
2444       directories under the <emphasis role="bold">/usr</emphasis> subdirectory. However, cells with more than a few hundred users
2445       sometimes find that mounting all user volumes in a single directory results in slow directory lookup. The solution is to
2446       distribute user volume mount points into several directories; there are a number of alternative methods to accomplish this.
2447       <itemizedlist>
2448           <listitem>
2449             <para>Distribute user home directories into multiple directories that reflect organizational divisions, such as academic
2450             or corporate departments. For example, a company can create group directories called <emphasis
2451             role="bold">usr/marketing</emphasis>, <emphasis role="bold">usr/research</emphasis>, <emphasis
2452             role="bold">usr/finance</emphasis>. A good feature of this scheme is that knowing a user's department is enough to find
2453             the user's home directory. Also, it makes it easy to set the ACL to limit access to members of the department only. A
2454             potential drawback arises if departments are of sufficiently unequal size that users in large departments experience
2455             slower lookup than users in small departments. This scheme is also not appropriate in cells where users frequently
2456             change between divisions.</para>
2457           </listitem>
2458
2459           <listitem>
2460             <para>Distribute home directories into alphabetic subdirectories of the <emphasis role="bold">usr</emphasis> directory
2461             (the <emphasis role="bold">usr/a</emphasis> subdirectory, the <emphasis role="bold">usr/b</emphasis> subdirectory, and
2462             so on), based on the first letter of the username. If the cell is very large, create subdirectories under each letter
2463             that correspond to the second letter in the user name. This scheme has the same advantages and disadvantages of a
2464             department-based scheme. Anyone who knows the user's username can find the user's home directory, but users with names
2465             that begin with popular letters sometimes experience slower lookup.</para>
2466           </listitem>
2467
2468           <listitem>
2469             <para>Distribute home directories randomly but evenly into more than one grouping directory. One cell that uses this
2470             scheme has over twenty such directories called the <emphasis role="bold">usr1</emphasis> directory, the <emphasis
2471             role="bold">usr2</emphasis> directory, and so on. This scheme is especially appropriate in cells where the other two
2472             schemes do not seem feasible. It eliminates the potential problem of differences in lookup speed, because all
2473             directories are about the same size. Its disadvantage is that there is no way to guess which directory a given user's
2474             volume is mounted in, but a solution is to create a symbolic link in the regular <emphasis role="bold">usr</emphasis>
2475             directory that references the actual mount point. For example, if user <emphasis role="bold">smith</emphasis>'s volume
2476             is mounted at the <emphasis role="bold">/afs/bigcell.com/usr17/smith</emphasis> directory, then the <emphasis
2477             role="bold">/afs/bigcell.com/usr/smith</emphasis> directory is a symbolic link to the <emphasis
2478             role="bold">../usr17/smith</emphasis> directory. This way, if someone does not know which directory the user <emphasis
2479             role="bold">smith</emphasis> is in, he or she can access it through the link called <emphasis
2480             role="bold">usr/smith</emphasis>; people who do know the appropriate directory save lookup time by specifying it.</para>
2481           </listitem>
2482         </itemizedlist></para>
2483
2484       <para>For instructions on how to implement the various schemes when using the <emphasis role="bold">uss</emphasis> program to
2485       create user accounts, see <link linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link> and
2486       <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
2487     </sect2>
2488
2489     <sect2 id="Header_72">
2490       <title>Making a Backup Version of User Volumes Available</title>
2491
2492       <para>Mounting the backup version of a user's volume is a simple way to enable users themselves to restore data they have
2493       accidentally removed or deleted. It is conventional to mount the backup version at a subdirectory of the user's home directory
2494       (called perhaps the <emphasis role="bold">OldFiles</emphasis> subdirectory), but other schemes are possible. Once per day you
2495       create a new backup version to capture the changes made that day, overwriting the previous day's backup version with the new
2496       one. Users can always retrieve the previous day's copy of a file without your assistance, freeing you to deal with more
2497       pressing tasks.</para>
2498
2499       <para>Users sometimes want to delete the mount point to their backup volume, because they erroneously believe that the backup
2500       volume's contents count against their quota. Remind them that the backup volume is separate, so the only space it uses in the
2501       user volume is the amount needed for the mount point.</para>
2502
2503       <para>For further discussion of backup volumes, see <link linkend="HDRWQ77">Backing Up AFS Data</link> and <link
2504       linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
2505
2506       <indexterm>
2507         <primary>file</primary>
2508
2509         <secondary>creating standard ones in new user account</secondary>
2510       </indexterm>
2511
2512       <indexterm>
2513         <primary>user account</primary>
2514
2515         <secondary>creating</secondary>
2516
2517         <tertiary>standard files in</tertiary>
2518       </indexterm>
2519
2520       <indexterm>
2521         <primary>creating</primary>
2522
2523         <secondary>standard files in new user account</secondary>
2524       </indexterm>
2525     </sect2>
2526
2527     <sect2 id="HDRWQ60">
2528       <title>Creating Standard Files in New AFS Accounts</title>
2529
2530       <para>From your experience as a UNIX administrator, you are probably familiar with the use of login and shell initialization
2531       files (such as the <emphasis role="bold">.login</emphasis> and <emphasis role="bold">.cshrc</emphasis> files) to make an
2532       account easier to use.</para>
2533
2534       <para>It is often practical to add some AFS-specific directories to the definition of the user's <envar>PATH</envar>
2535       environment variable, including the following: <itemizedlist>
2536           <listitem>
2537             <para>The path to a <emphasis role="bold">bin</emphasis> subdirectory in the user's home directory for binaries the user
2538             has created (that is, <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2539             role="bold">/usr/</emphasis><replaceable>username</replaceable><emphasis role="bold">/bin</emphasis>)</para>
2540           </listitem>
2541
2542           <listitem>
2543             <para>The <emphasis role="bold">/usr/afsws/bin</emphasis> path, which conventionally includes programs like <emphasis
2544             role="bold">fs</emphasis>, <emphasis role="bold">klog</emphasis>, <emphasis role="bold">kpasswd</emphasis>, <emphasis
2545             role="bold">pts</emphasis>, <emphasis role="bold">tokens</emphasis>, and <emphasis role="bold">unlog</emphasis></para>
2546           </listitem>
2547
2548           <listitem>
2549             <para>The <emphasis role="bold">/usr/afsws/etc</emphasis> path, if the user is an administrator; it usually houses the
2550             AFS command suites that require privilege (the <emphasis role="bold">backup</emphasis>, <emphasis
2551             role="bold">butc</emphasis>, <emphasis role="bold">kas</emphasis>, <emphasis role="bold">uss</emphasis>, <emphasis
2552             role="bold">vos</emphasis> commands), the <emphasis role="bold">package</emphasis> program, and others</para>
2553           </listitem>
2554         </itemizedlist></para>
2555
2556       <para>If you are not using an AFS-modified login utility, it can be helpful to users to invoke the <emphasis
2557       role="bold">klog</emphasis> command in their <emphasis role="bold">.login</emphasis> file so that they obtain AFS tokens as
2558       part of logging in. In the following example command sequence, the first line echoes the string
2559       <computeroutput>klog</computeroutput> to the standard output stream, so that the user understands the purpose of the
2560       <computeroutput>Password:</computeroutput> prompt that appears when the second line is executed. The <emphasis
2561       role="bold">-setpag</emphasis> flag associates the new tokens with a process authentication group (PAG), which is discussed
2562       further in <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
2563
2564       <programlisting>
2565    echo -n "klog "
2566    klog -setpag
2567 </programlisting>
2568
2569       <para>The following sequence of commands has a similar effect, except that the <emphasis role="bold">pagsh</emphasis> command
2570       forks a new shell with which the PAG and tokens are associated.</para>
2571
2572       <programlisting>
2573    pagsh
2574    echo -n "klog "
2575    klog
2576 </programlisting>
2577
2578       <para>If you use an AFS-modified login utility, this sequence is not necessary, because such utilities both log a user in
2579       locally and obtain AFS tokens.</para>
2580
2581       <indexterm>
2582         <primary>group</primary>
2583
2584         <secondary>AFS GID</secondary>
2585       </indexterm>
2586
2587       <indexterm>
2588         <primary>group</primary>
2589
2590         <secondary>restrictions</secondary>
2591       </indexterm>
2592
2593       <indexterm>
2594         <primary>group</primary>
2595
2596         <secondary>privacy flags</secondary>
2597       </indexterm>
2598
2599       <indexterm>
2600         <primary>privacy flags on Protection Database entry</primary>
2601       </indexterm>
2602     </sect2>
2603   </sect1>
2604
2605   <sect1 id="HDRWQ61">
2606     <title>Using AFS Protection Groups</title>
2607
2608     <para>AFS enables users to define their own groups of other users or machines. The groups are placed on ACLs to grant the same
2609     permissions to many users without listing each user individually. For group creation instructions, see <link
2610     linkend="HDRWQ531">Administering the Protection Database</link>.</para>
2611
2612     <para>Groups have AFS ID numbers, just as users do, but an AFS group ID (GID) is a negative integer whereas a user's AFS UID is
2613     a positive integer. By default, the Protection Server allocates a new group's AFS GID automatically, but members of the
2614     <emphasis role="bold">system:administrators</emphasis> group can assign a GID when issuing the <emphasis role="bold">pts
2615     creategroup</emphasis> command. Before explicitly assigning a GID, it is best to verify that it is not already in use.</para>
2616
2617     <para>A group cannot belong to another group, but it can own another group or even itself as long as it (the owning group) has
2618     at least one member. The current owner of a group can transfer ownership of the group to another user or group, even without the
2619     new owner's permission. At that point the former owner loses administrative control over the group.</para>
2620
2621     <para>By default, each user can create 20 groups. A system administrator can increase or decrease this group creation quota with
2622     the <emphasis role="bold">pts setfields</emphasis> command.</para>
2623
2624     <para>Each Protection Database entry (group or user) is protected by a set of five privacy flagswhich limit who can administer
2625     the entry and what they can do. The default privacy flags are fairly restrictive, especially for user entries. See <link
2626     linkend="HDRWQ559">Setting the Privacy Flags on Database Entries</link>.</para>
2627
2628     <indexterm>
2629       <primary>system:administrators group</primary>
2630
2631       <secondary>about</secondary>
2632     </indexterm>
2633
2634     <indexterm>
2635       <primary>system:anyuser group</primary>
2636
2637       <secondary>about</secondary>
2638     </indexterm>
2639
2640     <indexterm>
2641       <primary>system:authuser group</primary>
2642
2643       <secondary>about</secondary>
2644     </indexterm>
2645
2646     <indexterm>
2647       <primary>group</primary>
2648
2649       <secondary>system-defined</secondary>
2650     </indexterm>
2651
2652     <sect2 id="Header_75">
2653       <title>The Three System Groups</title>
2654
2655       <para>As the Protection Server initializes for the first time on a cell's first database server machine, it automatically
2656       creates three group entries: the <emphasis role="bold">system:anyuser</emphasis>, <emphasis
2657       role="bold">system:authuser</emphasis>, and <emphasis role="bold">system:administrators</emphasis> groups.</para>
2658
2659       <indexterm>
2660         <primary>AFS UID</primary>
2661
2662         <secondary>reserved</secondary>
2663
2664         <tertiary>system-defined groups</tertiary>
2665       </indexterm>
2666
2667       <para>The first two system groups are unlike any other groups in the Protection Database in that they do not have a stable
2668       membership: <itemizedlist>
2669           <listitem>
2670             <para>The <emphasis role="bold">system:anyuser</emphasis> group includes everyone who can access a cell's AFS filespace:
2671             users who have tokens for the local cell, users who have logged in on a local AFS client machine but not obtained tokens
2672             (such as the local superuser <emphasis role="bold">root</emphasis>), and users who have connected to a local machine
2673             from outside the cell. Placing the <emphasis role="bold">system:anyuser</emphasis> group on an ACL grants access to the
2674             widest possible range of users. It is the only way to extend access to users from foreign AFS cells that do not have
2675             local accounts.</para>
2676           </listitem>
2677
2678           <listitem>
2679             <para>The <emphasis role="bold">system:authuser</emphasis> group includes everyone who has a valid token obtained from
2680             the cell's AFS authentication service.</para>
2681           </listitem>
2682         </itemizedlist></para>
2683
2684       <para>Because the groups do not have a stable membership, the <emphasis role="bold">pts membership</emphasis> command produces
2685       no output for them. Similarly, they do not appear in the list of groups to which a user belongs.</para>
2686
2687       <para>The <emphasis role="bold">system:administrators</emphasis> group does have a stable membership, consisting of the cell's
2688       privileged administrators. Members of this group can issue any <emphasis role="bold">pts</emphasis> command, and are the only
2689       ones who can issue several other restricted commands (such as the <emphasis role="bold">chown</emphasis> command on AFS
2690       files). By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
2691       role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
2692       permissions on every ACL in the filespace. For information about changing this default, see <link
2693       linkend="HDRWQ586">Administering the system:administrators Group</link>.</para>
2694
2695       <para>For a discussion of how to use system groups effectively on ACLs, see <link linkend="HDRWQ571">Using Groups on
2696       ACLs</link>.</para>
2697     </sect2>
2698
2699     <sect2 id="HDRWQ62">
2700       <title>The Two Types of User-Defined Groups</title>
2701
2702       <para>All users can create regular groups. A regular group name has two fields separated by a colon, the first of which must
2703       indicate the group's ownership. The Protection Server refuses to create or change the name of a group if the result does not
2704       accurately indicate the ownership.</para>
2705
2706       <para>Members of the <emphasis role="bold">system:administrators</emphasis> group can create prefix-less groups whose names do
2707       not have the first field that indicates ownership. For suggestions on using the two types of groups effectively, see <link
2708       linkend="HDRWQ545">Using Groups Effectively</link>.</para>
2709
2710       <indexterm>
2711         <primary>authentication</primary>
2712
2713         <secondary>AFS separate from UNIX</secondary>
2714       </indexterm>
2715
2716       <indexterm>
2717         <primary>AFS</primary>
2718
2719         <secondary>authentication separate from UNIX</secondary>
2720       </indexterm>
2721     </sect2>
2722   </sect1>
2723
2724   <sect1 id="HDRWQ63">
2725     <title>Login and Authentication in AFS</title>
2726
2727     <para>As explained in <link linkend="HDRWQ31">Differences in Authentication</link>, AFS authentication is separate from UNIX
2728     authentication because the two file systems are separate. The separation has two practical implications: <itemizedlist>
2729         <listitem>
2730           <para>To access AFS files, users must both log into the local file system and authenticate with the AFS authentication
2731           service. (Logging into the local file system is necessary because the only way to access the AFS filespace is through a
2732           Cache Manager, which resides in the local machine's kernel.)</para>
2733         </listitem>
2734
2735         <listitem>
2736           <para>Passwords are stored in two separate places: in the Kerberos Database for AFS and in the each machine's local
2737           password file (the <emphasis role="bold">/etc/passwd</emphasis> file or equivalent) for the local file system.</para>
2738         </listitem>
2739       </itemizedlist></para>
2740
2741     <para>When a user successfully authenticates, the AFS authentication service passes a token to the user's Cache Manager. The
2742     token is a small collection of data that certifies that the user has correctly provided the password associated with a
2743     particular AFS identity. The Cache Manager presents the token to AFS server processes along with service requests, as proof that
2744     the user is genuine. To learn about the mutual authentication procedure they use to establish identity, see <link
2745     linkend="HDRWQ75">A More Detailed Look at Mutual Authentication</link>.</para>
2746
2747     <para>The Cache Manager stores tokens in the user's credential structure in kernel memory. To distinguish one user's credential
2748     structure from another's, the Cache Manager identifies each one either by the user's UNIX UID or by a process authentication
2749     group (PAG), which is an identification number guaranteed to be unique in the cell. For further discussion, see <link
2750     linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
2751
2752     <indexterm>
2753       <primary>tokens</primary>
2754
2755       <secondary>one-per-cell rule</secondary>
2756     </indexterm>
2757
2758     <para>A user can have only one token per cell in each separately identified credential structure. To obtain a second token for
2759     the same cell, the user must either log into a different machine or obtain another credential structure with a different
2760     identifier than any existing credential structure, which is most easily accomplished by issuing the <emphasis
2761     role="bold">pagsh</emphasis> command (see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>). In a single credential
2762     structure, a user can have one token for each of many cells at the same time. As this implies, authentication status on one
2763     machine or PAG is independent of authentication status on another machine or PAG, which can be very useful to a user or system
2764     administrator.</para>
2765
2766     <para>The AFS distribution includes library files that enable each system type's login utility to authenticate users with AFS
2767     and log them into the local file system in one step. If you do not configure an AFS-modified login utility on a client machine,
2768     its users must issue the <emphasis role="bold">klog</emphasis> command to authenticate with AFS after logging in.</para>
2769
2770     <note>
2771       <para>The AFS-modified libraries do not necessarily support all features available in an operating system's proprietary login
2772       utility. In some cases, it is not possible to support a utility at all. For more information about the supported utilities in
2773       each AFS version, see the OpenAFS Release Notes.</para>
2774     </note>
2775
2776     <indexterm>
2777       <primary>commands</primary>
2778
2779       <secondary>pagsh</secondary>
2780     </indexterm>
2781
2782     <indexterm>
2783       <primary>pagsh command</primary>
2784     </indexterm>
2785
2786     <indexterm>
2787       <primary>commands</primary>
2788
2789       <secondary>klog with -setpag flag</secondary>
2790     </indexterm>
2791
2792     <indexterm>
2793       <primary>klog command</primary>
2794
2795       <secondary>with -setpag flag</secondary>
2796     </indexterm>
2797
2798     <indexterm>
2799       <primary>PAG</primary>
2800
2801       <secondary>creating with klog or pagsh command</secondary>
2802     </indexterm>
2803
2804     <indexterm>
2805       <primary>creating</primary>
2806
2807       <secondary>PAG with klog or pagsh command</secondary>
2808     </indexterm>
2809
2810     <indexterm>
2811       <primary>process authentication group</primary>
2812
2813       <secondary></secondary>
2814
2815       <see>PAG</see>
2816     </indexterm>
2817
2818     <sect2 id="HDRWQ64">
2819       <title>Identifying AFS Tokens by PAG</title>
2820
2821       <para>As noted, the Cache Manager identifies user credential structures either by UNIX UID or by PAG. Using a PAG is
2822       preferable because it guaranteed to be unique: the Cache Manager allocates it based on a counter that increments with each
2823       use. In contrast, multiple users on a machine can share or assume the same UNIX UID, which creates potential security
2824       problems. The following are two common such situations: <itemizedlist>
2825           <listitem>
2826             <para>The local superuser <emphasis role="bold">root</emphasis> can always assume any other user's UNIX UID simply by
2827             issuing the <emphasis role="bold">su</emphasis> command, without providing the user's password. If the credential
2828             structure is associated with the user's UNIX UID, then assuming the UID means inheriting the AFS tokens.</para>
2829           </listitem>
2830
2831           <listitem>
2832             <para>Two users working on different NFS client machines can have the same UNIX UID in their respective local file
2833             systems. If they both access the same NFS/AFS Translator machine, and the Cache Manager there identifies them by their
2834             UNIX UID, they become indistinguishable. To eliminate this problem, the Cache Manager on a translator machine
2835             automatically generates a PAG for each user and uses it, rather than the UNIX UID, to tell users apart.</para>
2836           </listitem>
2837         </itemizedlist></para>
2838
2839       <para>Yet another advantage of PAGs over UIDs is that processes spawned by the user inherit the PAG and so share the token;
2840       thus they gain access to AFS as the authenticated user. In many environments, for example, printer and other daemons run under
2841       identities (such as the local superuser <emphasis role="bold">root</emphasis>) that the AFS server processes recognize only as
2842       the <emphasis role="bold">anonymous</emphasis> user. Unless PAGs are used, such daemons cannot access files for which the
2843       <emphasis role="bold">system:anyuser</emphasis> group does not have the necessary ACL permissions.</para>
2844
2845       <para>Once a user has a PAG, any new tokens the user obtains are associated with the PAG. The PAG expires two hours after any
2846       associated tokens expire or are discarded. If the user issues the <emphasis role="bold">klog</emphasis> command before the PAG
2847       expires, the new token is associated with the existing PAG (the PAG is said to be recycled in this case).</para>
2848
2849       <para>AFS-modified login utilities automatically generate a PAG, as described in the following section. If you use a standard
2850       login utility, your users must issue the <emphasis role="bold">pagsh</emphasis> command before the <emphasis
2851       role="bold">klog</emphasis> command, or include the latter command's <emphasis role="bold">-setpag</emphasis> flag. For
2852       instructions, see <link linkend="HDRWQ69">Using Two-Step Login and Authentication</link>.</para>
2853
2854       <para>Users can also use either command at any time to create a new PAG. The difference between the two commands is that the
2855       <emphasis role="bold">klog</emphasis> command replaces the PAG associated with the current command shell and tokens. The
2856       <emphasis role="bold">pagsh</emphasis> command initializes a new command shell before creating a new PAG. If the user already
2857       had a PAG, any running processes or jobs continue to use the tokens associated with the old PAG whereas any new jobs or
2858       processes use the new PAG and its associated tokens. When you exit the new shell (by pressing &lt;<emphasis
2859       role="bold">Ctrl-d</emphasis>&gt;, for example), you return to the original PAG and shell. By default, the <emphasis
2860       role="bold">pagsh</emphasis> command initializes a Bourne shell, but you can include the <emphasis role="bold">-c</emphasis>
2861       argument to initialize a C shell (the <emphasis role="bold">/bin/csh</emphasis> program on many system types) or Korn shell
2862       (the <emphasis role="bold">/bin/ksh</emphasis> program) instead.</para>
2863
2864       <indexterm>
2865         <primary>login utility</primary>
2866
2867         <secondary>AFS version</secondary>
2868       </indexterm>
2869     </sect2>
2870
2871     <sect2 id="HDRWQ65">
2872       <title>Using an AFS-modified login Utility</title>
2873
2874       <para>As previously mentioned, an AFS-modified login utility simultaneously obtains an AFS token and logs the user into the
2875       local file system. This section outlines the login and authentication process and its interaction with the value in the
2876       password field of the local password file.</para>
2877
2878       <para>An AFS-modified login utility performs a sequence of steps similar to the following; details can vary for different
2879       operating systems: <orderedlist>
2880           <listitem>
2881             <para>It checks the user's entry in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
2882             equivalent).</para>
2883           </listitem>
2884
2885           <listitem>
2886             <para>If no entry exists, or if an asterisk (<computeroutput>*</computeroutput>) appears in the entry's password field,
2887             the login attempt fails. If the entry exists, the attempt proceeds to the next step.</para>
2888           </listitem>
2889
2890           <listitem>
2891             <para><anchor id="LIWQ66" />The utility obtains a PAG.</para>
2892           </listitem>
2893
2894           <listitem>
2895             <para><anchor id="LIWQ67" />The utility converts the password provided by the user into an encryption key and encrypts a
2896             packet of data with the key. It sends the packet to the AFS authentication service (the AFS Authentication Server in the
2897             conventional configuration).</para>
2898           </listitem>
2899
2900           <listitem>
2901             <para>The authentication service decrypts the packet and, depending on the success of the decryption, judges the
2902             password to be correct or incorrect. (For more details, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
2903             Authentication</link>.) <itemizedlist>
2904                 <listitem>
2905                   <para>If the authentication service judges the password incorrect, the user does not receive an AFS token. The PAG
2906                   is retained, ready to be associated with any tokens obtained later. The attempt proceeds to Step <link
2907                   linkend="LIWQ68">6</link>.</para>
2908                 </listitem>
2909
2910                 <listitem>
2911                   <para>If the authentication service judges the password correct, it issues a token to the user as proof of AFS
2912                   authentication. The login utility logs the user into the local UNIX file system. Some login utilities echo the
2913                   following banner to the screen to alert the user to authentication with AFS. Step <link linkend="LIWQ68">6</link>
2914                   is skipped. <programlisting>
2915    AFS(R) version Login 
2916 </programlisting></para>
2917                 </listitem>
2918               </itemizedlist></para>
2919           </listitem>
2920
2921           <listitem>
2922             <para><anchor id="LIWQ68" />If no AFS token was granted in Step <link linkend="LIWQ67">4</link>, the login utility
2923             attempts to log the user into the local file system, by comparing the password provided to the local password file.
2924             <itemizedlist>
2925                 <listitem>
2926                   <para>If the password is incorrect or any value other than an encrypted 13-character string appears in the
2927                   password field, the login attempt fails.</para>
2928                 </listitem>
2929
2930                 <listitem>
2931                   <para>If the password is correct, the user is logged into the local file system only.</para>
2932                 </listitem>
2933               </itemizedlist></para>
2934           </listitem>
2935         </orderedlist></para>
2936
2937       <indexterm>
2938         <primary>local password file</primary>
2939
2940         <secondary>when using AFS--modified login utility</secondary>
2941       </indexterm>
2942
2943       <indexterm>
2944         <primary>login utility</primary>
2945
2946         <secondary>AFS version's interaction with local password file</secondary>
2947       </indexterm>
2948
2949       <indexterm>
2950         <primary>password</primary>
2951
2952         <secondary>local password file</secondary>
2953       </indexterm>
2954
2955       <para>As indicated, when you use an AFS-modified login utility, the password field in the local password file is no longer the
2956       primary gate for access to your system. If the user provides the correct AFS password, then the program never consults the
2957       local password file. However, you can still use the password field to control access, in the following way: <itemizedlist>
2958           <listitem>
2959             <para>To prevent both local login and AFS authentication, place an asterisk (<emphasis role="bold">*</emphasis>) in the
2960             field. This is useful mainly in emergencies, when you want to prevent a certain user from logging into the
2961             machine.</para>
2962           </listitem>
2963
2964           <listitem>
2965             <para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
2966             string of any length other than the standard thirteen characters in the field. This is appropriate if you want to permit
2967             only people with local AFS accounts to login on your machines. A single <emphasis role="bold">X</emphasis> or other
2968             character is the most easily recognizable way to do this.</para>
2969           </listitem>
2970
2971           <listitem>
2972             <para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
2973             standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
2974             role="bold">passwd</emphasis> or equivalent).</para>
2975           </listitem>
2976         </itemizedlist></para>
2977
2978       <para>Systems that use a Pluggable Authentication Module (PAM) for login and AFS authentication do not necessarily consult the
2979       local password file at all, in which case they do not use the password field to control authentication and login attempts.
2980       Instead, instructions in the PAM configuration file (on many system types, <emphasis role="bold">/etc/pam.conf</emphasis>)
2981       fill the same function. See the instructions in the OpenAFS Quick Beginnings for installing AFS-modified login
2982       utilities.</para>
2983
2984       <indexterm>
2985         <primary>local password file</primary>
2986
2987         <secondary>when not using AFS-modified login utility</secondary>
2988       </indexterm>
2989     </sect2>
2990
2991     <sect2 id="HDRWQ69">
2992       <title>Using Two-Step Login and Authentication</title>
2993
2994       <para>In cells that do not use an AFS-modified login utility, users must issue separate commands to login and authenticate, as
2995       detailed in the OpenAFS User Guide: <orderedlist>
2996           <listitem>
2997             <para>They use the standard <emphasis role="bold">login</emphasis> program to login to the local file system, providing
2998             the password listed in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
2999             equivalent).</para>
3000           </listitem>
3001
3002           <listitem>
3003             <para>They must issue the <emphasis role="bold">klog</emphasis> command to authenticate with the AFS authentication
3004             service, including its <emphasis role="bold">-setpag</emphasis> flag to associate the new tokens with a process
3005             authentication group (PAG).</para>
3006           </listitem>
3007         </orderedlist></para>
3008
3009       <para>As mentioned in <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>, you can invoke the <emphasis
3010       role="bold">klog -setpag</emphasis> command in a user's <emphasis role="bold">.login</emphasis> file (or equivalent) so that
3011       the user does not have to remember to issue the command after logging in. The user still must type a password twice, once at
3012       the prompt generated by the login utility and once at the <emphasis role="bold">klog</emphasis> command's prompt. This implies
3013       that the two passwords can differ, but it is less confusing if they do not.</para>
3014
3015       <para>Another effect of not using an AFS-modified login utility is that the AFS servers recognize the standard <emphasis
3016       role="bold">login</emphasis> program as the <emphasis role="bold">anonymous</emphasis> user. If the <emphasis
3017       role="bold">login</emphasis> program needs to access any AFS files (such as the <emphasis role="bold">.login</emphasis> file
3018       in a user's home directory), then the ACL that protects the file must include an entry granting the <emphasis
3019       role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
3020       role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group.</para>
3021
3022       <para>When you do not use an AFS-modified login utility, an actual (scrambled) password must appear in the local password file
3023       for each user. Use the <emphasis role="bold">/bin/passwd</emphasis> file to insert or change these passwords. It is simpler if
3024       the password in the local password file matches the AFS password, but it is not required.</para>
3025
3026       <indexterm>
3027         <primary>tokens</primary>
3028
3029         <secondary>displaying for user</secondary>
3030       </indexterm>
3031
3032       <indexterm>
3033         <primary>tokens</primary>
3034
3035         <secondary>command</secondary>
3036       </indexterm>
3037
3038       <indexterm>
3039         <primary>commands</primary>
3040
3041         <secondary>tokens</secondary>
3042       </indexterm>
3043
3044       <indexterm>
3045         <primary>listing</primary>
3046
3047         <secondary>tokens held by issuer</secondary>
3048       </indexterm>
3049
3050       <indexterm>
3051         <primary>commands</primary>
3052
3053         <secondary>klog</secondary>
3054       </indexterm>
3055
3056       <indexterm>
3057         <primary>klog command</primary>
3058       </indexterm>
3059
3060       <indexterm>
3061         <primary>server process</primary>
3062
3063         <secondary>creating ticket (tokens) for</secondary>
3064       </indexterm>
3065
3066       <indexterm>
3067         <primary>tickets</primary>
3068
3069         <secondary></secondary>
3070
3071         <see>tokens</see>
3072       </indexterm>
3073
3074       <indexterm>
3075         <primary>tokens</primary>
3076
3077         <secondary>creating for server process</secondary>
3078       </indexterm>
3079
3080       <indexterm>
3081         <primary>authenticated identity</primary>
3082
3083         <secondary>acquiring with klog command</secondary>
3084       </indexterm>
3085
3086       <indexterm>
3087         <primary>unlog command</primary>
3088       </indexterm>
3089
3090       <indexterm>
3091         <primary>commands</primary>
3092
3093         <secondary>unlog</secondary>
3094       </indexterm>
3095
3096       <indexterm>
3097         <primary>discarding</primary>
3098
3099         <secondary>tokens</secondary>
3100       </indexterm>
3101
3102       <indexterm>
3103         <primary>tokens</primary>
3104
3105         <secondary>discarding with unlog command</secondary>
3106       </indexterm>
3107     </sect2>
3108
3109     <sect2 id="Header_81">
3110       <title>Obtaining, Displaying, and Discarding Tokens</title>
3111
3112       <para>Once logged in, a user can obtain a token at any time with the <emphasis role="bold">klog</emphasis> command. If a valid
3113       token already exists, the new one overwrites it. If a PAG already exists, the new token is associated with it.</para>
3114
3115       <para>By default, the <emphasis role="bold">klog</emphasis> command authenticates the issuer using the identity currently
3116       logged in to the local file system. To authenticate as a different identity, use the <emphasis
3117       role="bold">-principal</emphasis> argument. To obtain a token for a foreign cell, use the <emphasis
3118       role="bold">-cell</emphasis> argument (it can be combined with the <emphasis role="bold">-principal</emphasis> argument). See
3119       the OpenAFS User Guide and the entry for the <emphasis role="bold">klog</emphasis> command in the OpenAFS Administration
3120       Reference.</para>
3121
3122       <para>To discard either all tokens or the token for a particular cell, issue the <emphasis role="bold">unlog</emphasis>
3123       command. The command affects only the tokens associated with the current command shell. See the OpenAFS User Guideand the
3124       entry for the <emphasis role="bold">unlog</emphasis> command in the OpenAFS Administration Reference.</para>
3125
3126       <para>To display the tokens associated with the current command shell, issue the <emphasis role="bold">tokens</emphasis>
3127       command. The following examples illustrate its output in various situations.</para>
3128
3129       <para>If the issuer is not authenticated in any cell:</para>
3130
3131       <programlisting>
3132    % <emphasis role="bold">tokens</emphasis>
3133    Tokens held by the Cache Manager:
3134           --End of list--
3135 </programlisting>
3136
3137       <para>The following shows the output for a user with AFS UID 1000 in the ABC Corporation cell:</para>
3138
3139       <programlisting>
3140    % <emphasis role="bold">tokens</emphasis>
3141    Tokens held by the Cache Manager: 
3142    User's (AFS ID 1000) tokens for afs@abc.com  [Expires Jun  2 10:00]
3143        --End of list--
3144 </programlisting>
3145
3146       <para>The following shows the output for a user who is authenticated in ABC Corporation cell, the State University cell and
3147       the DEF Company cell. The user has different AFS UIDs in the three cells. Tokens for the last cell are expired:</para>
3148
3149       <programlisting>
3150    % <emphasis role="bold">tokens</emphasis>
3151    Tokens held by the Cache Manager:
3152    User's (AFS ID 1000) tokens for afs@abc.com  [Expires Jun  2 10:00]
3153    User's (AFS ID 4286) tokens for afs@stateu.edu  [Expires Jun  3 1:34]
3154    User's (AFS ID 22) tokens for afs@def.com  [&gt;&gt;Expired&lt;&lt;]
3155        --End of list--
3156 </programlisting>
3157
3158       <para>The Kerberos version of the <emphasis role="bold">tokens</emphasis> command (the <emphasis
3159       role="bold">tokens.krb</emphasis> command), also reports information on the ticket-granting ticket, including the ticket's
3160       owner, the ticket-granting service, and the expiration date, as in the following example. Also see <link
3161       linkend="HDRWQ70">Support for Kerberos Authentication</link>.</para>
3162
3163       <programlisting>
3164    % <emphasis role="bold">tokens.krb</emphasis>
3165    Tokens held by the Cache Manager:
3166    User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun  2 10:00]
3167    User smith's tokens for krbtgt.ABC.COM@abc.com [Expires Jun  2