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