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