1bb7d900b5220f520177cc78352eec8b37fa378b
[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. For authenticated access, foreign clients
833       must be configured with the necessary Kerberos v5 domain-to-realm mappings and Key Distribution Center location information for both the local and remote Kerberos v5 realms.</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 the AFS Registrar</primary>
844
845             <secondary>as global update source</secondary>
846           </indexterm>
847
848           <listitem>
849             <para>In the
850             global <emphasis role="bold">CellServDB</emphasis> file
851             maintained by the AFS Registrar. This file lists the name and
852             database server machines of every cell that has agreed to make
853             this information available to other cells. This file is
854             available
855             at <ulink url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink></para>
856
857             <para>To add or change your cell's listing in this file,
858               follow the instructions at
859               <ulink url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink>.
860               It is a good policy to check the file for changes on a
861               regular schedule. An updated copy of this file is included
862               with new releases of OpenAFS.</para>
863
864             <indexterm>
865               <primary>files</primary>
866
867               <secondary>CellServDB.local</secondary>
868             </indexterm>
869
870             <indexterm>
871               <primary>CellServDB.local file</primary>
872             </indexterm>
873           </listitem>
874
875           <listitem>
876             <para>A file called <emphasis role="bold">CellServDB.local</emphasis> in the <emphasis
877             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/service/etc</emphasis> directory
878             of your cell's filespace. List only your cell's database server machines.</para>
879           </listitem>
880         </itemizedlist></para>
881
882       <para>Update the files whenever you change the identity of your cell's database server machines. Also update the copies of the
883       <emphasis role="bold">CellServDB</emphasis> files on all of your server machines (in the <emphasis
884       role="bold">/usr/afs/etc</emphasis> directory) and client machines (in the <emphasis role="bold">/usr/vice/etc</emphasis>
885       directory). For instructions, see <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and <link
886       linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
887
888       <para>Once you have advertised your database server machines, it can be difficult to make your cell invisible again. You can
889       remove the <emphasis role="bold">CellServDB.local</emphasis> file and ask the AFS Registrar to remove your entry from the
890       global <emphasis role="bold">CellServDB</emphasis> file, but other cells probably have an entry for your cell in their local
891       <emphasis role="bold">CellServDB</emphasis> files already. To make those entries invalid, you must change the names or IP
892       addresses of your database server machines.</para>
893
894       <para>Your cell does not have to be invisible to be inaccessible, however. To make your cell completely inaccessible to
895       foreign users, remove the <emphasis role="bold">system:anyuser</emphasis> group from all ACLs at the top three levels of your
896       filespace; see <link linkend="HDRWQ40">Granting and Denying Foreign Users Access to Your Cell</link>.</para>
897
898       <indexterm>
899         <primary>cell</primary>
900
901         <secondary>making foreign visible to local</secondary>
902       </indexterm>
903
904       <indexterm>
905         <primary>local cell</primary>
906
907         <secondary>making foreign cells visible in</secondary>
908       </indexterm>
909
910       <indexterm>
911         <primary>foreign cell</primary>
912
913         <secondary>making visible in local cell</secondary>
914       </indexterm>
915
916       <indexterm>
917         <primary>client machine</primary>
918
919         <secondary>making foreign cell visible</secondary>
920       </indexterm>
921     </sect2>
922
923     <sect2 id="HDRWQ39">
924       <title>Making Other Cells Visible in Your Cell</title>
925
926       <para>To make a foreign cell's filespace visible on a client machine
927       in your cell that is not configured
928       for <emphasis role="bold">Freelance Mode</emphasis>
929       or <emphasis role="bold">Dynamic Root</emphasis> mode, perform the
930       following three steps:
931       <orderedlist>
932           <listitem>
933             <para>Mount the cell's <emphasis role="bold">root.cell</emphasis> volume at the second level in your cell's filespace
934             just below the <emphasis role="bold">/afs</emphasis> directory. Use the <emphasis role="bold">fs mkmount</emphasis>
935             command with the <emphasis role="bold">-cell</emphasis> argument as instructed in <link linkend="HDRWQ213">To create a
936             cellular mount point</link>.</para>
937           </listitem>
938
939           <listitem>
940             <para>Mount AFS at the <emphasis role="bold">/afs</emphasis> directory on the client machine. The <emphasis
941             role="bold">afsd</emphasis> program, which initializes the Cache Manager, performs the mount automatically at the
942             directory named in the first field of the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file or by the
943             command's <emphasis role="bold">-mountdir</emphasis> argument. Mounting AFS at an alternate location makes it impossible
944             to reach the filespace of any cell that mounts its <emphasis role="bold">root.afs</emphasis> and <emphasis
945             role="bold">root.cell</emphasis> volumes at the conventional locations. See <link linkend="HDRWQ395">Displaying and
946             Setting the Cache Size and Location</link>.</para>
947           </listitem>
948
949           <listitem>
950             <para>Create an entry for the cell in the list of database server machines which the Cache Manager maintains in kernel
951             memory.</para>
952
953             <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on every client machine's local disk lists the
954             database server machines for the local and foreign cells. The <emphasis role="bold">afsd</emphasis> program reads the
955             contents of the <emphasis role="bold">CellServDB</emphasis> file into kernel memory as it initializes the Cache Manager.
956             You can also use the <emphasis role="bold">fs newcell</emphasis> command to add or alter entries in kernel memory
957             directly between reboots of the machine. See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server
958             Machines</link>.</para>
959           </listitem>
960         </orderedlist></para>
961
962       <para>Non-windows client machines may
963       enable <emphasis role="bold">Dynamic Root Mode</emphasis> by using
964       the <emphasis role="bold">-dynroot</emphasis> option
965       to <emphasis role="bold">afsd</emphasis>. When this option is
966       enabled, all cells listed in
967       the <emphasis role="bold">CellServDB</emphasis> file will appear in
968       the <emphasis role="bold">/afs</emphasis> directory. The contents of
969       the <emphasis role="bold">root.afs</emphasis> volume will be ignored.
970       </para>
971
972       <para>Windows client machines may
973       enable <emphasis role="bold">Freelance Mode</emphasis> during client
974       installation or by setting
975       the <emphasis role="bold">FreelanceClient</emphasis> setting
976       under <emphasis role="bold">Service Parameters</emphasis> in the
977       Windows Registry as mentioned in
978       the <ulink url="http://docs.openafs.org/ReleaseNotesWindows/">Release
979       Notes</ulink>.  When this option is enabled,
980       the <emphasis role="bold">root.afs</emphasis> volume is ignored and
981       a mounpoint for each cell is automatically created in the
982       the <emphasis role="bold">\\AFS</emphasis> directory when the
983       folder <emphasis role="bold">\\AFS\<replaceable>cellname</replaceable></emphasis>
984       is accessed and the foreign Volume Location servers can be reached.
985       </para>
986       <para>Note that making a foreign cell visible to client machines does not guarantee that your users can access its filespace.
987       The ACLs in the foreign cell must also grant them the necessary permissions.</para>
988
989       <indexterm>
990         <primary>cell</primary>
991
992         <secondary>granting local access to foreign users</secondary>
993       </indexterm>
994
995       <indexterm>
996         <primary>local cell</primary>
997
998         <secondary>granting foreign users access to</secondary>
999       </indexterm>
1000     </sect2>
1001
1002     <sect2 id="HDRWQ40">
1003       <title>Granting and Denying Foreign Users Access to Your Cell</title>
1004
1005       <para>Making your cell visible in the AFS global namespace does not take away your control over the way in which users from
1006       foreign cells access your file tree.</para>
1007
1008       <para>By default, foreign users access your cell as the user <emphasis role="bold">anonymous</emphasis>, which means they have
1009       only the permissions granted to the <emphasis role="bold">system:anyuser</emphasis> group on each directory's ACL. Normally
1010       these permissions are limited to the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and
1011       <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permissions.</para>
1012
1013       <para>There are three ways to grant wider access to foreign users: <itemizedlist>
1014           <listitem>
1015             <para>Grant additional permissions to the <emphasis role="bold">system:anyuser</emphasis> group on certain ACLs. Keep in
1016             mind, however, that all users can then access that directory in the indicated way (not just specific foreign users you
1017             have in mind).</para>
1018           </listitem>
1019
1020           <listitem>
1021             <para>Enable automatic registration for users in the foreign
1022             cell. This may be done by creating a cross-realm trust in
1023             the <emphasis role="bold">Kerberos Database</emphasis>. Then
1024             add a PTS group
1025             named <emphasis role="bold">system:authuser<replaceable>@FOREIGN.REALM</replaceable></emphasis>
1026             and give it a group quota greater than the number of foreign
1027             users expected to be registered. After the cross-realm trust
1028             and the PTS group are created,
1029             the <ulink url="http://docs.openafs.org/Reference/1/aklog.html">aklog</ulink>
1030             command will automatically register foreign users as
1031             needed. Consult the documentation for
1032             your <emphasis role="bold">Kerberos Server</emphasis> for
1033             instructions on how to establish a cross-realm trust.
1034             </para>
1035           </listitem>
1036
1037           <listitem>
1038             <para>Create a local authentication account for specific
1039             foreign users, by creating entries in the Protection Database,
1040             the Kerberos Database, and the local password file.</para>
1041           </listitem>
1042         </itemizedlist></para>
1043
1044       <indexterm>
1045         <primary>cell</primary>
1046
1047         <secondary>filespace configuration issues</secondary>
1048       </indexterm>
1049
1050       <indexterm>
1051         <primary>configuring</primary>
1052
1053         <secondary>filespace, issues</secondary>
1054       </indexterm>
1055
1056       <indexterm>
1057         <primary>file tree</primary>
1058
1059         <secondary>conventions</secondary>
1060
1061         <tertiary>for configuring</tertiary>
1062       </indexterm>
1063     </sect2>
1064   </sect1>
1065
1066   <sect1 id="HDRWQ41">
1067     <title>Configuring Your AFS Filespace</title>
1068
1069     <para>This section summarizes the issues to consider when configuring your AFS filespace. For a discussion of creating volumes
1070     that correspond most efficiently to the filespace's directory structure, see <link linkend="HDRWQ44">Creating Volumes to
1071     Simplify Administration</link>.</para>
1072
1073     <note>
1074       <para><emphasis role="bold">For Windows users:</emphasis> Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather
1075       than a forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname. The hierarchical
1076       organization of the filespace is however the same as on a UNIX machine.</para>
1077     </note>
1078
1079     <para>AFS pathnames must follow a few conventions so the AFS global namespace looks the same from any AFS client machine. There
1080     are corresponding conventions to follow in building your file tree, not just because pathnames reflect the structure of a file
1081     tree, but also because the AFS Cache Manager expects a certain configuration.</para>
1082
1083     <indexterm>
1084       <primary>AFS</primary>
1085
1086       <secondary>root directory (/afs)</secondary>
1087
1088       <tertiary>in cell filespace</tertiary>
1089     </indexterm>
1090
1091     <indexterm>
1092       <primary>directories</primary>
1093
1094       <secondary>/afs</secondary>
1095     </indexterm>
1096
1097     <sect2 id="Header_51">
1098       <title>The Top /afs Level</title>
1099
1100       <para>The first convention is that the top level in your file tree be called the <emphasis role="bold">/afs</emphasis>
1101       directory. If you name it something else, then you must use the <emphasis role="bold">-mountdir</emphasis> argument with the
1102       <emphasis role="bold">afsd</emphasis> program to get Cache Managers to mount AFS properly. You cannot participate in the AFS
1103       global namespace in that case.</para>
1104
1105       <indexterm>
1106         <primary>cell</primary>
1107
1108         <secondary>name</secondary>
1109
1110         <tertiary>at second level in file tree</tertiary>
1111       </indexterm>
1112
1113       <indexterm>
1114         <primary>directories</primary>
1115
1116         <secondary>/afs/<emphasis>cellname</emphasis></secondary>
1117       </indexterm>
1118
1119       <indexterm>
1120         <primary>symbolic link</primary>
1121
1122         <secondary>at second level of AFS pathname</secondary>
1123       </indexterm>
1124     </sect2>
1125
1126     <sect2 id="HDRWQ42">
1127       <title>The Second (Cellname) Level</title>
1128
1129       <para>The second convention is that just below the <emphasis role="bold">/afs</emphasis> directory you place directories
1130       corresponding to each cell whose file tree is visible and accessible from the local cell. Minimally, there must be a directory
1131       for the local cell. Each such directory is a mount point to the indicated cell's <emphasis role="bold">root.cell</emphasis>
1132       volume. For example, in the ABC Corporation cell, <emphasis role="bold">/afs/abc.com</emphasis> is a mount point for the
1133       cell's own <emphasis role="bold">root.cell</emphasis> volume and <emphasis role="bold">stateu.edu</emphasis> is a mount point
1134       for the State University cell's <emphasis role="bold">root.cell</emphasis> volume. The <emphasis role="bold">fs
1135       lsmount</emphasis> command displays the mount points.</para>
1136
1137       <programlisting>
1138    % <emphasis role="bold">fs lsmount /afs/abc.com</emphasis> 
1139    '/afs/abc.com' is a mount point for volume '#root.cell'
1140    % <emphasis role="bold">fs lsmount /afs/stateu.edu</emphasis>
1141    '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
1142 </programlisting>
1143
1144       <para>To reduce the amount of typing necessary in pathnames, you can create a symbolic link with an abbreviated name to the
1145       mount point of each cell your users frequently access (particularly the home cell). In the ABC Corporation cell, for instance,
1146       <emphasis role="bold">/afs/abc</emphasis> is a symbolic link to the <emphasis role="bold">/afs/abc.com</emphasis> mount point,
1147       as the <emphasis role="bold">fs lsmount</emphasis> command reveals.</para>
1148
1149       <programlisting>
1150    % <emphasis role="bold">fs lsmount /afs/abc</emphasis>
1151    '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
1152 </programlisting>
1153
1154       <indexterm>
1155         <primary>file tree</primary>
1156
1157         <secondary>conventions</secondary>
1158
1159         <tertiary>third level</tertiary>
1160       </indexterm>
1161
1162       <indexterm>
1163         <primary>directories</primary>
1164
1165         <secondary>conventional under /afs/cellname</secondary>
1166       </indexterm>
1167     </sect2>
1168
1169     <sect2 id="HDRWQ43">
1170       <title>The Third Level</title>
1171
1172       <para>You can organize the third level of your cell's file tree any way you wish. The following list describes directories
1173       that appear at this level in the conventional configuration: <variablelist>
1174           <varlistentry>
1175             <term><emphasis role="bold">common</emphasis></term>
1176
1177             <listitem>
1178               <para>This directory contains programs and files needed by users working on machines of all system types, such as text
1179               editors, online documentation files, and so on. Its <emphasis role="bold">/etc</emphasis> subdirectory is a logical
1180               place to keep the central update sources for files used on all of your cell's client machines, such as the <emphasis
1181               role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files.</para>
1182             </listitem>
1183           </varlistentry>
1184
1185           <varlistentry>
1186             <term><emphasis role="bold">public</emphasis></term>
1187
1188             <listitem>
1189               <para>A directory accessible to anyone who can access your filespace, because its ACL grants the <emphasis
1190               role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
1191               role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group. It is useful if
1192               you want to enable your users to make selected information available to everyone, but do not want to grant foreign
1193               users access to the contents of the <emphasis role="bold">usr</emphasis> directory which houses user home directories
1194               (and is also at this level). It is conventional to create a subdirectory for each of your cell's users.</para>
1195             </listitem>
1196           </varlistentry>
1197
1198           <varlistentry>
1199             <term><emphasis role="bold">service</emphasis></term>
1200
1201             <listitem>
1202               <para>This directory contains files and subdirectories that help cells coordinate resource sharing. For a list of the
1203               proposed standard files and subdirectories to create, call or write to AFS Product Support.</para>
1204
1205               <para>As an example, files that other cells expect to find in this directory's <emphasis role="bold">etc</emphasis>
1206               subdirectory can include the following: <itemizedlist>
1207                   <listitem>
1208                     <para><emphasis role="bold">CellServDB.export</emphasis>, a list of database server machines for many
1209                     cells</para>
1210                   </listitem>
1211
1212                   <listitem>
1213                     <para><emphasis role="bold">CellServDB.local</emphasis>, a list of the cell's own database server
1214                     machines</para>
1215                   </listitem>
1216
1217                   <listitem>
1218                     <para><emphasis role="bold">passwd</emphasis>, a copy of the local password file (<emphasis
1219                     role="bold">/etc/passwd</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
1220                   </listitem>
1221
1222                   <listitem>
1223                     <para><emphasis role="bold">group</emphasis>, a copy of the local groups file (<emphasis
1224                     role="bold">/etc/group</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
1225                   </listitem>
1226                 </itemizedlist></para>
1227             </listitem>
1228           </varlistentry>
1229
1230           <varlistentry>
1231             <term><emphasis>sys_type</emphasis></term>
1232
1233             <listitem>
1234               <para>A separate directory for storing the server and client binaries for each system type you use in the cell.
1235               Configuration is simplest if you use the system type names assigned in the AFS distribution, particularly if you wish
1236               to use the <emphasis role="bold">@sys</emphasis> variable in pathnames (see <link linkend="HDRWQ56">Using the @sys
1237               Variable in Pathnames</link>). The <emphasis>OpenAFS Release Notes</emphasis> lists the conventional name for each
1238               supported system type.</para>
1239
1240               <para>Within each such directory, create directories named <emphasis role="bold">bin</emphasis>, <emphasis
1241               role="bold">etc</emphasis>, <emphasis role="bold">usr</emphasis>, and so on, to store the programs normally kept in
1242               the <emphasis role="bold">/bin</emphasis>, <emphasis role="bold">/etc</emphasis> and <emphasis
1243               role="bold">/usr</emphasis> directories on a local disk. Then create symbolic links from the local directories on
1244               client machines into AFS; see <link linkend="HDRWQ55">Configuring the Local Disk</link>. Even if you do not choose to
1245               use symbolic links in this way, it can be convenient to have central copies of system binaries in AFS. If binaries are
1246               accidentally removed from a machine, you can recopy them onto the local disk from AFS rather than having to recover
1247               them from tape</para>
1248             </listitem>
1249           </varlistentry>
1250
1251           <varlistentry>
1252             <term><emphasis role="bold">usr</emphasis></term>
1253
1254             <listitem>
1255               <para>This directory contains home directories for your local users. As discussed in the previous entry for the
1256               <emphasis role="bold">public</emphasis> directory, it is often practical to protect this directory so that only
1257               locally authenticated users can access it. This keeps the contents of your user's home directories as secure as
1258               possible.</para>
1259
1260               <para>If your cell is quite large, directory lookup can be slowed if you put all home directories in a single
1261               <emphasis role="bold">usr</emphasis> directory. For suggestions on distributing user home directories among multiple
1262               grouping directories, see <link linkend="HDRWQ59">Grouping Home Directories</link>.</para>
1263             </listitem>
1264           </varlistentry>
1265
1266           <varlistentry>
1267             <term><emphasis role="bold">wsadmin</emphasis></term>
1268
1269             <listitem>
1270               <para>This directory contains prototype, configuration and library files for use with the <emphasis
1271               role="bold">package</emphasis> program. See <link linkend="HDRWQ419">Configuring Client Machines with the package
1272               Program</link>.</para>
1273             </listitem>
1274           </varlistentry>
1275         </variablelist></para>
1276
1277       <indexterm>
1278         <primary>volume name</primary>
1279
1280         <secondary>conventions for</secondary>
1281       </indexterm>
1282
1283       <indexterm>
1284         <primary>conventions</primary>
1285
1286         <secondary>volume names</secondary>
1287       </indexterm>
1288
1289       <indexterm>
1290         <primary>volume</primary>
1291
1292         <secondary>separate for each top level directory</secondary>
1293       </indexterm>
1294
1295       <indexterm>
1296         <primary>file tree</primary>
1297
1298         <secondary>creating volumes to match top level directories</secondary>
1299       </indexterm>
1300     </sect2>
1301   </sect1>
1302
1303   <sect1 id="HDRWQ44">
1304     <title>Creating Volumes to Simplify Administration</title>
1305
1306     <para>This section discusses how to create volumes in ways that make administering your system easier.</para>
1307
1308     <para>At the top levels of your file tree (at least through the third level), each directory generally corresponds to a separate
1309     volume. Some cells also configure the subdirectories of some third level directories as separate volumes. Common examples are
1310     the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/common</emphasis> and
1311     <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis>
1312     directories.</para>
1313
1314     <para>You do not have to create a separate volume for every directory level in a tree, but the advantage is that each volume
1315     tends to be smaller and easier to move for load balancing. The overhead for a mount point is no greater than for a standard
1316     directory, nor does the volume structure itself require much disk space. Most cells find that below the fourth level in the
1317     tree, using a separate volume for each directory is no longer efficient. For instance, while each user's home directory (at the
1318     fourth level in the tree) corresponds to a separate volume, all of the subdirectories in the home directory normally reside in
1319     the same volume.</para>
1320
1321     <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
1322     mounted at several locations, though this is not recommended because it distorts the hierarchical nature of the file tree,
1323     potentially causing confusion.</para>
1324
1325     <indexterm>
1326       <primary>volume name</primary>
1327
1328       <secondary>restrictions</secondary>
1329     </indexterm>
1330
1331     <indexterm>
1332       <primary>restrictions</primary>
1333
1334       <secondary>on volume names</secondary>
1335     </indexterm>
1336
1337     <indexterm>
1338       <primary>volume name</primary>
1339
1340       <secondary>two required</secondary>
1341     </indexterm>
1342
1343     <indexterm>
1344       <primary>volume</primary>
1345
1346       <secondary>root (root.afs and root.cell)</secondary>
1347     </indexterm>
1348
1349     <indexterm>
1350       <primary>root volumes (root.afs and root.cell)</primary>
1351     </indexterm>
1352
1353     <sect2 id="Header_55">
1354       <title>Assigning Volume Names</title>
1355
1356       <para>You can name your volumes anything you choose, subject to a few restrictions: <itemizedlist>
1357           <listitem>
1358             <para>Read/write volume names can be up to 22 characters in length. The maximum length for volume names is 31
1359             characters, and there must be room to add the <emphasis role="bold">.readonly</emphasis> extension on read-only
1360             volumes.</para>
1361           </listitem>
1362
1363           <listitem>
1364             <para>Do not add the <emphasis role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extensions
1365             to volume names yourself, even if they are appropriate. The Volume Server adds them automatically as it creates a
1366             read-only or backup version of a volume.</para>
1367           </listitem>
1368
1369           <listitem>
1370             <para>There must be volumes named <emphasis role="bold">root.afs</emphasis> and <emphasis
1371             role="bold">root.cell</emphasis>, mounted respectively at the top (<emphasis role="bold">/afs</emphasis>) level in the
1372             filespace and just below that level, at the cell's name (for example, at <emphasis role="bold">/afs/abc.com</emphasis>
1373             in the ABC Corporation cell).</para>
1374
1375             <para>Deviating from these names only creates confusion and extra work. Changing the name of the <emphasis
1376             role="bold">root.afs</emphasis> volume, for instance, means that you must use the <emphasis
1377             role="bold">-rootvol</emphasis> argument to the <emphasis role="bold">afsd</emphasis> program on every client machine,
1378             to name the alternate volume.</para>
1379
1380             <para>Similarly, changing the <emphasis role="bold">root.cell</emphasis> volume name prevents users in foreign cells
1381             from accessing your filespace, if the mount point for your cell in their filespace refers to the conventional <emphasis
1382             role="bold">root.cell</emphasis> name. Of course, this is one way to make your cell invisible to other cells.</para>
1383           </listitem>
1384         </itemizedlist></para>
1385
1386       <para>It is best to assign volume names that indicate the type of data they contain, and to use similar names for volumes with
1387       similar contents. It is also helpful if the volume name is similar to (or at least has elements in common with) the name of
1388       the directory at which it is mounted. Understanding the pattern then enables you accurately to guess what a volume contains
1389       and where it is mounted.</para>
1390
1391       <para>Many cells find that the most effective volume naming scheme puts a common prefix on the names of all related volumes.
1392       <link linkend="TBLVOL-PREFIX">Table 1</link> describes the recommended prefixing scheme.</para>
1393
1394       <table id="TBLVOL-PREFIX" label="1">
1395         <title>Suggested volume prefixes</title>
1396
1397         <tgroup cols="4">
1398           <colspec colwidth="14*" />
1399
1400           <colspec colwidth="28*" />
1401
1402           <colspec colwidth="22*" />
1403
1404           <colspec colwidth="36*" />
1405
1406           <thead>
1407             <row>
1408               <entry><emphasis role="bold">Prefix</emphasis></entry>
1409
1410               <entry><emphasis role="bold">Contents</emphasis></entry>
1411
1412               <entry><emphasis role="bold">Example Name</emphasis></entry>
1413
1414               <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
1415             </row>
1416           </thead>
1417
1418           <tbody>
1419             <row>
1420               <entry><emphasis role="bold">common.</emphasis></entry>
1421
1422               <entry>popular programs and files</entry>
1423
1424               <entry><emphasis role="bold">common.etc</emphasis></entry>
1425
1426               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1427               role="bold">/common/etc</emphasis></entry>
1428             </row>
1429
1430             <row>
1431               <entry><emphasis role="bold">src.</emphasis></entry>
1432
1433               <entry>source code</entry>
1434
1435               <entry><emphasis role="bold">src.afs</emphasis></entry>
1436
1437               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1438               role="bold">/src/afs</emphasis></entry>
1439             </row>
1440
1441             <row>
1442               <entry><emphasis role="bold">proj.</emphasis></entry>
1443
1444               <entry>project data</entry>
1445
1446               <entry><emphasis role="bold">proj.portafs</emphasis></entry>
1447
1448               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1449               role="bold">/proj/portafs</emphasis></entry>
1450             </row>
1451
1452             <row>
1453               <entry><emphasis role="bold">test.</emphasis></entry>
1454
1455               <entry>testing or other temporary data</entry>
1456
1457               <entry><emphasis role="bold">test.smith</emphasis></entry>
1458
1459               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1460               role="bold">/usr/smith/test</emphasis></entry>
1461             </row>
1462
1463             <row>
1464               <entry><emphasis role="bold">user.</emphasis></entry>
1465
1466               <entry>user home directory data</entry>
1467
1468               <entry><emphasis role="bold">user.terry</emphasis></entry>
1469
1470               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1471               role="bold">/usr/terry</emphasis></entry>
1472             </row>
1473
1474             <row>
1475               <entry>sys_type<emphasis role="bold">.</emphasis></entry>
1476
1477               <entry>programs compiled for an operating system type</entry>
1478
1479               <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
1480
1481               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1482               role="bold">/rs_aix42/bin</emphasis></entry>
1483             </row>
1484           </tbody>
1485         </tgroup>
1486       </table>
1487
1488       <para><link linkend="TBLPREFIX-EXAMPLE">Table 2</link> is a more specific example for a cell's <emphasis
1489       role="bold">rs_aix42</emphasis> system volumes and directories:</para>
1490
1491       <table id="TBLPREFIX-EXAMPLE" label="2">
1492         <title>Example volume-prefixing scheme</title>
1493
1494         <tgroup cols="2">
1495           <colspec colwidth="14*" />
1496
1497           <colspec colwidth="28*" />
1498
1499           <colspec colwidth="22*" />
1500
1501           <colspec colwidth="36*" />
1502
1503           <thead>
1504             <row>
1505               <entry><emphasis role="bold">Example Name</emphasis></entry>
1506
1507               <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
1508             </row>
1509           </thead>
1510
1511           <tbody>
1512             <row>
1513               <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
1514
1515               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1516               role="bold">/rs_aix42/bin</emphasis>, <emphasis
1517               role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/rs_aix42/bin</emphasis></entry>
1518             </row>
1519
1520             <row>
1521               <entry><emphasis role="bold">rs_aix42.etc</emphasis></entry>
1522
1523               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1524               role="bold">/rs_aix42/etc</emphasis></entry>
1525             </row>
1526
1527             <row>
1528               <entry><emphasis role="bold">rs_aix42.usr</emphasis></entry>
1529
1530               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1531               role="bold">/rs_aix42/usr</emphasis></entry>
1532             </row>
1533
1534             <row>
1535               <entry><emphasis role="bold">rs_aix42.usr.afsws</emphasis></entry>
1536
1537               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1538               role="bold">/rs_aix42/usr/afsws</emphasis></entry>
1539             </row>
1540
1541             <row>
1542               <entry><emphasis role="bold">rs_aix42.usr.lib</emphasis></entry>
1543
1544               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1545               role="bold">/rs_aix42/usr/lib</emphasis></entry>
1546             </row>
1547
1548             <row>
1549               <entry><emphasis role="bold">rs_aix42.usr.bin</emphasis></entry>
1550
1551               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1552               role="bold">/rs_aix42/usr/bin</emphasis></entry>
1553             </row>
1554
1555             <row>
1556               <entry><emphasis role="bold">rs_aix42.usr.etc</emphasis></entry>
1557
1558               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1559               role="bold">/rs_aix42/usr/etc</emphasis></entry>
1560             </row>
1561
1562             <row>
1563               <entry><emphasis role="bold">rs_aix42.usr.inc</emphasis></entry>
1564
1565               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1566               role="bold">/rs_aix42/usr/inc</emphasis></entry>
1567             </row>
1568
1569             <row>
1570               <entry><emphasis role="bold">rs_aix42.usr.man</emphasis></entry>
1571
1572               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1573               role="bold">/rs_aix42/usr/man</emphasis></entry>
1574             </row>
1575
1576             <row>
1577               <entry><emphasis role="bold">rs_aix42.usr.sys</emphasis></entry>
1578
1579               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1580               role="bold">/rs_aix42/usr/sys</emphasis></entry>
1581             </row>
1582
1583             <row>
1584               <entry><emphasis role="bold">rs_aix42.usr.local</emphasis></entry>
1585
1586               <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1587               role="bold">/rs_aix42/usr/local</emphasis></entry>
1588             </row>
1589           </tbody>
1590         </tgroup>
1591       </table>
1592
1593       <para>There are several advantages to this scheme: <itemizedlist>
1594           <listitem>
1595             <para>The volume name is similar to the mount point name in the filespace. In all of the entries in <link
1596             linkend="TBLPREFIX-EXAMPLE">Table 2</link>, for example, the only difference between the volume and mount point name is
1597             that the former uses periods as separators and the latter uses slashes. Another advantage is that the volume name
1598             indicates the contents, or at least suggests the directory on which to issue the <emphasis role="bold">ls</emphasis>
1599             command to learn the contents.</para>
1600           </listitem>
1601
1602           <listitem>
1603             <para>It makes it easy to manipulate groups of related volumes at one time. In particular, the <emphasis role="bold">vos
1604             backupsys</emphasis> command's <emphasis role="bold">-prefix</emphasis> argument enables you to create a backup version
1605             of every volume whose name starts with the same string of characters. Making a backup version of each volume is one of
1606             the first steps in backing up a volume with the AFS Backup System, and doing it for many volumes with one command saves
1607             you a good deal of typing. For instructions for creating backup volumes, see <link linkend="HDRWQ201">Creating Backup
1608             Volumes</link>, For information on the AFS Backup System, see <link linkend="HDRWQ248">Configuring the AFS Backup
1609             System</link> and <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
1610           </listitem>
1611
1612           <listitem>
1613             <para>It makes it easy to group related volumes together on a partition. Grouping related volumes together has several
1614             advantages of its own, discussed in <link linkend="HDRWQ49">Grouping Related Volumes on a Partition</link>.</para>
1615           </listitem>
1616         </itemizedlist></para>
1617
1618       <indexterm>
1619         <primary>volume</primary>
1620
1621         <secondary>grouping related on same partition</secondary>
1622       </indexterm>
1623
1624       <indexterm>
1625         <primary>disk partition</primary>
1626
1627         <secondary>grouping related volumes on</secondary>
1628       </indexterm>
1629     </sect2>
1630
1631     <sect2 id="HDRWQ49">
1632       <title>Grouping Related Volumes on a Partition</title>
1633
1634       <para>If your cell is large enough to make it practical, consider grouping related volumes together on a partition. In
1635       general, you need at least three file server machines for volume grouping to be effective. Grouping has several advantages,
1636       which are most obvious when the file server machine becomes inaccessible: <itemizedlist>
1637           <listitem>
1638             <para>If you keep a hardcopy record of the volumes on a partition, you know which volumes are unavailable. You can keep
1639             such a record without grouping related volumes, but a list composed of unrelated volumes is much harder to maintain.
1640             Note that the record must be on paper, because the outage can prevent you from accessing an online copy or from issuing
1641             the <emphasis role="bold">vos listvol</emphasis> command, which gives you the same information.</para>
1642           </listitem>
1643
1644           <listitem>
1645             <para>The effect of an outage is more localized. For example, if all of the binaries for a given system type are on one
1646             partition, then only users of that system type are affected. If a partition houses binary volumes from several system
1647             types, then an outage can affect more people, particularly if the binaries that remain available are interdependent with
1648             those that are not available.</para>
1649           </listitem>
1650         </itemizedlist></para>
1651
1652       <para>The advantages of grouping related volumes on a partition do not necessarily extend to the grouping of all related
1653       volumes on one file server machine. For instance, it is probably unwise in a cell with two file server machines to put all
1654       system volumes on one machine and all user volumes on the other. An outage of either machine probably affects everyone.</para>
1655
1656       <para>Admittedly, the need to move volumes for load balancing purposes can limit the practicality of grouping related volumes.
1657       You need to weigh the complementary advantages case by case.</para>
1658
1659       <indexterm>
1660         <primary>replication</primary>
1661
1662         <secondary>appropriate volumes</secondary>
1663       </indexterm>
1664
1665       <indexterm>
1666         <primary>volume</primary>
1667
1668         <secondary>type to replicate</secondary>
1669       </indexterm>
1670
1671       <indexterm>
1672         <primary>volume</primary>
1673
1674         <secondary>where to place replicated</secondary>
1675       </indexterm>
1676
1677       <indexterm>
1678         <primary>read-only volume</primary>
1679
1680         <secondary>selecting site</secondary>
1681       </indexterm>
1682     </sect2>
1683
1684     <sect2 id="HDRWQ50">
1685       <title>When to Replicate Volumes</title>
1686
1687       <para>As discussed in <link linkend="HDRWQ15">Replication</link>, replication refers to making a copy, or clone, of a
1688       read/write source volume and then placing the copy on one or more additional file server machines. Replicating a volume can
1689       increase the availability of the contents. If one file server machine housing the volume becomes inaccessible, users can still
1690       access the copy of the volume stored on a different machine. No one machine is likely to become overburdened with requests for
1691       a popular file, either, because the file is available from several machines.</para>
1692
1693       <para>However, replication is not appropriate for all cells. If a cell does not have much disk space, replication can be
1694       unduly expensive, because each clone not on the same partition as the read/write source takes up as much disk space as its
1695       source volume did at the time the clone was made. Also, if you have only one file server machine, replication uses up disk
1696       space without increasing availability.</para>
1697
1698       <para>Replication is also not appropriate for volumes that change frequently. You must issue the <emphasis role="bold">vos
1699       release</emphasis> command every time you need to update a read-only volume to reflect changes in its read/write
1700       source.</para>
1701
1702       <para>For both of these reasons, replication is appropriate only for popular volumes whose contents do not change very often,
1703       such as system binaries and other volumes mounted at the upper levels of your filespace. User volumes usually exist only in a
1704       read/write version since they change so often.</para>
1705
1706       <para>If you are replicating any volumes, you must replicate the <emphasis role="bold">root.afs</emphasis> and <emphasis
1707       role="bold">root.cell</emphasis> volumes, preferably at two or three sites each (even if your cell only has two or three file
1708       server machines). The Cache Manager needs to pass through the directories corresponding to the <emphasis
1709       role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes as it interprets any pathname. The
1710       unavailability of these volumes makes all other volumes unavailable too, even if the file server machines storing the other
1711       volumes are still functioning.</para>
1712
1713       <para>Another reason to replicate the <emphasis role="bold">root.afs</emphasis> volume is that it can lessen the load on the
1714       File Server machine. The Cache Manager has a bias to access a read-only version of the <emphasis
1715       role="bold">root.afs</emphasis> volume if it is replicate, which puts the Cache Manager onto the <emphasis>read-only
1716       path</emphasis> through the AFS filespace. While on the read-only path, the Cache Manager attempts to access a read-only copy
1717       of replicated volumes. The File Server needs to track only one callback per Cache Manager for all of the data in a read-only
1718       volume, rather than the one callback per file it must track for read/write volumes. Fewer callbacks translate into a smaller
1719       load on the File Server.</para>
1720
1721       <para>If the <emphasis role="bold">root.afs</emphasis> volume is not replicated, the Cache Manager follows a read/write path
1722       through the filespace, accessing the read/write version of each volume. The File Server distributes and tracks a separate
1723       callback for each file in a read/write volume, imposing a greater load on it.</para>
1724
1725       <para>For more on read/write and read-only paths, see <link linkend="HDRWQ209">The Rules of Mount Point
1726       Traversal</link>.</para>
1727
1728       <para>It also makes sense to replicate system binary volumes in many cases, as well as the volume corresponding to the
1729       <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis> directory and
1730       the volumes corresponding to the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1731       role="bold">/common</emphasis> directory and its subdirectories.</para>
1732
1733       <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
1734       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
1735       contents. Only if the read/write volume moves to another partition or changes substantially does the read-only volume consume
1736       significant disk space. Read-only volumes kept on other partitions always consume the full amount of disk space that the
1737       read/write source consumed when the read-only volume was created.</para>
1738     </sect2>
1739
1740     <sect2 id="Header_58">
1741       <title>The Default Quota and ACL on a New Volume</title>
1742
1743       <para>Every AFS volume has associated with it a quota that limits the amount of disk space the volume is allowed to use. To
1744       set and change quota, use the commands described in <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current
1745       Size</link>.</para>
1746
1747       <para>By default, every new volume is assigned a space quota of 5000 KB blocks unless you include the <emphasis
1748       role="bold">-maxquota</emphasis> argument to the <emphasis role="bold">vos create</emphasis> command. Also by default, the ACL
1749       on the root directory of every new volume grants all permissions to the members of the <emphasis
1750       role="bold">system:administrators</emphasis> group. To learn how to change these values when creating an account with
1751       individual commands, see <link linkend="HDRWQ503">To create one user account with individual commands</link>. When using
1752       <emphasis role="bold">uss</emphasis> commands to create accounts, you can specify alternate ACL and quota values in the
1753       template file's <emphasis role="bold">V</emphasis> instruction; see <link linkend="HDRWQ473">Creating a Volume with the V
1754       Instruction</link>.</para>
1755
1756       <indexterm>
1757         <primary>server machine</primary>
1758
1759         <secondary>configuration issues</secondary>
1760       </indexterm>
1761
1762       <indexterm>
1763         <primary>configuring</primary>
1764
1765         <secondary>file server machine, issues</secondary>
1766       </indexterm>
1767
1768       <indexterm>
1769         <primary>roles for server machine</primary>
1770
1771         <secondary>summary</secondary>
1772       </indexterm>
1773
1774       <indexterm>
1775         <primary>server machine</primary>
1776
1777         <secondary>roles for</secondary>
1778
1779         <tertiary>summary</tertiary>
1780       </indexterm>
1781
1782       <indexterm>
1783         <primary>server machine</primary>
1784
1785         <secondary>first installed</secondary>
1786       </indexterm>
1787     </sect2>
1788   </sect1>
1789
1790   <sect1 id="HDRWQ51">
1791     <title>Configuring Server Machines</title>
1792
1793     <para>This section discusses some issues to consider when configuring server machines, which store AFS data, transfer it to
1794     client machines on request, and house the AFS administrative databases. To learn about client machines, see <link
1795     linkend="HDRWQ54">Configuring Client Machines</link>.</para>
1796
1797     <para>If your cell has more than one AFS server machine, you can configure them to perform specialized functions. A machine can
1798     assume one or more of the roles described in the following list. For more details, see <link linkend="HDRWQ90">The Four Roles
1799     for File Server Machines</link>. <itemizedlist>
1800         <listitem>
1801           <para>A <emphasis>simple file server</emphasis> machine runs only the processes that store and deliver AFS files to client
1802           machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
1803           requirements.</para>
1804         </listitem>
1805
1806         <listitem>
1807           <para>A <emphasis>database server machine</emphasis> runs the four database server processes that maintain AFS's
1808           replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
1809           processes.</para>
1810         </listitem>
1811
1812         <listitem>
1813           <para>A <emphasis>binary distribution machine</emphasis> distributes the AFS server binaries for its system type to all
1814           other server machines of that system type.</para>
1815         </listitem>
1816
1817         <listitem>
1818           <para>The single <emphasis>system control machine</emphasis> distributes common server configuration files to all other
1819           server machines in the cell, in a cell that runs the United States edition of AFS (cells that use the international
1820           edition of AFS must not use the system control machine for this purpose). The machine conventionally also serves as the
1821           time synchronization source for the cell, adjusting its clock according to a time source outside the cell.</para>
1822         </listitem>
1823       </itemizedlist></para>
1824
1825     <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to configure your cell's first file server machine to
1826     assume all four roles. The <emphasis>OpenAFS Quick Beginnings</emphasis> chapter on installing additional server machines also
1827     explains how to configure them to perform one or more roles.</para>
1828
1829     <indexterm>
1830       <primary>database server machine</primary>
1831
1832       <secondary>reason to run three</secondary>
1833     </indexterm>
1834
1835     <indexterm>
1836       <primary>distribution</primary>
1837
1838       <secondary>of databases</secondary>
1839     </indexterm>
1840
1841     <indexterm>
1842       <primary>databases, distributed</primary>
1843     </indexterm>
1844
1845     <indexterm>
1846       <primary>distributed databases</primary>
1847     </indexterm>
1848
1849     <sect2 id="HDRWQ52">
1850       <title>Replicating the OpenAFS Administrative Databases</title>
1851
1852       <para>The AFS administrative databases are housed on database server machines and store information that is crucial for
1853       correct cell functioning. Both server processes and Cache Managers access the information frequently: <itemizedlist>
1854           <listitem>
1855             <para>Every time a Cache Manager fetches a file from a directory that it has not previously accessed, it must look up
1856             the file's location in the Volume Location Database (VLDB).</para>
1857           </listitem>
1858
1859           <listitem>
1860             <para>Every time a user obtains an AFS token from the Authentication Server, the server looks up the user's password in
1861             the Authentication Database.</para>
1862           </listitem>
1863
1864           <listitem>
1865             <para>The first time that a user accesses a volume housed on a specific file server machine, the File Server contacts
1866             the Protection Server for a list of the user's group memberships as recorded in the Protection Database.</para>
1867           </listitem>
1868
1869           <listitem>
1870             <para>Every time you back up a volume using the AFS Backup System, the Backup Server creates records for it in the
1871             Backup Database.</para>
1872           </listitem>
1873         </itemizedlist></para>
1874
1875       <para>Maintaining your cell is simplest if the first machine has the lowest IP address of any machine you plan to use as a
1876       database server machine. If you later decide to use a machine with a lower IP address as a database server machine, you must
1877       update the <emphasis role="bold">CellServDB</emphasis> file on all clients before introducing the new machine.</para>
1878
1879       <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
1880       than three are rarely necessary). Replicating the administrative databases in this way yields the same benefits as replicating
1881       volumes: increased availability and reliability. If one database server machine or process stops functioning, the information
1882       in the database is still available from others. The load of requests for database information is spread across multiple
1883       machines, preventing any one from becoming overloaded.</para>
1884
1885       <para>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
1886       that all copies of the database always be identical, so it is not acceptable to record changes in only some of them. To
1887       synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <link
1888       linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
1889
1890       <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
1891       server machines, it is not always advantageous to run both as database server machines. If a server, process, or network
1892       failure interrupts communications between the database server processes on the two machines, it can become impossible to
1893       update the information in the database because neither of them can alone elect itself as the synchronization site.</para>
1894
1895       <indexterm>
1896         <primary>server machine</primary>
1897
1898         <secondary>protecting directories on local disk</secondary>
1899       </indexterm>
1900
1901       <indexterm>
1902         <primary>local disk</primary>
1903
1904         <secondary>protecting on file server machine</secondary>
1905       </indexterm>
1906     </sect2>
1907
1908     <sect2 id="HDRWQ53">
1909       <title>AFS Files on the Local Disk</title>
1910
1911       <para>It is generally simplest to store the binaries for all AFS server processes in the <emphasis
1912       role="bold">/usr/afs/bin</emphasis> directory on every file server machine, even if some processes do not actively run on the
1913       machine. This makes it easier to reconfigure a machine to fill a new role.</para>
1914
1915       <para>For security reasons, the <emphasis role="bold">/usr/afs</emphasis> directory on a file server machine and all of its
1916       subdirectories and files must be owned by the local superuser <emphasis role="bold">root</emphasis> and have only the first
1917       <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit turned on. Some files even have only the
1918       first <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) mode bit turned on (for example, the
1919       <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file, which lists the AFS server encryption keys). Each time the BOS
1920       Server starts, it checks that the mode bits on certain files and directories match the expected values. For a list, see the
1921       <emphasis>OpenAFS Quick Beginnings</emphasis> section about protecting sensitive AFS directories, or the discussion of the
1922       output from the <emphasis role="bold">bos status</emphasis> command in <link linkend="HDRWQ159">To display the status of
1923       server processes and their BosConfig entries</link>.</para>
1924
1925       <para>For a description of the contents of all AFS directories on a file server machine's local disk, see <link
1926       linkend="HDRWQ80">Administering Server Machines</link>.</para>
1927     </sect2>
1928
1929     <sect2 id="Header_62">
1930       <title>Configuring Partitions to Store AFS Data</title>
1931
1932       <para>The partitions that house AFS volumes on a file server machine must be mounted at directories named</para>
1933
1934       <para><emphasis role="bold">/vicep</emphasis><emphasis>index</emphasis></para>
1935
1936       <para>where <emphasis>index</emphasis> is one or two lowercase letters. By convention, the first AFS partition created is
1937       mounted at the <emphasis role="bold">/vicepa</emphasis> directory, the second at the <emphasis role="bold">/vicepb</emphasis>
1938       directory, and so on through the <emphasis role="bold">/vicepz</emphasis> directory. The names then continue with <emphasis
1939       role="bold">/vicepaa</emphasis> through <emphasis role="bold">/vicepaz</emphasis>, <emphasis role="bold">/vicepba</emphasis>
1940       through <emphasis role="bold">/vicepbz</emphasis>, and so on, up to the maximum supported number of server partitions, which
1941       is specified in the OpenAFS Release Notes.</para>
1942
1943       <para>Each <emphasis role="bold">/vicep</emphasis>x directory must correspond to an entire partition or logical volume, and
1944       must be a subdirectory of the root directory (/). It is not acceptable to configure part of (for example) the <emphasis
1945       role="bold">/usr</emphasis> partition as an AFS server partition and mount it on a directory called <emphasis
1946       role="bold">/usr/vicepa</emphasis>.</para>
1947
1948       <para>Also, do not store non-AFS files on AFS server partitions. The File Server and Volume Server expect to have available
1949       all of the space on the partition. Sharing space also creates competition between AFS and the local UNIX file system for
1950       access to the partition, particularly if the UNIX files are frequently used.</para>
1951
1952       <indexterm>
1953         <primary>server machine</primary>
1954
1955         <secondary>monitoring</secondary>
1956       </indexterm>
1957
1958       <indexterm>
1959         <primary>file server machine</primary>
1960
1961         <secondary>rebooting, about</secondary>
1962       </indexterm>
1963
1964       <indexterm>
1965         <primary>rebooting</primary>
1966
1967         <secondary>file server machine, limiting</secondary>
1968       </indexterm>
1969
1970       <indexterm>
1971         <primary>weekly restart of BOS Server (automatic)</primary>
1972
1973         <secondary>about</secondary>
1974       </indexterm>
1975
1976       <indexterm>
1977         <primary>restart times for BOS Server</primary>
1978
1979         <secondary>about</secondary>
1980       </indexterm>
1981     </sect2>
1982
1983     <sect2 id="Header_63">
1984       <title>Monitoring, Rebooting and Automatic Process Restarts</title>
1985
1986       <para>AFS provides several tools for monitoring the File Server, including the <emphasis role="bold">scout</emphasis> and
1987       <emphasis role="bold">afsmonitor</emphasis> programs. You can configure them to alert you when certain threshold values are
1988       exceeded, for example when a server partition is more than 95% full. See <link linkend="HDRWQ323">Monitoring and Auditing AFS
1989       Performance</link>.</para>
1990
1991       <para>Rebooting a file server machine requires shutting down the AFS processes and so inevitably causes a service outage.
1992       Reboot file server machines as infrequently as possible. For instructions, see <link linkend="HDRWQ139">Rebooting a Server
1993       Machine</link>.</para>
1994
1995       <para>By default, the BOS Server on each file server machine stops and immediately restarts all AFS server processes on the
1996       machine (including itself) once a week, at 4:00 a.m. on Sunday. This reduces the potential for the core leaks that can develop
1997       as any process runs for an extended time.</para>
1998
1999       <para>The BOS Server also checks each morning at 5:00 a.m. for any newly installed binary files in the <emphasis
2000       role="bold">/usr/afs/bin</emphasis> directory. It compares the timestamp on each binary file to the time at which the
2001       corresponding process last restarted. If the timestamp on the binary is later, the BOS Server restarts the corresponding
2002       process to start using it.</para>
2003
2004       <para>The default times are in the early morning hours when the outage that results from restarting a process is likely to
2005       disturb the fewest number of people. You can display the restart times for each machine with the <emphasis role="bold">bos
2006       getrestart</emphasis> command, and set them with the <emphasis role="bold">bos setrestart</emphasis> command. The latter
2007       command enables you to disable automatic restarts entirely, by setting the time to <emphasis role="bold">never</emphasis>. See
2008       <link linkend="HDRWQ171">Setting the BOS Server's Restart Times</link>.</para>
2009
2010       <indexterm>
2011         <primary>client machine</primary>
2012
2013         <secondary>configuration issues</secondary>
2014       </indexterm>
2015
2016       <indexterm>
2017         <primary>configuring</primary>
2018
2019         <secondary>client machine, issues</secondary>
2020       </indexterm>
2021     </sect2>
2022   </sect1>
2023
2024   <sect1 id="HDRWQ54">
2025     <title>Configuring Client Machines</title>
2026
2027     <para>This section summarizes issues to consider as you install and configure client machines in your cell.</para>
2028
2029     <indexterm>
2030       <primary>client machine</primary>
2031
2032       <secondary>files required on local disk</secondary>
2033     </indexterm>
2034
2035     <indexterm>
2036       <primary>local disk</primary>
2037
2038       <secondary>files required on client machine</secondary>
2039     </indexterm>
2040
2041     <indexterm>
2042       <primary>file</primary>
2043
2044       <secondary>required on client machine local disk</secondary>
2045     </indexterm>
2046
2047     <sect2 id="HDRWQ55">
2048       <title>Configuring the Local Disk</title>
2049
2050       <para>You can often free up significant amounts of local disk space on AFS client machines by storing standard UNIX files in
2051       AFS and creating symbolic links to them from the local disk. The <emphasis role="bold">@sys</emphasis> pathname variable can
2052       be useful in links to system-specific files; see <link linkend="HDRWQ56">Using the @sys Variable in Pathnames</link>.</para>
2053
2054       <para>There are two types of files that must actually reside on the local disk: boot sequence files needed before the
2055       <emphasis role="bold">afsd</emphasis> program is invoked, and files that can be helpful during file server machine
2056       outages.</para>
2057
2058       <para>During a reboot, AFS is inaccessible until the <emphasis role="bold">afsd</emphasis> program executes and initializes
2059       the Cache Manager. (In the conventional configuration, the AFS initialization file is included in the machine's initialization
2060       sequence and invokes the <emphasis role="bold">afsd</emphasis> program.) Files needed during reboot prior to that point must
2061       reside on the local disk. They include the following, but this list is not necessarily exhaustive. <itemizedlist>
2062           <listitem>
2063             <para>Standard UNIX utilities including the following or their equivalents: <itemizedlist>
2064                 <listitem>
2065                   <para>Machine initialization files (stored in the <emphasis role="bold">/etc</emphasis> or <emphasis
2066                   role="bold">/sbin</emphasis> directory on many system types)</para>
2067                 </listitem>
2068
2069                 <listitem>
2070                   <para>The <emphasis role="bold">fstab</emphasis> file</para>
2071                 </listitem>
2072
2073                 <listitem>
2074                   <para>The <emphasis role="bold">mount</emphasis> command binary</para>
2075                 </listitem>
2076
2077                 <listitem>
2078                   <para>The <emphasis role="bold">umount</emphasis> command binary</para>
2079                 </listitem>
2080               </itemizedlist></para>
2081           </listitem>
2082
2083           <listitem>
2084             <para>All subdirectories and files in the <emphasis role="bold">/usr/vice</emphasis> directory, including the following:
2085             <itemizedlist>
2086                 <listitem>
2087                   <para>The <emphasis role="bold">/usr/vice/cache</emphasis> directory</para>
2088                 </listitem>
2089
2090                 <listitem>
2091                   <para>The <emphasis role="bold">/usr/vice/etc/afsd</emphasis> command binary</para>
2092                 </listitem>
2093
2094                 <listitem>
2095                   <para>The <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file</para>
2096                 </listitem>
2097
2098                 <listitem>
2099                   <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file</para>
2100                 </listitem>
2101
2102                 <listitem>
2103                   <para>The <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file</para>
2104                 </listitem>
2105               </itemizedlist></para>
2106
2107             <para>For more information on these files, see <link linkend="HDRWQ391">Configuration and Cache-Related Files on the
2108             Local Disk</link>.</para>
2109           </listitem>
2110         </itemizedlist></para>
2111
2112       <para>The other type of files and programs to retain on the local disk are those you need when diagnosing and fixing problems
2113       caused by a file server outage, because the outage can make inaccessible the copies stored in AFS. Examples include the
2114       binaries for a text editor (such as <emphasis role="bold">ed</emphasis> or <emphasis role="bold">vi</emphasis>) and for the
2115       <emphasis role="bold">fs</emphasis> and <emphasis role="bold">bos</emphasis> commands. Store copies of AFS command binaries in
2116       the <emphasis role="bold">/usr/vice/etc</emphasis> directory as well as including them in the <emphasis
2117       role="bold">/usr/afsws</emphasis> directory, which is normally a link into AFS. Then place the <emphasis
2118       role="bold">/usr/afsws</emphasis> directory before the <emphasis role="bold">/usr/vice/etc</emphasis> directory in users'
2119       <envar>PATH</envar> environment variable definition. When AFS is functioning normally, users access the copy in the <emphasis
2120       role="bold">/usr/afsws</emphasis> directory, which is more likely to be current than a local copy.</para>
2121
2122       <para>You can automate the configuration of client machine local disks by using the <emphasis role="bold">package</emphasis>
2123       program, which updates the contents of the local disk to match a configuration file. See <link linkend="HDRWQ419">Configuring
2124       Client Machines with the package Program</link>.</para>
2125     </sect2>
2126
2127     <sect2 id="Header_66">
2128       <title>Enabling Access to Foreign Cells</title>
2129
2130       <indexterm>
2131         <primary>client machine</primary>
2132
2133         <secondary>enabling access to foreign cell</secondary>
2134       </indexterm>
2135
2136       <para>As detailed in <link linkend="HDRWQ39">Making Other Cells Visible in Your Cell</link>, you enable the Cache Manager to
2137       access a cell's AFS filespace by storing a list of the cell's database server machines in the local <emphasis
2138       role="bold">/usr/vice/etc/CellServDB</emphasis> file. The Cache Manager reads the list into kernel memory at reboot for faster
2139       retrieval. You can change the list in kernel memory between reboots by using the <emphasis role="bold">fs newcell</emphasis>
2140       command. It is often practical to store a central version of the <emphasis role="bold">CellServDB</emphasis> file in AFS and
2141       use the <emphasis role="bold">package</emphasis> program periodically to update each client's version with the source copy.
2142       See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
2143
2144       <para>Because each client machine maintains its own copy of the <emphasis role="bold">CellServDB</emphasis> file, you can in
2145       theory enable access to different foreign cells on different client machines. This is not usually practical, however,
2146       especially if users do not always work on the same machine.</para>
2147
2148       <indexterm>
2149         <primary>at-sys (@sys) variable in pathnames</primary>
2150       </indexterm>
2151
2152       <indexterm>
2153         <primary>sys (@sys) variable in pathnames</primary>
2154       </indexterm>
2155
2156       <indexterm>
2157         <primary>variables</primary>
2158
2159         <secondary>@sys in pathnames</secondary>
2160       </indexterm>
2161     </sect2>
2162
2163     <sect2 id="HDRWQ56">
2164       <title>Using the @sys Variable in Pathnames</title>
2165
2166       <para>When creating symbolic links into AFS on the local disk, it is often practical to use the @sys variable in pathnames.
2167       The Cache Manager automatically substitutes the local machine's AFS system name (CPU/operating system type) for the @sys
2168       variable. This means you can place the same links on machines of various system types and still have each machine access the
2169       binaries for its system type. For example, the Cache Manager on a machine running AIX 4.2 converts <emphasis
2170       role="bold">/afs/abc.com/@sys</emphasis> to <emphasis role="bold">/afs/abc.com/rs_aix42</emphasis>, whereas a machine running
2171       Solaris 7 converts it to <emphasis role="bold">/afs/abc.com/sun4x_57</emphasis>.</para>
2172
2173       <para>If you want to use the @sys variable, it is simplest to use the conventional AFS system type names as specified in the
2174       OpenAFS Release Notes. The Cache Manager records the local machine's system type name in kernel memory during initialization.
2175       If you do not use the conventional names, you must use the <emphasis role="bold">fs sysname</emphasis> command to change the
2176       value in kernel memory from its default just after Cache Manager initialization, on every client machine of the relevant
2177       system type. The <emphasis role="bold">fs sysname</emphasis> command also displays the current value; see <link
2178       linkend="HDRWQ417">Displaying and Setting the System Type Name</link>.</para>
2179
2180       <para>In pathnames in the AFS filespace itself, use the @sys variable carefully and sparingly, because it can lead to
2181       unexpected results. It is generally best to restrict its use to only one level in the filespace. The third level is a common
2182       choice, because that is where many cells store the binaries for different machine types.</para>
2183
2184       <para>Multiple instances of the @sys variable in a pathname are especially dangerous to people who must explicitly change
2185       directories (with the <emphasis role="bold">cd</emphasis> command, for example) into directories that store binaries for
2186       system types other than the machine on which they are working, such as administrators or developers who maintain those
2187       directories. After changing directories, it is recommended that such people verify they are in the desired directory.</para>
2188     </sect2>
2189
2190     <sect2 id="Header_68">
2191       <title>Setting Server Preferences</title>
2192
2193       <para>The Cache Manager stores a table of preferences for file server machines in kernel memory. A preference rank pairs a
2194       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
2195       Cache Manager compares the ranks for the interfaces of all machines that house the file, and first attempts to access the file
2196       via the interface with the best rank. As it initializes, the Cache Manager sets default ranks that bias it to access files via
2197       interfaces that are close to it in terms of network topology. You can adjust the preference ranks to improve performance if
2198       you wish.</para>
2199
2200       <para>The Cache Manager also uses similar preferences for Volume Location (VL) Server machines. Use the <emphasis
2201       role="bold">fs getserverprefs</emphasis> command to display preference ranks and the <emphasis role="bold">fs
2202       setserverprefs</emphasis> command to set them. See <link linkend="HDRWQ414">Maintaining Server Preference Ranks</link>.</para>
2203
2204       <indexterm>
2205         <primary>user account</primary>
2206
2207         <secondary>configuration issues</secondary>
2208       </indexterm>
2209     </sect2>
2210   </sect1>
2211
2212   <sect1 id="HDRWQ57">
2213     <title>Configuring AFS User Accounts</title>
2214
2215     <para>This section discusses some of the issues to consider when configuring AFS user accounts. Because AFS is separate from the
2216     UNIX file system, a user's AFS account is separate from her UNIX account.</para>
2217
2218     <para>The preferred method for creating a user account is with the <emphasis role="bold">uss</emphasis> suite of commands. With
2219     a single command, you can create all the components of one or many accounts, after you have prepared a template file that guides
2220     the account creation. See <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>.</para>
2221
2222     <para>Alternatively, you can issue the individual commands that create each component of an account. For instructions, along
2223     with instructions for removing user accounts and changing user passwords, user volume quotas and usernames, see <link
2224     linkend="HDRWQ491">Administering User Accounts</link>.</para>
2225
2226     <para>When users leave your system, it is often good policy to remove their accounts. Instructions appear in <link
2227     linkend="HDRWQ486">Deleting Individual Accounts with the uss delete Command</link> and <link linkend="HDRWQ524">Removing a User
2228     Account</link>.</para>
2229
2230     <para>An AFS user account consists of the following components, which are described in greater detail in <link
2231     linkend="HDRWQ494">The Components of an AFS User Account</link>. <itemizedlist>
2232         <listitem>
2233           <para>A Protection Database entry</para>
2234         </listitem>
2235
2236         <listitem>
2237           <para>An Authentication Database entry</para>
2238         </listitem>
2239
2240         <listitem>
2241           <para>A volume</para>
2242         </listitem>
2243
2244         <listitem>
2245           <para>A home directory at which the volume is mounted</para>
2246         </listitem>
2247
2248         <listitem>
2249           <para>Ownership of the home directory and full permissions on its ACL</para>
2250         </listitem>
2251
2252         <listitem>
2253           <para>An entry in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of each machine the
2254           user needs to log into</para>
2255         </listitem>
2256
2257         <listitem>
2258           <para>Optionally, standard files and subdirectories that make the account more useful</para>
2259         </listitem>
2260       </itemizedlist></para>
2261
2262     <para>By creating some components but not others, you can create accounts at different levels of functionality, using either
2263     <emphasis role="bold">uss</emphasis> commands as described in <link linkend="HDRWQ449">Creating and Deleting User Accounts with
2264     the uss Command Suite</link> or individual commands as described in <link linkend="HDRWQ491">Administering User Accounts</link>.
2265     The levels of functionality include the following <itemizedlist>
2266         <listitem>
2267           <para>An authentication-only account enables the user to obtain AFS tokens and so to access protected AFS data and to
2268           issue privileged commands. It consists only of entries in the Authentication and Protection Database. This type of account
2269           is suitable for administrative accounts and for users from foreign cells who need to access protected data. Local users
2270           generally also need a volume and home directory.</para>
2271         </listitem>
2272
2273         <listitem>
2274           <para>A basic user account includes a volume for the user, in addition to Authentication and Protection Database entries.
2275           The volume is mounted in the AFS filespace as the user's home directory, and provides a repository for the user's personal
2276           files.</para>
2277         </listitem>
2278
2279         <listitem>
2280           <para>A full account adds configuration files for basic functions such as logging in, printing, and mail delivery to a
2281           basic account, making it more convenient and useful. For a discussion of some useful types of configuration files, see
2282           <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>.</para>
2283         </listitem>
2284       </itemizedlist></para>
2285
2286     <para>If your users have UNIX user accounts that predate the introduction of AFS in the cell, you possibly want to convert them
2287     into AFS accounts. There are three main issues to consider: <itemizedlist>
2288         <listitem>
2289           <para>Making UNIX and AFS UIDs match</para>
2290         </listitem>
2291
2292         <listitem>
2293           <para>Setting the password field in the local password file appropriately</para>
2294         </listitem>
2295
2296         <listitem>
2297           <para>Moving files from the UNIX file system into AFS</para>
2298         </listitem>
2299       </itemizedlist></para>
2300
2301     <para>For further discussion, see <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link> or <link
2302     linkend="HDRWQ498">Converting Existing UNIX Accounts</link>.</para>
2303
2304     <indexterm>
2305       <primary>username</primary>
2306
2307       <secondary>choosing</secondary>
2308     </indexterm>
2309
2310     <indexterm>
2311       <primary>user</primary>
2312
2313       <secondary>name</secondary>
2314
2315       <see>username</see>
2316     </indexterm>
2317
2318     <indexterm>
2319       <primary>choosing</primary>
2320
2321       <secondary>name</secondary>
2322
2323       <tertiary>user</tertiary>
2324     </indexterm>
2325
2326     <indexterm>
2327       <primary>anonymous user</primary>
2328
2329       <secondary>AFS UID reserved</secondary>
2330     </indexterm>
2331
2332     <indexterm>
2333       <primary>AFS UID</primary>
2334
2335       <secondary>reserved</secondary>
2336
2337       <tertiary>anonymous user</tertiary>
2338     </indexterm>
2339
2340     <sect2 id="HDRWQ58">
2341       <title>Choosing Usernames and Naming Other Account Components</title>
2342
2343       <para>This section suggests schemes for choosing usernames, AFS UIDs, user volume names and mount point names, and also
2344       outlines some restrictions on your choices.</para>
2345
2346       <formalpara>
2347         <title>Usernames</title>
2348
2349         <para>AFS imposes very few restrictions on the form of usernames. It is best to keep usernames short, both because many
2350         utilities and applications can handle usernames of no more than eight characters and because by convention many components
2351         of and AFS account incorporate the name. These include the entries in the Protection and Authentication Databases, the
2352         volume, and the mount point. Depending on your electronic mail delivery system, the username can become part of the user's
2353         mailing address. The username is also the string that the user types when logging in to a client machine.</para>
2354       </formalpara>
2355
2356       <para>Some common choices for usernames are last names, first names, initials, or a combination, with numbers sometimes added.
2357       It is also best to avoid using the following characters, many of which have special meanings to the command shell.
2358       <itemizedlist>
2359           <listitem>
2360             <para>The comma (<emphasis role="bold">,</emphasis>)</para>
2361           </listitem>
2362
2363           <listitem>
2364             <para>The colon (<emphasis role="bold">:</emphasis>), because AFS reserves it as a field separator in protection group
2365             names; see <link linkend="HDRWQ62">The Two Types of User-Defined Groups</link></para>
2366           </listitem>
2367
2368           <listitem>
2369             <para>The semicolon (<emphasis role="bold">;</emphasis>)</para>
2370           </listitem>
2371
2372           <listitem>
2373             <para>The "at-sign" (<emphasis role="bold">@</emphasis>); this character is reserved for Internet mailing
2374             addresses</para>
2375           </listitem>
2376
2377           <listitem>
2378             <para>Spaces</para>
2379           </listitem>
2380
2381           <listitem>
2382             <para>The newline character</para>
2383           </listitem>
2384
2385           <listitem>
2386             <para>The period (<emphasis role="bold">.</emphasis>); it is conventional to use this character only in the special
2387             username that an administrator adopts while performing privileged tasks, such as <emphasis
2388             role="bold">pat.admin</emphasis></para>
2389           </listitem>
2390         </itemizedlist></para>
2391
2392       <formalpara>
2393         <title>AFS UIDs and UNIX UIDs</title>
2394
2395         <para>AFS associates a unique identification number, the AFS UID, with every username, recording the mapping in the user's
2396         Protection Database entry. The AFS UID functions within AFS much as the UNIX UID does in the local file system: the AFS
2397         server processes and the Cache Manager use it internally to identify a user, rather than the username.</para>
2398       </formalpara>
2399
2400       <para>Every AFS user also must have a UNIX UID recorded in the local password file (<emphasis
2401       role="bold">/etc/passwd</emphasis> or equivalent) of each client machine they log onto. Both administration and a user's AFS
2402       access are simplest if the AFS UID and UNIX UID match. One important consequence of matching UIDs is that the owner reported
2403       by the <emphasis role="bold">ls -l</emphasis> command matches the AFS username.</para>
2404
2405       <para>It is usually best to allow the Protection Server to allocate the AFS UID as it creates the Protection Database entry.
2406       However, both the <emphasis role="bold">pts createuser</emphasis> command and the <emphasis role="bold">uss</emphasis>
2407       commands that create user accounts enable you to assign AFS UIDs explicitly. This is appropriate in two cases: <itemizedlist>
2408           <listitem>
2409             <para>You wish to group together the AFS UIDs of related users</para>
2410           </listitem>
2411
2412           <listitem>
2413             <para>You are converting an existing UNIX account into an AFS account and want to make the AFS UID match the existing
2414             UNIX UID</para>
2415           </listitem>
2416         </itemizedlist></para>
2417
2418       <para>After the Protection Server initializes for the first time on a cell's first file server machine, it starts assigning
2419       AFS UIDs at a default value. To change the default before creating any user accounts, or at any time, use the <emphasis
2420       role="bold">pts setmax</emphasis> command to reset the <computeroutput>max user id counter</computeroutput>. To display the
2421       counter, use the <emphasis role="bold">pts listmax</emphasis> command. See <link linkend="HDRWQ560">Displaying and Setting the
2422       AFS UID and GID Counters</link>.</para>
2423
2424       <para>AFS reserves one AFS UID, 32766, for the user <emphasis role="bold">anonymous</emphasis>. The AFS server processes
2425       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
2426       any other user or hardcode its current value into any programs or a file's owner field, because it is subject to change in
2427       future releases.</para>
2428
2429       <indexterm>
2430         <primary>username</primary>
2431
2432         <secondary>part of volume name</secondary>
2433       </indexterm>
2434
2435       <indexterm>
2436         <primary>choosing</primary>
2437
2438         <secondary>name</secondary>
2439
2440         <tertiary>user volume</tertiary>
2441       </indexterm>
2442
2443       <formalpara>
2444         <title>User Volume Names</title>
2445
2446         <para>Like any volume name, a user volume's base (read/write) name cannot exceed 22 characters in length or include the
2447         <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension. See <link
2448         linkend="HDRWQ44">Creating Volumes to Simplify Administration</link>. By convention, user volume names have the format
2449         <emphasis role="bold">user.</emphasis>username. Using the <emphasis role="bold">user.</emphasis> prefix not only makes it
2450         easy to identify the volume's contents, but also to create a backup version of all user volumes by issuing a single
2451         <emphasis role="bold">vos backupsys</emphasis> command.</para>
2452       </formalpara>
2453
2454       <indexterm>
2455         <primary>mount point</primary>
2456
2457         <secondary>choosing name for user volume</secondary>
2458       </indexterm>
2459
2460       <indexterm>
2461         <primary>choosing</primary>
2462
2463         <secondary>name</secondary>
2464
2465         <tertiary>user volume mount point</tertiary>
2466       </indexterm>
2467
2468       <formalpara>
2469         <title>Mount Point Names</title>
2470
2471         <para>By convention, the mount point for a user's volume is named after the username. Many cells follow the convention of
2472         mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2473         role="bold">/usr</emphasis> directory, as discussed in <link linkend="HDRWQ43">The Third Level</link>. Very large cells
2474         sometimes find that mounting all user volumes in the same directory slows directory lookup, however; for suggested
2475         alternatives, see the following section.</para>
2476       </formalpara>
2477
2478       <indexterm>
2479         <primary>directories</primary>
2480
2481         <secondary>for grouping user home directories</secondary>
2482       </indexterm>
2483
2484       <indexterm>
2485         <primary>user account</primary>
2486
2487         <secondary>suggestions for grouping home directories</secondary>
2488       </indexterm>
2489     </sect2>
2490
2491     <sect2 id="HDRWQ59">
2492       <title>Grouping Home Directories</title>
2493
2494       <para>Mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2495       role="bold">/usr</emphasis> directory is an AFS-appropriate variation on the standard UNIX practice of putting user home
2496       directories under the <emphasis role="bold">/usr</emphasis> subdirectory. However, cells with more than a few hundred users
2497       sometimes find that mounting all user volumes in a single directory results in slow directory lookup. The solution is to
2498       distribute user volume mount points into several directories; there are a number of alternative methods to accomplish this.
2499       <itemizedlist>
2500           <listitem>
2501             <para>Distribute user home directories into multiple directories that reflect organizational divisions, such as academic
2502             or corporate departments. For example, a company can create group directories called <emphasis
2503             role="bold">usr/marketing</emphasis>, <emphasis role="bold">usr/research</emphasis>, <emphasis
2504             role="bold">usr/finance</emphasis>. A good feature of this scheme is that knowing a user's department is enough to find
2505             the user's home directory. Also, it makes it easy to set the ACL to limit access to members of the department only. A
2506             potential drawback arises if departments are of sufficiently unequal size that users in large departments experience
2507             slower lookup than users in small departments. This scheme is also not appropriate in cells where users frequently
2508             change between divisions.</para>
2509           </listitem>
2510
2511           <listitem>
2512             <para>Distribute home directories into alphabetic subdirectories of the <emphasis role="bold">usr</emphasis> directory
2513             (the <emphasis role="bold">usr/a</emphasis> subdirectory, the <emphasis role="bold">usr/b</emphasis> subdirectory, and
2514             so on), based on the first letter of the username. If the cell is very large, create subdirectories under each letter
2515             that correspond to the second letter in the user name. This scheme has the same advantages and disadvantages of a
2516             department-based scheme. Anyone who knows the user's username can find the user's home directory, but users with names
2517             that begin with popular letters sometimes experience slower lookup.</para>
2518           </listitem>
2519
2520           <listitem>
2521             <para>Distribute home directories randomly but evenly into more than one grouping directory. One cell that uses this
2522             scheme has over twenty such directories called the <emphasis role="bold">usr1</emphasis> directory, the <emphasis
2523             role="bold">usr2</emphasis> directory, and so on. This scheme is especially appropriate in cells where the other two
2524             schemes do not seem feasible. It eliminates the potential problem of differences in lookup speed, because all
2525             directories are about the same size. Its disadvantage is that there is no way to guess which directory a given user's
2526             volume is mounted in, but a solution is to create a symbolic link in the regular <emphasis role="bold">usr</emphasis>
2527             directory that references the actual mount point. For example, if user <emphasis role="bold">smith</emphasis>'s volume
2528             is mounted at the <emphasis role="bold">/afs/bigcell.com/usr17/smith</emphasis> directory, then the <emphasis
2529             role="bold">/afs/bigcell.com/usr/smith</emphasis> directory is a symbolic link to the <emphasis
2530             role="bold">../usr17/smith</emphasis> directory. This way, if someone does not know which directory the user <emphasis
2531             role="bold">smith</emphasis> is in, he or she can access it through the link called <emphasis
2532             role="bold">usr/smith</emphasis>; people who do know the appropriate directory save lookup time by specifying it.</para>
2533           </listitem>
2534         </itemizedlist></para>
2535
2536       <para>For instructions on how to implement the various schemes when using the <emphasis role="bold">uss</emphasis> program to
2537       create user accounts, see <link linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link> and
2538       <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
2539     </sect2>
2540
2541     <sect2 id="Header_72">
2542       <title>Making a Backup Version of User Volumes Available</title>
2543
2544       <para>Mounting the backup version of a user's volume is a simple way to enable users themselves to restore data they have
2545       accidentally removed or deleted. It is conventional to mount the backup version at a subdirectory of the user's home directory
2546       (called perhaps the <emphasis role="bold">OldFiles</emphasis> subdirectory), but other schemes are possible. Once per day you
2547       create a new backup version to capture the changes made that day, overwriting the previous day's backup version with the new
2548       one. Users can always retrieve the previous day's copy of a file without your assistance, freeing you to deal with more
2549       pressing tasks.</para>
2550
2551       <para>Users sometimes want to delete the mount point to their backup volume, because they erroneously believe that the backup
2552       volume's contents count against their quota. Remind them that the backup volume is separate, so the only space it uses in the
2553       user volume is the amount needed for the mount point.</para>
2554
2555       <para>For further discussion of backup volumes, see <link linkend="HDRWQ77">Backing Up AFS Data</link> and <link
2556       linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
2557
2558       <indexterm>
2559         <primary>file</primary>
2560
2561         <secondary>creating standard ones in new user account</secondary>
2562       </indexterm>
2563
2564       <indexterm>
2565         <primary>user account</primary>
2566
2567         <secondary>creating</secondary>
2568
2569         <tertiary>standard files in</tertiary>
2570       </indexterm>
2571
2572       <indexterm>
2573         <primary>creating</primary>
2574
2575         <secondary>standard files in new user account</secondary>
2576       </indexterm>
2577     </sect2>
2578
2579     <sect2 id="HDRWQ60">
2580       <title>Creating Standard Files in New AFS Accounts</title>
2581
2582       <para>From your experience as a UNIX administrator, you are probably familiar with the use of login and shell initialization
2583       files (such as the <emphasis role="bold">.login</emphasis> and <emphasis role="bold">.cshrc</emphasis> files) to make an
2584       account easier to use.</para>
2585
2586       <para>It is often practical to add some AFS-specific directories to the definition of the user's <envar>PATH</envar>
2587       environment variable, including the following: <itemizedlist>
2588           <listitem>
2589             <para>The path to a <emphasis role="bold">bin</emphasis> subdirectory in the user's home directory for binaries the user
2590             has created (that is, <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2591             role="bold">/usr/</emphasis><replaceable>username</replaceable><emphasis role="bold">/bin</emphasis>)</para>
2592           </listitem>
2593
2594           <listitem>
2595             <para>The <emphasis role="bold">/usr/afsws/bin</emphasis> path, which conventionally includes programs like <emphasis
2596             role="bold">fs</emphasis>, <emphasis role="bold">klog</emphasis>, <emphasis role="bold">kpasswd</emphasis>, <emphasis
2597             role="bold">pts</emphasis>, <emphasis role="bold">tokens</emphasis>, and <emphasis role="bold">unlog</emphasis></para>
2598           </listitem>
2599
2600           <listitem>
2601             <para>The <emphasis role="bold">/usr/afsws/etc</emphasis> path, if the user is an administrator; it usually houses the
2602             AFS command suites that require privilege (the <emphasis role="bold">backup</emphasis>, <emphasis
2603             role="bold">butc</emphasis>, <emphasis role="bold">kas</emphasis>, <emphasis role="bold">uss</emphasis>, <emphasis
2604             role="bold">vos</emphasis> commands), the <emphasis role="bold">package</emphasis> program, and others</para>
2605           </listitem>
2606         </itemizedlist></para>
2607
2608       <para>If you are not using an AFS-modified login utility, it can be helpful to users to invoke the <emphasis
2609       role="bold">klog</emphasis> command in their <emphasis role="bold">.login</emphasis> file so that they obtain AFS tokens as
2610       part of logging in. In the following example command sequence, the first line echoes the string
2611       <computeroutput>klog</computeroutput> to the standard output stream, so that the user understands the purpose of the
2612       <computeroutput>Password:</computeroutput> prompt that appears when the second line is executed. The <emphasis
2613       role="bold">-setpag</emphasis> flag associates the new tokens with a process authentication group (PAG), which is discussed
2614       further in <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
2615
2616       <programlisting>
2617    echo -n "klog "
2618    klog -setpag
2619 </programlisting>
2620
2621       <para>The following sequence of commands has a similar effect, except that the <emphasis role="bold">pagsh</emphasis> command
2622       forks a new shell with which the PAG and tokens are associated.</para>
2623
2624       <programlisting>
2625    pagsh
2626    echo -n "klog "
2627    klog
2628 </programlisting>
2629
2630       <para>If you use an AFS-modified login utility, this sequence is not necessary, because such utilities both log a user in
2631       locally and obtain AFS tokens.</para>
2632
2633       <indexterm>
2634         <primary>group</primary>
2635
2636         <secondary>AFS GID</secondary>
2637       </indexterm>
2638
2639       <indexterm>
2640         <primary>group</primary>
2641
2642         <secondary>restrictions</secondary>
2643       </indexterm>
2644
2645       <indexterm>
2646         <primary>group</primary>
2647
2648         <secondary>privacy flags</secondary>
2649       </indexterm>
2650
2651       <indexterm>
2652         <primary>privacy flags on Protection Database entry</primary>
2653       </indexterm>
2654     </sect2>
2655   </sect1>
2656
2657   <sect1 id="HDRWQ61">
2658     <title>Using AFS Protection Groups</title>
2659
2660     <para>AFS enables users to define their own groups of other users or machines. The groups are placed on ACLs to grant the same
2661     permissions to many users without listing each user individually. For group creation instructions, see <link
2662     linkend="HDRWQ531">Administering the Protection Database</link>.</para>
2663
2664     <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
2665     a positive integer. By default, the Protection Server allocates a new group's AFS GID automatically, but members of the
2666     <emphasis role="bold">system:administrators</emphasis> group can assign a GID when issuing the <emphasis role="bold">pts
2667     creategroup</emphasis> command. Before explicitly assigning a GID, it is best to verify that it is not already in use.</para>
2668
2669     <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
2670     at least one member. The current owner of a group can transfer ownership of the group to another user or group, even without the
2671     new owner's permission. At that point the former owner loses administrative control over the group.</para>
2672
2673     <para>By default, each user can create 20 groups. A system administrator can increase or decrease this group creation quota with
2674     the <emphasis role="bold">pts setfields</emphasis> command.</para>
2675
2676     <para>Each Protection Database entry (group or user) is protected by a set of five privacy flagswhich limit who can administer
2677     the entry and what they can do. The default privacy flags are fairly restrictive, especially for user entries. See <link
2678     linkend="HDRWQ559">Setting the Privacy Flags on Database Entries</link>.</para>
2679
2680     <indexterm>
2681       <primary>system:administrators group</primary>
2682
2683       <secondary>about</secondary>
2684     </indexterm>
2685
2686     <indexterm>
2687       <primary>system:anyuser group</primary>
2688
2689       <secondary>about</secondary>
2690     </indexterm>
2691
2692     <indexterm>
2693       <primary>system:authuser group</primary>
2694
2695       <secondary>about</secondary>
2696     </indexterm>
2697
2698     <indexterm>
2699       <primary>group</primary>
2700
2701       <secondary>system-defined</secondary>
2702     </indexterm>
2703
2704     <sect2 id="Header_75">
2705       <title>The Three System Groups</title>
2706
2707       <para>As the Protection Server initializes for the first time on a cell's first database server machine, it automatically
2708       creates three group entries: the <emphasis role="bold">system:anyuser</emphasis>, <emphasis
2709       role="bold">system:authuser</emphasis>, and <emphasis role="bold">system:administrators</emphasis> groups.</para>
2710
2711       <indexterm>
2712         <primary>AFS UID</primary>
2713
2714         <secondary>reserved</secondary>
2715
2716         <tertiary>system-defined groups</tertiary>
2717       </indexterm>
2718
2719       <para>The first two system groups are unlike any other groups in the Protection Database in that they do not have a stable
2720       membership: <itemizedlist>
2721           <listitem>
2722             <para>The <emphasis role="bold">system:anyuser</emphasis> group includes everyone who can access a cell's AFS filespace:
2723             users who have tokens for the local cell, users who have logged in on a local AFS client machine but not obtained tokens
2724             (such as the local superuser <emphasis role="bold">root</emphasis>), and users who have connected to a local machine
2725             from outside the cell. Placing the <emphasis role="bold">system:anyuser</emphasis> group on an ACL grants access to the
2726             widest possible range of users. It is the only way to extend access to users from foreign AFS cells that do not have
2727             local accounts.</para>
2728           </listitem>
2729
2730           <listitem>
2731             <para>The <emphasis role="bold">system:authuser</emphasis> group includes everyone who has a valid token obtained from
2732             the cell's AFS authentication service.</para>
2733           </listitem>
2734         </itemizedlist></para>
2735
2736       <para>Because the groups do not have a stable membership, the <emphasis role="bold">pts membership</emphasis> command produces
2737       no output for them. Similarly, they do not appear in the list of groups to which a user belongs.</para>
2738
2739       <para>The <emphasis role="bold">system:administrators</emphasis> group does have a stable membership, consisting of the cell's
2740       privileged administrators. Members of this group can issue any <emphasis role="bold">pts</emphasis> command, and are the only
2741       ones who can issue several other restricted commands (such as the <emphasis role="bold">chown</emphasis> command on AFS
2742       files). By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
2743       role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
2744       permissions on every ACL in the filespace. For information about changing this default, see <link
2745       linkend="HDRWQ586">Administering the system:administrators Group</link>.</para>
2746
2747       <para>For a discussion of how to use system groups effectively on ACLs, see <link linkend="HDRWQ571">Using Groups on
2748       ACLs</link>.</para>
2749     </sect2>
2750
2751     <sect2 id="HDRWQ62">
2752       <title>The Two Types of User-Defined Groups</title>
2753
2754       <para>All users can create regular groups. A regular group name has two fields separated by a colon, the first of which must
2755       indicate the group's ownership. The Protection Server refuses to create or change the name of a group if the result does not
2756       accurately indicate the ownership.</para>
2757
2758       <para>Members of the <emphasis role="bold">system:administrators</emphasis> group can create prefix-less groups whose names do
2759       not have the first field that indicates ownership. For suggestions on using the two types of groups effectively, see <link
2760       linkend="HDRWQ545">Using Groups Effectively</link>.</para>
2761
2762       <indexterm>
2763         <primary>authentication</primary>
2764
2765         <secondary>AFS separate from UNIX</secondary>
2766       </indexterm>
2767
2768       <indexterm>
2769         <primary>AFS</primary>
2770
2771         <secondary>authentication separate from UNIX</secondary>
2772       </indexterm>
2773     </sect2>
2774   </sect1>
2775
2776   <sect1 id="HDRWQ63">
2777     <title>Login and Authentication in AFS</title>
2778
2779     <para>As explained in <link linkend="HDRWQ31">Differences in Authentication</link>, AFS authentication is separate from UNIX
2780     authentication because the two file systems are separate. The separation has two practical implications: <itemizedlist>
2781         <listitem>
2782           <para>To access AFS files, users must both log into the local file system and authenticate with the AFS authentication
2783           service. (Logging into the local file system is necessary because the only way to access the AFS filespace is through a
2784           Cache Manager, which resides in the local machine's kernel.)</para>
2785         </listitem>
2786
2787         <listitem>
2788           <para>Passwords are stored in two separate places: in the Kerberos Database for AFS and in the each machine's local
2789           password file (the <emphasis role="bold">/etc/passwd</emphasis> file or equivalent) for the local file system.</para>
2790         </listitem>
2791       </itemizedlist></para>
2792
2793     <para>When a user successfully authenticates, the AFS authentication service passes a token to the user's Cache Manager. The
2794     token is a small collection of data that certifies that the user has correctly provided the password associated with a
2795     particular AFS identity. The Cache Manager presents the token to AFS server processes along with service requests, as proof that
2796     the user is genuine. To learn about the mutual authentication procedure they use to establish identity, see <link
2797     linkend="HDRWQ75">A More Detailed Look at Mutual Authentication</link>.</para>
2798
2799     <para>The Cache Manager stores tokens in the user's credential structure in kernel memory. To distinguish one user's credential
2800     structure from another's, the Cache Manager identifies each one either by the user's UNIX UID or by a process authentication
2801     group (PAG), which is an identification number guaranteed to be unique in the cell. For further discussion, see <link
2802     linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
2803
2804     <indexterm>
2805       <primary>tokens</primary>
2806
2807       <secondary>one-per-cell rule</secondary>
2808     </indexterm>
2809
2810     <para>A user can have only one token per cell in each separately identified credential structure. To obtain a second token for
2811     the same cell, the user must either log into a different machine or obtain another credential structure with a different
2812     identifier than any existing credential structure, which is most easily accomplished by issuing the <emphasis
2813     role="bold">pagsh</emphasis> command (see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>). In a single credential
2814     structure, a user can have one token for each of many cells at the same time. As this implies, authentication status on one
2815     machine or PAG is independent of authentication status on another machine or PAG, which can be very useful to a user or system
2816     administrator.</para>
2817
2818     <para>The AFS distribution includes library files that enable each system type's login utility to authenticate users with AFS
2819     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,
2820     its users must issue the <emphasis role="bold">klog</emphasis> command to authenticate with AFS after logging in.</para>
2821
2822     <note>
2823       <para>The AFS-modified libraries do not necessarily support all features available in an operating system's proprietary login
2824       utility. In some cases, it is not possible to support a utility at all. For more information about the supported utilities in
2825       each AFS version, see the OpenAFS Release Notes.</para>
2826     </note>
2827
2828     <indexterm>
2829       <primary>commands</primary>
2830
2831       <secondary>pagsh</secondary>
2832     </indexterm>
2833
2834     <indexterm>
2835       <primary>pagsh command</primary>
2836     </indexterm>
2837
2838     <indexterm>
2839       <primary>commands</primary>
2840
2841       <secondary>klog with -setpag flag</secondary>
2842     </indexterm>
2843
2844     <indexterm>
2845       <primary>klog command</primary>
2846
2847       <secondary>with -setpag flag</secondary>
2848     </indexterm>
2849
2850     <indexterm>
2851       <primary>PAG</primary>
2852
2853       <secondary>creating with klog or pagsh command</secondary>
2854     </indexterm>
2855
2856     <indexterm>
2857       <primary>creating</primary>
2858
2859       <secondary>PAG with klog or pagsh command</secondary>
2860     </indexterm>
2861
2862     <indexterm>
2863       <primary>process authentication group</primary>
2864
2865       <secondary></secondary>
2866
2867       <see>PAG</see>
2868     </indexterm>
2869
2870     <sect2 id="HDRWQ64">
2871       <title>Identifying AFS Tokens by PAG</title>
2872
2873       <para>As noted, the Cache Manager identifies user credential structures either by UNIX UID or by PAG. Using a PAG is
2874       preferable because it guaranteed to be unique: the Cache Manager allocates it based on a counter that increments with each
2875       use. In contrast, multiple users on a machine can share or assume the same UNIX UID, which creates potential security
2876       problems. The following are two common such situations: <itemizedlist>
2877           <listitem>
2878             <para>The local superuser <emphasis role="bold">root</emphasis> can always assume any other user's UNIX UID simply by
2879             issuing the <emphasis role="bold">su</emphasis> command, without providing the user's password. If the credential
2880             structure is associated with the user's UNIX UID, then assuming the UID means inheriting the AFS tokens.</para>
2881           </listitem>
2882
2883           <listitem>
2884             <para>Two users working on different NFS client machines can have the same UNIX UID in their respective local file
2885             systems. If they both access the same NFS/AFS Translator machine, and the Cache Manager there identifies them by their
2886             UNIX UID, they become indistinguishable. To eliminate this problem, the Cache Manager on a translator machine
2887             automatically generates a PAG for each user and uses it, rather than the UNIX UID, to tell users apart.</para>
2888           </listitem>
2889         </itemizedlist></para>
2890
2891       <para>Yet another advantage of PAGs over UIDs is that processes spawned by the user inherit the PAG and so share the token;
2892       thus they gain access to AFS as the authenticated user. In many environments, for example, printer and other daemons run under
2893       identities (such as the local superuser <emphasis role="bold">root</emphasis>) that the AFS server processes recognize only as
2894       the <emphasis role="bold">anonymous</emphasis> user. Unless PAGs are used, such daemons cannot access files for which the
2895       <emphasis role="bold">system:anyuser</emphasis> group does not have the necessary ACL permissions.</para>
2896
2897       <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
2898       associated tokens expire or are discarded. If the user issues the <emphasis role="bold">klog</emphasis> command before the PAG
2899       expires, the new token is associated with the existing PAG (the PAG is said to be recycled in this case).</para>
2900
2901       <para>AFS-modified login utilities automatically generate a PAG, as described in the following section. If you use a standard
2902       login utility, your users must issue the <emphasis role="bold">pagsh</emphasis> command before the <emphasis
2903       role="bold">klog</emphasis> command, or include the latter command's <emphasis role="bold">-setpag</emphasis> flag. For
2904       instructions, see <link linkend="HDRWQ69">Using Two-Step Login and Authentication</link>.</para>
2905
2906       <para>Users can also use either command at any time to create a new PAG. The difference between the two commands is that the
2907       <emphasis role="bold">klog</emphasis> command replaces the PAG associated with the current command shell and tokens. The
2908       <emphasis role="bold">pagsh</emphasis> command initializes a new command shell before creating a new PAG. If the user already
2909       had a PAG, any running processes or jobs continue to use the tokens associated with the old PAG whereas any new jobs or
2910       processes use the new PAG and its associated tokens. When you exit the new shell (by pressing &lt;<emphasis
2911       role="bold">Ctrl-d</emphasis>&gt;, for example), you return to the original PAG and shell. By default, the <emphasis
2912       role="bold">pagsh</emphasis> command initializes a Bourne shell, but you can include the <emphasis role="bold">-c</emphasis>
2913       argument to initialize a C shell (the <emphasis role="bold">/bin/csh</emphasis> program on many system types) or Korn shell
2914       (the <emphasis role="bold">/bin/ksh</emphasis> program) instead.</para>
2915
2916       <indexterm>
2917         <primary>login utility</primary>
2918
2919         <secondary>AFS version</secondary>
2920       </indexterm>
2921     </sect2>
2922
2923     <sect2 id="HDRWQ65">
2924       <title>Using an AFS-modified login Utility</title>
2925
2926       <para>As previously mentioned, an AFS-modified login utility simultaneously obtains an AFS token and logs the user into the
2927       local file system. This section outlines the login and authentication process and its interaction with the value in the
2928       password field of the local password file.</para>
2929
2930       <para>An AFS-modified login utility performs a sequence of steps similar to the following; details can vary for different
2931       operating systems: <orderedlist>
2932           <listitem>
2933             <para>It checks the user's entry in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
2934             equivalent).</para>
2935           </listitem>
2936
2937           <listitem>
2938             <para>If no entry exists, or if an asterisk (<computeroutput>*</computeroutput>) appears in the entry's password field,
2939             the login attempt fails. If the entry exists, the attempt proceeds to the next step.</para>
2940           </listitem>
2941
2942           <listitem>
2943             <para><anchor id="LIWQ66" />The utility obtains a PAG.</para>
2944           </listitem>
2945
2946           <listitem>
2947             <para><anchor id="LIWQ67" />The utility converts the password provided by the user into an encryption key and encrypts a
2948             packet of data with the key. It sends the packet to the AFS authentication service (the AFS Authentication Server in the
2949             conventional configuration).</para>
2950           </listitem>
2951
2952           <listitem>
2953             <para>The authentication service decrypts the packet and, depending on the success of the decryption, judges the
2954             password to be correct or incorrect. (For more details, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
2955             Authentication</link>.) <itemizedlist>
2956                 <listitem>
2957                   <para>If the authentication service judges the password incorrect, the user does not receive an AFS token. The PAG
2958                   is retained, ready to be associated with any tokens obtained later. The attempt proceeds to Step <link
2959                   linkend="LIWQ68">6</link>.</para>
2960                 </listitem>
2961
2962                 <listitem>
2963                   <para>If the authentication service judges the password correct, it issues a token to the user as proof of AFS
2964                   authentication. The login utility logs the user into the local UNIX file system. Some login utilities echo the
2965                   following banner to the screen to alert the user to authentication with AFS. Step <link linkend="LIWQ68">6</link>
2966                   is skipped. <programlisting>
2967    AFS(R) version Login 
2968 </programlisting></para>
2969                 </listitem>
2970               </itemizedlist></para>
2971           </listitem>
2972
2973           <listitem>
2974             <para><anchor id="LIWQ68" />If no AFS token was granted in Step <link linkend="LIWQ67">4</link>, the login utility
2975             attempts to log the user into the local file system, by comparing the password provided to the local password file.
2976             <itemizedlist>
2977                 <listitem>
2978                   <para>If the password is incorrect or any value other than an encrypted 13-character string appears in the
2979                   password field, the login attempt fails.</para>
2980                 </listitem>
2981
2982                 <listitem>
2983                   <para>If the password is correct, the user is logged into the local file system only.</para>
2984                 </listitem>
2985               </itemizedlist></para>
2986           </listitem>
2987         </orderedlist></para>
2988
2989       <indexterm>
2990         <primary>local password file</primary>
2991
2992         <secondary>when using AFS--modified login utility</secondary>
2993       </indexterm>
2994
2995       <indexterm>
2996         <primary>login utility</primary>
2997
2998         <secondary>AFS version's interaction with local password file</secondary>
2999       </indexterm>
3000
3001       <indexterm>
3002         <primary>password</primary>
3003
3004         <secondary>local password file</secondary>
3005       </indexterm>
3006
3007       <para>As indicated, when you use an AFS-modified login utility, the password field in the local password file is no longer the
3008       primary gate for access to your system. If the user provides the correct AFS password, then the program never consults the
3009       local password file. However, you can still use the password field to control access, in the following way: <itemizedlist>
3010           <listitem>
3011             <para>To prevent both local login and AFS authentication, place an asterisk (<emphasis role="bold">*</emphasis>) in the
3012             field. This is useful mainly in emergencies, when you want to prevent a certain user from logging into the
3013             machine.</para>
3014           </listitem>
3015
3016           <listitem>
3017             <para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
3018             string of any length other than the standard thirteen characters in the field. This is appropriate if you want to permit
3019             only people with local AFS accounts to login on your machines. A single <emphasis role="bold">X</emphasis> or other
3020             character is the most easily recognizable way to do this.</para>
3021           </listitem>
3022
3023           <listitem>
3024             <para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
3025             standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
3026             role="bold">passwd</emphasis> or equivalent).</para>
3027           </listitem>
3028         </itemizedlist></para>
3029
3030       <para>Systems that use a Pluggable Authentication Module (PAM) for login and AFS authentication do not necessarily consult the
3031       local password file at all, in which case they do not use the password field to control authentication and login attempts.
3032       Instead, instructions in the PAM configuration file (on many system types, <emphasis role="bold">/etc/pam.conf</emphasis>)
3033       fill the same function. See the instructions in the OpenAFS Quick Beginnings for installing AFS-modified login
3034       utilities.</para>
3035
3036       <indexterm>
3037         <primary>local password file</primary>
3038
3039         <secondary>when not using AFS-modified login utility</secondary>
3040       </indexterm>
3041     </sect2>
3042
3043     <sect2 id="HDRWQ69">
3044       <title>Using Two-Step Login and Authentication</title>
3045
3046       <para>In cells that do not use an AFS-modified login utility, users must issue separate commands to login and authenticate, as
3047       detailed in the OpenAFS User Guide: <orderedlist>
3048           <listitem>
3049             <para>They use the standard <emphasis role="bold">login</emphasis> program to login to the local file system, providing
3050             the password listed in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
3051             equivalent).</para>
3052           </listitem>
3053
3054           <listitem>
3055             <para>They must issue the <emphasis role="bold">klog</emphasis> command to authenticate with the AFS authentication
3056             service, including its <emphasis role="bold">-setpag</emphasis> flag to associate the new tokens with a process
3057             authentication group (PAG).</para>
3058           </listitem>
3059         </orderedlist></para>
3060
3061       <para>As mentioned in <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>, you can invoke the <emphasis
3062       role="bold">klog -setpag</emphasis> command in a user's <emphasis role="bold">.login</emphasis> file (or equivalent) so that
3063       the user does not have to remember to issue the command after logging in. The user still must type a password twice, once at
3064       the prompt generated by the login utility and once at the <emphasis role="bold">klog</emphasis> command's prompt. This implies
3065       that the two passwords can differ, but it is less confusing if they do not.</para>
3066
3067       <para>Another effect of not using an AFS-modified login utility is that the AFS servers recognize the standard <emphasis
3068       role="bold">login</emphasis> program as the <emphasis role="bold">anonymous</emphasis> user. If the <emphasis
3069       role="bold">login</emphasis> program needs to access any AFS files (such as the <emphasis role="bold">.login</emphasis> file
3070       in a user's home directory), then the ACL that protects the file must include an entry granting the <emphasis
3071       role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
3072       role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group.</para>
3073
3074       <para>When you do not use an AFS-modified login utility, an actual (scrambled) password must appear in the local password file
3075       for each user. Use the <emphasis role="bold">/bin/passwd</emphasis> file to insert or change these passwords. It is simpler if
3076       the password in the local password file matches the AFS password, but it is not required.</para>
3077
3078       <indexterm>
3079         <primary>tokens</primary>
3080
3081         <secondary>displaying for user</secondary>
3082       </indexterm>
3083
3084       <indexterm>
3085         <primary>tokens</primary>
3086
3087         <secondary>command</secondary>
3088       </indexterm>
3089
3090       <indexterm>
3091         <primary>commands</primary>
3092
3093         <secondary>tokens</secondary>
3094       </indexterm>
3095
3096       <indexterm>
3097         <primary>listing</primary>
3098
3099         <secondary>tokens held by issuer</secondary>
3100       </indexterm>
3101
3102       <indexterm>
3103         <primary>commands</primary>
3104
3105         <secondary>klog</secondary>
3106       </indexterm>
3107
3108       <indexterm>
3109         <primary>klog command</primary>
3110       </indexterm>
3111
3112       <indexterm>
3113         <primary>server process</primary>
3114
3115         <secondary>creating ticket (tokens) for</secondary>
3116       </indexterm>
3117
3118       <indexterm>
3119         <primary>tickets</primary>
3120
3121         <secondary></secondary>
3122
3123         <see>tokens</see>
3124       </indexterm>
3125
3126       <indexterm>
3127         <primary>tokens</primary>
3128
3129         <secondary>creating for server process</secondary>
3130       </indexterm>
3131
3132       <indexterm>
3133         <primary>authenticated identity</primary>
3134
3135         <secondary>acquiring with klog command</secondary>
3136       </indexterm>
3137
3138       <indexterm>
3139         <primary>unlog command</primary>
3140       </indexterm>
3141
3142       <indexterm>
3143         <primary>commands</primary>
3144
3145         <secondary>unlog</secondary>
3146       </indexterm>
3147
3148       <indexterm>
3149         <primary>discarding</primary>
3150
3151         <secondary>tokens</secondary>
3152       </indexterm>
3153
3154       <indexterm>
3155         <primary>tokens</primary>
3156
3157         <secondary>discarding with unlog command</secondary>
3158       </indexterm>
3159     </sect2>
3160
3161     <sect2 id="Header_81">
3162       <title>Obtaining, Displaying, and Discarding Tokens</title>
3163
3164       <para>Once logged in, a user can obtain a token at any time with the <emphasis role="bold">klog</emphasis> command. If a valid
3165       token already exists, the new one overwrites it. If a PAG already exists, the new token is associated with it.</para>
3166
3167       <para>By default, the <emphasis role="bold">klog</emphasis> command authenticates the issuer using the identity currently
3168       logged in to the local file system. To authenticate as a different identity, use the <emphasis
3169       role="bold">-principal</emphasis> argument. To obtain a token for a foreign cell, use the <emphasis
3170       role="bold">-cell</emphasis> argument (it can be combined with the <emphasis role="bold">-principal</emphasis> argument). See
3171       the OpenAFS User Guide and the entry for the <emphasis role="bold">klog</emphasis> command in the OpenAFS Administration
3172       Reference.</para>
3173
3174       <para>To discard either all tokens or the token for a particular cell, issue the <emphasis role="bold">unlog</emphasis>
3175       command. The command affects only the tokens associated with the current command shell. See the OpenAFS User Guideand the
3176       entry for the <emphasis role="bold">unlog</emphasis> command in the OpenAFS Administration Reference.</para>
3177
3178       <para>To display the tokens associated with the current command shell, issue the <emphasis role="bold">tokens</emphasis>
3179       command. The following examples illustrate its output in various situations.</para>
3180
3181       <para>If the issuer is not authenticated in any cell:</para>
3182
3183       <programlisting>
3184    % <emphasis role="bold">tokens</emphasis>
3185    Tokens held by the Cache Manager:
3186           --End of list--
3187 </programlisting>
3188
3189       <para>The following shows the output for a user with AFS UID 1000 in the ABC Corporation cell:</para>
3190
3191       <programlisting>
3192    % <emphasis role="bold">tokens</emphasis>
3193    Tokens held by the Cache Manager: 
3194    User's (AFS ID 1000) tokens for afs@abc.com  [Expires Jun  2 10:00]
3195        --End of list--
3196 </programlisting>
3197
3198       <para>The following shows the output for a user who is authenticated in ABC Corporation cell, the State University cell and
3199       the DEF Company cell. The user has different AFS UIDs in the three cells. Tokens for the last cell are expired:</para>
3200
3201       <programlisting>
3202    % <emphasis role="bold">tokens</emphasis>
3203    Tokens held by the Cache Manager:
3204    User's (AFS ID 1000) tokens for afs@abc.com  [Expires Jun  2 10:00]
3205    User's (AFS ID 4286) tokens for afs@stateu.edu  [Expires Jun  3 1:34]
3206    User's (AFS ID 22) tokens for afs@def.com  [&gt;&gt;Expired&lt;&lt;]
3207        --End of list--
3208 </programlisting>
3209
3210       <para>The Kerberos version of the <emphasis role="bold">tokens</emphasis> command (the <emphasis
3211       role="bold">tokens.krb</emphasis> command), also reports information on the ticket-granting ticket, including the ticket's
3212       owner, the ticket-granting service, and the expiration date, as in the following example. Also see <link
3213       linkend="HDRWQ70">Support for Kerberos Authentication</link>.</para>
3214
3215       <programlisting>
3216    % <emphasis role="bold">tokens.krb</emphasis>
3217    Tokens held by the Cache Manager:
3218    User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun  2 10:00]
3219    User smith's tokens for krbtgt.ABC.COM@abc.com [Expires Jun  2 10:00]
3220      --End of list--
3221 </programlisting>
3222     </sect2>
3223
3224     <sect2 id="Header_82">
3225       <title>Setting Default Token Lifetimes for Users</title>
3226
3227       <indexterm>
3228         <primary>tokens</primary>
3229
3230         <secondary>setting default lifetimes for users</secondary>
3231       </indexterm>
3232
3233       <para>The maximum lifetime of a user token is the smallest of the ticket lifetimes recorded in the following three
3234       Authentication Database entries. The <emphasis role="bold">kas examine</emphasis> command reports the lifetime as
3235       <computeroutput>Max ticket lifetime</computeroutput>. Administrators who have the <computeroutput>ADMIN</computeroutput> flag
3236       on their Authentication Database entry can use the <emphasis role="bold">-lifetime</emphasis> argument to the <emphasis
3237       role="bold">kas setfields</emphasis> command to set an entry's ticket lifetime. <itemizedlist>
3238           <listitem>
3239             <para>The <emphasis role="bold">afs</emphasis> entry, which corresponds to the AFS server processes. The default is 100
3240             hours.</para>
3241           </listitem>
3242
3243           <listitem>
3244             <para>The <emphasis role="bold">krbtgt</emphasis>.cellname entry, which corresponds to the ticket-granting ticket used
3245             internally in generating the token. The default is 720 hours (30 days).</para>
3246           </listitem>
3247
3248           <listitem>
3249             <para>The entry for the user of the AFS-modified login utility or issuer of the <emphasis role="bold">klog</emphasis>
3250             command. The default is 25 hours for user entries created using the AFS 3.1 or later version of the Authentication
3251             Server, and 100 hours for user entries created using the AFS 3.0 version of the Authentication Server. A user can use
3252             the <emphasis role="bold">kas examine</emphasis> command to display his or her own Authentication Database entry.</para>
3253           </listitem>
3254         </itemizedlist></para>
3255
3256       <note>
3257         <para>An AFS-modified login utility always grants a token with a lifetime calculated from the previously described three
3258         values. When issuing the <emphasis role="bold">klog</emphasis> command, a user can request a lifetime shorter than the
3259         default by using the <emphasis role="bold">-lifetime</emphasis> argument. For further information, see the OpenAFS User
3260         Guide and the <emphasis role="bold">klog</emphasis> reference page in the OpenAFS Administration Reference.</para>
3261       </note>
3262     </sect2>
3263
3264     <sect2 id="Header_83">
3265       <title>Changing Passwords</title>
3266
3267       <indexterm>
3268         <primary>password</primary>
3269
3270         <secondary>changing in AFS</secondary>
3271       </indexterm>
3272
3273       <indexterm>
3274         <primary>kpasswd command</primary>
3275       </indexterm>
3276
3277       <indexterm>
3278         <primary>commands</primary>
3279
3280         <secondary>kpasswd</secondary>
3281       </indexterm>
3282
3283       <indexterm>
3284         <primary>kas commands</primary>
3285
3286         <secondary>setpassword</secondary>
3287       </indexterm>
3288
3289       <indexterm>
3290         <primary>commands</primary>
3291
3292         <secondary>kas setpassword</secondary>
3293       </indexterm>
3294
3295       <para>Regular AFS users can change their own passwords by using either the <emphasis role="bold">kpasswd</emphasis> or
3296       <emphasis role="bold">kas setpassword</emphasis> command. The commands prompt for the current password and then twice for the
3297       new password, to screen out typing errors.</para>
3298
3299       <para>Administrators who have the <computeroutput>ADMIN</computeroutput> flag on their Authentication Database entries can
3300       change any user's password, either by using the <emphasis role="bold">kpasswd</emphasis> command (which requires knowing the
3301       current password) or the <emphasis role="bold">kas setpassword</emphasis> command.</para>
3302
3303       <para>If your cell does not use an AFS-modified login utility, remember also to change the local password, using the operating
3304       system's password-changing command. For more instructions on changing passwords, see <link linkend="HDRWQ516">Changing AFS
3305       Passwords</link>.</para>
3306     </sect2>
3307
3308     <sect2 id="Header_84">
3309       <title>Imposing Restrictions on Passwords and Authentication Attempts</title>
3310
3311       <para>You can help to make your cell more secure by imposing restrictions on user passwords and authentication attempts. To
3312       impose the restrictions as you create an account, use the <emphasis role="bold">A</emphasis> instruction in the <emphasis
3313       role="bold">uss</emphasis> template file as described in <link linkend="HDRWQ478">Increasing Account Security with the A
3314       Instruction</link>. To set or change the values on an existing account, use the <emphasis role="bold">kas setfields</emphasis>
3315       command as described in <link linkend="HDRWQ515">Improving Password and Authentication Security</link>.</para>
3316
3317       <indexterm>
3318         <primary>password</primary>
3319
3320         <secondary>expiration</secondary>
3321       </indexterm>
3322
3323       <indexterm>
3324         <primary>password</primary>
3325
3326         <secondary>lifetime</secondary>
3327       </indexterm>
3328
3329       <indexterm>
3330         <primary>kas commands</primary>
3331
3332         <secondary>setfields</secondary>
3333       </indexterm>
3334
3335       <indexterm>
3336         <primary>commands</primary>
3337
3338         <secondary>kas setfields</secondary>
3339       </indexterm>
3340
3341       <indexterm>
3342         <primary>Authentication Database</primary>
3343
3344         <secondary>password lifetime, setting</secondary>
3345       </indexterm>
3346
3347       <indexterm>
3348         <primary>password</primary>
3349
3350         <secondary>restricting reuse</secondary>
3351       </indexterm>
3352
3353       <para>By default, AFS passwords never expire. Limiting password lifetime can help improve security by decreasing the time the
3354       password is subject to cracking attempts. You can choose an lifetime from 1 to 254 days after the password was last changed.
3355       It automatically applies to each new password as it is set. When the user changes passwords, you can also insist that the new
3356       password is not similar to any of the 20 passwords previously used.</para>
3357
3358       <indexterm>
3359         <primary>password</primary>
3360
3361         <secondary>consequences of multiple failed authentication attempts</secondary>
3362       </indexterm>
3363
3364       <indexterm>
3365         <primary>kas commands</primary>
3366
3367         <secondary>setfields</secondary>
3368       </indexterm>
3369
3370       <indexterm>
3371         <primary>commands</primary>
3372
3373         <secondary>kas setfields</secondary>
3374       </indexterm>
3375
3376       <indexterm>
3377         <primary>authentication</primary>
3378
3379         <secondary>consequences of multiple failures</secondary>
3380       </indexterm>
3381
3382       <para>Unscrupulous users can try to gain access to your AFS cell by guessing an authorized user's password. To protect against
3383       this type of attack, you can limit the number of times that a user can consecutively fail to provide the correct password.
3384       When the limit is exceeded, the authentication service refuses further authentication attempts for a specified period of time
3385       (the lockout time). To reenable authentication attempts before the lockout time expires, an administrator must issue the
3386       <emphasis role="bold">kas unlock</emphasis> command.</para>
3387
3388       <indexterm>
3389         <primary>password</primary>
3390
3391         <secondary>checking quality of</secondary>
3392       </indexterm>
3393
3394       <indexterm>
3395         <primary>kpasswd command</primary>
3396       </indexterm>
3397
3398       <indexterm>
3399         <primary>commands</primary>
3400
3401         <secondary>kpasswd</secondary>
3402       </indexterm>
3403
3404       <indexterm>
3405         <primary>kas commands</primary>
3406
3407         <secondary>setpassword</secondary>
3408       </indexterm>
3409
3410       <indexterm>
3411         <primary>kpwvalid program</primary>
3412       </indexterm>
3413
3414       <para>In addition to settings on user's authentication accounts, you can improve security by automatically checking the
3415       quality of new user passwords. The <emphasis role="bold">kpasswd</emphasis> and <emphasis role="bold">kas
3416       setpassword</emphasis> commands pass the proposed password to a program or script called <emphasis
3417       role="bold">kpwvalid</emphasis>, if it exists. The <emphasis role="bold">kpwvalid</emphasis> performs quality checks and
3418       returns a code to indicate whether the password is acceptable. You can create your own program or modified the sample program
3419       included in the AFS distribution. See the <emphasis role="bold">kpwvalid</emphasis> reference page in the OpenAFS
3420       Administration Reference.</para>
3421
3422       <para>There are several types of quality checks that can improve password quality. <itemizedlist>
3423           <listitem>
3424             <para>The password is a minimum length</para>
3425           </listitem>
3426
3427           <listitem>
3428             <para>The password is not a word</para>
3429           </listitem>
3430
3431           <listitem>
3432             <para>The password contains both numbers and letters</para>
3433           </listitem>
3434         </itemizedlist></para>
3435     </sect2>
3436
3437     <sect2 id="HDRWQ70">
3438       <title>Support for Kerberos Authentication</title>
3439
3440       <indexterm>
3441         <primary>Kerberos</primary>
3442
3443         <secondary>support for in AFS</secondary>
3444       </indexterm>
3445
3446       <indexterm>
3447         <primary>commands</primary>
3448
3449         <secondary>klog.krb</secondary>
3450       </indexterm>
3451
3452       <indexterm>
3453         <primary>commands</primary>
3454
3455         <secondary>pagsh.krb</secondary>
3456       </indexterm>
3457
3458       <indexterm>
3459         <primary>commands</primary>
3460
3461         <secondary>tokens.krb</secondary>
3462       </indexterm>
3463
3464       <indexterm>
3465         <primary>klog.krb command</primary>
3466       </indexterm>
3467
3468       <indexterm>
3469         <primary>pagsh.krb command</primary>
3470       </indexterm>
3471
3472       <indexterm>
3473         <primary>tokens.krb command</primary>
3474       </indexterm>
3475
3476       <para>If your site is using standard Kerberos authentication rather than the AFS Authentication Server, use the modified
3477       versions of the <emphasis role="bold">klog</emphasis>, <emphasis role="bold">pagsh</emphasis>, and <emphasis
3478       role="bold">tokens</emphasis> commands that support Kerberos authentication. The binaries for the modified version of these
3479       commands have the same name as the standard binaries with the addition of a <emphasis role="bold">.krb</emphasis>
3480       extension.</para>
3481
3482       <para>Use either the Kerberos version or the standard command throughout the cell; do not mix the two versions. AFS Product
3483       Support can provide instructions on installing the Kerberos version of these four commands. For information on the differences
3484       between the two versions of these commands, see the OpenAFS Administration Reference.</para>
3485     </sect2>
3486   </sect1>
3487
3488   <sect1 id="HDRWQ71">
3489     <title>Security and Authorization in AFS</title>
3490
3491     <para>AFS incorporates several features to ensure that only authorized users gain access to data. This section summarizes the
3492     most important of them and suggests methods for improving security in your cell.</para>
3493
3494     <sect2 id="HDRWQ72">
3495       <title>Some Important Security Features</title>
3496
3497       <indexterm>
3498         <primary>security</primary>
3499
3500         <secondary>AFS features</secondary>
3501       </indexterm>
3502
3503       <indexterm>
3504         <primary>AFS</primary>
3505
3506         <secondary>security features</secondary>
3507       </indexterm>
3508
3509       <formalpara>
3510         <title>ACLs on Directories</title>
3511
3512         <para>Files in AFS are protected by the access control list (ACL) associated with their parent directory. The ACL defines
3513         which users or groups can access the data in the directory, and in what way. See <link linkend="HDRWQ562">Managing Access
3514         Control Lists</link>.</para>
3515       </formalpara>
3516
3517       <formalpara>
3518         <title>Mutual Authentication Between Client and Server</title>
3519
3520         <para>When an AFS client and server process communicate, each requires the other to prove its identity during mutual
3521         authentication, which involves the exchange of encrypted information that only valid parties can decrypt and respond to. For
3522         a detailed description of the mutual authentication process, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
3523         Authentication</link>.</para>
3524       </formalpara>
3525
3526       <para>AFS server processes mutually authenticate both with one another and with processes that represent human users. After
3527       mutual authentication is complete, the server and client have established an authenticated connection, across which they can
3528       communicate repeatedly without having to authenticate again until the connection expires or one of the parties closes it.
3529       Authenticated connections have varying lifetimes.</para>
3530
3531       <formalpara>
3532         <title>Tokens</title>
3533
3534         <para>In order to access AFS files, users must prove their identities to the AFS authentication service by providing the
3535         correct AFS password. If the password is correct, the authentication service sends the user a token as evidence of
3536         authenticated status. See <link linkend="HDRWQ63">Login and Authentication in AFS</link>.</para>
3537       </formalpara>
3538
3539       <para>Servers assign the user identity <emphasis role="bold">anonymous</emphasis> to users and processes that do not have a
3540       valid token. The <emphasis role="bold">anonymous</emphasis> identity has only the access granted to the <emphasis
3541       role="bold">system:anyuser</emphasis> group on ACLs.</para>
3542
3543       <formalpara>
3544         <title>Authorization Checking</title>
3545
3546         <para>Mutual authentication establishes that two parties communicating with one another are actually who they claim to be.
3547         For many functions, AFS server processes also check that the client whose identity they have verified is also authorized to
3548         make the request. Different requests require different kinds of privilege. See <link linkend="HDRWQ73">Three Types of
3549         Privilege</link>.</para>
3550       </formalpara>
3551
3552       <formalpara>
3553         <title>Encrypted Network Communications</title>
3554
3555         <indexterm>
3556           <primary>network</primary>
3557
3558           <secondary>encrypted communication in AFS</secondary>
3559         </indexterm>
3560
3561         <indexterm>
3562           <primary>encrypted network communication</primary>
3563         </indexterm>
3564
3565         <indexterm>
3566           <primary>security</primary>
3567
3568           <secondary>encrypted network communication</secondary>
3569         </indexterm>
3570
3571         <para>The AFS server processes encrypt particularly sensitive information before sending it back to clients. Even if an
3572         unauthorized party is able to eavesdrop on an authenticated connection, they cannot decipher encrypted data without the
3573         proper key.</para>
3574       </formalpara>
3575
3576       <para>The following AFS commands encrypt data because they involve server encryption keys and passwords: <itemizedlist>
3577           <listitem>
3578             <para>The <emphasis role="bold">bos addkey</emphasis> command, which adds a server encryption key to the <emphasis
3579             role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
3580           </listitem>
3581
3582           <listitem>
3583             <para>The <emphasis role="bold">bos listkeys</emphasis> command, which lists the server encryption keys from the
3584             <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
3585           </listitem>
3586
3587           <listitem>
3588             <para>The <emphasis role="bold">kpasswd</emphasis> command, which changes a password in the Authentication
3589             Database</para>
3590           </listitem>
3591
3592           <listitem>
3593             <para>Most commands in the <emphasis role="bold">kas</emphasis> command suite</para>
3594           </listitem>
3595         </itemizedlist></para>
3596
3597       <para>In addition, the United States edition of the Update Server encrypts sensitive information (such as the contents of
3598       <emphasis role="bold">KeyFile</emphasis>) when distributing it. Other commands in the <emphasis role="bold">bos</emphasis>
3599       suite and the commands in the <emphasis role="bold">fs</emphasis>, <emphasis role="bold">pts</emphasis> and <emphasis
3600       role="bold">vos</emphasis> suites do not encrypt data before transmitting it.</para>
3601     </sect2>
3602
3603     <sect2 id="HDRWQ73">
3604       <title>Three Types of Privilege</title>
3605
3606       <para>AFS uses three separate types of privilege for the reasons discussed in <link linkend="HDRWQ585">The Reason for Separate
3607       Privileges</link>. <itemizedlist>
3608           <listitem>
3609             <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. Members are entitled to issue any
3610             <emphasis role="bold">pts</emphasis> command and those <emphasis role="bold">fs</emphasis> commands that set volume
3611             quota. By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
3612             role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
3613             permissions on every ACL in the file tree even if the ACL does not include an entry for them.</para>
3614           </listitem>
3615
3616           <listitem>
3617             <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. An administrator with this
3618             flag can issue any <emphasis role="bold">kas</emphasis> command.</para>
3619           </listitem>
3620
3621           <listitem>
3622             <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. An administrator whose username
3623             appears in this file can issue any <emphasis role="bold">bos</emphasis>, <emphasis role="bold">vos</emphasis>, or
3624             <emphasis role="bold">backup</emphasis> command (although some <emphasis role="bold">backup</emphasis> commands require
3625             additional privilege as described in <link linkend="HDRWQ260">Granting Administrative Privilege to Backup
3626             Operators</link>).</para>
3627           </listitem>
3628         </itemizedlist></para>
3629     </sect2>
3630
3631     <sect2 id="Header_89">
3632       <title>Authorization Checking versus Authentication</title>
3633
3634       <para>AFS distinguishes between authentication and authorization checking. Authentication refers to the process of proving
3635       identity. Authorization checking refers to the process of verifying that an authenticated identity is allowed to perform a
3636       certain action.</para>
3637
3638       <para>AFS implements authentication at the level of connections. Each time two parties establish a new connection, they
3639       mutually authenticate. In general, each issue of an AFS command establishes a new connection between AFS server process and
3640       client.</para>
3641
3642       <para>AFS implements authorization checking at the level of server machines. If authorization checking is enabled on a server
3643       machine, then all of the server processes running on it provide services only to authorized users. If authorization checking
3644       is disabled on a server machine, then all of the server processes perform any action for anyone. Obviously, disabling
3645       authorization checking is an extreme security exposure. For more information, see <link linkend="HDRWQ123">Managing
3646       Authentication and Authorization Requirements</link>.</para>
3647     </sect2>
3648
3649     <sect2 id="HDRWQ74">
3650       <title>Improving Security in Your Cell</title>
3651
3652       <indexterm>
3653         <primary>security</primary>
3654
3655         <secondary>suggestions for improving</secondary>
3656       </indexterm>
3657
3658       <para>You can improve the level of security in your cell by configuring user accounts, server machines, and system
3659       administrator accounts in the indicated way.</para>
3660
3661       <formalpara>
3662         <title>User Accounts</title>
3663
3664         <para><itemizedlist>
3665             <listitem>
3666               <para>Use an AFS-modified login utility, or include the <emphasis role="bold">-setpag</emphasis> flag to the <emphasis
3667               role="bold">klog</emphasis> command, to associate the credential structure that houses tokens with a PAG rather than a
3668               UNIX UID. This prevents users from inheriting someone else's tokens by assuming their UNIX identity. For further
3669               discussion, see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
3670             </listitem>
3671
3672             <listitem>
3673               <para>Encourage users to issue the <emphasis role="bold">unlog</emphasis> command to destroy their tokens before
3674               logging out. This forestalls attempts to access tokens left behind kernel memory. Consider including the <emphasis
3675               role="bold">unlog</emphasis> command in every user's <emphasis role="bold">.logout</emphasis> file or
3676               equivalent.</para>
3677 &nb