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