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