1 <?xml version="1.0" encoding="UTF-8"?>
3 <title>Issues in Cell Configuration and Administration</title>
5 <para>This chapter discusses many of the issues to consider when configuring and administering a cell, and directs you to detailed
6 related information available elsewhere in this guide. It is assumed you are already familiar with the material in <link
7 linkend="HDRWQ5">An Overview of OpenAFS Administration</link>.</para>
9 <para>It is best to read this chapter before installing your cell's first file server machine or performing any other
10 administrative task.</para>
13 <primary>AFS</primary>
15 <secondary>differences from UNIX summarized</secondary>
19 <primary>UNIX</primary>
21 <secondary>differences from AFS summarized</secondary>
25 <primary>differences</primary>
27 <secondary>between AFS and UNIX, summarized</secondary>
31 <title>Differences between AFS and UNIX: A Summary</title>
33 <para>AFS behaves like a standard UNIX file system in most respects, while also making file sharing easy within and between
34 cells. This section describes some differences between AFS and the UNIX file system, referring you to more detailed information
35 as appropriate.</para>
38 <primary>protection</primary>
40 <secondary>AFS compared to UNIX</secondary>
43 <sect2 id="Header_35">
44 <title>Differences in File and Directory Protection</title>
46 <para>AFS augments the standard UNIX file protection mechanism in two ways: it associates an <emphasis>access control list
47 (ACL)</emphasis> with each directory, and it enables users to define a large number of their own groups, which can be placed
50 <para>AFS uses ACLs to protect files and directories, rather than relying exclusively on the mode bits. This has several
51 implications, which are discussed further in the indicated sections: <itemizedlist>
53 <para>AFS ACLs use seven access permissions rather than the three UNIX mode bits. See <link linkend="HDRWQ567">The AFS
54 ACL Permissions</link>.</para>
58 <para>For directories, AFS ignores the UNIX mode bits. For files, AFS uses only the first set of mode bits (the
59 <emphasis role="bold">owner</emphasis> bits) , and their meaning interacts with permissions on the directory's ACL. See
60 <link linkend="HDRWQ580">How AFS Interprets the UNIX Mode Bits</link>.</para>
64 <para>A directory's ACL protects all of the files in a directory in the same manner. To apply a more restrictive set of
65 AFS permissions to certain file, place it in directory with a different ACL.</para>
69 <para>Moving a file to a different directory changes its protection. See <link linkend="HDRWQ566">Differences Between
70 UFS and AFS Data Protection</link>.</para>
74 <para>An ACL can include about 20 entries granting different combinations of permissions to different users or groups,
75 rather than only the three UNIX entities represented by the three sets of mode bits. See <link
76 linkend="HDRWQ566">Differences Between UFS and AFS Data Protection</link>.</para>
80 <para>You can designate an AFS file as write-only as in the UNIX file system, by setting only the <emphasis
81 role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit. You cannot designate an AFS directory as
82 write-only, because AFS ignores the mode bits on a directory. See <link linkend="HDRWQ580">How AFS Interprets the UNIX
83 Mode Bits</link>.</para>
85 </itemizedlist></para>
87 <para>AFS enables users to define the groups of other users. Placing these groups on ACLs extends the same permissions to a
88 number of exactly specified users at the same time, which is much more convenient than placing the individuals on the ACLs
89 directly. See <link linkend="HDRWQ531">Administering the Protection Database</link>.</para>
91 <para>There are also system-defined groups, <emphasis role="bold">system:anyuser</emphasis> and <emphasis
92 role="bold">system:authuser</emphasis>, whose presence on an ACL extends access to a wide range of users at once. See <link
93 linkend="HDRWQ535">The System Groups</link> and <link linkend="HDRWQ571">Using Groups on ACLs</link>.</para>
96 <primary>authentication</primary>
98 <secondary>AFS compared to UNIX</secondary>
102 <primary>password</primary>
104 <secondary>AFS compared to UNIX</secondary>
109 <title>Differences in Authentication</title>
111 <para>Just as the AFS filespace is distinct from each machine's local file system, AFS authentication is separate from local
112 login. This has two practical implications, which are discussed further in <link linkend="HDRWQ65">Using an AFS-modified login
113 Utility</link>. <itemizedlist>
115 <para>To access AFS files, users must both log into the local machine's UNIX file system and authenticate with the AFS
116 authentication service. (Logging into the local UNIX file system is necessary because the AFS filespace is accessed
117 through the Cache Manager, which resides in the local machine's kernel.)</para>
119 <para>AFS provides a modified login utility for each system type that accomplishes both local login and AFS
120 authentication in one step, based on a single password. If you choose not to use the AFS-modified login utility, your
121 users must login and authenticate in separate steps, as detailed in the <emphasis>OpenAFS User Guide</emphasis>.</para>
125 <para>Passwords may be stored in two separate places: the Kerberos Server and, optionally, each machine's local password
126 file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) for the UNIX file system. A user's passwords in the
127 two places can differ if desired, though the resulting behavior depends on whether and how the cell is using an
128 AFS-modified login utility.</para>
130 </itemizedlist></para>
133 <sect2 id="Header_37">
134 <title>Differences in the Semantics of Standard UNIX Commands</title>
136 <para>This section summarizes how AFS modifies the functionality of some UNIX commands. <variablelist>
138 <primary>chmod command</primary>
140 <secondary>AFS compared to UNIX</secondary>
144 <primary>commands</primary>
146 <secondary>chmod (AFS compared to UNIX)</secondary>
150 <primary>setuid programs</primary>
152 <secondary>setting mode bits</secondary>
156 <term><emphasis role="bold">The chmod command</emphasis></term>
159 <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can use this command to turn on
160 the setuid, setgid or sticky mode bits on AFS files. For more information, see <link linkend="HDRWQ409">Determining if
161 a Client Can Run Setuid Programs</link>.</para>
164 <primary>chown command</primary>
166 <secondary>AFS compared to UNIX</secondary>
170 <primary>commands</primary>
172 <secondary>chown (AFS compared to UNIX)</secondary>
178 <term><emphasis role="bold">The chown command</emphasis></term>
181 <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can issue this command on AFS
185 <primary>chgrp command</primary>
187 <secondary>AFS compared to UNIX</secondary>
191 <primary>commands</primary>
193 <secondary>chgrp (AFS compared to UNIX)</secondary>
199 <term><emphasis role="bold">The chgrp command</emphasis></term>
202 <para>Only members of the <emphasis role="bold">system:administrators</emphasis> can issue this command on AFS files
203 and directories.</para>
206 <primary>groups command</primary>
208 <secondary>AFS compared to UNIX</secondary>
212 <primary>commands</primary>
214 <secondary>groups (AFS compared to UNIX)</secondary>
220 <term><emphasis role="bold">The groups command</emphasis></term>
223 <para>If the user's AFS tokens are associated with a process authentication group (PAG), the output of this command
224 can include one or two large numbers. To learn about PAGs, see <link linkend="HDRWQ64">Identifying AFS Tokens by
228 <primary>login utility</primary>
230 <secondary>AFS compared to UNIX</secondary>
234 <primary>commands</primary>
236 <secondary>login (AFS compared to UNIX)</secondary>
243 <term><emphasis role="bold">The login utility</emphasis></term>
246 <para>AFS-modified login utilities both log the issuer into the local file system and authenticate the user with the
247 AFS authentication service. See <link linkend="HDRWQ65">Using an AFS-modified login Utility</link>.</para>
250 <primary>ln command</primary>
252 <secondary>AFS compared to UNIX</secondary>
256 <primary>commands</primary>
258 <secondary>ln (AFS compared to UNIX)</secondary>
264 <term><emphasis role="bold">The ln command</emphasis></term>
267 <para>This command cannot create hard links between files in different AFS directories. See <link
268 linkend="HDRWQ32">Creating Hard Links</link>.</para>
271 <primary>sshd command</primary>
273 <secondary>AFS compared to UNIX</secondary>
277 <primary>commands</primary>
279 <secondary>sshd (AFS compared to UNIX)</secondary>
285 <term><emphasis role="bold">The sshd daemon</emphasis></term>
288 <para>The <ulink url="http://www.openssh.org/">OpenSSH project</ulink> provides an sshd daemon that uses the GSSAPI protocol to pass Kerberos tickets between machines.</para>
291 <primary>ssh command</primary>
293 <secondary>AFS compared to UNIX</secondary>
297 <primary>commands</primary>
299 <secondary>ssh (AFS compared to UNIX)</secondary>
303 </variablelist></para>
306 <primary>fsck command</primary>
308 <secondary>AFS compared to UNIX</secondary>
312 <primary>inode-based fileserver</primary>
316 <primary>namei-based fileserver</primary>
320 <primary>commands</primary>
322 <secondary>fsck (AFS compared to UNIX)</secondary>
326 <primary>fsck command</primary>
328 <secondary>AFS version</secondary>
332 <primary>commands</primary>
334 <secondary>fsck (AFS version)</secondary>
338 <primary>directories</primary>
340 <secondary>lost+found</secondary>
344 <primary>lost+found directory</primary>
348 <sect2 id="Header_38">
349 <title>The AFS version of the fsck Command and inode-based fileservers</title>
352 <para>The fileserver uses either of two formats for storing data
353 on disk. The inode format uses a combination of regular files and
354 extra fields stored in the inode data structures that are normally
355 reserved for use by the operating system. The namei interface uses
356 normal file storage and does not use special structures. The
357 choice of storage formats is chosen at compile time and the two
358 formats are incompatible. The storage format must be consistent
359 for the fileserver binaries and all vice partitions on a given
360 fileserver machine.</para>
363 <important><para>This section on fsck advice only applies to the inode-based fileserver binaries. On servers using namei-based binaries, the vendor-supplied fsck is required.</para></important>
365 <para>If you are using AFS fileserver binaries compiled with the inode-based format, never run the standard UNIX <emphasis role="bold">fsck</emphasis> command on an AFS file server machine. It does not
366 understand how the File Server organizes volume data on disk, and so moves all AFS data into the <emphasis
367 role="bold">lost+found</emphasis> directory on the partition.</para>
369 <para>Instead, use the version of the <emphasis role="bold">fsck</emphasis> program that is included in the AFS distribution.
370 The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to replace the vendor-supplied <emphasis
371 role="bold">fsck</emphasis> program with the AFS version as you install each server machine.</para>
373 <para>The AFS version functions like the standard <emphasis role="bold">fsck</emphasis> program on data stored on both UFS and
374 AFS partitions. The appearance of a banner like the following as the <emphasis role="bold">fsck</emphasis> program initializes
375 confirms that you are running the correct one:</para>
378 --- AFS (R) version fsck---
381 <para>where <emphasis>version</emphasis> is the AFS version. For correct results, it must match the AFS version of the server
382 binaries in use on the machine.</para>
384 <para>If you ever accidentally run the standard version of the program, contact your AFS support provider or refer to the <ulink url="http://www.openafs.org/support.html">OpenAFS support web page</ulink> for support options. It is
385 sometimes possible to recover volume data from the <emphasis role="bold">lost+found</emphasis> directory. If the data is not recoverabled, then restoring from backup is recommended.</para>
387 <warning><para>Running the fsck binary supplied by the operating system vendor on an fileserver using inode-based binaries will result in data corruption!</para></warning>
390 <primary>hard link</primary>
392 <secondary>AFS restrictions on</secondary>
396 <primary>restrictions</primary>
398 <secondary>on hard links in AFS</secondary>
403 <title>Creating Hard Links</title>
405 <para>AFS does not allow hard links (created with the UNIX <emphasis role="bold">ln</emphasis> command) between files that
406 reside in different directories, because in that case it is unclear which of the directory's ACLs to associate with the
409 <para>AFS also does not allow hard links to directories, in order to keep the file system organized as a tree.</para>
411 <para>It is possible to create symbolic links (with the UNIX <emphasis role="bold">ln -s</emphasis> command) between elements
412 in two different AFS directories, or even between an element in AFS and one in a machine's local UNIX file system. Do not
413 create a symbolic link to a file whose name begins with either a number sign (<emphasis role="bold">#</emphasis>) or a percent
414 sign (<emphasis role="bold">%</emphasis>), however. The Cache Manager interprets such links as a mount point to a regular or
415 read/write volume, respectively.</para>
418 <primary>fsync system call</primary>
420 <secondary>for files saved on AFS client</secondary>
424 <primary>close system call</primary>
426 <secondary>for files saved on AFS client</secondary>
430 <primary>write</primary>
432 <secondary>system call for files saved on AFS client</secondary>
437 <title>AFS Implements Save on Close</title>
439 <para>When an application issues the UNIX <emphasis role="bold">close</emphasis> system call on a file, the Cache Manager
440 performs a synchronous write of the data to the File Server that maintains the central copy of the file. It does not return
441 control to the application until the File Server has acknowledged receipt of the data. For the <emphasis
442 role="bold">fsync</emphasis> system call, control does not return to the application until the File Server indicates that it
443 has written the data to non-volatile storage on the file server machine.</para>
445 <para>When an application issues the UNIX <emphasis role="bold">write</emphasis> system call, the Cache Manager writes
446 modifications to the local AFS client cache only. If the local machine crashes or an application program exits without issuing
447 the <emphasis role="bold">close</emphasis> system call, it is possible that the modifications are not recorded in the central
448 copy of the file maintained by the File Server. The Cache Manager does sometimes write this type of modified data from the
449 cache to the File Server without receiving the <emphasis role="bold">close</emphasis> or <emphasis
450 role="bold">fsync</emphasis> system call, for example if it needs to free cache chunks for new data. However, it is not
451 generally possible to predict when the Cache Manager transfers modified data to the File Server in this way.</para>
453 <para>The implication is that if an application's <emphasis role="bold">Save</emphasis> option invokes the <emphasis
454 role="bold">write</emphasis> system call rather than <emphasis role="bold">close</emphasis> or <emphasis
455 role="bold">fsync</emphasis>, the changes are not necessarily stored permanently on the File Server machine. Most application
456 programs issue the <emphasis role="bold">close</emphasis> system call for save operations, as well as when they finish
457 handling a file and when they exit.</para>
460 <sect2 id="Header_41">
461 <title>Setuid Programs</title>
464 <primary>setuid programs</primary>
466 <secondary>restrictions on</secondary>
469 <para>Set the UNIX setuid bit only for the local superuser <emphasis role="bold">root</emphasis>; this does not present an
470 automatic security risk: the local superuser has no special privilege in AFS, but only in the local machine's UNIX file system
473 <para>Any file can be marked with the setuid bit, but only members of the <emphasis
474 role="bold">system:administrators</emphasis> group can issue the <emphasis role="bold">chown</emphasis> system call or the
475 <emphasis role="bold">chown</emphasis> command.</para>
477 <para>The <emphasis role="bold">fs setcell</emphasis> command determines whether setuid programs that originate in a foreign
478 cell can run on a given client machine. See <link linkend="HDRWQ409">Determining if a Client Can Run Setuid
479 Programs</link>.</para>
482 <primary>cell</primary>
484 <secondary>name</secondary>
486 <tertiary>choosing</tertiary>
490 <primary>choosing</primary>
492 <secondary>name</secondary>
494 <tertiary>cell</tertiary>
498 <primary>conventions</primary>
500 <secondary>cell name</secondary>
504 <primary>Internet</primary>
506 <secondary>conventions for cell name</secondary>
512 <title>Choosing a Cell Name</title>
514 <para>This section explains how to choose a cell name and explains why choosing an appropriate cell name is important.</para>
516 <para>Your cell name must distinguish your cell from all others in the AFS global namespace. By conventions, the cell name is
517 the second element in any AFS pathname; therefore, a unique cell name guarantees that every AFS pathname uniquely identifies a
518 file, even if cells use the same directory names at lower levels in their local AFS filespace. For example, both the ABC
519 Corporation cell and the State University cell can have a home directory for the user <emphasis role="bold">pat</emphasis>,
520 because the pathnames are distinct: <emphasis role="bold">/afs/abc.com/usr/pat</emphasis> and <emphasis
521 role="bold">/afs/stateu.edu/usr/pat</emphasis>.</para>
523 <para>By convention, cell names follow the ARPA Internet Domain System conventions for site names. If you are already an
524 Internet site, then it is simplest to choose your Internet domain name as the cellname.</para>
526 <para>If you are not an Internet site, it is best to choose a unique Internet-style name, particularly if you plan to connect to
527 the Internet in the future. There are a few
528 constraints on AFS cell names: <itemizedlist>
530 <para>It can contain as many as 64 characters, but shorter names are better because the cell name frequently is part of
531 machine and file names. If your cell name is long, you can reduce pathname length by creating a symbolic link to the
532 complete cell name, at the second level in your file tree. See <link linkend="HDRWQ42">The Second (Cellname)
537 <para>To guarantee it is suitable for different operating system types, the cell name can contain only lowercase
538 characters, numbers, underscores, dashes, and periods. Do not include command shell metacharacters.</para>
542 <para>It can include any number of fields, which are conventionally separated by periods (see the examples below).</para>
546 <para>It must end in a suffix that indicates the type of institution it is, or the country in which it is situated. The
547 following are some of the standard suffixes: <variablelist>
549 <term><emphasis role="bold">.com</emphasis></term>
552 <para>For businesses and other commercial organizations. Example: <emphasis role="bold">abc.com</emphasis> for the
553 ABC Corporation cell.</para>
558 <term><emphasis role="bold">.edu</emphasis></term>
561 <para>For educational institutions such as universities. Example: <emphasis role="bold">stateu.edu</emphasis> for
562 the State University cell.</para>
567 <term><emphasis role="bold">.gov</emphasis></term>
570 <para>For United States government institutions.</para>
575 <term><emphasis role="bold">.mil</emphasis></term>
578 <para>For United States military installations.</para>
581 </variablelist></para>
583 </itemizedlist></para>
586 <primary>Internet</primary>
588 <secondary>Domain Registrar</secondary>
592 <primary>Domain Registrar</primary>
595 <para>Other suffixes are available if none of these are
596 appropriate. Contact a domain registrar to purchase a domain name for
600 <primary>setting</primary>
602 <secondary>cell name</secondary>
606 <primary>cell</primary>
608 <secondary>name</secondary>
610 <tertiary>setting</tertiary>
614 <primary>server machine</primary>
616 <secondary>setting home cell</secondary>
620 <primary>client machine</primary>
622 <secondary>setting home cell</secondary>
625 <sect2 id="Header_43">
626 <title>How to Set the Cell Name</title>
628 <para>The cell name is recorded in two files on the local disk of each file server and client machine. Among other functions,
629 these files define the machine's cell membership and so affect how programs and processes run on the machine; see <link
630 linkend="HDRWQ35">Why Choosing the Appropriate Cell Name is Important</link>. The procedure for setting the cell name is
631 different for the two types of machines.</para>
633 <para>For file server machines, the two files that record the cell name are the <emphasis
634 role="bold">/usr/afs/etc/ThisCell</emphasis> and <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> files. As described
635 more explicitly in the <emphasis>OpenAFS Quick Beginnings</emphasis>, you set the cell name in both by issuing the <emphasis
636 role="bold">bos setcellname</emphasis> command on the first file server machine you install in your cell. It is not usually
637 necessary to issue the command again. If you use the Update Server, it distributes
638 its copy of the <emphasis role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files to additional
639 server machines that you install. If you do not use the Update Server, the <emphasis>OpenAFS Quick
640 Beginnings</emphasis> explains how to copy the files manually.</para>
642 <para>For client machines, the two files that record the cell name are the <emphasis
643 role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> files. You create
644 these files on a per-client basis, either with a text editor or by copying them onto the machine from a central source in AFS.
645 See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link> for details.</para>
647 <para>Change the cell name in these files only when you want to transfer the machine to a different cell (it can only belong
648 to one cell at a time). If the machine is a file server, follow the complete set of instructions in the <emphasis>OpenAFS
649 Quick Beginnings</emphasis> for configuring a new cell. If the machine is a client, all you need to do is change the files
650 appropriately and reboot the machine. The next section explains further the negative consequences of changing the name of an
651 existing cell.</para>
653 <para>To set the default cell name used by most AFS commands without changing the local <emphasis
654 role="bold">/usr/vice/etc/ThisCell</emphasis> file, set the AFSCELL environment variable in the command shell. It is worth
655 setting this variable if you need to complete significant administrative work in a foreign cell.</para>
658 <para>The <emphasis role="bold">fs checkservers</emphasis> and <emphasis role="bold">fs mkmount</emphasis> commands do not
659 use the AFSCELL variable. The <emphasis role="bold">fs checkservers</emphasis> command always defaults to the cell named in
660 the <emphasis role="bold">ThisCell</emphasis> file, unless the <emphasis role="bold">-cell</emphasis> argument is used. The
661 <emphasis role="bold">fs mkmount</emphasis> command defaults to the cell in which the parent directory of the new mount
662 point resides.</para>
666 <primary>ThisCell file (client)</primary>
668 <secondary>how used by programs</secondary>
673 <title>Why Choosing the Appropriate Cell Name is Important</title>
675 <para>Take care to select a cell name that is suitable for long-term use. Changing a cell name later is complicated. An
676 appropriate cell name is important because it is the second element in the pathname of all files in a cell's file tree.
677 Because each cell name is unique, its presence in an AFS pathname makes the pathname unique in the AFS global namespace, even
678 if multiple cells use similar filespace organization at lower levels. For instance, it means that every cell can have a home
679 directory called <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
680 role="bold">/usr/pat</emphasis> without causing a conflict. The presence of the cell name in pathnames also means that users
681 in every cell use the same pathname to access a file, whether the file resides in their local cell or in a foreign
684 <para>Another reason to choose the correct cell name early in the process of installing your cell is that the cell membership
685 defined in each machine's <emphasis role="bold">ThisCell</emphasis> file affects the performance of many programs and
686 processes running on the machine. For instance, AFS commands (<emphasis role="bold">fs</emphasis>, <emphasis
687 role="bold">kas</emphasis>, <emphasis role="bold">pts</emphasis> and <emphasis role="bold">vos</emphasis> commands) by default
688 execute in the cell of the machine on which they are issued. The command interpreters check the <emphasis
689 role="bold">ThisCell</emphasis> file on the local disk and then contact the database server machines listed in the <emphasis
690 role="bold">CellServDB</emphasis> file for the indicated cell (the <emphasis role="bold">bos</emphasis> commands work
691 differently because the issuer always has to name of the machine on which to run the command).</para>
692 <para>The <emphasis role="bold">ThisCell</emphasis> file also determines the cell for which a
693 user receives an AFS token when
694 he or she logs in to a machine.</para>
695 <para>This method of converting passwords into encryption keys means that the same password results in different keys in
696 different cells. Even if a user uses the same password in multiple cells, obtaining a user's token from one cell does not
697 enable unauthorized access to the user's account in another cell.</para>
699 <para>If you change the cell name, you must change the <emphasis role="bold">ThisCell</emphasis> and <emphasis
700 role="bold">CellServDB</emphasis> files on every server and client machine. Failure to change them all can prevent login,
701 because the encryption keys produced by the login utility do not match the keys stored in the Authentication Database. In
702 addition, many commands from the AFS suites do not work as expected.</para>
705 <primary>participation</primary>
707 <secondary>in AFS global namespace</secondary>
711 <primary>AFS</primary>
713 <secondary>global namespace</secondary>
717 <primary>global namespace</primary>
723 <title>Participating in the AFS Global Namespace</title>
725 <para>Participating in the AFS global namespace makes your cell's local file tree visible to AFS users in foreign cells and
726 makes other cells' file trees visible to your local users. It makes file sharing across cells just as easy as sharing within a
727 cell. This section outlines the procedures necessary for participating in the global namespace. <itemizedlist>
729 <para>Participation in the global namespace is not mandatory. Some cells use AFS primarily to facilitate file sharing
730 within the cell, and are not interested in providing their users with access to foreign cells.</para>
734 <para>Making your file tree visible does not mean making it vulnerable. You control how foreign users access your cell
735 using the same protection mechanisms that control local users' access. See <link linkend="HDRWQ40">Granting and Denying
736 Foreign Users Access to Your Cell</link>.</para>
740 <para>The two aspects of participation are independent. A cell can make its file tree visible without allowing its users
741 to see foreign cells' file trees, or can enable its users to see other file trees without advertising its own.</para>
745 <para>You make your cell visible to others by advertising your database server machines. See <link
746 linkend="HDRWQ38">Making Your Cell Visible to Others</link>.</para>
750 <para>You control access to foreign cells on a per-client machine basis. In other words, it is possible to make a foreign
751 cell accessible from one client machine in your cell but not another. See <link linkend="HDRWQ39">Making Other Cells
752 Visible in Your Cell</link>.</para>
754 </itemizedlist></para>
757 <primary>conventions</primary>
759 <secondary>AFS pathnames</secondary>
763 <primary>AFS</primary>
765 <secondary>root directory (/afs)</secondary>
767 <tertiary>on client machine</tertiary>
771 <primary>directories</primary>
773 <secondary>/afs</secondary>
777 <primary>directories</primary>
779 <secondary>/afs/<emphasis>cellname</emphasis></secondary>
783 <primary>cell</primary>
785 <secondary>name</secondary>
787 <tertiary>at second level in file tree</tertiary>
791 <title>What the Global Namespace Looks Like</title>
793 <para>The AFS global namespace appears the same to all AFS cells that participate in it, because they all agree to follow a
794 small set of conventions in constructing pathnames.</para>
796 <para>The first convention is that all AFS pathnames begin with the string <emphasis role="bold">/afs</emphasis> to indicate
797 that they belong to the AFS global namespace.</para>
799 <para>The second convention is that the cell name is the second element in an AFS pathname; it indicates where the file
800 resides (that is, the cell in which a file server machine houses the file). As noted, the presence of a cell name in pathnames
801 makes the global namespace possible, because it guarantees that all AFS pathnames are unique even if cells use the same
802 directory names at lower levels in their AFS filespace.</para>
804 <para>What appears at the third and lower levels in an AFS pathname depends on how a cell has chosen to arrange its filespace.
805 There are some suggested conventional directories at the third level; see <link linkend="HDRWQ43">The Third
809 <primary>cell</primary>
811 <secondary>making local visible to foreign</secondary>
815 <primary>local cell</primary>
817 <secondary>making visible to foreign cells</secondary>
821 <primary>foreign cell</primary>
823 <secondary>making local cell visible</secondary>
828 <title>Making Your Cell Visible to Others</title>
830 <para>You make your cell visible to others by advertising your cell name and database server machines. Just like client
831 machines in the local cell, the Cache Manager on machines in foreign cells use the information to reach your cell's Volume
832 Location (VL) Servers when they need volume and file location information. For authenticated access, foreign clients
833 must be configured with the necessary Kerberos v5 domain-to-realm mappings and Key Distribution Center location information for both the local and remote Kerberos v5 realms.</para>
835 <para>There are two places you can make this information available: <itemizedlist>
837 <primary>files</primary>
839 <secondary>global CellServDB</secondary>
843 <primary>CellServDB file maintained by the AFS Registrar</primary>
845 <secondary>as global update source</secondary>
850 global <emphasis role="bold">CellServDB</emphasis> file
851 maintained by the AFS Registrar. This file lists the name and
852 database server machines of every cell that has agreed to make
853 this information available to other cells. This file is
855 at <ulink url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink></para>
857 <para>To add or change your cell's listing in this file,
858 follow the instructions at
859 <ulink url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink>.
860 It is a good policy to check the file for changes on a
861 regular schedule. An updated copy of this file is included
862 with new releases of OpenAFS.</para>
865 <primary>files</primary>
867 <secondary>CellServDB.local</secondary>
871 <primary>CellServDB.local file</primary>
876 <para>A file called <emphasis role="bold">CellServDB.local</emphasis> in the <emphasis
877 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/service/etc</emphasis> directory
878 of your cell's filespace. List only your cell's database server machines.</para>
880 </itemizedlist></para>
882 <para>Update the files whenever you change the identity of your cell's database server machines. Also update the copies of the
883 <emphasis role="bold">CellServDB</emphasis> files on all of your server machines (in the <emphasis
884 role="bold">/usr/afs/etc</emphasis> directory) and client machines (in the <emphasis role="bold">/usr/vice/etc</emphasis>
885 directory). For instructions, see <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and <link
886 linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
888 <para>Once you have advertised your database server machines, it can be difficult to make your cell invisible again. You can
889 remove the <emphasis role="bold">CellServDB.local</emphasis> file and ask the AFS Registrar to remove your entry from the
890 global <emphasis role="bold">CellServDB</emphasis> file, but other cells probably have an entry for your cell in their local
891 <emphasis role="bold">CellServDB</emphasis> files already. To make those entries invalid, you must change the names or IP
892 addresses of your database server machines.</para>
894 <para>Your cell does not have to be invisible to be inaccessible, however. To make your cell completely inaccessible to
895 foreign users, remove the <emphasis role="bold">system:anyuser</emphasis> group from all ACLs at the top three levels of your
896 filespace; see <link linkend="HDRWQ40">Granting and Denying Foreign Users Access to Your Cell</link>.</para>
899 <primary>cell</primary>
901 <secondary>making foreign visible to local</secondary>
905 <primary>local cell</primary>
907 <secondary>making foreign cells visible in</secondary>
911 <primary>foreign cell</primary>
913 <secondary>making visible in local cell</secondary>
917 <primary>client machine</primary>
919 <secondary>making foreign cell visible</secondary>
924 <title>Making Other Cells Visible in Your Cell</title>
926 <para>To make a foreign cell's filespace visible on a client machine
927 in your cell that is not configured
928 for <emphasis role="bold">Freelance Mode</emphasis>
929 or <emphasis role="bold">Dynamic Root</emphasis> mode, perform the
930 following three steps:
933 <para>Mount the cell's <emphasis role="bold">root.cell</emphasis> volume at the second level in your cell's filespace
934 just below the <emphasis role="bold">/afs</emphasis> directory. Use the <emphasis role="bold">fs mkmount</emphasis>
935 command with the <emphasis role="bold">-cell</emphasis> argument as instructed in <link linkend="HDRWQ213">To create a
936 cellular mount point</link>.</para>
940 <para>Mount AFS at the <emphasis role="bold">/afs</emphasis> directory on the client machine. The <emphasis
941 role="bold">afsd</emphasis> program, which initializes the Cache Manager, performs the mount automatically at the
942 directory named in the first field of the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file or by the
943 command's <emphasis role="bold">-mountdir</emphasis> argument. Mounting AFS at an alternate location makes it impossible
944 to reach the filespace of any cell that mounts its <emphasis role="bold">root.afs</emphasis> and <emphasis
945 role="bold">root.cell</emphasis> volumes at the conventional locations. See <link linkend="HDRWQ395">Displaying and
946 Setting the Cache Size and Location</link>.</para>
950 <para>Create an entry for the cell in the list of database server machines which the Cache Manager maintains in kernel
953 <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on every client machine's local disk lists the
954 database server machines for the local and foreign cells. The <emphasis role="bold">afsd</emphasis> program reads the
955 contents of the <emphasis role="bold">CellServDB</emphasis> file into kernel memory as it initializes the Cache Manager.
956 You can also use the <emphasis role="bold">fs newcell</emphasis> command to add or alter entries in kernel memory
957 directly between reboots of the machine. See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server
958 Machines</link>.</para>
960 </orderedlist></para>
962 <para>Non-windows client machines may
963 enable <emphasis role="bold">Dynamic Root Mode</emphasis> by using
964 the <emphasis role="bold">-dynroot</emphasis> option
965 to <emphasis role="bold">afsd</emphasis>. When this option is
966 enabled, all cells listed in
967 the <emphasis role="bold">CellServDB</emphasis> file will appear in
968 the <emphasis role="bold">/afs</emphasis> directory. The contents of
969 the <emphasis role="bold">root.afs</emphasis> volume will be ignored.
972 <para>Windows client machines may
973 enable <emphasis role="bold">Freelance Mode</emphasis> during client
974 installation or by setting
975 the <emphasis role="bold">FreelanceClient</emphasis> setting
976 under <emphasis role="bold">Service Parameters</emphasis> in the
977 Windows Registry as mentioned in
978 the <ulink url="http://docs.openafs.org/ReleaseNotesWindows/">Release
979 Notes</ulink>. When this option is enabled,
980 the <emphasis role="bold">root.afs</emphasis> volume is ignored and
981 a mounpoint for each cell is automatically created in the
982 the <emphasis role="bold">\\AFS</emphasis> directory when the
983 folder <emphasis role="bold">\\AFS\<replaceable>cellname</replaceable></emphasis>
984 is accessed and the foreign Volume Location servers can be reached.
986 <para>Note that making a foreign cell visible to client machines does not guarantee that your users can access its filespace.
987 The ACLs in the foreign cell must also grant them the necessary permissions.</para>
990 <primary>cell</primary>
992 <secondary>granting local access to foreign users</secondary>
996 <primary>local cell</primary>
998 <secondary>granting foreign users access to</secondary>
1002 <sect2 id="HDRWQ40">
1003 <title>Granting and Denying Foreign Users Access to Your Cell</title>
1005 <para>Making your cell visible in the AFS global namespace does not take away your control over the way in which users from
1006 foreign cells access your file tree.</para>
1008 <para>By default, foreign users access your cell as the user <emphasis role="bold">anonymous</emphasis>, which means they have
1009 only the permissions granted to the <emphasis role="bold">system:anyuser</emphasis> group on each directory's ACL. Normally
1010 these permissions are limited to the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and
1011 <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permissions.</para>
1013 <para>There are three ways to grant wider access to foreign users: <itemizedlist>
1015 <para>Grant additional permissions to the <emphasis role="bold">system:anyuser</emphasis> group on certain ACLs. Keep in
1016 mind, however, that all users can then access that directory in the indicated way (not just specific foreign users you
1017 have in mind).</para>
1021 <para>Enable automatic registration for users in the foreign
1022 cell. This may be done by creating a cross-realm trust in
1023 the <emphasis role="bold">Kerberos Database</emphasis>. Then
1025 named <emphasis role="bold">system:authuser<replaceable>@FOREIGN.REALM</replaceable></emphasis>
1026 and give it a group quota greater than the number of foreign
1027 users expected to be registered. After the cross-realm trust
1028 and the PTS group are created,
1029 the <ulink url="http://docs.openafs.org/Reference/1/aklog.html">aklog</ulink>
1030 command will automatically register foreign users as
1031 needed. Consult the documentation for
1032 your <emphasis role="bold">Kerberos Server</emphasis> for
1033 instructions on how to establish a cross-realm trust.
1038 <para>Create a local authentication account for specific
1039 foreign users, by creating entries in the Protection Database,
1040 the Kerberos Database, and the local password file.</para>
1042 </itemizedlist></para>
1045 <primary>cell</primary>
1047 <secondary>filespace configuration issues</secondary>
1051 <primary>configuring</primary>
1053 <secondary>filespace, issues</secondary>
1057 <primary>file tree</primary>
1059 <secondary>conventions</secondary>
1061 <tertiary>for configuring</tertiary>
1066 <sect1 id="HDRWQ41">
1067 <title>Configuring Your AFS Filespace</title>
1069 <para>This section summarizes the issues to consider when configuring your AFS filespace. For a discussion of creating volumes
1070 that correspond most efficiently to the filespace's directory structure, see <link linkend="HDRWQ44">Creating Volumes to
1071 Simplify Administration</link>.</para>
1074 <para><emphasis role="bold">For Windows users:</emphasis> Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather
1075 than a forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname. The hierarchical
1076 organization of the filespace is however the same as on a UNIX machine.</para>
1079 <para>AFS pathnames must follow a few conventions so the AFS global namespace looks the same from any AFS client machine. There
1080 are corresponding conventions to follow in building your file tree, not just because pathnames reflect the structure of a file
1081 tree, but also because the AFS Cache Manager expects a certain configuration.</para>
1084 <primary>AFS</primary>
1086 <secondary>root directory (/afs)</secondary>
1088 <tertiary>in cell filespace</tertiary>
1092 <primary>directories</primary>
1094 <secondary>/afs</secondary>
1097 <sect2 id="Header_51">
1098 <title>The Top /afs Level</title>
1100 <para>The first convention is that the top level in your file tree be called the <emphasis role="bold">/afs</emphasis>
1101 directory. If you name it something else, then you must use the <emphasis role="bold">-mountdir</emphasis> argument with the
1102 <emphasis role="bold">afsd</emphasis> program to get Cache Managers to mount AFS properly. You cannot participate in the AFS
1103 global namespace in that case.</para>
1106 <primary>cell</primary>
1108 <secondary>name</secondary>
1110 <tertiary>at second level in file tree</tertiary>
1114 <primary>directories</primary>
1116 <secondary>/afs/<emphasis>cellname</emphasis></secondary>
1120 <primary>symbolic link</primary>
1122 <secondary>at second level of AFS pathname</secondary>
1126 <sect2 id="HDRWQ42">
1127 <title>The Second (Cellname) Level</title>
1129 <para>The second convention is that just below the <emphasis role="bold">/afs</emphasis> directory you place directories
1130 corresponding to each cell whose file tree is visible and accessible from the local cell. Minimally, there must be a directory
1131 for the local cell. Each such directory is a mount point to the indicated cell's <emphasis role="bold">root.cell</emphasis>
1132 volume. For example, in the ABC Corporation cell, <emphasis role="bold">/afs/abc.com</emphasis> is a mount point for the
1133 cell's own <emphasis role="bold">root.cell</emphasis> volume and <emphasis role="bold">stateu.edu</emphasis> is a mount point
1134 for the State University cell's <emphasis role="bold">root.cell</emphasis> volume. The <emphasis role="bold">fs
1135 lsmount</emphasis> command displays the mount points.</para>
1138 % <emphasis role="bold">fs lsmount /afs/abc.com</emphasis>
1139 '/afs/abc.com' is a mount point for volume '#root.cell'
1140 % <emphasis role="bold">fs lsmount /afs/stateu.edu</emphasis>
1141 '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
1144 <para>To reduce the amount of typing necessary in pathnames, you can create a symbolic link with an abbreviated name to the
1145 mount point of each cell your users frequently access (particularly the home cell). In the ABC Corporation cell, for instance,
1146 <emphasis role="bold">/afs/abc</emphasis> is a symbolic link to the <emphasis role="bold">/afs/abc.com</emphasis> mount point,
1147 as the <emphasis role="bold">fs lsmount</emphasis> command reveals.</para>
1150 % <emphasis role="bold">fs lsmount /afs/abc</emphasis>
1151 '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
1155 <primary>file tree</primary>
1157 <secondary>conventions</secondary>
1159 <tertiary>third level</tertiary>
1163 <primary>directories</primary>
1165 <secondary>conventional under /afs/cellname</secondary>
1169 <sect2 id="HDRWQ43">
1170 <title>The Third Level</title>
1172 <para>You can organize the third level of your cell's file tree any way you wish. The following list describes directories
1173 that appear at this level in the conventional configuration: <variablelist>
1175 <term><emphasis role="bold">common</emphasis></term>
1178 <para>This directory contains programs and files needed by users working on machines of all system types, such as text
1179 editors, online documentation files, and so on. Its <emphasis role="bold">/etc</emphasis> subdirectory is a logical
1180 place to keep the central update sources for files used on all of your cell's client machines, such as the <emphasis
1181 role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files.</para>
1186 <term><emphasis role="bold">public</emphasis></term>
1189 <para>A directory accessible to anyone who can access your filespace, because its ACL grants the <emphasis
1190 role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
1191 role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group. It is useful if
1192 you want to enable your users to make selected information available to everyone, but do not want to grant foreign
1193 users access to the contents of the <emphasis role="bold">usr</emphasis> directory which houses user home directories
1194 (and is also at this level). It is conventional to create a subdirectory for each of your cell's users.</para>
1199 <term><emphasis role="bold">service</emphasis></term>
1202 <para>This directory contains files and subdirectories that help cells coordinate resource sharing. For a list of the
1203 proposed standard files and subdirectories to create, call or write to AFS Product Support.</para>
1205 <para>As an example, files that other cells expect to find in this directory's <emphasis role="bold">etc</emphasis>
1206 subdirectory can include the following: <itemizedlist>
1208 <para><emphasis role="bold">CellServDB.export</emphasis>, a list of database server machines for many
1213 <para><emphasis role="bold">CellServDB.local</emphasis>, a list of the cell's own database server
1218 <para><emphasis role="bold">passwd</emphasis>, a copy of the local password file (<emphasis
1219 role="bold">/etc/passwd</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
1223 <para><emphasis role="bold">group</emphasis>, a copy of the local groups file (<emphasis
1224 role="bold">/etc/group</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
1226 </itemizedlist></para>
1231 <term><emphasis>sys_type</emphasis></term>
1234 <para>A separate directory for storing the server and client binaries for each system type you use in the cell.
1235 Configuration is simplest if you use the system type names assigned in the AFS distribution, particularly if you wish
1236 to use the <emphasis role="bold">@sys</emphasis> variable in pathnames (see <link linkend="HDRWQ56">Using the @sys
1237 Variable in Pathnames</link>). The <emphasis>OpenAFS Release Notes</emphasis> lists the conventional name for each
1238 supported system type.</para>
1240 <para>Within each such directory, create directories named <emphasis role="bold">bin</emphasis>, <emphasis
1241 role="bold">etc</emphasis>, <emphasis role="bold">usr</emphasis>, and so on, to store the programs normally kept in
1242 the <emphasis role="bold">/bin</emphasis>, <emphasis role="bold">/etc</emphasis> and <emphasis
1243 role="bold">/usr</emphasis> directories on a local disk. Then create symbolic links from the local directories on
1244 client machines into AFS; see <link linkend="HDRWQ55">Configuring the Local Disk</link>. Even if you do not choose to
1245 use symbolic links in this way, it can be convenient to have central copies of system binaries in AFS. If binaries are
1246 accidentally removed from a machine, you can recopy them onto the local disk from AFS rather than having to recover
1247 them from tape</para>
1252 <term><emphasis role="bold">usr</emphasis></term>
1255 <para>This directory contains home directories for your local users. As discussed in the previous entry for the
1256 <emphasis role="bold">public</emphasis> directory, it is often practical to protect this directory so that only
1257 locally authenticated users can access it. This keeps the contents of your user's home directories as secure as
1260 <para>If your cell is quite large, directory lookup can be slowed if you put all home directories in a single
1261 <emphasis role="bold">usr</emphasis> directory. For suggestions on distributing user home directories among multiple
1262 grouping directories, see <link linkend="HDRWQ59">Grouping Home Directories</link>.</para>
1267 <term><emphasis role="bold">wsadmin</emphasis></term>
1270 <para>This directory contains prototype, configuration and library files for use with the <emphasis
1271 role="bold">package</emphasis> program. See <link linkend="HDRWQ419">Configuring Client Machines with the package
1272 Program</link>.</para>
1275 </variablelist></para>
1278 <primary>volume name</primary>
1280 <secondary>conventions for</secondary>
1284 <primary>conventions</primary>
1286 <secondary>volume names</secondary>
1290 <primary>volume</primary>
1292 <secondary>separate for each top level directory</secondary>
1296 <primary>file tree</primary>
1298 <secondary>creating volumes to match top level directories</secondary>
1303 <sect1 id="HDRWQ44">
1304 <title>Creating Volumes to Simplify Administration</title>
1306 <para>This section discusses how to create volumes in ways that make administering your system easier.</para>
1308 <para>At the top levels of your file tree (at least through the third level), each directory generally corresponds to a separate
1309 volume. Some cells also configure the subdirectories of some third level directories as separate volumes. Common examples are
1310 the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/common</emphasis> and
1311 <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis>
1314 <para>You do not have to create a separate volume for every directory level in a tree, but the advantage is that each volume
1315 tends to be smaller and easier to move for load balancing. The overhead for a mount point is no greater than for a standard
1316 directory, nor does the volume structure itself require much disk space. Most cells find that below the fourth level in the
1317 tree, using a separate volume for each directory is no longer efficient. For instance, while each user's home directory (at the
1318 fourth level in the tree) corresponds to a separate volume, all of the subdirectories in the home directory normally reside in
1319 the same volume.</para>
1321 <para>Keep in mind that only one volume can be mounted at a given directory location in the tree. In contrast, a volume can be
1322 mounted at several locations, though this is not recommended because it distorts the hierarchical nature of the file tree,
1323 potentially causing confusion.</para>
1326 <primary>volume name</primary>
1328 <secondary>restrictions</secondary>
1332 <primary>restrictions</primary>
1334 <secondary>on volume names</secondary>
1338 <primary>volume name</primary>
1340 <secondary>two required</secondary>
1344 <primary>volume</primary>
1346 <secondary>root (root.afs and root.cell)</secondary>
1350 <primary>root volumes (root.afs and root.cell)</primary>
1353 <sect2 id="Header_55">
1354 <title>Assigning Volume Names</title>
1356 <para>You can name your volumes anything you choose, subject to a few restrictions: <itemizedlist>
1358 <para>Read/write volume names can be up to 22 characters in length. The maximum length for volume names is 31
1359 characters, and there must be room to add the <emphasis role="bold">.readonly</emphasis> extension on read-only
1364 <para>Do not add the <emphasis role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extensions
1365 to volume names yourself, even if they are appropriate. The Volume Server adds them automatically as it creates a
1366 read-only or backup version of a volume.</para>
1370 <para>There must be volumes named <emphasis role="bold">root.afs</emphasis> and <emphasis
1371 role="bold">root.cell</emphasis>, mounted respectively at the top (<emphasis role="bold">/afs</emphasis>) level in the
1372 filespace and just below that level, at the cell's name (for example, at <emphasis role="bold">/afs/abc.com</emphasis>
1373 in the ABC Corporation cell).</para>
1375 <para>Deviating from these names only creates confusion and extra work. Changing the name of the <emphasis
1376 role="bold">root.afs</emphasis> volume, for instance, means that you must use the <emphasis
1377 role="bold">-rootvol</emphasis> argument to the <emphasis role="bold">afsd</emphasis> program on every client machine,
1378 to name the alternate volume.</para>
1380 <para>Similarly, changing the <emphasis role="bold">root.cell</emphasis> volume name prevents users in foreign cells
1381 from accessing your filespace, if the mount point for your cell in their filespace refers to the conventional <emphasis
1382 role="bold">root.cell</emphasis> name. Of course, this is one way to make your cell invisible to other cells.</para>
1384 </itemizedlist></para>
1386 <para>It is best to assign volume names that indicate the type of data they contain, and to use similar names for volumes with
1387 similar contents. It is also helpful if the volume name is similar to (or at least has elements in common with) the name of
1388 the directory at which it is mounted. Understanding the pattern then enables you accurately to guess what a volume contains
1389 and where it is mounted.</para>
1391 <para>Many cells find that the most effective volume naming scheme puts a common prefix on the names of all related volumes.
1392 <link linkend="TBLVOL-PREFIX">Table 1</link> describes the recommended prefixing scheme.</para>
1394 <table id="TBLVOL-PREFIX" label="1">
1395 <title>Suggested volume prefixes</title>
1398 <colspec colwidth="14*" />
1400 <colspec colwidth="28*" />
1402 <colspec colwidth="22*" />
1404 <colspec colwidth="36*" />
1408 <entry><emphasis role="bold">Prefix</emphasis></entry>
1410 <entry><emphasis role="bold">Contents</emphasis></entry>
1412 <entry><emphasis role="bold">Example Name</emphasis></entry>
1414 <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
1420 <entry><emphasis role="bold">common.</emphasis></entry>
1422 <entry>popular programs and files</entry>
1424 <entry><emphasis role="bold">common.etc</emphasis></entry>
1426 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1427 role="bold">/common/etc</emphasis></entry>
1431 <entry><emphasis role="bold">src.</emphasis></entry>
1433 <entry>source code</entry>
1435 <entry><emphasis role="bold">src.afs</emphasis></entry>
1437 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1438 role="bold">/src/afs</emphasis></entry>
1442 <entry><emphasis role="bold">proj.</emphasis></entry>
1444 <entry>project data</entry>
1446 <entry><emphasis role="bold">proj.portafs</emphasis></entry>
1448 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1449 role="bold">/proj/portafs</emphasis></entry>
1453 <entry><emphasis role="bold">test.</emphasis></entry>
1455 <entry>testing or other temporary data</entry>
1457 <entry><emphasis role="bold">test.smith</emphasis></entry>
1459 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1460 role="bold">/usr/smith/test</emphasis></entry>
1464 <entry><emphasis role="bold">user.</emphasis></entry>
1466 <entry>user home directory data</entry>
1468 <entry><emphasis role="bold">user.terry</emphasis></entry>
1470 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1471 role="bold">/usr/terry</emphasis></entry>
1475 <entry>sys_type<emphasis role="bold">.</emphasis></entry>
1477 <entry>programs compiled for an operating system type</entry>
1479 <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
1481 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1482 role="bold">/rs_aix42/bin</emphasis></entry>
1488 <para><link linkend="TBLPREFIX-EXAMPLE">Table 2</link> is a more specific example for a cell's <emphasis
1489 role="bold">rs_aix42</emphasis> system volumes and directories:</para>
1491 <table id="TBLPREFIX-EXAMPLE" label="2">
1492 <title>Example volume-prefixing scheme</title>
1495 <colspec colwidth="14*" />
1497 <colspec colwidth="28*" />
1499 <colspec colwidth="22*" />
1501 <colspec colwidth="36*" />
1505 <entry><emphasis role="bold">Example Name</emphasis></entry>
1507 <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
1513 <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
1515 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1516 role="bold">/rs_aix42/bin</emphasis>, <emphasis
1517 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/rs_aix42/bin</emphasis></entry>
1521 <entry><emphasis role="bold">rs_aix42.etc</emphasis></entry>
1523 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1524 role="bold">/rs_aix42/etc</emphasis></entry>
1528 <entry><emphasis role="bold">rs_aix42.usr</emphasis></entry>
1530 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1531 role="bold">/rs_aix42/usr</emphasis></entry>
1535 <entry><emphasis role="bold">rs_aix42.usr.afsws</emphasis></entry>
1537 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1538 role="bold">/rs_aix42/usr/afsws</emphasis></entry>
1542 <entry><emphasis role="bold">rs_aix42.usr.lib</emphasis></entry>
1544 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1545 role="bold">/rs_aix42/usr/lib</emphasis></entry>
1549 <entry><emphasis role="bold">rs_aix42.usr.bin</emphasis></entry>
1551 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1552 role="bold">/rs_aix42/usr/bin</emphasis></entry>
1556 <entry><emphasis role="bold">rs_aix42.usr.etc</emphasis></entry>
1558 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1559 role="bold">/rs_aix42/usr/etc</emphasis></entry>
1563 <entry><emphasis role="bold">rs_aix42.usr.inc</emphasis></entry>
1565 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1566 role="bold">/rs_aix42/usr/inc</emphasis></entry>
1570 <entry><emphasis role="bold">rs_aix42.usr.man</emphasis></entry>
1572 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1573 role="bold">/rs_aix42/usr/man</emphasis></entry>
1577 <entry><emphasis role="bold">rs_aix42.usr.sys</emphasis></entry>
1579 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1580 role="bold">/rs_aix42/usr/sys</emphasis></entry>
1584 <entry><emphasis role="bold">rs_aix42.usr.local</emphasis></entry>
1586 <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1587 role="bold">/rs_aix42/usr/local</emphasis></entry>
1593 <para>There are several advantages to this scheme: <itemizedlist>
1595 <para>The volume name is similar to the mount point name in the filespace. In all of the entries in <link
1596 linkend="TBLPREFIX-EXAMPLE">Table 2</link>, for example, the only difference between the volume and mount point name is
1597 that the former uses periods as separators and the latter uses slashes. Another advantage is that the volume name
1598 indicates the contents, or at least suggests the directory on which to issue the <emphasis role="bold">ls</emphasis>
1599 command to learn the contents.</para>
1603 <para>It makes it easy to manipulate groups of related volumes at one time. In particular, the <emphasis role="bold">vos
1604 backupsys</emphasis> command's <emphasis role="bold">-prefix</emphasis> argument enables you to create a backup version
1605 of every volume whose name starts with the same string of characters. Making a backup version of each volume is one of
1606 the first steps in backing up a volume with the AFS Backup System, and doing it for many volumes with one command saves
1607 you a good deal of typing. For instructions for creating backup volumes, see <link linkend="HDRWQ201">Creating Backup
1608 Volumes</link>, For information on the AFS Backup System, see <link linkend="HDRWQ248">Configuring the AFS Backup
1609 System</link> and <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
1613 <para>It makes it easy to group related volumes together on a partition. Grouping related volumes together has several
1614 advantages of its own, discussed in <link linkend="HDRWQ49">Grouping Related Volumes on a Partition</link>.</para>
1616 </itemizedlist></para>
1619 <primary>volume</primary>
1621 <secondary>grouping related on same partition</secondary>
1625 <primary>disk partition</primary>
1627 <secondary>grouping related volumes on</secondary>
1631 <sect2 id="HDRWQ49">
1632 <title>Grouping Related Volumes on a Partition</title>
1634 <para>If your cell is large enough to make it practical, consider grouping related volumes together on a partition. In
1635 general, you need at least three file server machines for volume grouping to be effective. Grouping has several advantages,
1636 which are most obvious when the file server machine becomes inaccessible: <itemizedlist>
1638 <para>If you keep a hardcopy record of the volumes on a partition, you know which volumes are unavailable. You can keep
1639 such a record without grouping related volumes, but a list composed of unrelated volumes is much harder to maintain.
1640 Note that the record must be on paper, because the outage can prevent you from accessing an online copy or from issuing
1641 the <emphasis role="bold">vos listvol</emphasis> command, which gives you the same information.</para>
1645 <para>The effect of an outage is more localized. For example, if all of the binaries for a given system type are on one
1646 partition, then only users of that system type are affected. If a partition houses binary volumes from several system
1647 types, then an outage can affect more people, particularly if the binaries that remain available are interdependent with
1648 those that are not available.</para>
1650 </itemizedlist></para>
1652 <para>The advantages of grouping related volumes on a partition do not necessarily extend to the grouping of all related
1653 volumes on one file server machine. For instance, it is probably unwise in a cell with two file server machines to put all
1654 system volumes on one machine and all user volumes on the other. An outage of either machine probably affects everyone.</para>
1656 <para>Admittedly, the need to move volumes for load balancing purposes can limit the practicality of grouping related volumes.
1657 You need to weigh the complementary advantages case by case.</para>
1660 <primary>replication</primary>
1662 <secondary>appropriate volumes</secondary>
1666 <primary>volume</primary>
1668 <secondary>type to replicate</secondary>
1672 <primary>volume</primary>
1674 <secondary>where to place replicated</secondary>
1678 <primary>read-only volume</primary>
1680 <secondary>selecting site</secondary>
1684 <sect2 id="HDRWQ50">
1685 <title>When to Replicate Volumes</title>
1687 <para>As discussed in <link linkend="HDRWQ15">Replication</link>, replication refers to making a copy, or clone, of a
1688 read/write source volume and then placing the copy on one or more additional file server machines. Replicating a volume can
1689 increase the availability of the contents. If one file server machine housing the volume becomes inaccessible, users can still
1690 access the copy of the volume stored on a different machine. No one machine is likely to become overburdened with requests for
1691 a popular file, either, because the file is available from several machines.</para>
1693 <para>However, replication is not appropriate for all cells. If a cell does not have much disk space, replication can be
1694 unduly expensive, because each clone not on the same partition as the read/write source takes up as much disk space as its
1695 source volume did at the time the clone was made. Also, if you have only one file server machine, replication uses up disk
1696 space without increasing availability.</para>
1698 <para>Replication is also not appropriate for volumes that change frequently. You must issue the <emphasis role="bold">vos
1699 release</emphasis> command every time you need to update a read-only volume to reflect changes in its read/write
1702 <para>For both of these reasons, replication is appropriate only for popular volumes whose contents do not change very often,
1703 such as system binaries and other volumes mounted at the upper levels of your filespace. User volumes usually exist only in a
1704 read/write version since they change so often.</para>
1706 <para>If you are replicating any volumes, you must replicate the <emphasis role="bold">root.afs</emphasis> and <emphasis
1707 role="bold">root.cell</emphasis> volumes, preferably at two or three sites each (even if your cell only has two or three file
1708 server machines). The Cache Manager needs to pass through the directories corresponding to the <emphasis
1709 role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes as it interprets any pathname. The
1710 unavailability of these volumes makes all other volumes unavailable too, even if the file server machines storing the other
1711 volumes are still functioning.</para>
1713 <para>Another reason to replicate the <emphasis role="bold">root.afs</emphasis> volume is that it can lessen the load on the
1714 File Server machine. The Cache Manager has a bias to access a read-only version of the <emphasis
1715 role="bold">root.afs</emphasis> volume if it is replicate, which puts the Cache Manager onto the <emphasis>read-only
1716 path</emphasis> through the AFS filespace. While on the read-only path, the Cache Manager attempts to access a read-only copy
1717 of replicated volumes. The File Server needs to track only one callback per Cache Manager for all of the data in a read-only
1718 volume, rather than the one callback per file it must track for read/write volumes. Fewer callbacks translate into a smaller
1719 load on the File Server.</para>
1721 <para>If the <emphasis role="bold">root.afs</emphasis> volume is not replicated, the Cache Manager follows a read/write path
1722 through the filespace, accessing the read/write version of each volume. The File Server distributes and tracks a separate
1723 callback for each file in a read/write volume, imposing a greater load on it.</para>
1725 <para>For more on read/write and read-only paths, see <link linkend="HDRWQ209">The Rules of Mount Point
1726 Traversal</link>.</para>
1728 <para>It also makes sense to replicate system binary volumes in many cases, as well as the volume corresponding to the
1729 <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis> directory and
1730 the volumes corresponding to the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1731 role="bold">/common</emphasis> directory and its subdirectories.</para>
1733 <para>It is a good idea to place a replica on the same partition as the read/write source. In this case, the read-only volume
1734 is a clone (like a backup volume): it is a copy of the source volume's vnode index, rather than a full copy of the volume
1735 contents. Only if the read/write volume moves to another partition or changes substantially does the read-only volume consume
1736 significant disk space. Read-only volumes kept on other partitions always consume the full amount of disk space that the
1737 read/write source consumed when the read-only volume was created.</para>
1740 <sect2 id="Header_58">
1741 <title>The Default Quota and ACL on a New Volume</title>
1743 <para>Every AFS volume has associated with it a quota that limits the amount of disk space the volume is allowed to use. To
1744 set and change quota, use the commands described in <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current
1747 <para>By default, every new volume is assigned a space quota of 5000 KB blocks unless you include the <emphasis
1748 role="bold">-maxquota</emphasis> argument to the <emphasis role="bold">vos create</emphasis> command. Also by default, the ACL
1749 on the root directory of every new volume grants all permissions to the members of the <emphasis
1750 role="bold">system:administrators</emphasis> group. To learn how to change these values when creating an account with
1751 individual commands, see <link linkend="HDRWQ503">To create one user account with individual commands</link>. When using
1752 <emphasis role="bold">uss</emphasis> commands to create accounts, you can specify alternate ACL and quota values in the
1753 template file's <emphasis role="bold">V</emphasis> instruction; see <link linkend="HDRWQ473">Creating a Volume with the V
1754 Instruction</link>.</para>
1757 <primary>server machine</primary>
1759 <secondary>configuration issues</secondary>
1763 <primary>configuring</primary>
1765 <secondary>file server machine, issues</secondary>
1769 <primary>roles for server machine</primary>
1771 <secondary>summary</secondary>
1775 <primary>server machine</primary>
1777 <secondary>roles for</secondary>
1779 <tertiary>summary</tertiary>
1783 <primary>server machine</primary>
1785 <secondary>first installed</secondary>
1790 <sect1 id="HDRWQ51">
1791 <title>Configuring Server Machines</title>
1793 <para>This section discusses some issues to consider when configuring server machines, which store AFS data, transfer it to
1794 client machines on request, and house the AFS administrative databases. To learn about client machines, see <link
1795 linkend="HDRWQ54">Configuring Client Machines</link>.</para>
1797 <para>If your cell has more than one AFS server machine, you can configure them to perform specialized functions. A machine can
1798 assume one or more of the roles described in the following list. For more details, see <link linkend="HDRWQ90">The Four Roles
1799 for File Server Machines</link>. <itemizedlist>
1801 <para>A <emphasis>simple file server</emphasis> machine runs only the processes that store and deliver AFS files to client
1802 machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
1803 requirements.</para>
1807 <para>A <emphasis>database server machine</emphasis> runs the four database server processes that maintain AFS's
1808 replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
1813 <para>A <emphasis>binary distribution machine</emphasis> distributes the AFS server binaries for its system type to all
1814 other server machines of that system type.</para>
1818 <para>The single <emphasis>system control machine</emphasis> distributes common server configuration files to all other
1819 server machines in the cell, in a cell that runs the United States edition of AFS (cells that use the international
1820 edition of AFS must not use the system control machine for this purpose). The machine conventionally also serves as the
1821 time synchronization source for the cell, adjusting its clock according to a time source outside the cell.</para>
1823 </itemizedlist></para>
1825 <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to configure your cell's first file server machine to
1826 assume all four roles. The <emphasis>OpenAFS Quick Beginnings</emphasis> chapter on installing additional server machines also
1827 explains how to configure them to perform one or more roles.</para>
1830 <primary>database server machine</primary>
1832 <secondary>reason to run three</secondary>
1836 <primary>distribution</primary>
1838 <secondary>of databases</secondary>
1842 <primary>databases, distributed</primary>
1846 <primary>distributed databases</primary>
1849 <sect2 id="HDRWQ52">
1850 <title>Replicating the OpenAFS Administrative Databases</title>
1852 <para>The AFS administrative databases are housed on database server machines and store information that is crucial for
1853 correct cell functioning. Both server processes and Cache Managers access the information frequently: <itemizedlist>
1855 <para>Every time a Cache Manager fetches a file from a directory that it has not previously accessed, it must look up
1856 the file's location in the Volume Location Database (VLDB).</para>
1860 <para>Every time a user obtains an AFS token from the Authentication Server, the server looks up the user's password in
1861 the Authentication Database.</para>
1865 <para>The first time that a user accesses a volume housed on a specific file server machine, the File Server contacts
1866 the Protection Server for a list of the user's group memberships as recorded in the Protection Database.</para>
1870 <para>Every time you back up a volume using the AFS Backup System, the Backup Server creates records for it in the
1871 Backup Database.</para>
1873 </itemizedlist></para>
1875 <para>Maintaining your cell is simplest if the first machine has the lowest IP address of any machine you plan to use as a
1876 database server machine. If you later decide to use a machine with a lower IP address as a database server machine, you must
1877 update the <emphasis role="bold">CellServDB</emphasis> file on all clients before introducing the new machine.</para>
1879 <para>If your cell has more than one server machine, it is best to run more than one as a database server machine (but more
1880 than three are rarely necessary). Replicating the administrative databases in this way yields the same benefits as replicating
1881 volumes: increased availability and reliability. If one database server machine or process stops functioning, the information
1882 in the database is still available from others. The load of requests for database information is spread across multiple
1883 machines, preventing any one from becoming overloaded.</para>
1885 <para>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
1886 that all copies of the database always be identical, so it is not acceptable to record changes in only some of them. To
1887 synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <link
1888 linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
1890 <para>If your cell has only one file server machine, it must also serve as a database server machine. If you cell has two file
1891 server machines, it is not always advantageous to run both as database server machines. If a server, process, or network
1892 failure interrupts communications between the database server processes on the two machines, it can become impossible to
1893 update the information in the database because neither of them can alone elect itself as the synchronization site.</para>
1896 <primary>server machine</primary>
1898 <secondary>protecting directories on local disk</secondary>
1902 <primary>local disk</primary>
1904 <secondary>protecting on file server machine</secondary>
1908 <sect2 id="HDRWQ53">
1909 <title>AFS Files on the Local Disk</title>
1911 <para>It is generally simplest to store the binaries for all AFS server processes in the <emphasis
1912 role="bold">/usr/afs/bin</emphasis> directory on every file server machine, even if some processes do not actively run on the
1913 machine. This makes it easier to reconfigure a machine to fill a new role.</para>
1915 <para>For security reasons, the <emphasis role="bold">/usr/afs</emphasis> directory on a file server machine and all of its
1916 subdirectories and files must be owned by the local superuser <emphasis role="bold">root</emphasis> and have only the first
1917 <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit turned on. Some files even have only the
1918 first <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) mode bit turned on (for example, the
1919 <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file, which lists the AFS server encryption keys). Each time the BOS
1920 Server starts, it checks that the mode bits on certain files and directories match the expected values. For a list, see the
1921 <emphasis>OpenAFS Quick Beginnings</emphasis> section about protecting sensitive AFS directories, or the discussion of the
1922 output from the <emphasis role="bold">bos status</emphasis> command in <link linkend="HDRWQ159">To display the status of
1923 server processes and their BosConfig entries</link>.</para>
1925 <para>For a description of the contents of all AFS directories on a file server machine's local disk, see <link
1926 linkend="HDRWQ80">Administering Server Machines</link>.</para>
1929 <sect2 id="Header_62">
1930 <title>Configuring Partitions to Store AFS Data</title>
1932 <para>The partitions that house AFS volumes on a file server machine must be mounted at directories named</para>
1934 <para><emphasis role="bold">/vicep</emphasis><emphasis>index</emphasis></para>
1936 <para>where <emphasis>index</emphasis> is one or two lowercase letters. By convention, the first AFS partition created is
1937 mounted at the <emphasis role="bold">/vicepa</emphasis> directory, the second at the <emphasis role="bold">/vicepb</emphasis>
1938 directory, and so on through the <emphasis role="bold">/vicepz</emphasis> directory. The names then continue with <emphasis
1939 role="bold">/vicepaa</emphasis> through <emphasis role="bold">/vicepaz</emphasis>, <emphasis role="bold">/vicepba</emphasis>
1940 through <emphasis role="bold">/vicepbz</emphasis>, and so on, up to the maximum supported number of server partitions, which
1941 is specified in the OpenAFS Release Notes.</para>
1943 <para>Each <emphasis role="bold">/vicep</emphasis>x directory must correspond to an entire partition or logical volume, and
1944 must be a subdirectory of the root directory (/). It is not acceptable to configure part of (for example) the <emphasis
1945 role="bold">/usr</emphasis> partition as an AFS server partition and mount it on a directory called <emphasis
1946 role="bold">/usr/vicepa</emphasis>.</para>
1948 <para>Also, do not store non-AFS files on AFS server partitions. The File Server and Volume Server expect to have available
1949 all of the space on the partition. Sharing space also creates competition between AFS and the local UNIX file system for
1950 access to the partition, particularly if the UNIX files are frequently used.</para>
1953 <primary>server machine</primary>
1955 <secondary>monitoring</secondary>
1959 <primary>file server machine</primary>
1961 <secondary>rebooting, about</secondary>
1965 <primary>rebooting</primary>
1967 <secondary>file server machine, limiting</secondary>
1971 <primary>weekly restart of BOS Server (automatic)</primary>
1973 <secondary>about</secondary>
1977 <primary>restart times for BOS Server</primary>
1979 <secondary>about</secondary>
1983 <sect2 id="Header_63">
1984 <title>Monitoring, Rebooting and Automatic Process Restarts</title>
1986 <para>AFS provides several tools for monitoring the File Server, including the <emphasis role="bold">scout</emphasis> and
1987 <emphasis role="bold">afsmonitor</emphasis> programs. You can configure them to alert you when certain threshold values are
1988 exceeded, for example when a server partition is more than 95% full. See <link linkend="HDRWQ323">Monitoring and Auditing AFS
1989 Performance</link>.</para>
1991 <para>Rebooting a file server machine requires shutting down the AFS processes and so inevitably causes a service outage.
1992 Reboot file server machines as infrequently as possible. For instructions, see <link linkend="HDRWQ139">Rebooting a Server
1993 Machine</link>.</para>
1995 <para>By default, the BOS Server on each file server machine stops and immediately restarts all AFS server processes on the
1996 machine (including itself) once a week, at 4:00 a.m. on Sunday. This reduces the potential for the core leaks that can develop
1997 as any process runs for an extended time.</para>
1999 <para>The BOS Server also checks each morning at 5:00 a.m. for any newly installed binary files in the <emphasis
2000 role="bold">/usr/afs/bin</emphasis> directory. It compares the timestamp on each binary file to the time at which the
2001 corresponding process last restarted. If the timestamp on the binary is later, the BOS Server restarts the corresponding
2002 process to start using it.</para>
2004 <para>The default times are in the early morning hours when the outage that results from restarting a process is likely to
2005 disturb the fewest number of people. You can display the restart times for each machine with the <emphasis role="bold">bos
2006 getrestart</emphasis> command, and set them with the <emphasis role="bold">bos setrestart</emphasis> command. The latter
2007 command enables you to disable automatic restarts entirely, by setting the time to <emphasis role="bold">never</emphasis>. See
2008 <link linkend="HDRWQ171">Setting the BOS Server's Restart Times</link>.</para>
2011 <primary>client machine</primary>
2013 <secondary>configuration issues</secondary>
2017 <primary>configuring</primary>
2019 <secondary>client machine, issues</secondary>
2024 <sect1 id="HDRWQ54">
2025 <title>Configuring Client Machines</title>
2027 <para>This section summarizes issues to consider as you install and configure client machines in your cell.</para>
2030 <primary>client machine</primary>
2032 <secondary>files required on local disk</secondary>
2036 <primary>local disk</primary>
2038 <secondary>files required on client machine</secondary>
2042 <primary>file</primary>
2044 <secondary>required on client machine local disk</secondary>
2047 <sect2 id="HDRWQ55">
2048 <title>Configuring the Local Disk</title>
2050 <para>You can often free up significant amounts of local disk space on AFS client machines by storing standard UNIX files in
2051 AFS and creating symbolic links to them from the local disk. The <emphasis role="bold">@sys</emphasis> pathname variable can
2052 be useful in links to system-specific files; see <link linkend="HDRWQ56">Using the @sys Variable in Pathnames</link>.</para>
2054 <para>There are two types of files that must actually reside on the local disk: boot sequence files needed before the
2055 <emphasis role="bold">afsd</emphasis> program is invoked, and files that can be helpful during file server machine
2058 <para>During a reboot, AFS is inaccessible until the <emphasis role="bold">afsd</emphasis> program executes and initializes
2059 the Cache Manager. (In the conventional configuration, the AFS initialization file is included in the machine's initialization
2060 sequence and invokes the <emphasis role="bold">afsd</emphasis> program.) Files needed during reboot prior to that point must
2061 reside on the local disk. They include the following, but this list is not necessarily exhaustive. <itemizedlist>
2063 <para>Standard UNIX utilities including the following or their equivalents: <itemizedlist>
2065 <para>Machine initialization files (stored in the <emphasis role="bold">/etc</emphasis> or <emphasis
2066 role="bold">/sbin</emphasis> directory on many system types)</para>
2070 <para>The <emphasis role="bold">fstab</emphasis> file</para>
2074 <para>The <emphasis role="bold">mount</emphasis> command binary</para>
2078 <para>The <emphasis role="bold">umount</emphasis> command binary</para>
2080 </itemizedlist></para>
2084 <para>All subdirectories and files in the <emphasis role="bold">/usr/vice</emphasis> directory, including the following:
2087 <para>The <emphasis role="bold">/usr/vice/cache</emphasis> directory</para>
2091 <para>The <emphasis role="bold">/usr/vice/etc/afsd</emphasis> command binary</para>
2095 <para>The <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file</para>
2099 <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file</para>
2103 <para>The <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file</para>
2105 </itemizedlist></para>
2107 <para>For more information on these files, see <link linkend="HDRWQ391">Configuration and Cache-Related Files on the
2108 Local Disk</link>.</para>
2110 </itemizedlist></para>
2112 <para>The other type of files and programs to retain on the local disk are those you need when diagnosing and fixing problems
2113 caused by a file server outage, because the outage can make inaccessible the copies stored in AFS. Examples include the
2114 binaries for a text editor (such as <emphasis role="bold">ed</emphasis> or <emphasis role="bold">vi</emphasis>) and for the
2115 <emphasis role="bold">fs</emphasis> and <emphasis role="bold">bos</emphasis> commands. Store copies of AFS command binaries in
2116 the <emphasis role="bold">/usr/vice/etc</emphasis> directory as well as including them in the <emphasis
2117 role="bold">/usr/afsws</emphasis> directory, which is normally a link into AFS. Then place the <emphasis
2118 role="bold">/usr/afsws</emphasis> directory before the <emphasis role="bold">/usr/vice/etc</emphasis> directory in users'
2119 <envar>PATH</envar> environment variable definition. When AFS is functioning normally, users access the copy in the <emphasis
2120 role="bold">/usr/afsws</emphasis> directory, which is more likely to be current than a local copy.</para>
2122 <para>You can automate the configuration of client machine local disks by using the <emphasis role="bold">package</emphasis>
2123 program, which updates the contents of the local disk to match a configuration file. See <link linkend="HDRWQ419">Configuring
2124 Client Machines with the package Program</link>.</para>
2127 <sect2 id="Header_66">
2128 <title>Enabling Access to Foreign Cells</title>
2131 <primary>client machine</primary>
2133 <secondary>enabling access to foreign cell</secondary>
2136 <para>As detailed in <link linkend="HDRWQ39">Making Other Cells Visible in Your Cell</link>, you enable the Cache Manager to
2137 access a cell's AFS filespace by storing a list of the cell's database server machines in the local <emphasis
2138 role="bold">/usr/vice/etc/CellServDB</emphasis> file. The Cache Manager reads the list into kernel memory at reboot for faster
2139 retrieval. You can change the list in kernel memory between reboots by using the <emphasis role="bold">fs newcell</emphasis>
2140 command. It is often practical to store a central version of the <emphasis role="bold">CellServDB</emphasis> file in AFS and
2141 use the <emphasis role="bold">package</emphasis> program periodically to update each client's version with the source copy.
2142 See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
2144 <para>Because each client machine maintains its own copy of the <emphasis role="bold">CellServDB</emphasis> file, you can in
2145 theory enable access to different foreign cells on different client machines. This is not usually practical, however,
2146 especially if users do not always work on the same machine.</para>
2149 <primary>at-sys (@sys) variable in pathnames</primary>
2153 <primary>sys (@sys) variable in pathnames</primary>
2157 <primary>variables</primary>
2159 <secondary>@sys in pathnames</secondary>
2163 <sect2 id="HDRWQ56">
2164 <title>Using the @sys Variable in Pathnames</title>
2166 <para>When creating symbolic links into AFS on the local disk, it is often practical to use the @sys variable in pathnames.
2167 The Cache Manager automatically substitutes the local machine's AFS system name (CPU/operating system type) for the @sys
2168 variable. This means you can place the same links on machines of various system types and still have each machine access the
2169 binaries for its system type. For example, the Cache Manager on a machine running AIX 4.2 converts <emphasis
2170 role="bold">/afs/abc.com/@sys</emphasis> to <emphasis role="bold">/afs/abc.com/rs_aix42</emphasis>, whereas a machine running
2171 Solaris 7 converts it to <emphasis role="bold">/afs/abc.com/sun4x_57</emphasis>.</para>
2173 <para>If you want to use the @sys variable, it is simplest to use the conventional AFS system type names as specified in the
2174 OpenAFS Release Notes. The Cache Manager records the local machine's system type name in kernel memory during initialization.
2175 If you do not use the conventional names, you must use the <emphasis role="bold">fs sysname</emphasis> command to change the
2176 value in kernel memory from its default just after Cache Manager initialization, on every client machine of the relevant
2177 system type. The <emphasis role="bold">fs sysname</emphasis> command also displays the current value; see <link
2178 linkend="HDRWQ417">Displaying and Setting the System Type Name</link>.</para>
2180 <para>In pathnames in the AFS filespace itself, use the @sys variable carefully and sparingly, because it can lead to
2181 unexpected results. It is generally best to restrict its use to only one level in the filespace. The third level is a common
2182 choice, because that is where many cells store the binaries for different machine types.</para>
2184 <para>Multiple instances of the @sys variable in a pathname are especially dangerous to people who must explicitly change
2185 directories (with the <emphasis role="bold">cd</emphasis> command, for example) into directories that store binaries for
2186 system types other than the machine on which they are working, such as administrators or developers who maintain those
2187 directories. After changing directories, it is recommended that such people verify they are in the desired directory.</para>
2190 <sect2 id="Header_68">
2191 <title>Setting Server Preferences</title>
2193 <para>The Cache Manager stores a table of preferences for file server machines in kernel memory. A preference rank pairs a
2194 file server machine interface's IP address with an integer in the range from 1 to 65,534. When it needs to access a file, the
2195 Cache Manager compares the ranks for the interfaces of all machines that house the file, and first attempts to access the file
2196 via the interface with the best rank. As it initializes, the Cache Manager sets default ranks that bias it to access files via
2197 interfaces that are close to it in terms of network topology. You can adjust the preference ranks to improve performance if
2200 <para>The Cache Manager also uses similar preferences for Volume Location (VL) Server machines. Use the <emphasis
2201 role="bold">fs getserverprefs</emphasis> command to display preference ranks and the <emphasis role="bold">fs
2202 setserverprefs</emphasis> command to set them. See <link linkend="HDRWQ414">Maintaining Server Preference Ranks</link>.</para>
2205 <primary>user account</primary>
2207 <secondary>configuration issues</secondary>
2212 <sect1 id="HDRWQ57">
2213 <title>Configuring AFS User Accounts</title>
2215 <para>This section discusses some of the issues to consider when configuring AFS user accounts. Because AFS is separate from the
2216 UNIX file system, a user's AFS account is separate from her UNIX account.</para>
2218 <para>The preferred method for creating a user account is with the <emphasis role="bold">uss</emphasis> suite of commands. With
2219 a single command, you can create all the components of one or many accounts, after you have prepared a template file that guides
2220 the account creation. See <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>.</para>
2222 <para>Alternatively, you can issue the individual commands that create each component of an account. For instructions, along
2223 with instructions for removing user accounts and changing user passwords, user volume quotas and usernames, see <link
2224 linkend="HDRWQ491">Administering User Accounts</link>.</para>
2226 <para>When users leave your system, it is often good policy to remove their accounts. Instructions appear in <link
2227 linkend="HDRWQ486">Deleting Individual Accounts with the uss delete Command</link> and <link linkend="HDRWQ524">Removing a User
2228 Account</link>.</para>
2230 <para>An AFS user account consists of the following components, which are described in greater detail in <link
2231 linkend="HDRWQ494">The Components of an AFS User Account</link>. <itemizedlist>
2233 <para>A Protection Database entry</para>
2237 <para>An Authentication Database entry</para>
2241 <para>A volume</para>
2245 <para>A home directory at which the volume is mounted</para>
2249 <para>Ownership of the home directory and full permissions on its ACL</para>
2253 <para>An entry in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of each machine the
2254 user needs to log into</para>
2258 <para>Optionally, standard files and subdirectories that make the account more useful</para>
2260 </itemizedlist></para>
2262 <para>By creating some components but not others, you can create accounts at different levels of functionality, using either
2263 <emphasis role="bold">uss</emphasis> commands as described in <link linkend="HDRWQ449">Creating and Deleting User Accounts with
2264 the uss Command Suite</link> or individual commands as described in <link linkend="HDRWQ491">Administering User Accounts</link>.
2265 The levels of functionality include the following <itemizedlist>
2267 <para>An authentication-only account enables the user to obtain AFS tokens and so to access protected AFS data and to
2268 issue privileged commands. It consists only of entries in the Authentication and Protection Database. This type of account
2269 is suitable for administrative accounts and for users from foreign cells who need to access protected data. Local users
2270 generally also need a volume and home directory.</para>
2274 <para>A basic user account includes a volume for the user, in addition to Authentication and Protection Database entries.
2275 The volume is mounted in the AFS filespace as the user's home directory, and provides a repository for the user's personal
2280 <para>A full account adds configuration files for basic functions such as logging in, printing, and mail delivery to a
2281 basic account, making it more convenient and useful. For a discussion of some useful types of configuration files, see
2282 <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>.</para>
2284 </itemizedlist></para>
2286 <para>If your users have UNIX user accounts that predate the introduction of AFS in the cell, you possibly want to convert them
2287 into AFS accounts. There are three main issues to consider: <itemizedlist>
2289 <para>Making UNIX and AFS UIDs match</para>
2293 <para>Setting the password field in the local password file appropriately</para>
2297 <para>Moving files from the UNIX file system into AFS</para>
2299 </itemizedlist></para>
2301 <para>For further discussion, see <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link> or <link
2302 linkend="HDRWQ498">Converting Existing UNIX Accounts</link>.</para>
2305 <primary>username</primary>
2307 <secondary>choosing</secondary>
2311 <primary>user</primary>
2313 <secondary>name</secondary>
2319 <primary>choosing</primary>
2321 <secondary>name</secondary>
2323 <tertiary>user</tertiary>
2327 <primary>anonymous user</primary>
2329 <secondary>AFS UID reserved</secondary>
2333 <primary>AFS UID</primary>
2335 <secondary>reserved</secondary>
2337 <tertiary>anonymous user</tertiary>
2340 <sect2 id="HDRWQ58">
2341 <title>Choosing Usernames and Naming Other Account Components</title>
2343 <para>This section suggests schemes for choosing usernames, AFS UIDs, user volume names and mount point names, and also
2344 outlines some restrictions on your choices.</para>
2347 <title>Usernames</title>
2349 <para>AFS imposes very few restrictions on the form of usernames. It is best to keep usernames short, both because many
2350 utilities and applications can handle usernames of no more than eight characters and because by convention many components
2351 of and AFS account incorporate the name. These include the entries in the Protection and Authentication Databases, the
2352 volume, and the mount point. Depending on your electronic mail delivery system, the username can become part of the user's
2353 mailing address. The username is also the string that the user types when logging in to a client machine.</para>
2356 <para>Some common choices for usernames are last names, first names, initials, or a combination, with numbers sometimes added.
2357 It is also best to avoid using the following characters, many of which have special meanings to the command shell.
2360 <para>The comma (<emphasis role="bold">,</emphasis>)</para>
2364 <para>The colon (<emphasis role="bold">:</emphasis>), because AFS reserves it as a field separator in protection group
2365 names; see <link linkend="HDRWQ62">The Two Types of User-Defined Groups</link></para>
2369 <para>The semicolon (<emphasis role="bold">;</emphasis>)</para>
2373 <para>The "at-sign" (<emphasis role="bold">@</emphasis>); this character is reserved for Internet mailing
2382 <para>The newline character</para>
2386 <para>The period (<emphasis role="bold">.</emphasis>); it is conventional to use this character only in the special
2387 username that an administrator adopts while performing privileged tasks, such as <emphasis
2388 role="bold">pat.admin</emphasis></para>
2390 </itemizedlist></para>
2393 <title>AFS UIDs and UNIX UIDs</title>
2395 <para>AFS associates a unique identification number, the AFS UID, with every username, recording the mapping in the user's
2396 Protection Database entry. The AFS UID functions within AFS much as the UNIX UID does in the local file system: the AFS
2397 server processes and the Cache Manager use it internally to identify a user, rather than the username.</para>
2400 <para>Every AFS user also must have a UNIX UID recorded in the local password file (<emphasis
2401 role="bold">/etc/passwd</emphasis> or equivalent) of each client machine they log onto. Both administration and a user's AFS
2402 access are simplest if the AFS UID and UNIX UID match. One important consequence of matching UIDs is that the owner reported
2403 by the <emphasis role="bold">ls -l</emphasis> command matches the AFS username.</para>
2405 <para>It is usually best to allow the Protection Server to allocate the AFS UID as it creates the Protection Database entry.
2406 However, both the <emphasis role="bold">pts createuser</emphasis> command and the <emphasis role="bold">uss</emphasis>
2407 commands that create user accounts enable you to assign AFS UIDs explicitly. This is appropriate in two cases: <itemizedlist>
2409 <para>You wish to group together the AFS UIDs of related users</para>
2413 <para>You are converting an existing UNIX account into an AFS account and want to make the AFS UID match the existing
2416 </itemizedlist></para>
2418 <para>After the Protection Server initializes for the first time on a cell's first file server machine, it starts assigning
2419 AFS UIDs at a default value. To change the default before creating any user accounts, or at any time, use the <emphasis
2420 role="bold">pts setmax</emphasis> command to reset the <computeroutput>max user id counter</computeroutput>. To display the
2421 counter, use the <emphasis role="bold">pts listmax</emphasis> command. See <link linkend="HDRWQ560">Displaying and Setting the
2422 AFS UID and GID Counters</link>.</para>
2424 <para>AFS reserves one AFS UID, 32766, for the user <emphasis role="bold">anonymous</emphasis>. The AFS server processes
2425 assign this identity and AFS UID to any user who does not possess a token for the local cell. Do not assign this AFS UID to
2426 any other user or hardcode its current value into any programs or a file's owner field, because it is subject to change in
2427 future releases.</para>
2430 <primary>username</primary>
2432 <secondary>part of volume name</secondary>
2436 <primary>choosing</primary>
2438 <secondary>name</secondary>
2440 <tertiary>user volume</tertiary>
2444 <title>User Volume Names</title>
2446 <para>Like any volume name, a user volume's base (read/write) name cannot exceed 22 characters in length or include the
2447 <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension. See <link
2448 linkend="HDRWQ44">Creating Volumes to Simplify Administration</link>. By convention, user volume names have the format
2449 <emphasis role="bold">user.</emphasis>username. Using the <emphasis role="bold">user.</emphasis> prefix not only makes it
2450 easy to identify the volume's contents, but also to create a backup version of all user volumes by issuing a single
2451 <emphasis role="bold">vos backupsys</emphasis> command.</para>
2455 <primary>mount point</primary>
2457 <secondary>choosing name for user volume</secondary>
2461 <primary>choosing</primary>
2463 <secondary>name</secondary>
2465 <tertiary>user volume mount point</tertiary>
2469 <title>Mount Point Names</title>
2471 <para>By convention, the mount point for a user's volume is named after the username. Many cells follow the convention of
2472 mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2473 role="bold">/usr</emphasis> directory, as discussed in <link linkend="HDRWQ43">The Third Level</link>. Very large cells
2474 sometimes find that mounting all user volumes in the same directory slows directory lookup, however; for suggested
2475 alternatives, see the following section.</para>
2479 <primary>directories</primary>
2481 <secondary>for grouping user home directories</secondary>
2485 <primary>user account</primary>
2487 <secondary>suggestions for grouping home directories</secondary>
2491 <sect2 id="HDRWQ59">
2492 <title>Grouping Home Directories</title>
2494 <para>Mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2495 role="bold">/usr</emphasis> directory is an AFS-appropriate variation on the standard UNIX practice of putting user home
2496 directories under the <emphasis role="bold">/usr</emphasis> subdirectory. However, cells with more than a few hundred users
2497 sometimes find that mounting all user volumes in a single directory results in slow directory lookup. The solution is to
2498 distribute user volume mount points into several directories; there are a number of alternative methods to accomplish this.
2501 <para>Distribute user home directories into multiple directories that reflect organizational divisions, such as academic
2502 or corporate departments. For example, a company can create group directories called <emphasis
2503 role="bold">usr/marketing</emphasis>, <emphasis role="bold">usr/research</emphasis>, <emphasis
2504 role="bold">usr/finance</emphasis>. A good feature of this scheme is that knowing a user's department is enough to find
2505 the user's home directory. Also, it makes it easy to set the ACL to limit access to members of the department only. A
2506 potential drawback arises if departments are of sufficiently unequal size that users in large departments experience
2507 slower lookup than users in small departments. This scheme is also not appropriate in cells where users frequently
2508 change between divisions.</para>
2512 <para>Distribute home directories into alphabetic subdirectories of the <emphasis role="bold">usr</emphasis> directory
2513 (the <emphasis role="bold">usr/a</emphasis> subdirectory, the <emphasis role="bold">usr/b</emphasis> subdirectory, and
2514 so on), based on the first letter of the username. If the cell is very large, create subdirectories under each letter
2515 that correspond to the second letter in the user name. This scheme has the same advantages and disadvantages of a
2516 department-based scheme. Anyone who knows the user's username can find the user's home directory, but users with names
2517 that begin with popular letters sometimes experience slower lookup.</para>
2521 <para>Distribute home directories randomly but evenly into more than one grouping directory. One cell that uses this
2522 scheme has over twenty such directories called the <emphasis role="bold">usr1</emphasis> directory, the <emphasis
2523 role="bold">usr2</emphasis> directory, and so on. This scheme is especially appropriate in cells where the other two
2524 schemes do not seem feasible. It eliminates the potential problem of differences in lookup speed, because all
2525 directories are about the same size. Its disadvantage is that there is no way to guess which directory a given user's
2526 volume is mounted in, but a solution is to create a symbolic link in the regular <emphasis role="bold">usr</emphasis>
2527 directory that references the actual mount point. For example, if user <emphasis role="bold">smith</emphasis>'s volume
2528 is mounted at the <emphasis role="bold">/afs/bigcell.com/usr17/smith</emphasis> directory, then the <emphasis
2529 role="bold">/afs/bigcell.com/usr/smith</emphasis> directory is a symbolic link to the <emphasis
2530 role="bold">../usr17/smith</emphasis> directory. This way, if someone does not know which directory the user <emphasis
2531 role="bold">smith</emphasis> is in, he or she can access it through the link called <emphasis
2532 role="bold">usr/smith</emphasis>; people who do know the appropriate directory save lookup time by specifying it.</para>
2534 </itemizedlist></para>
2536 <para>For instructions on how to implement the various schemes when using the <emphasis role="bold">uss</emphasis> program to
2537 create user accounts, see <link linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link> and
2538 <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
2541 <sect2 id="Header_72">
2542 <title>Making a Backup Version of User Volumes Available</title>
2544 <para>Mounting the backup version of a user's volume is a simple way to enable users themselves to restore data they have
2545 accidentally removed or deleted. It is conventional to mount the backup version at a subdirectory of the user's home directory
2546 (called perhaps the <emphasis role="bold">OldFiles</emphasis> subdirectory), but other schemes are possible. Once per day you
2547 create a new backup version to capture the changes made that day, overwriting the previous day's backup version with the new
2548 one. Users can always retrieve the previous day's copy of a file without your assistance, freeing you to deal with more
2549 pressing tasks.</para>
2551 <para>Users sometimes want to delete the mount point to their backup volume, because they erroneously believe that the backup
2552 volume's contents count against their quota. Remind them that the backup volume is separate, so the only space it uses in the
2553 user volume is the amount needed for the mount point.</para>
2555 <para>For further discussion of backup volumes, see <link linkend="HDRWQ77">Backing Up AFS Data</link> and <link
2556 linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
2559 <primary>file</primary>
2561 <secondary>creating standard ones in new user account</secondary>
2565 <primary>user account</primary>
2567 <secondary>creating</secondary>
2569 <tertiary>standard files in</tertiary>
2573 <primary>creating</primary>
2575 <secondary>standard files in new user account</secondary>
2579 <sect2 id="HDRWQ60">
2580 <title>Creating Standard Files in New AFS Accounts</title>
2582 <para>From your experience as a UNIX administrator, you are probably familiar with the use of login and shell initialization
2583 files (such as the <emphasis role="bold">.login</emphasis> and <emphasis role="bold">.cshrc</emphasis> files) to make an
2584 account easier to use.</para>
2586 <para>It is often practical to add some AFS-specific directories to the definition of the user's <envar>PATH</envar>
2587 environment variable, including the following: <itemizedlist>
2589 <para>The path to a <emphasis role="bold">bin</emphasis> subdirectory in the user's home directory for binaries the user
2590 has created (that is, <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2591 role="bold">/usr/</emphasis><replaceable>username</replaceable><emphasis role="bold">/bin</emphasis>)</para>
2595 <para>The <emphasis role="bold">/usr/afsws/bin</emphasis> path, which conventionally includes programs like <emphasis
2596 role="bold">fs</emphasis>, <emphasis role="bold">klog</emphasis>, <emphasis role="bold">kpasswd</emphasis>, <emphasis
2597 role="bold">pts</emphasis>, <emphasis role="bold">tokens</emphasis>, and <emphasis role="bold">unlog</emphasis></para>
2601 <para>The <emphasis role="bold">/usr/afsws/etc</emphasis> path, if the user is an administrator; it usually houses the
2602 AFS command suites that require privilege (the <emphasis role="bold">backup</emphasis>, <emphasis
2603 role="bold">butc</emphasis>, <emphasis role="bold">kas</emphasis>, <emphasis role="bold">uss</emphasis>, <emphasis
2604 role="bold">vos</emphasis> commands), the <emphasis role="bold">package</emphasis> program, and others</para>
2606 </itemizedlist></para>
2608 <para>If you are not using an AFS-modified login utility, it can be helpful to users to invoke the <emphasis
2609 role="bold">klog</emphasis> command in their <emphasis role="bold">.login</emphasis> file so that they obtain AFS tokens as
2610 part of logging in. In the following example command sequence, the first line echoes the string
2611 <computeroutput>klog</computeroutput> to the standard output stream, so that the user understands the purpose of the
2612 <computeroutput>Password:</computeroutput> prompt that appears when the second line is executed. The <emphasis
2613 role="bold">-setpag</emphasis> flag associates the new tokens with a process authentication group (PAG), which is discussed
2614 further in <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
2621 <para>The following sequence of commands has a similar effect, except that the <emphasis role="bold">pagsh</emphasis> command
2622 forks a new shell with which the PAG and tokens are associated.</para>
2630 <para>If you use an AFS-modified login utility, this sequence is not necessary, because such utilities both log a user in
2631 locally and obtain AFS tokens.</para>
2634 <primary>group</primary>
2636 <secondary>AFS GID</secondary>
2640 <primary>group</primary>
2642 <secondary>restrictions</secondary>
2646 <primary>group</primary>
2648 <secondary>privacy flags</secondary>
2652 <primary>privacy flags on Protection Database entry</primary>
2657 <sect1 id="HDRWQ61">
2658 <title>Using AFS Protection Groups</title>
2660 <para>AFS enables users to define their own groups of other users or machines. The groups are placed on ACLs to grant the same
2661 permissions to many users without listing each user individually. For group creation instructions, see <link
2662 linkend="HDRWQ531">Administering the Protection Database</link>.</para>
2664 <para>Groups have AFS ID numbers, just as users do, but an AFS group ID (GID) is a negative integer whereas a user's AFS UID is
2665 a positive integer. By default, the Protection Server allocates a new group's AFS GID automatically, but members of the
2666 <emphasis role="bold">system:administrators</emphasis> group can assign a GID when issuing the <emphasis role="bold">pts
2667 creategroup</emphasis> command. Before explicitly assigning a GID, it is best to verify that it is not already in use.</para>
2669 <para>A group cannot belong to another group, but it can own another group or even itself as long as it (the owning group) has
2670 at least one member. The current owner of a group can transfer ownership of the group to another user or group, even without the
2671 new owner's permission. At that point the former owner loses administrative control over the group.</para>
2673 <para>By default, each user can create 20 groups. A system administrator can increase or decrease this group creation quota with
2674 the <emphasis role="bold">pts setfields</emphasis> command.</para>
2676 <para>Each Protection Database entry (group or user) is protected by a set of five privacy flagswhich limit who can administer
2677 the entry and what they can do. The default privacy flags are fairly restrictive, especially for user entries. See <link
2678 linkend="HDRWQ559">Setting the Privacy Flags on Database Entries</link>.</para>
2681 <primary>system:administrators group</primary>
2683 <secondary>about</secondary>
2687 <primary>system:anyuser group</primary>
2689 <secondary>about</secondary>
2693 <primary>system:authuser group</primary>
2695 <secondary>about</secondary>
2699 <primary>group</primary>
2701 <secondary>system-defined</secondary>
2704 <sect2 id="Header_75">
2705 <title>The Three System Groups</title>
2707 <para>As the Protection Server initializes for the first time on a cell's first database server machine, it automatically
2708 creates three group entries: the <emphasis role="bold">system:anyuser</emphasis>, <emphasis
2709 role="bold">system:authuser</emphasis>, and <emphasis role="bold">system:administrators</emphasis> groups.</para>
2712 <primary>AFS UID</primary>
2714 <secondary>reserved</secondary>
2716 <tertiary>system-defined groups</tertiary>
2719 <para>The first two system groups are unlike any other groups in the Protection Database in that they do not have a stable
2720 membership: <itemizedlist>
2722 <para>The <emphasis role="bold">system:anyuser</emphasis> group includes everyone who can access a cell's AFS filespace:
2723 users who have tokens for the local cell, users who have logged in on a local AFS client machine but not obtained tokens
2724 (such as the local superuser <emphasis role="bold">root</emphasis>), and users who have connected to a local machine
2725 from outside the cell. Placing the <emphasis role="bold">system:anyuser</emphasis> group on an ACL grants access to the
2726 widest possible range of users. It is the only way to extend access to users from foreign AFS cells that do not have
2727 local accounts.</para>
2731 <para>The <emphasis role="bold">system:authuser</emphasis> group includes everyone who has a valid token obtained from
2732 the cell's AFS authentication service.</para>
2734 </itemizedlist></para>
2736 <para>Because the groups do not have a stable membership, the <emphasis role="bold">pts membership</emphasis> command produces
2737 no output for them. Similarly, they do not appear in the list of groups to which a user belongs.</para>
2739 <para>The <emphasis role="bold">system:administrators</emphasis> group does have a stable membership, consisting of the cell's
2740 privileged administrators. Members of this group can issue any <emphasis role="bold">pts</emphasis> command, and are the only
2741 ones who can issue several other restricted commands (such as the <emphasis role="bold">chown</emphasis> command on AFS
2742 files). By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
2743 role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
2744 permissions on every ACL in the filespace. For information about changing this default, see <link
2745 linkend="HDRWQ586">Administering the system:administrators Group</link>.</para>
2747 <para>For a discussion of how to use system groups effectively on ACLs, see <link linkend="HDRWQ571">Using Groups on
2751 <sect2 id="HDRWQ62">
2752 <title>The Two Types of User-Defined Groups</title>
2754 <para>All users can create regular groups. A regular group name has two fields separated by a colon, the first of which must
2755 indicate the group's ownership. The Protection Server refuses to create or change the name of a group if the result does not
2756 accurately indicate the ownership.</para>
2758 <para>Members of the <emphasis role="bold">system:administrators</emphasis> group can create prefix-less groups whose names do
2759 not have the first field that indicates ownership. For suggestions on using the two types of groups effectively, see <link
2760 linkend="HDRWQ545">Using Groups Effectively</link>.</para>
2763 <primary>authentication</primary>
2765 <secondary>AFS separate from UNIX</secondary>
2769 <primary>AFS</primary>
2771 <secondary>authentication separate from UNIX</secondary>
2776 <sect1 id="HDRWQ63">
2777 <title>Login and Authentication in AFS</title>
2779 <para>As explained in <link linkend="HDRWQ31">Differences in Authentication</link>, AFS authentication is separate from UNIX
2780 authentication because the two file systems are separate. The separation has two practical implications: <itemizedlist>
2782 <para>To access AFS files, users must both log into the local file system and authenticate with the AFS authentication
2783 service. (Logging into the local file system is necessary because the only way to access the AFS filespace is through a
2784 Cache Manager, which resides in the local machine's kernel.)</para>
2788 <para>Passwords are stored in two separate places: in the Kerberos Database for AFS and in the each machine's local
2789 password file (the <emphasis role="bold">/etc/passwd</emphasis> file or equivalent) for the local file system.</para>
2791 </itemizedlist></para>
2793 <para>When a user successfully authenticates, the AFS authentication service passes a token to the user's Cache Manager. The
2794 token is a small collection of data that certifies that the user has correctly provided the password associated with a
2795 particular AFS identity. The Cache Manager presents the token to AFS server processes along with service requests, as proof that
2796 the user is genuine. To learn about the mutual authentication procedure they use to establish identity, see <link
2797 linkend="HDRWQ75">A More Detailed Look at Mutual Authentication</link>.</para>
2799 <para>The Cache Manager stores tokens in the user's credential structure in kernel memory. To distinguish one user's credential
2800 structure from another's, the Cache Manager identifies each one either by the user's UNIX UID or by a process authentication
2801 group (PAG), which is an identification number guaranteed to be unique in the cell. For further discussion, see <link
2802 linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
2805 <primary>tokens</primary>
2807 <secondary>one-per-cell rule</secondary>
2810 <para>A user can have only one token per cell in each separately identified credential structure. To obtain a second token for
2811 the same cell, the user must either log into a different machine or obtain another credential structure with a different
2812 identifier than any existing credential structure, which is most easily accomplished by issuing the <emphasis
2813 role="bold">pagsh</emphasis> command (see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>). In a single credential
2814 structure, a user can have one token for each of many cells at the same time. As this implies, authentication status on one
2815 machine or PAG is independent of authentication status on another machine or PAG, which can be very useful to a user or system
2816 administrator.</para>
2818 <para>The AFS distribution includes library files that enable each system type's login utility to authenticate users with AFS
2819 and log them into the local file system in one step. If you do not configure an AFS-modified login utility on a client machine,
2820 its users must issue the <emphasis role="bold">klog</emphasis> command to authenticate with AFS after logging in.</para>
2823 <para>The AFS-modified libraries do not necessarily support all features available in an operating system's proprietary login
2824 utility. In some cases, it is not possible to support a utility at all. For more information about the supported utilities in
2825 each AFS version, see the OpenAFS Release Notes.</para>
2829 <primary>commands</primary>
2831 <secondary>pagsh</secondary>
2835 <primary>pagsh command</primary>
2839 <primary>commands</primary>
2841 <secondary>klog with -setpag flag</secondary>
2845 <primary>klog command</primary>
2847 <secondary>with -setpag flag</secondary>
2851 <primary>PAG</primary>
2853 <secondary>creating with klog or pagsh command</secondary>
2857 <primary>creating</primary>
2859 <secondary>PAG with klog or pagsh command</secondary>
2863 <primary>process authentication group</primary>
2865 <secondary></secondary>
2870 <sect2 id="HDRWQ64">
2871 <title>Identifying AFS Tokens by PAG</title>
2873 <para>As noted, the Cache Manager identifies user credential structures either by UNIX UID or by PAG. Using a PAG is
2874 preferable because it guaranteed to be unique: the Cache Manager allocates it based on a counter that increments with each
2875 use. In contrast, multiple users on a machine can share or assume the same UNIX UID, which creates potential security
2876 problems. The following are two common such situations: <itemizedlist>
2878 <para>The local superuser <emphasis role="bold">root</emphasis> can always assume any other user's UNIX UID simply by
2879 issuing the <emphasis role="bold">su</emphasis> command, without providing the user's password. If the credential
2880 structure is associated with the user's UNIX UID, then assuming the UID means inheriting the AFS tokens.</para>
2884 <para>Two users working on different NFS client machines can have the same UNIX UID in their respective local file
2885 systems. If they both access the same NFS/AFS Translator machine, and the Cache Manager there identifies them by their
2886 UNIX UID, they become indistinguishable. To eliminate this problem, the Cache Manager on a translator machine
2887 automatically generates a PAG for each user and uses it, rather than the UNIX UID, to tell users apart.</para>
2889 </itemizedlist></para>
2891 <para>Yet another advantage of PAGs over UIDs is that processes spawned by the user inherit the PAG and so share the token;
2892 thus they gain access to AFS as the authenticated user. In many environments, for example, printer and other daemons run under
2893 identities (such as the local superuser <emphasis role="bold">root</emphasis>) that the AFS server processes recognize only as
2894 the <emphasis role="bold">anonymous</emphasis> user. Unless PAGs are used, such daemons cannot access files for which the
2895 <emphasis role="bold">system:anyuser</emphasis> group does not have the necessary ACL permissions.</para>
2897 <para>Once a user has a PAG, any new tokens the user obtains are associated with the PAG. The PAG expires two hours after any
2898 associated tokens expire or are discarded. If the user issues the <emphasis role="bold">klog</emphasis> command before the PAG
2899 expires, the new token is associated with the existing PAG (the PAG is said to be recycled in this case).</para>
2901 <para>AFS-modified login utilities automatically generate a PAG, as described in the following section. If you use a standard
2902 login utility, your users must issue the <emphasis role="bold">pagsh</emphasis> command before the <emphasis
2903 role="bold">klog</emphasis> command, or include the latter command's <emphasis role="bold">-setpag</emphasis> flag. For
2904 instructions, see <link linkend="HDRWQ69">Using Two-Step Login and Authentication</link>.</para>
2906 <para>Users can also use either command at any time to create a new PAG. The difference between the two commands is that the
2907 <emphasis role="bold">klog</emphasis> command replaces the PAG associated with the current command shell and tokens. The
2908 <emphasis role="bold">pagsh</emphasis> command initializes a new command shell before creating a new PAG. If the user already
2909 had a PAG, any running processes or jobs continue to use the tokens associated with the old PAG whereas any new jobs or
2910 processes use the new PAG and its associated tokens. When you exit the new shell (by pressing <<emphasis
2911 role="bold">Ctrl-d</emphasis>>, for example), you return to the original PAG and shell. By default, the <emphasis
2912 role="bold">pagsh</emphasis> command initializes a Bourne shell, but you can include the <emphasis role="bold">-c</emphasis>
2913 argument to initialize a C shell (the <emphasis role="bold">/bin/csh</emphasis> program on many system types) or Korn shell
2914 (the <emphasis role="bold">/bin/ksh</emphasis> program) instead.</para>
2917 <primary>login utility</primary>
2919 <secondary>AFS version</secondary>
2923 <sect2 id="HDRWQ65">
2924 <title>Using an AFS-modified login Utility</title>
2926 <para>As previously mentioned, an AFS-modified login utility simultaneously obtains an AFS token and logs the user into the
2927 local file system. This section outlines the login and authentication process and its interaction with the value in the
2928 password field of the local password file.</para>
2930 <para>An AFS-modified login utility performs a sequence of steps similar to the following; details can vary for different
2931 operating systems: <orderedlist>
2933 <para>It checks the user's entry in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
2938 <para>If no entry exists, or if an asterisk (<computeroutput>*</computeroutput>) appears in the entry's password field,
2939 the login attempt fails. If the entry exists, the attempt proceeds to the next step.</para>
2943 <para><anchor id="LIWQ66" />The utility obtains a PAG.</para>
2947 <para><anchor id="LIWQ67" />The utility converts the password provided by the user into an encryption key and encrypts a
2948 packet of data with the key. It sends the packet to the AFS authentication service (the AFS Authentication Server in the
2949 conventional configuration).</para>
2953 <para>The authentication service decrypts the packet and, depending on the success of the decryption, judges the
2954 password to be correct or incorrect. (For more details, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
2955 Authentication</link>.) <itemizedlist>
2957 <para>If the authentication service judges the password incorrect, the user does not receive an AFS token. The PAG
2958 is retained, ready to be associated with any tokens obtained later. The attempt proceeds to Step <link
2959 linkend="LIWQ68">6</link>.</para>
2963 <para>If the authentication service judges the password correct, it issues a token to the user as proof of AFS
2964 authentication. The login utility logs the user into the local UNIX file system. Some login utilities echo the
2965 following banner to the screen to alert the user to authentication with AFS. Step <link linkend="LIWQ68">6</link>
2966 is skipped. <programlisting>
2967 AFS(R) version Login
2968 </programlisting></para>
2970 </itemizedlist></para>
2974 <para><anchor id="LIWQ68" />If no AFS token was granted in Step <link linkend="LIWQ67">4</link>, the login utility
2975 attempts to log the user into the local file system, by comparing the password provided to the local password file.
2978 <para>If the password is incorrect or any value other than an encrypted 13-character string appears in the
2979 password field, the login attempt fails.</para>
2983 <para>If the password is correct, the user is logged into the local file system only.</para>
2985 </itemizedlist></para>
2987 </orderedlist></para>
2990 <primary>local password file</primary>
2992 <secondary>when using AFS--modified login utility</secondary>
2996 <primary>login utility</primary>
2998 <secondary>AFS version's interaction with local password file</secondary>
3002 <primary>password</primary>
3004 <secondary>local password file</secondary>
3007 <para>As indicated, when you use an AFS-modified login utility, the password field in the local password file is no longer the
3008 primary gate for access to your system. If the user provides the correct AFS password, then the program never consults the
3009 local password file. However, you can still use the password field to control access, in the following way: <itemizedlist>
3011 <para>To prevent both local login and AFS authentication, place an asterisk (<emphasis role="bold">*</emphasis>) in the
3012 field. This is useful mainly in emergencies, when you want to prevent a certain user from logging into the
3017 <para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
3018 string of any length other than the standard thirteen characters in the field. This is appropriate if you want to permit
3019 only people with local AFS accounts to login on your machines. A single <emphasis role="bold">X</emphasis> or other
3020 character is the most easily recognizable way to do this.</para>
3024 <para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
3025 standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
3026 role="bold">passwd</emphasis> or equivalent).</para>
3028 </itemizedlist></para>
3030 <para>Systems that use a Pluggable Authentication Module (PAM) for login and AFS authentication do not necessarily consult the
3031 local password file at all, in which case they do not use the password field to control authentication and login attempts.
3032 Instead, instructions in the PAM configuration file (on many system types, <emphasis role="bold">/etc/pam.conf</emphasis>)
3033 fill the same function. See the instructions in the OpenAFS Quick Beginnings for installing AFS-modified login
3037 <primary>local password file</primary>
3039 <secondary>when not using AFS-modified login utility</secondary>
3043 <sect2 id="HDRWQ69">
3044 <title>Using Two-Step Login and Authentication</title>
3046 <para>In cells that do not use an AFS-modified login utility, users must issue separate commands to login and authenticate, as
3047 detailed in the OpenAFS User Guide: <orderedlist>
3049 <para>They use the standard <emphasis role="bold">login</emphasis> program to login to the local file system, providing
3050 the password listed in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
3055 <para>They must issue the <emphasis role="bold">klog</emphasis> command to authenticate with the AFS authentication
3056 service, including its <emphasis role="bold">-setpag</emphasis> flag to associate the new tokens with a process
3057 authentication group (PAG).</para>
3059 </orderedlist></para>
3061 <para>As mentioned in <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>, you can invoke the <emphasis
3062 role="bold">klog -setpag</emphasis> command in a user's <emphasis role="bold">.login</emphasis> file (or equivalent) so that
3063 the user does not have to remember to issue the command after logging in. The user still must type a password twice, once at
3064 the prompt generated by the login utility and once at the <emphasis role="bold">klog</emphasis> command's prompt. This implies
3065 that the two passwords can differ, but it is less confusing if they do not.</para>
3067 <para>Another effect of not using an AFS-modified login utility is that the AFS servers recognize the standard <emphasis
3068 role="bold">login</emphasis> program as the <emphasis role="bold">anonymous</emphasis> user. If the <emphasis
3069 role="bold">login</emphasis> program needs to access any AFS files (such as the <emphasis role="bold">.login</emphasis> file
3070 in a user's home directory), then the ACL that protects the file must include an entry granting the <emphasis
3071 role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
3072 role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group.</para>
3074 <para>When you do not use an AFS-modified login utility, an actual (scrambled) password must appear in the local password file
3075 for each user. Use the <emphasis role="bold">/bin/passwd</emphasis> file to insert or change these passwords. It is simpler if
3076 the password in the local password file matches the AFS password, but it is not required.</para>
3079 <primary>tokens</primary>
3081 <secondary>displaying for user</secondary>
3085 <primary>tokens</primary>
3087 <secondary>command</secondary>
3091 <primary>commands</primary>
3093 <secondary>tokens</secondary>
3097 <primary>listing</primary>
3099 <secondary>tokens held by issuer</secondary>
3103 <primary>commands</primary>
3105 <secondary>klog</secondary>
3109 <primary>klog command</primary>
3113 <primary>server process</primary>
3115 <secondary>creating ticket (tokens) for</secondary>
3119 <primary>tickets</primary>
3121 <secondary></secondary>
3127 <primary>tokens</primary>
3129 <secondary>creating for server process</secondary>
3133 <primary>authenticated identity</primary>
3135 <secondary>acquiring with klog command</secondary>
3139 <primary>unlog command</primary>
3143 <primary>commands</primary>
3145 <secondary>unlog</secondary>
3149 <primary>discarding</primary>
3151 <secondary>tokens</secondary>
3155 <primary>tokens</primary>
3157 <secondary>discarding with unlog command</secondary>
3161 <sect2 id="Header_81">
3162 <title>Obtaining, Displaying, and Discarding Tokens</title>
3164 <para>Once logged in, a user can obtain a token at any time with the <emphasis role="bold">klog</emphasis> command. If a valid
3165 token already exists, the new one overwrites it. If a PAG already exists, the new token is associated with it.</para>
3167 <para>By default, the <emphasis role="bold">klog</emphasis> command authenticates the issuer using the identity currently
3168 logged in to the local file system. To authenticate as a different identity, use the <emphasis
3169 role="bold">-principal</emphasis> argument. To obtain a token for a foreign cell, use the <emphasis
3170 role="bold">-cell</emphasis> argument (it can be combined with the <emphasis role="bold">-principal</emphasis> argument). See
3171 the OpenAFS User Guide and the entry for the <emphasis role="bold">klog</emphasis> command in the OpenAFS Administration
3174 <para>To discard either all tokens or the token for a particular cell, issue the <emphasis role="bold">unlog</emphasis>
3175 command. The command affects only the tokens associated with the current command shell. See the OpenAFS User Guideand the
3176 entry for the <emphasis role="bold">unlog</emphasis> command in the OpenAFS Administration Reference.</para>
3178 <para>To display the tokens associated with the current command shell, issue the <emphasis role="bold">tokens</emphasis>
3179 command. The following examples illustrate its output in various situations.</para>
3181 <para>If the issuer is not authenticated in any cell:</para>
3184 % <emphasis role="bold">tokens</emphasis>
3185 Tokens held by the Cache Manager:
3189 <para>The following shows the output for a user with AFS UID 1000 in the ABC Corporation cell:</para>
3192 % <emphasis role="bold">tokens</emphasis>
3193 Tokens held by the Cache Manager:
3194 User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun 2 10:00]
3198 <para>The following shows the output for a user who is authenticated in ABC Corporation cell, the State University cell and
3199 the DEF Company cell. The user has different AFS UIDs in the three cells. Tokens for the last cell are expired:</para>
3202 % <emphasis role="bold">tokens</emphasis>
3203 Tokens held by the Cache Manager:
3204 User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun 2 10:00]
3205 User's (AFS ID 4286) tokens for afs@stateu.edu [Expires Jun 3 1:34]
3206 User's (AFS ID 22) tokens for afs@def.com [>>Expired<<]
3210 <para>The Kerberos version of the <emphasis role="bold">tokens</emphasis> command (the <emphasis
3211 role="bold">tokens.krb</emphasis> command), also reports information on the ticket-granting ticket, including the ticket's
3212 owner, the ticket-granting service, and the expiration date, as in the following example. Also see <link
3213 linkend="HDRWQ70">Support for Kerberos Authentication</link>.</para>
3216 % <emphasis role="bold">tokens.krb</emphasis>
3217 Tokens held by the Cache Manager:
3218 User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun 2 10:00]
3219 User smith's tokens for krbtgt.ABC.COM@abc.com [Expires Jun 2 10:00]
3224 <sect2 id="Header_82">
3225 <title>Setting Default Token Lifetimes for Users</title>
3228 <primary>tokens</primary>
3230 <secondary>setting default lifetimes for users</secondary>
3233 <para>The maximum lifetime of a user token is the smallest of the ticket lifetimes recorded in the following three
3234 Authentication Database entries. The <emphasis role="bold">kas examine</emphasis> command reports the lifetime as
3235 <computeroutput>Max ticket lifetime</computeroutput>. Administrators who have the <computeroutput>ADMIN</computeroutput> flag
3236 on their Authentication Database entry can use the <emphasis role="bold">-lifetime</emphasis> argument to the <emphasis
3237 role="bold">kas setfields</emphasis> command to set an entry's ticket lifetime. <itemizedlist>
3239 <para>The <emphasis role="bold">afs</emphasis> entry, which corresponds to the AFS server processes. The default is 100
3244 <para>The <emphasis role="bold">krbtgt</emphasis>.cellname entry, which corresponds to the ticket-granting ticket used
3245 internally in generating the token. The default is 720 hours (30 days).</para>
3249 <para>The entry for the user of the AFS-modified login utility or issuer of the <emphasis role="bold">klog</emphasis>
3250 command. The default is 25 hours for user entries created using the AFS 3.1 or later version of the Authentication
3251 Server, and 100 hours for user entries created using the AFS 3.0 version of the Authentication Server. A user can use
3252 the <emphasis role="bold">kas examine</emphasis> command to display his or her own Authentication Database entry.</para>
3254 </itemizedlist></para>
3257 <para>An AFS-modified login utility always grants a token with a lifetime calculated from the previously described three
3258 values. When issuing the <emphasis role="bold">klog</emphasis> command, a user can request a lifetime shorter than the
3259 default by using the <emphasis role="bold">-lifetime</emphasis> argument. For further information, see the OpenAFS User
3260 Guide and the <emphasis role="bold">klog</emphasis> reference page in the OpenAFS Administration Reference.</para>
3264 <sect2 id="Header_83">
3265 <title>Changing Passwords</title>
3268 <primary>password</primary>
3270 <secondary>changing in AFS</secondary>
3274 <primary>kpasswd command</primary>
3278 <primary>commands</primary>
3280 <secondary>kpasswd</secondary>
3284 <primary>kas commands</primary>
3286 <secondary>setpassword</secondary>
3290 <primary>commands</primary>
3292 <secondary>kas setpassword</secondary>
3295 <para>Regular AFS users can change their own passwords by using either the <emphasis role="bold">kpasswd</emphasis> or
3296 <emphasis role="bold">kas setpassword</emphasis> command. The commands prompt for the current password and then twice for the
3297 new password, to screen out typing errors.</para>
3299 <para>Administrators who have the <computeroutput>ADMIN</computeroutput> flag on their Authentication Database entries can
3300 change any user's password, either by using the <emphasis role="bold">kpasswd</emphasis> command (which requires knowing the
3301 current password) or the <emphasis role="bold">kas setpassword</emphasis> command.</para>
3303 <para>If your cell does not use an AFS-modified login utility, remember also to change the local password, using the operating
3304 system's password-changing command. For more instructions on changing passwords, see <link linkend="HDRWQ516">Changing AFS
3305 Passwords</link>.</para>
3308 <sect2 id="Header_84">
3309 <title>Imposing Restrictions on Passwords and Authentication Attempts</title>
3311 <para>You can help to make your cell more secure by imposing restrictions on user passwords and authentication attempts. To
3312 impose the restrictions as you create an account, use the <emphasis role="bold">A</emphasis> instruction in the <emphasis
3313 role="bold">uss</emphasis> template file as described in <link linkend="HDRWQ478">Increasing Account Security with the A
3314 Instruction</link>. To set or change the values on an existing account, use the <emphasis role="bold">kas setfields</emphasis>
3315 command as described in <link linkend="HDRWQ515">Improving Password and Authentication Security</link>.</para>
3318 <primary>password</primary>
3320 <secondary>expiration</secondary>
3324 <primary>password</primary>
3326 <secondary>lifetime</secondary>
3330 <primary>kas commands</primary>
3332 <secondary>setfields</secondary>
3336 <primary>commands</primary>
3338 <secondary>kas setfields</secondary>
3342 <primary>Authentication Database</primary>
3344 <secondary>password lifetime, setting</secondary>
3348 <primary>password</primary>
3350 <secondary>restricting reuse</secondary>
3353 <para>By default, AFS passwords never expire. Limiting password lifetime can help improve security by decreasing the time the
3354 password is subject to cracking attempts. You can choose an lifetime from 1 to 254 days after the password was last changed.
3355 It automatically applies to each new password as it is set. When the user changes passwords, you can also insist that the new
3356 password is not similar to any of the 20 passwords previously used.</para>
3359 <primary>password</primary>
3361 <secondary>consequences of multiple failed authentication attempts</secondary>
3365 <primary>kas commands</primary>
3367 <secondary>setfields</secondary>
3371 <primary>commands</primary>
3373 <secondary>kas setfields</secondary>
3377 <primary>authentication</primary>
3379 <secondary>consequences of multiple failures</secondary>
3382 <para>Unscrupulous users can try to gain access to your AFS cell by guessing an authorized user's password. To protect against
3383 this type of attack, you can limit the number of times that a user can consecutively fail to provide the correct password.
3384 When the limit is exceeded, the authentication service refuses further authentication attempts for a specified period of time
3385 (the lockout time). To reenable authentication attempts before the lockout time expires, an administrator must issue the
3386 <emphasis role="bold">kas unlock</emphasis> command.</para>
3389 <primary>password</primary>
3391 <secondary>checking quality of</secondary>
3395 <primary>kpasswd command</primary>
3399 <primary>commands</primary>
3401 <secondary>kpasswd</secondary>
3405 <primary>kas commands</primary>
3407 <secondary>setpassword</secondary>
3411 <primary>kpwvalid program</primary>
3414 <para>In addition to settings on user's authentication accounts, you can improve security by automatically checking the
3415 quality of new user passwords. The <emphasis role="bold">kpasswd</emphasis> and <emphasis role="bold">kas
3416 setpassword</emphasis> commands pass the proposed password to a program or script called <emphasis
3417 role="bold">kpwvalid</emphasis>, if it exists. The <emphasis role="bold">kpwvalid</emphasis> performs quality checks and
3418 returns a code to indicate whether the password is acceptable. You can create your own program or modified the sample program
3419 included in the AFS distribution. See the <emphasis role="bold">kpwvalid</emphasis> reference page in the OpenAFS
3420 Administration Reference.</para>
3422 <para>There are several types of quality checks that can improve password quality. <itemizedlist>
3424 <para>The password is a minimum length</para>
3428 <para>The password is not a word</para>
3432 <para>The password contains both numbers and letters</para>
3434 </itemizedlist></para>
3437 <sect2 id="HDRWQ70">
3438 <title>Support for Kerberos Authentication</title>
3441 <primary>Kerberos</primary>
3443 <secondary>support for in AFS</secondary>
3447 <primary>commands</primary>
3449 <secondary>klog.krb</secondary>
3453 <primary>commands</primary>
3455 <secondary>pagsh.krb</secondary>
3459 <primary>commands</primary>
3461 <secondary>tokens.krb</secondary>
3465 <primary>klog.krb command</primary>
3469 <primary>pagsh.krb command</primary>
3473 <primary>tokens.krb command</primary>
3476 <para>If your site is using standard Kerberos authentication rather than the AFS Authentication Server, use the modified
3477 versions of the <emphasis role="bold">klog</emphasis>, <emphasis role="bold">pagsh</emphasis>, and <emphasis
3478 role="bold">tokens</emphasis> commands that support Kerberos authentication. The binaries for the modified version of these
3479 commands have the same name as the standard binaries with the addition of a <emphasis role="bold">.krb</emphasis>
3482 <para>Use either the Kerberos version or the standard command throughout the cell; do not mix the two versions. AFS Product
3483 Support can provide instructions on installing the Kerberos version of these four commands. For information on the differences
3484 between the two versions of these commands, see the OpenAFS Administration Reference.</para>
3488 <sect1 id="HDRWQ71">
3489 <title>Security and Authorization in AFS</title>
3491 <para>AFS incorporates several features to ensure that only authorized users gain access to data. This section summarizes the
3492 most important of them and suggests methods for improving security in your cell.</para>
3494 <sect2 id="HDRWQ72">
3495 <title>Some Important Security Features</title>
3498 <primary>security</primary>
3500 <secondary>AFS features</secondary>
3504 <primary>AFS</primary>
3506 <secondary>security features</secondary>
3510 <title>ACLs on Directories</title>
3512 <para>Files in AFS are protected by the access control list (ACL) associated with their parent directory. The ACL defines
3513 which users or groups can access the data in the directory, and in what way. See <link linkend="HDRWQ562">Managing Access
3514 Control Lists</link>.</para>
3518 <title>Mutual Authentication Between Client and Server</title>
3520 <para>When an AFS client and server process communicate, each requires the other to prove its identity during mutual
3521 authentication, which involves the exchange of encrypted information that only valid parties can decrypt and respond to. For
3522 a detailed description of the mutual authentication process, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
3523 Authentication</link>.</para>
3526 <para>AFS server processes mutually authenticate both with one another and with processes that represent human users. After
3527 mutual authentication is complete, the server and client have established an authenticated connection, across which they can
3528 communicate repeatedly without having to authenticate again until the connection expires or one of the parties closes it.
3529 Authenticated connections have varying lifetimes.</para>
3532 <title>Tokens</title>
3534 <para>In order to access AFS files, users must prove their identities to the AFS authentication service by providing the
3535 correct AFS password. If the password is correct, the authentication service sends the user a token as evidence of
3536 authenticated status. See <link linkend="HDRWQ63">Login and Authentication in AFS</link>.</para>
3539 <para>Servers assign the user identity <emphasis role="bold">anonymous</emphasis> to users and processes that do not have a
3540 valid token. The <emphasis role="bold">anonymous</emphasis> identity has only the access granted to the <emphasis
3541 role="bold">system:anyuser</emphasis> group on ACLs.</para>
3544 <title>Authorization Checking</title>
3546 <para>Mutual authentication establishes that two parties communicating with one another are actually who they claim to be.
3547 For many functions, AFS server processes also check that the client whose identity they have verified is also authorized to
3548 make the request. Different requests require different kinds of privilege. See <link linkend="HDRWQ73">Three Types of
3549 Privilege</link>.</para>
3553 <title>Encrypted Network Communications</title>
3556 <primary>network</primary>
3558 <secondary>encrypted communication in AFS</secondary>
3562 <primary>encrypted network communication</primary>
3566 <primary>security</primary>
3568 <secondary>encrypted network communication</secondary>
3571 <para>The AFS server processes encrypt particularly sensitive information before sending it back to clients. Even if an
3572 unauthorized party is able to eavesdrop on an authenticated connection, they cannot decipher encrypted data without the
3576 <para>The following AFS commands encrypt data because they involve server encryption keys and passwords: <itemizedlist>
3578 <para>The <emphasis role="bold">bos addkey</emphasis> command, which adds a server encryption key to the <emphasis
3579 role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
3583 <para>The <emphasis role="bold">bos listkeys</emphasis> command, which lists the server encryption keys from the
3584 <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
3588 <para>The <emphasis role="bold">kpasswd</emphasis> command, which changes a password in the Authentication
3593 <para>Most commands in the <emphasis role="bold">kas</emphasis> command suite</para>
3595 </itemizedlist></para>
3597 <para>In addition, the United States edition of the Update Server encrypts sensitive information (such as the contents of
3598 <emphasis role="bold">KeyFile</emphasis>) when distributing it. Other commands in the <emphasis role="bold">bos</emphasis>
3599 suite and the commands in the <emphasis role="bold">fs</emphasis>, <emphasis role="bold">pts</emphasis> and <emphasis
3600 role="bold">vos</emphasis> suites do not encrypt data before transmitting it.</para>
3603 <sect2 id="HDRWQ73">
3604 <title>Three Types of Privilege</title>
3606 <para>AFS uses three separate types of privilege for the reasons discussed in <link linkend="HDRWQ585">The Reason for Separate
3607 Privileges</link>. <itemizedlist>
3609 <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. Members are entitled to issue any
3610 <emphasis role="bold">pts</emphasis> command and those <emphasis role="bold">fs</emphasis> commands that set volume
3611 quota. By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
3612 role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
3613 permissions on every ACL in the file tree even if the ACL does not include an entry for them.</para>
3617 <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. An administrator with this
3618 flag can issue any <emphasis role="bold">kas</emphasis> command.</para>
3622 <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. An administrator whose username
3623 appears in this file can issue any <emphasis role="bold">bos</emphasis>, <emphasis role="bold">vos</emphasis>, or
3624 <emphasis role="bold">backup</emphasis> command (although some <emphasis role="bold">backup</emphasis> commands require
3625 additional privilege as described in <link linkend="HDRWQ260">Granting Administrative Privilege to Backup
3626 Operators</link>).</para>
3628 </itemizedlist></para>
3631 <sect2 id="Header_89">
3632 <title>Authorization Checking versus Authentication</title>
3634 <para>AFS distinguishes between authentication and authorization checking. Authentication refers to the process of proving
3635 identity. Authorization checking refers to the process of verifying that an authenticated identity is allowed to perform a
3636 certain action.</para>
3638 <para>AFS implements authentication at the level of connections. Each time two parties establish a new connection, they
3639 mutually authenticate. In general, each issue of an AFS command establishes a new connection between AFS server process and
3642 <para>AFS implements authorization checking at the level of server machines. If authorization checking is enabled on a server
3643 machine, then all of the server processes running on it provide services only to authorized users. If authorization checking
3644 is disabled on a server machine, then all of the server processes perform any action for anyone. Obviously, disabling
3645 authorization checking is an extreme security exposure. For more information, see <link linkend="HDRWQ123">Managing
3646 Authentication and Authorization Requirements</link>.</para>
3649 <sect2 id="HDRWQ74">
3650 <title>Improving Security in Your Cell</title>
3653 <primary>security</primary>
3655 <secondary>suggestions for improving</secondary>
3658 <para>You can improve the level of security in your cell by configuring user accounts, server machines, and system
3659 administrator accounts in the indicated way.</para>
3662 <title>User Accounts</title>
3664 <para><itemizedlist>
3666 <para>Use an AFS-modified login utility, or include the <emphasis role="bold">-setpag</emphasis> flag to the <emphasis
3667 role="bold">klog</emphasis> command, to associate the credential structure that houses tokens with a PAG rather than a
3668 UNIX UID. This prevents users from inheriting someone else's tokens by assuming their UNIX identity. For further
3669 discussion, see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
3673 <para>Encourage users to issue the <emphasis role="bold">unlog</emphasis> command to destroy their tokens before
3674 logging out. This forestalls attempts to access tokens left behind kernel memory. Consider including the <emphasis
3675 role="bold">unlog</emphasis> command in every user's <emphasis role="bold">.logout</emphasis> file or
3678 </itemizedlist></para>
3682 <title>Server Machines</title>
3684 <para><itemizedlist>
3686 <para>Disable authorization checking only in emergencies or for very brief periods of time. It is best to work at the
3687 console of the affected machine during this time, to prevent anyone else from accessing the machine through the
3692 <para>Change the AFS server encryption key on a frequent and regular schedule. Make it difficult to guess (a long
3693 string including nonalphabetic characters, for instance). Unlike user passwords, the password from which the AFS key
3694 is derived can be longer than eight characters, because it is never used during login. The <emphasis role="bold">kas
3695 setpassword</emphasis> command accepts a password hundreds of characters long. For instructions, see <link
3696 linkend="HDRWQ355">Managing Server Encryption Keys</link>.</para>
3700 <para>As much as possible, limit the number of people who can login at a server machine's console or remotely.
3701 Imposing this limit is an extra security precaution rather than a necessity. The machine cannot serve as an AFS client
3702 in this case.</para>
3706 <para>Particularly limit access to the local superuser <emphasis role="bold">root</emphasis> account on a server
3707 machine. The local superuser <emphasis role="bold">root</emphasis> has free access to important administrative
3708 subdirectories of the <emphasis role="bold">/usr/afs</emphasis> directory, as described in <link linkend="HDRWQ53">AFS
3709 Files on the Local Disk</link>.</para>
3712 <primary>root superuser</primary>
3714 <secondary>limiting logins</secondary>
3719 <para>As in any computing environment, server machines must be located in a secured area. Any other security measures
3720 are effectively worthless if unauthorized people can access the computer hardware.</para>
3722 </itemizedlist></para>
3726 <title>System Administrators</title>
3728 <para><itemizedlist>
3730 <para>Limit the number of system administrators in your cell. Limit the use of system administrator accounts on
3731 publicly accessible workstations. Such machines are not secure, so unscrupulous users can install programs that try to
3732 steal tokens or passwords. If administrators must use publicly accessible workstations at times, they must issue the
3733 <emphasis role="bold">unlog</emphasis> command before leaving the machine.</para>
3737 <para>Create an administrative account for each administrator separate from the personal account, and assign AFS
3738 privileges only to the administrative account. The administrators must authenticate to the administrative accounts to
3739 perform duties that require privilege, which provides a useful audit trail as well.</para>
3743 <para>Administrators must not leave a machine unattended while they have valid tokens. Issue the <emphasis
3744 role="bold">unlog</emphasis> command before leaving.</para>
3748 <para>Use the <emphasis role="bold">-lifetime</emphasis> argument to the <emphasis role="bold">kas
3749 setfields</emphasis> command to set the token lifetime for administrative accounts to a fairly short amount of time.
3750 The default lifetime for AFS tokens is 25 hours, but 30 or 60 minutes is possibly a more reasonable lifetime for
3751 administrative tokens. The tokens for administrators who initiate AFS Backup System operations must last somewhat
3752 longer, because it can take several hours to complete some dump operations, depending on the speed of the tape device
3753 and the network connecting it to the file server machines that house the volumes is it accessing.</para>
3757 <para>Limit administrators' use of the <emphasis role="bold">telnet</emphasis> program. It sends unencrypted passwords
3758 across the network. Similarly, limit use of other remote programs such as <emphasis role="bold">rsh</emphasis> and
3759 <emphasis role="bold">rcp</emphasis>, which send unencrypted tokens across the network.</para>
3761 </itemizedlist></para>
3765 <sect2 id="HDRWQ75">
3766 <title>A More Detailed Look at Mutual Authentication</title>
3769 <primary>mutual authentication</primary>
3773 <primary>distributed file system</primary>
3775 <secondary>security issues</secondary>
3779 <primary>shared secret</primary>
3783 <primary>server encryption key</primary>
3785 <secondary>defined</secondary>
3788 <para>As in any file system, security is a prime concern in AFS. A file system that makes file sharing easy is not useful if
3789 it makes file sharing mandatory, so AFS incorporates several features that prevent unauthorized users from accessing data.
3790 Security in a networked environment is difficult because almost all procedures require transmission of information across
3791 wires that almost anyone can tap into. Also, many machines on networks are powerful enough that unscrupulous users can monitor
3792 transactions or even intercept transmissions and fake the identity of one of the participants.</para>
3794 <para>The most effective precaution against eavesdropping and information theft or fakery is for servers and clients to accept
3795 the claimed identity of the other party only with sufficient proof. In other words, the nature of the network forces all
3796 parties on the network to assume that the other party in a transaction is not genuine until proven so. Mutual authentication
3797 is the means through which parties prove their genuineness.</para>
3799 <para>Because the measures needed to prevent fakery must be quite sophisticated, the implementation of mutual authentication
3800 procedures is complex. The underlying concept is simple, however: parties prove their identities by demonstrating knowledge of
3801 a shared secret. A shared secret is a piece of information known only to the parties who are mutually authenticating (they can
3802 sometimes learn it in the first place from a trusted third party or some other source). The party who originates the
3803 transaction presents the shared secret and refuses to accept the other party as valid until it shows that it knows the secret
3806 <para>The most common form of shared secret in AFS transactions is the encryption key, also referred to simply as a key. The
3807 two parties use their shared key to encrypt the packets of information they send and to decrypt the ones they receive.
3808 Encryption using keys actually serves two related purposes. First, it protects messages as they cross the network, preventing
3809 anyone who does not know the key from eavesdropping. Second, ability to encrypt and decrypt messages successfully indicates
3810 that the parties are using the key (it is their shared secret). If they are using different keys, messages remain scrambled
3811 and unintelligible after decryption.</para>
3813 <para>The following sections describe AFS's mutual authentication procedures in more detail. Feel free to skip these sections
3814 if you are not interested in the mutual authentication process.</para>
3816 <sect3 id="Header_92">
3817 <title>Simple Mutual Authentication</title>
3819 <para>Simple mutual authentication involves only one encryption key and two parties, generally a client and server. The
3820 client contacts the server by sending a challenge message encrypted with a key known only to the two of them. The server
3821 decrypts the message using its key, which is the same as the client's if they really do share the same secret. The server
3822 responds to the challenge and uses its key to encrypt its response. The client uses its key to decrypt the server's
3823 response, and if it is correct, then the client can be sure that the server is genuine: only someone who knows the same key
3824 as the client can decrypt the challenge and answer it correctly. On its side, the server concludes that the client is
3825 genuine because the challenge message made sense when the server decrypted it.</para>
3827 <para>AFS uses simple mutual authentication to verify user identities during the first part of the login procedure. In that
3828 case, the key is based on the user's password.</para>
3831 <sect3 id="HDRWQ76">
3832 <title>Complex Mutual Authentication</title>
3834 <para>Complex mutual authentication involves three encryption keys and three parties. All secure AFS transactions (except
3835 the first part of the login process) employ complex mutual authentication.</para>
3838 <primary>ticket-granter</primary>
3842 <primary>server encryption key</primary>
3846 <primary>tokens</primary>
3848 <secondary>data in</secondary>
3851 <para>When a client wishes to communicate with a server, it first contacts a third party called a ticket-granter. The
3852 ticket-granter and the client mutually authenticate using the simple procedure. When they finish, the ticket-granter gives
3853 the client a server ticket (or simply ticket) as proof that it (the ticket-granter) has preverified the identity of the
3854 client. The ticket-granter encrypts the ticket with the first of the three keys, called the server encryption key because it
3855 is known only to the ticket-granter and the server the client wants to contact. The client does not know this key.</para>
3857 <para>The ticket-granter sends several other pieces of information along with the ticket. They enable the client to use the
3858 ticket effectively despite being unable to decrypt the ticket itself. Along with the ticket, the items constitute a token:
3861 <para>A session key, which is the second encryption key involved in mutual authentication. The ticket-granter invents
3862 the session key at random as the shared secret between client and server. For reasons explained further below, the
3863 ticket-granter also puts a copy of the session key inside the ticket. The client and server use the session key to
3864 encrypt messages they send to one another during their transactions. The ticket-granter invents a different session
3865 key for each connection between a client and a server (there can be several transactions during a single
3869 <primary>session key</primary>
3874 <para>The name of the server for which the ticket is valid (and so which server encryption key encrypts the ticket
3879 <para>A ticket lifetime indicator. The default lifetime of AFS server tickets is 100 hours. If the client wants to
3880 contact the server again after the ticket expires, it must contact the ticket-granter to get a new ticket.</para>
3882 </itemizedlist></para>
3884 <para>The ticket-granter seals the entire token with the third key involved in complex mutual authentication--the key known
3885 only to it (the ticket-granter) and the client. In some cases, this third key is derived from the password of the human user
3886 whom the client represents.</para>
3888 <para>Now that the client has a valid server ticket, it is ready to contact the server. It sends the server two things:
3891 <para>The server ticket. This is encrypted with the server encryption key.</para>
3895 <para>Its request message, encrypted with the session key. Encrypting the message protects it as it crosses the
3896 network, since only the server/client pair for whom the ticket-granter invented the session key know it.</para>
3898 </itemizedlist></para>
3900 <para>At this point, the server does not know the session key, because the ticket-granter just created it. However, the
3901 ticket-granter put a copy of the session key inside the ticket. The server uses the server encryption key to decrypts the
3902 ticket and learns the session key. It then uses the session key to decrypt the client's request message. It generates a
3903 response and sends it to the client. It encrypts the response with the session key to protect it as it crosses the
3906 <para>This step is the heart of mutual authentication between client and server, because it proves to both parties that they
3907 know the same secret: <itemizedlist>
3909 <para>The server concludes that the client is authorized to make a request because the request message makes sense
3910 when the server decrypts it using the session key. If the client uses a different session key than the one the server
3911 finds inside the ticket, then the request message remains unintelligible even after decryption. The two copies of the
3912 session key (the one inside the ticket and the one the client used) can only be the same if they both came from the
3913 ticket-granter. The client cannot fake knowledge of the session key because it cannot look inside the ticket, sealed
3914 as it is with the server encryption key known only to the server and the ticket-granter. The server trusts the
3915 ticket-granter to give tokens only to clients with whom it (the ticket-granter) has authenticated, so the server
3916 decides the client is legitimate.</para>
3918 <para>(Note that there is no direct communication between the ticket-granter and the server, even though their
3919 relationship is central to ticket-based mutual authentication. They interact only indirectly, via the client's
3920 possession of a ticket sealed with their shared secret.)</para>
3924 <para>The client concludes that the server is genuine and trusts the response it gets back from the server, because
3925 the response makes sense after the client decrypts it using the session key. This indicates that the server encrypted
3926 the response with the same session key as the client knows. The only way for the server to learn that matching session
3927 key is to decrypt the ticket first. The server can only decrypt the ticket because it shares the secret of the server
3928 encryption key with the ticket-granter. The client trusts the ticket-granter to give out tickets only for legitimate
3929 servers, so the client accepts a server that can decrypt the ticket as genuine, and accepts its response.</para>
3931 </itemizedlist></para>
3936 <sect1 id="HDRWQ77">
3937 <title>Backing Up AFS Data</title>
3939 <para>AFS provides two related facilities that help the administrator back up AFS data: backup volumes and the AFS Backup
3942 <sect2 id="Header_95">
3943 <title>Backup Volumes</title>
3945 <para>The first facility is the backup volume, which you create by cloning a read/write volume. The backup volume is read-only
3946 and so preserves the state of the read/write volume at the time the clone is made.</para>
3948 <para>Backup volumes can ease administration if you mount them in the file system and make their contents available to users.
3949 For example, it often makes sense to mount the backup version of each user volume as a subdirectory of the user's home
3950 directory. A conventional name for this mount point is <emphasis role="bold">OldFiles</emphasis>. Create a new version of the
3951 backup volume (that is, reclone the read/write) once a day to capture any changes that were made since the previous backup. If
3952 a user accidentally removes or changes data, the user can restore it from the backup volume, rather than having to ask you to
3955 <para>The OpenAFS User Guide does not mention backup volumes, so regular users do not know about them if you decide not to use
3956 them. This implies that if you <emphasis role="bold">do</emphasis> make backup versions of user volumes, you need to tell your
3957 users about how the backup works and where you have mounted it.</para>
3959 <para>Users are often concerned that the data in a backup volume counts against their volume quota and some of them even want
3960 to remove the <emphasis role="bold">OldFiles</emphasis> mount point. It does not, because the backup volume is a separate
3961 volume. The only amount of space it uses in the user's volume is the amount needed for the mount point, which is about the
3962 same as the amount needed for a standard directory element.</para>
3964 <para>Backup volumes are discussed in detail in <link linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
3967 <sect2 id="Header_96">
3968 <title>The AFS Backup System</title>
3970 <para>Backup volumes can reduce restoration requests, but they reside on disk and so do not protect data from loss due to
3971 hardware failure. Like any file system, AFS is vulnerable to this sort of data loss.</para>
3973 <para>To protect your cell's users from permanent loss of data, you are strongly urged to back up your file system to tape on
3974 a regular and frequent schedule. The AFS Backup System is available to ease the administration and performance of backups. For
3975 detailed information about the AFS Backup System, see <link linkend="HDRWQ248">Configuring the AFS Backup System</link> and
3976 <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
3981 <sect1 id="HDRWQ79">
3982 <title>Accessing AFS through NFS</title>
3984 <para>Users of NFS client machines can access the AFS filespace by mounting the <emphasis role="bold">/afs</emphasis> directory
3985 of an AFS client machine that is running the NFS/AFS Translator. This is a particular advantage in cells already running NFS who
3986 want to access AFS using client machines for which AFS is not available. See <link linkend="HDRWQ595">Appendix A, Managing the
3987 NFS/AFS Translator</link>.</para>