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