1 <?xml version="1.0" encoding="UTF-8"?>
4 <title>Issues in Cell Configuration and Administration</title>
6 <para>This chapter discusses many of the issues to consider when
7 configuring and administering a cell, and directs you to detailed
8 related information available elsewhere in this guide. It is assumed you
9 are already familiar with the material in <link linkend="HDRWQ5">An
10 Overview of OpenAFS Administration</link>.</para>
12 <para>It is best to read this chapter before installing your cell's
13 first file server machine or performing any other administrative
17 <primary>AFS</primary>
19 <secondary>differences from UNIX summarized</secondary>
23 <primary>UNIX</primary>
25 <secondary>differences from AFS summarized</secondary>
29 <primary>differences</primary>
31 <secondary>between AFS and UNIX, summarized</secondary>
36 <title>Differences between AFS and UNIX: A Summary</title>
38 <para>AFS behaves like a standard UNIX file system in most respects,
39 while also making file sharing easy within and between cells. This
40 section describes some differences between AFS and the UNIX file
41 system, referring you to more detailed information as
45 <primary>protection</primary>
47 <secondary>AFS compared to UNIX</secondary>
50 <sect2 id="Header_35">
51 <title>Differences in File and Directory Protection</title>
53 <para>AFS augments the standard UNIX file protection mechanism in
54 two ways: it associates an <emphasis>access control list
55 (ACL)</emphasis> with each directory, and it enables users to define
56 a large number of their own groups, which can be placed on
59 <para>AFS uses ACLs to protect files and directories, rather than
60 relying exclusively on the mode bits. This has several implications,
61 which are discussed further in the indicated sections:
64 <para>AFS ACLs use seven access permissions rather than the
65 three UNIX mode bits. See <link linkend="HDRWQ567">The AFS ACL
66 Permissions</link>.</para>
70 <para>For directories, AFS ignores the UNIX mode bits. For
71 files, AFS uses only the first set of mode bits (the <emphasis
72 role="bold">owner</emphasis> bits), and their meaning
73 interacts with permissions on the directory's ACL. See <link
74 linkend="HDRWQ580">How AFS Interprets the UNIX Mode
79 <para>A directory's ACL protects all of the files in a
80 directory in the same manner. To apply a more restrictive set
81 of AFS permissions to certain file, place it in directory with
82 a different ACL. If a directory must contain files with
83 different permissions, use symbolic links to point to files
84 stored in directories with different ACLs.</para>
88 <para>Moving a file to a different directory changes its
89 protection. See <link linkend="HDRWQ566">Differences Between
90 UFS and AFS Data Protection</link>.</para>
94 <para>An ACL can include about 20 entries granting different
95 combinations of permissions to different users or groups,
96 rather than only the three UNIX entities represented by the
97 three sets of mode bits. See <link
98 linkend="HDRWQ566">Differences Between UFS and AFS Data
99 Protection</link>.</para>
103 <para>You can designate an AFS file as write-only as in the
104 UNIX file system, by setting only the <emphasis
105 role="bold">w</emphasis> (<emphasis
106 role="bold">write</emphasis>) mode bit. You cannot designate
107 an AFS directory as write-only, because AFS ignores the mode
108 bits on a directory. See <link linkend="HDRWQ580">How AFS
109 Interprets the UNIX Mode Bits</link>.</para>
114 <para>AFS enables users to create groups and add other users to
115 those groups. Placing these groups on ACLs extends the same
116 permissions to a number of exactly specified users at the same time,
117 which is much more convenient than placing the individuals on the
118 ACLs directly. See <link linkend="HDRWQ531">Administering the
119 Protection Database</link>.</para>
121 <para>There are also system-defined groups, <emphasis
122 role="bold">system:anyuser</emphasis> and <emphasis
123 role="bold">system:authuser</emphasis>, whose presence on an ACL
124 extends access to a wide range of users at once. See <link
125 linkend="HDRWQ535">The System Groups</link> and <link
126 linkend="HDRWQ571">Using Groups on ACLs</link>.</para>
129 <primary>authentication</primary>
131 <secondary>AFS compared to UNIX</secondary>
135 <primary>password</primary>
137 <secondary>AFS compared to UNIX</secondary>
142 <title>Differences in Authentication</title>
144 <para>Just as the AFS filespace is distinct from each machine's
145 local file system, AFS authentication is separate from local
146 login. This has two practical implications, which will already be
147 familiar to users and system administrators who use Kerberos for
151 <para>To access AFS files, users must log into the local
152 machine as normal, obtain Kerberos tickets, and then obtain
153 AFS tokens. This process can often be automated through the
154 system authentication configuration so that the user logs into
155 the system as normal and obtains Kerberos tickets and AFS
156 tokens transparently. If you cannot or chose not to configure
157 the system this way, your users must login and authenticate in
158 separate steps, as detailed in the <emphasis>OpenAFS User
159 Guide</emphasis>.</para>
163 <para>Passwords may be stored in two separate places: the
164 Kerberos KDC and, optionally, each machine's local user
165 database (<emphasis role="bold">/etc/passwd</emphasis> or
166 equivalent) for the local system. A user's passwords in the
167 two places can differ if desired.</para>
173 <sect2 id="Header_37">
174 <title>Differences in the Semantics of Standard UNIX
177 <para>This section summarizes how AFS modifies the functionality of
181 <term><emphasis role="bold">The chmod
182 command</emphasis></term>
186 <primary>chmod command</primary>
187 <secondary>AFS compared to UNIX</secondary>
191 <primary>commands</primary>
192 <secondary>chmod (AFS compared to UNIX)</secondary>
196 <primary>setuid programs</primary>
197 <secondary>setting mode bits</secondary>
200 <para>Only members of the <emphasis
201 role="bold">system:administrators</emphasis> group can use
202 this command to turn on the setuid, setgid or sticky mode
203 bits on AFS files. For more information, see <link
204 linkend="HDRWQ409">Determining if a Client Can Run Setuid
205 Programs</link>.</para>
210 <term><emphasis role="bold">The chown
211 command</emphasis></term>
215 <primary>chown command</primary>
216 <secondary>AFS compared to UNIX</secondary>
220 <primary>commands</primary>
221 <secondary>chown (AFS compared to UNIX)</secondary>
224 <para>Only members of the <emphasis
225 role="bold">system:administrators</emphasis> group can issue
226 this command on AFS files.</para>
231 <term><emphasis role="bold">The chgrp
232 command</emphasis></term>
236 <primary>chgrp command</primary>
237 <secondary>AFS compared to UNIX</secondary>
241 <primary>commands</primary>
242 <secondary>chgrp (AFS compared to UNIX)</secondary>
245 <para>Only members of the <emphasis
246 role="bold">system:administrators</emphasis> can issue this
247 command on AFS files and directories.</para>
252 <term><emphasis role="bold">The groups and id
253 commands</emphasis></term>
257 <primary>groups command</primary>
258 <secondary>AFS compared to UNIX</secondary>
262 <primary>id command</primary>
263 <secondary>AFS compared to UNIX</secondary>
267 <primary>commands</primary>
268 <secondary>groups (AFS compared to UNIX)</secondary>
272 <primary>commands</primary>
273 <secondary>id (AFS compared to UNIX)</secondary>
276 <para>If the user's AFS tokens are associated with a process
277 authentication group (PAG), the output of these commands may
278 include one or two large numbers. These are artificial
279 groups used by the OpenAFS Cache Manager to track the PAG on
280 some platforms. Other platforms may use other methods, such
281 as native kernel support for a PAG or a similar concept, in
282 which case the large GIDs may not appear. To learn about
283 PAGs, see <link linkend="HDRWQ64">Identifying AFS Tokens by
289 <term><emphasis role="bold">The ln command</emphasis></term>
293 <primary>ln command</primary>
294 <secondary>AFS compared to UNIX</secondary>
298 <primary>commands</primary>
299 <secondary>ln (AFS compared to UNIX)</secondary>
302 <para>This command cannot create hard links between files in
303 different AFS directories. See <link
304 linkend="HDRWQ32">Creating Hard Links</link>.</para>
309 <term><emphasis role="bold">The sshd daemon and ssh
310 command</emphasis></term>
314 <primary>sshd command</primary>
315 <secondary>AFS compared to UNIX</secondary>
319 <primary>commands</primary>
320 <secondary>sshd (AFS compared to UNIX)</secondary>
324 <primary>ssh command</primary>
325 <secondary>AFS compared to UNIX</secondary>
329 <primary>commands</primary>
330 <secondary>ssh (AFS compared to UNIX)</secondary>
333 <para>In order for a user to have access to files stored in
334 AFS, that user needs to have Kerberos tickets and an AFS token
335 on the system from which they're accessing AFS. This has an
336 implication for users who log in remotely via protocols such
337 as Secure Shell (SSH): that log-in process must create local
338 Kerberos tickets and an AFS token on the system, or the user
339 will have to separately authenticate to Kerberos and AFS
340 after logging in.</para>
342 <para>The <ulink url="http://www.openssh.org/">OpenSSH
343 project</ulink> provides an SSH client and server that uses
344 the GSS-API protocol to pass Kerberos tickets between
345 machines. With a suitable SSH client, this allows users to
346 delegate their Kerberos tickets to the remote machine, and
347 that machine to store those tickets and obtain AFS tokens as
348 part of the log-in process.</para>
355 <primary>fsck command</primary>
357 <secondary>AFS compared to UNIX</secondary>
361 <primary>file server machine</primary>
362 <secondary>inode-based</secondary>
366 <primary>file server machine</primary>
367 <secondary>namei-based</secondary>
371 <primary>namei</primary>
372 <secondary>definition</secondary>
376 <primary>commands</primary>
378 <secondary>fsck (AFS compared to UNIX)</secondary>
382 <primary>fsck command</primary>
384 <secondary>AFS version</secondary>
388 <primary>commands</primary>
390 <secondary>fsck (AFS version)</secondary>
394 <primary>directories</primary>
396 <secondary>lost+found</secondary>
400 <primary>lost+found directory</primary>
404 <sect2 id="Header_38">
405 <title>The AFS version of the fsck Command and inode-based
409 <para>The fileserver uses either of two formats for storing data
410 on disk. The inode-based format uses a combination of regular
411 files and extra fields stored in the inode data structures that
412 are normally reserved for use by the operating system. The namei
413 format uses normal file storage and does not use special
414 structures. The choice of storage formats is chosen at compile
415 time and the two formats are incompatible. The inode format is
416 only available on certain platforms. The storage format must be
417 consistent for the fileserver binaries and all vice partitions on
418 a given file server machine.</para>
422 <para>This section on fsck advice only applies to the inode-based
423 fileserver binaries. On servers using namei-based binaries, the
424 vendor-supplied fsck can be used as normal.</para>
427 <para>If you are using AFS fileserver binaries compiled with the
428 inode-based format, never run the standard UNIX <emphasis
429 role="bold">fsck</emphasis> command on an AFS file server
430 machine. It does not understand how the File Server organizes volume
431 data on disk, and so moves all AFS data into the <emphasis
432 role="bold">lost+found</emphasis> directory on the partition.</para>
434 <para>Instead, use the version of the <emphasis
435 role="bold">fsck</emphasis> program that is included in the AFS
436 distribution. The <emphasis>OpenAFS Quick Start Guide</emphasis>
437 explains how to replace the vendor-supplied <emphasis
438 role="bold">fsck</emphasis> program with the AFS version as you
439 install each server machine.</para>
441 <para>The AFS version functions like the standard <emphasis
442 role="bold">fsck</emphasis> program on data stored on both UFS and
443 AFS partitions. The appearance of a banner like the following as the
444 <emphasis role="bold">fsck</emphasis> program initializes confirms
445 that you are running the correct one:</para>
448 --- AFS (R) version fsck---
451 <para>where <emphasis>version</emphasis> is the AFS version. For
452 correct results, it must match the AFS version of the server
453 binaries in use on the machine.</para>
455 <para>If you ever accidentally run the standard version of the
456 program, contact your AFS support provider, contact the OpenAFS
457 mailing lists, or refer to the <ulink
458 url="http://www.openafs.org/support.html">OpenAFS support web
459 page</ulink> for support options. It is sometimes possible to
460 recover volume data from the <emphasis
461 role="bold">lost+found</emphasis> directory. If the data is not
462 recoverabled, then restoring from backup is recommended.</para>
465 <para>Running the fsck binary supplied by the operating system
466 vendor on an fileserver using inode-based file storage will result
467 in data corruption!</para>
472 <title>Creating Hard Links</title>
475 <primary>hard link</primary>
477 <secondary>AFS restrictions on</secondary>
481 <primary>restrictions</primary>
483 <secondary>on hard links in AFS</secondary>
486 <para>AFS does not allow hard links (created with the UNIX <emphasis
487 role="bold">ln</emphasis> command) between files that reside in
488 different directories, because in that case it is unclear which of
489 the directory's ACLs to associate with the link.</para>
491 <para>AFS also does not allow hard links to directories, in order to
492 keep the file system organized as a tree.</para>
494 <para>It is possible to create symbolic links (with the UNIX
495 <emphasis role="bold">ln -s</emphasis> command) between elements in
496 two different AFS directories, or even between an element in AFS and
497 one in a machine's local UNIX file system. Do not create a symbolic
498 link in AFS to a file whose name begins with either a number sign
499 (<emphasis role="bold">#</emphasis>) or a percent sign (<emphasis
500 role="bold">%</emphasis>), however. The Cache Manager interprets
501 such links as a mount point to a regular or read/write volume,
506 <title>AFS Implements Save on Close</title>
509 <primary>fsync system call</primary>
511 <secondary>for files saved on AFS client</secondary>
515 <primary>close system call</primary>
517 <secondary>for files saved on AFS client</secondary>
521 <primary>write</primary>
523 <secondary>system call for files saved on AFS client</secondary>
526 <para>When an application issues the UNIX <emphasis
527 role="bold">close</emphasis> system call on a file, the Cache
528 Manager performs a synchronous write of the data to the File Server
529 that maintains the central copy of the file. It does not return
530 control to the application until the File Server has acknowledged
531 receipt of the data. For the <emphasis role="bold">fsync</emphasis>
532 system call, control does not return to the application until the
533 File Server indicates that it has written the data to non-volatile
534 storage on the file server machine.</para>
536 <para>When an application issues the UNIX <emphasis
537 role="bold">write</emphasis> system call, the Cache Manager writes
538 modifications to the local AFS client cache only. If the local
539 machine crashes or an application program exits without issuing the
540 <emphasis role="bold">close</emphasis> system call, it is possible
541 that the modifications are not recorded in the central copy of the
542 file maintained by the File Server. The Cache Manager does sometimes
543 write this type of modified data from the cache to the File Server
544 without receiving the <emphasis role="bold">close</emphasis> or
545 <emphasis role="bold">fsync</emphasis> system call, such as when it
546 needs to free cache chunks for new data. However, it is not
547 generally possible to predict when the Cache Manager transfers
548 modified data to the File Server in this way.</para>
550 <para>The implication is that if an application's <emphasis
551 role="bold">Save</emphasis> option invokes the <emphasis
552 role="bold">write</emphasis> system call rather than <emphasis
553 role="bold">close</emphasis> or <emphasis
554 role="bold">fsync</emphasis>, the changes are not necessarily stored
555 permanently on the File Server machine. Most application programs
556 issue the <emphasis role="bold">close</emphasis> system call for
557 save operations, as well as when they finish handling a file and
558 when they exit.</para>
561 <sect2 id="Header_41">
562 <title>Setuid Programs</title>
565 <primary>setuid programs</primary>
567 <secondary>restrictions on</secondary>
570 <para>The UNIX setuid bit is ignored by default for programs run
571 from AFS, but can be enabled by the system administrator on a client
572 machine. The <emphasis role="bold">fs setcell</emphasis> command
573 determines whether setuid programs that originate in a particular
574 cell can run on a given client machine. Running setuid binaries from
575 AFS poses a security risk due to weaknesses in the integrity checks
576 of the AFS protocol and should normally not be permitted. See <link
577 linkend="HDRWQ409">Determining if a Client Can Run Setuid
578 Programs</link>.</para>
580 <para>Set the UNIX setuid bit only for files whose owner is UID 0
581 (the local superuser <emphasis role="bold">root</emphasis>). This
582 does not present an automatic security risk: the local superuser has
583 no special privilege in AFS, but only in the local machine's UNIX
584 file system and kernel. Setting the UNIX setuid bit for files owned
585 with a different UID will have unpredictable resuilts, since that
586 UID will be interpreted as possibly different users on each AFS
587 client machine.</para>
589 <para>Any file can be marked with the setuid bit, but only members
590 of the <emphasis role="bold">system:administrators</emphasis> group
591 can issue the <emphasis role="bold">chown</emphasis> system call or
592 the <emphasis role="bold">chown</emphasis> command, or issue the
593 <emphasis role="bold">chmod</emphasis> system call or the <emphasis
594 role="bold">chmod</emphasis> command to set the setuid bit.</para>
599 <title>Choosing a Cell Name</title>
602 <primary>cell</primary>
604 <secondary>name</secondary>
606 <tertiary>choosing</tertiary>
610 <primary>choosing</primary>
612 <secondary>name</secondary>
614 <tertiary>cell</tertiary>
618 <primary>conventions</primary>
620 <secondary>cell name</secondary>
624 <primary>Internet</primary>
626 <secondary>conventions for cell name</secondary>
629 <para>This section explains how to choose a cell name and explains why
630 choosing an appropriate cell name is important.</para>
632 <para>Your cell name must distinguish your cell from all others in the
633 AFS global namespace. By convention, the cell name is the second
634 element in any AFS pathname; therefore, a unique cell name guarantees
635 that every AFS pathname uniquely identifies a file, even if cells use
636 the same directory names at lower levels in their local AFS
637 filespace. For example, both the Example Corporation cell and the Example
638 Organization cell can have a home directory for the user <emphasis
639 role="bold">pat</emphasis>, because the pathnames are distinct:
640 <emphasis role="bold">/afs/example.com/usr/pat</emphasis> and <emphasis
641 role="bold">/afs/example.org/usr/pat</emphasis>.</para>
643 <para>By convention, cell names follow the Domain Name System (DNS)
644 conventions for domain names. If you are already an Internet site,
645 then it is simplest and strongly recommended to choose your Internet
646 domain name as the cell name.</para>
648 <para>If you are not an Internet site, it is best to choose a unique
649 DNS-style name, particularly if you plan to connect to the Internet in
650 the future. There are a few constraints on AFS cell names:
653 <para>It can contain as many as 64 characters, but shorter names
654 are better because the cell name frequently is part of machine
655 and file names. If your cell name is long, you can reduce
656 pathname length either by creating a symbolic link to the
657 complete cell name, at the second level in your file tree or by
658 using the <emphasis role="bold">CellAlias</emphasis>
659 configuration file on a client machine. See <link
660 linkend="HDRWQ42">The Second (Cellname) Level</link>.</para>
664 <para>To guarantee it is suitable for different operating system
665 types, the cell name can contain only lowercase characters,
666 numbers, underscores, dashes, and periods. Do not include
667 command shell metacharacters.</para>
671 <para>It can include any number of fields, which are
672 conventionally separated by periods (see the examples
678 <sect2 id="Header_43">
679 <title>How to Set the Cell Name</title>
682 <primary>setting</primary>
683 <secondary>cell name</secondary>
687 <primary>cell</primary>
688 <secondary>name</secondary>
689 <tertiary>setting</tertiary>
693 <primary>server machine</primary>
694 <secondary>setting home cell</secondary>
698 <primary>client machine</primary>
699 <secondary>setting home cell</secondary>
702 <para>The cell name is recorded in two files on the local disk of
703 each file server and client machine. Among other functions, these
704 files define the machine's cell membership and so affect how
705 programs and processes run on the machine; see <link
706 linkend="HDRWQ35">Why Choosing the Appropriate Cell Name is
707 Important</link>. The procedure for setting the cell name is
708 different for the two types of machines.</para>
710 <para>For file server machines, the two files that record the cell
711 name are the <emphasis role="bold">/usr/afs/etc/ThisCell</emphasis>
712 and <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>
713 files. As described more explicitly in the <emphasis>OpenAFS Quick
714 Start Guide</emphasis>, you set the cell name in both by issuing the
715 <emphasis role="bold">bos setcellname</emphasis> command on the
716 first file server machine you install in your cell. It is not
717 usually necessary to issue the command again. If you use the Update
718 Server, it distributes its copy of the <emphasis
719 role="bold">ThisCell</emphasis> and <emphasis
720 role="bold">CellServDB</emphasis> files to additional server
721 machines that you install. If you do not use the Update Server, the
722 <emphasis>OpenAFS Quick Start Guide</emphasis> explains how to copy
723 the files manually.</para>
725 <para>For client machines, the two files that record the cell name
726 are the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and
727 <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> files. You
728 create these files on a per-client basis, either with a text editor
729 or by copying them onto the machine from a central source in AFS.
730 See <link linkend="HDRWQ406">Maintaining Knowledge of Database
731 Server Machines</link> for details.</para>
733 <para>Change the cell name in these files only when you want to
734 transfer the machine to a different cell (client machines can only
735 have one default cell at a time and server machines can only belong
736 to one cell at a time). If the machine is a file server, follow the
737 complete set of instructions in the <emphasis>OpenAFS Quick Start
738 Guide</emphasis> for configuring a new cell. If the machine is a
739 client, all you need to do is change the files appropriately and
740 reboot the machine. The next section explains further the negative
741 consequences of changing the name of an existing cell.</para>
743 <para>To set the default cell name used by most AFS commands without
744 changing the local <emphasis
745 role="bold">/usr/vice/etc/ThisCell</emphasis> file, set the AFSCELL
746 environment variable in the command shell. It is worth setting this
747 variable if you need to complete significant administrative work in
748 a foreign cell.</para>
751 <para>The <emphasis role="bold">fs checkservers</emphasis> and
752 <emphasis role="bold">fs mkmount</emphasis> commands do not use
753 the AFSCELL variable. The <emphasis role="bold">fs
754 checkservers</emphasis> command always defaults to the cell named
755 in the <emphasis role="bold">ThisCell</emphasis> file, unless the
756 <emphasis role="bold">-cell</emphasis> argument is used. The
757 <emphasis role="bold">fs mkmount</emphasis> command defaults to
758 the cell in which the parent directory of the new mount point
764 <title>Why Choosing the Appropriate Cell Name is Important</title>
767 <primary>ThisCell file (client)</primary>
768 <secondary>how used by programs</secondary>
771 <para>Take care to select a cell name that is suitable for long-term
772 use. Changing a cell name later is complicated. An appropriate cell
773 name is important because it is the second element in the pathname
774 of all files in a cell's file tree. Because each cell name is
775 unique, its presence in an AFS pathname makes the pathname unique in
776 the AFS global namespace, even if multiple cells use similar
777 filespace organization at lower levels. For instance, it means that
778 every cell can have a home directory called <emphasis
779 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
780 role="bold">/usr/pat</emphasis> without causing a conflict. The
781 presence of the cell name in pathnames also means that users in
782 every cell use the same pathname to access a file, whether the file
783 resides in their local cell or in a foreign cell.</para>
785 <para>Another reason to choose the correct cell name early in the
786 process of installing your cell is that the cell membership defined
787 in each machine's <emphasis role="bold">ThisCell</emphasis> file
788 affects the performance of many programs and processes running on
789 the machine. For instance, AFS commands (<emphasis
790 role="bold">fs</emphasis>, <emphasis role="bold">pts</emphasis>, and
791 <emphasis role="bold">vos</emphasis> commands, for example) by
792 default execute in the cell of the machine on which they are
793 issued. The command interpreters check the <emphasis
794 role="bold">ThisCell</emphasis> file on the local disk and then
795 contact the database server machines listed in the <emphasis
796 role="bold">CellServDB</emphasis> file or configured in DNS for the
797 indicated cell. (The <emphasis role="bold">bos</emphasis> commands
798 work differently because the issuer always has to name of the
799 machine on which to run the command.)</para>
801 <para>The <emphasis role="bold">ThisCell</emphasis> file also
802 normally determines the cell for which a user receives an AFS token
803 when he or she logs in to a machine.</para>
805 <para>If you change the cell name, you must change the <emphasis
806 role="bold">ThisCell</emphasis> and <emphasis
807 role="bold">CellServDB</emphasis> files on every server and client
808 machine. Failure to change them all will cause many commands from
809 the AFS suites to not work as expected.</para>
814 <title>Participating in the AFS Global Namespace</title>
817 <primary>participation</primary>
818 <secondary>in AFS global namespace</secondary>
822 <primary>AFS</primary>
823 <secondary>global namespace</secondary>
827 <primary>global namespace</primary>
830 <para>Participating in the AFS global namespace makes your cell's
831 local file tree visible to AFS users in foreign cells and makes other
832 cells' file trees visible to your local users. It makes file sharing
833 across cells just as easy as sharing within a cell. This section
834 outlines the procedures necessary for participating in the global
838 <para>Participation in the global namespace is not
839 mandatory. Some cells use AFS primarily to facilitate file
840 sharing within the cell, and are not interested in providing
841 their users with access to foreign cells.</para>
845 <para>Making your file tree visible does not mean making it
846 vulnerable. You control how foreign users access your cell using
847 the same protection mechanisms that control local users'
848 access. See <link linkend="HDRWQ40">Granting and Denying Foreign
849 Users Access to Your Cell</link>.</para>
853 <para>The two aspects of participation are independent. A cell
854 can make its file tree visible without allowing its users to see
855 foreign cells' file trees, or can enable its users to see other
856 file trees without advertising its own.</para>
860 <para>You make your cell visible to others by advertising your
861 database server machines and allowing users at other sites to
862 access your database server and file server machines. See <link
863 linkend="HDRWQ38">Making Your Cell Visible to
864 Others</link>.</para>
868 <para>You control access to foreign cells on a per-client
869 machine basis. In other words, it is possible to make a foreign
870 cell accessible from one client machine in your cell but not
871 another. See <link linkend="HDRWQ39">Making Other Cells Visible
872 in Your Cell</link>.</para>
878 <title>What the Global Namespace Looks Like</title>
881 <primary>conventions</primary>
882 <secondary>AFS pathnames</secondary>
886 <primary>AFS</primary>
887 <secondary>root directory (/afs)</secondary>
888 <tertiary>on client machine</tertiary>
892 <primary>directories</primary>
893 <secondary>/afs</secondary>
897 <primary>directories</primary>
898 <secondary>/afs/<emphasis>cellname</emphasis></secondary>
902 <primary>cell</primary>
903 <secondary>name</secondary>
904 <tertiary>at second level in file tree</tertiary>
907 <para>The AFS global namespace appears the same to all AFS cells
908 that participate in it, because they all agree to follow a small set
909 of conventions in constructing pathnames.</para>
911 <para>The first convention is that all AFS pathnames begin with the
912 string <emphasis role="bold">/afs</emphasis> to indicate that they
913 belong to the AFS global namespace.</para>
915 <para>The second convention is that the cell name is the second
916 element in an AFS pathname; it indicates where the file resides
917 (that is, the cell in which a file server machine houses the
918 file). As noted, the presence of a cell name in pathnames makes the
919 global namespace possible, because it guarantees that all AFS
920 pathnames are unique even if cells use the same directory names at
921 lower levels in their AFS filespace.</para>
923 <para>What appears at the third and lower levels in an AFS pathname
924 depends on how a cell has chosen to arrange its filespace. There
925 are some suggested conventional directories at the third level; see
926 <link linkend="HDRWQ43">The Third Level</link>.</para>
930 <title>Making Your Cell Visible to Others</title>
933 <primary>cell</primary>
934 <secondary>making local visible to foreign</secondary>
938 <primary>local cell</primary>
939 <secondary>making visible to foreign cells</secondary>
943 <primary>foreign cell</primary>
944 <secondary>making local cell visible</secondary>
947 <para>You make your cell visible to others by advertising your cell
948 name and database server machines. Just like client machines in the
949 local cell, the Cache Manager on machines in foreign cells use the
950 information to reach your cell's Volume Location (VL) Servers when
951 they need volume and file location information. For authenticated
952 access, foreign clients must be configured with the necessary
953 Kerberos version 5 domain-to-realm mappings and Key Distribution
954 Center (KDC) location information for both the local and remote
955 Kerberos version 5 realms.</para>
957 <para>There are two places you can make this information available:
960 <primary>files</primary>
962 <secondary>global CellServDB</secondary>
966 <primary>CellServDB file maintained by the AFS
969 <secondary>as global update source</secondary>
973 <para>In the global <emphasis
974 role="bold">CellServDB</emphasis> file maintained by the AFS
975 Registrar. This file lists the name and database server
976 machines of every cell that has agreed to make this
977 information available to other cells. This file is available
979 url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink></para>
981 <para>To add or change your cell's listing in this file,
982 follow the instructions at <ulink
983 url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink>.
984 It is a good policy to check the file for changes on a
985 regular schedule. An updated copy of this file is included
986 with new releases of OpenAFS.</para>
989 <primary>files</primary>
991 <secondary>CellServDB.local</secondary>
995 <primary>CellServDB.local file</primary>
1000 <para>A file called <emphasis
1001 role="bold">CellServDB.local</emphasis> in the <emphasis
1002 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1003 role="bold">/service/etc</emphasis> directory of your cell's
1004 filespace. List only your cell's database server
1010 <para>Update the files whenever you change the identity of your
1011 cell's database server machines. Also update the copies of the
1012 <emphasis role="bold">CellServDB</emphasis> files on all of your
1013 server machines (in the <emphasis
1014 role="bold">/usr/afs/etc</emphasis> directory) and client machines
1015 (in the <emphasis role="bold">/usr/vice/etc</emphasis>
1016 directory). For instructions, see <link
1017 linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and
1018 <link linkend="HDRWQ406">Maintaining Knowledge of Database Server
1019 Machines</link>.</para>
1021 <para>Once you have advertised your database server machines, it can
1022 be difficult to make your cell invisible again. You can remove the
1023 <emphasis role="bold">CellServDB.local</emphasis> file and ask the
1024 AFS Registrar to remove your entry from the global <emphasis
1025 role="bold">CellServDB</emphasis> file, but other cells probably
1026 have an entry for your cell in their local <emphasis
1027 role="bold">CellServDB</emphasis> files already. To make those
1028 entries invalid, you must change the names or IP addresses of your
1029 database server machines.</para>
1031 <para>Your cell does not have to be invisible to be inaccessible,
1032 however. To make your cell completely inaccessible to foreign users,
1033 remove the <emphasis role="bold">system:anyuser</emphasis> group
1034 from all ACLs at the top three levels of your filespace; see <link
1035 linkend="HDRWQ40">Granting and Denying Foreign Users Access to Your
1039 <primary>cell</primary>
1041 <secondary>making foreign visible to local</secondary>
1045 <primary>local cell</primary>
1047 <secondary>making foreign cells visible in</secondary>
1051 <primary>foreign cell</primary>
1053 <secondary>making visible in local cell</secondary>
1057 <primary>client machine</primary>
1059 <secondary>making foreign cell visible</secondary>
1063 <sect2 id="HDRWQ39">
1064 <title>Making Other Cells Visible in Your Cell</title>
1066 <para>To make a foreign cell's filespace visible on a client machine
1067 in your cell that is not configured for <emphasis
1068 role="bold">Freelance Mode</emphasis> or <emphasis
1069 role="bold">Dynamic Root</emphasis> mode, perform the following
1073 <para>Mount the cell's <emphasis
1074 role="bold">root.cell</emphasis> volume at the second level in
1075 your cell's filespace just below the <emphasis
1076 role="bold">/afs</emphasis> directory. Use the <emphasis
1077 role="bold">fs mkmount</emphasis> command with the <emphasis
1078 role="bold">-cell</emphasis> argument as instructed in <link
1079 linkend="HDRWQ213">To create a cellular mount
1080 point</link>.</para>
1084 <para>Mount AFS at the <emphasis role="bold">/afs</emphasis>
1085 directory on the client machine. The <emphasis
1086 role="bold">afsd</emphasis> program, which initializes the
1087 Cache Manager, performs the mount automatically at the
1088 directory named in the first field of the local <emphasis
1089 role="bold">/usr/vice/etc/cacheinfo</emphasis> file or by the
1090 command's <emphasis role="bold">-mountdir</emphasis>
1091 argument. Mounting AFS at an alternate location makes it
1092 impossible to reach the filespace of any cell that mounts its
1093 <emphasis role="bold">root.afs</emphasis> and <emphasis
1094 role="bold">root.cell</emphasis> volumes at the conventional
1095 locations. See <link linkend="HDRWQ395">Displaying and Setting
1096 the Cache Size and Location</link>.</para>
1100 <para>Create an entry for the cell in the list of database
1101 server machines which the Cache Manager maintains in kernel
1105 role="bold">/usr/vice/etc/CellServDB</emphasis> file on every
1106 client machine's local disk lists the database server machines
1107 for the local and foreign cells. The <emphasis
1108 role="bold">afsd</emphasis> program reads the contents of the
1109 <emphasis role="bold">CellServDB</emphasis> file into kernel
1110 memory as it initializes the Cache Manager. You can also use
1111 the <emphasis role="bold">fs newcell</emphasis> command to add
1112 or alter entries in kernel memory directly between reboots of
1113 the machine. See <link linkend="HDRWQ406">Maintaining
1114 Knowledge of Database Server Machines</link>.</para>
1119 <para>Non-windows client machines may enable <emphasis
1120 role="bold">Dynamic Root Mode</emphasis> by using the <emphasis
1121 role="bold">-dynroot</emphasis> option to <emphasis
1122 role="bold">afsd</emphasis>. When this option is enabled, all cells
1123 listed in the <emphasis role="bold">CellServDB</emphasis> file will
1124 appear in the <emphasis role="bold">/afs</emphasis> directory. The
1125 contents of the <emphasis role="bold">root.afs</emphasis> volume
1126 will be ignored. </para>
1128 <para>Windows client machines may enable <emphasis
1129 role="bold">Freelance Mode</emphasis> during client installation or
1130 by setting the <emphasis role="bold">FreelanceClient</emphasis>
1131 setting under <emphasis role="bold">Service Parameters</emphasis> in
1132 the Windows Registry as mentioned in the <ulink
1133 url="http://docs.openafs.org/ReleaseNotesWindows/">Release
1134 Notes</ulink>. When this option is enabled, the <emphasis
1135 role="bold">root.afs</emphasis> volume is ignored and a mounpoint
1136 for each cell is automatically created in the the <emphasis
1137 role="bold">\\AFS</emphasis> directory when the folder <emphasis
1138 role="bold">\\AFS\<replaceable>cellname</replaceable></emphasis> is
1139 accessed and the foreign Volume Location servers can be reached.
1140 </para> <para>Note that making a foreign cell visible to client
1141 machines does not guarantee that your users can access its
1142 filespace. The ACLs in the foreign cell must also grant them the
1143 necessary permissions.</para>
1146 <primary>cell</primary>
1148 <secondary>granting local access to foreign users</secondary>
1152 <primary>local cell</primary>
1154 <secondary>granting foreign users access to</secondary>
1158 <sect2 id="HDRWQ40">
1159 <title>Granting and Denying Foreign Users Access to Your
1162 <para>Making your cell visible in the AFS global namespace does not
1163 take away your control over the way in which users from foreign
1164 cells access your file tree.</para>
1166 <para>By default, foreign users access your cell as the user
1167 <emphasis role="bold">anonymous</emphasis>, which means they have
1168 only the permissions granted to the <emphasis
1169 role="bold">system:anyuser</emphasis> group on each directory's
1170 ACL. Normally these permissions are limited to the <emphasis
1171 role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
1172 and <emphasis role="bold">r</emphasis> (<emphasis
1173 role="bold">read</emphasis>) permissions.</para>
1175 <para>There are three ways to grant wider access to foreign users:
1178 <para>Grant additional permissions to the <emphasis
1179 role="bold">system:anyuser</emphasis> group on certain
1180 ACLs. Keep in mind, however, that all users can then access
1181 that directory in the indicated way (not just specific foreign
1182 users you have in mind).</para>
1186 <para>Enable automatic registration for users in the foreign
1187 cell. This may be done by creating a cross-realm trust in the
1188 <emphasis role="bold">Kerberos Database</emphasis>. Then add a
1189 PTS group named <emphasis
1190 role="bold">system:authuser<replaceable>@FOREIGN.REALM</replaceable></emphasis>
1191 and give it a group quota greater than the number of foreign
1192 users expected to be registered. After the cross-realm trust
1193 and the PTS group are created, the <ulink
1194 url="http://docs.openafs.org/Reference/1/aklog.html">aklog</ulink>
1195 command will automatically register foreign users as
1196 needed. Consult the documentation for your <emphasis
1197 role="bold">Kerberos Server</emphasis> for instructions on how
1198 to establish a cross-realm trust. </para>
1202 <para>Create a local authentication account for specific
1203 foreign users, by creating entries in the Protection Database,
1204 the Kerberos Database, and the local password file.</para>
1210 <primary>cell</primary>
1212 <secondary>filespace configuration issues</secondary>
1216 <primary>configuring</primary>
1218 <secondary>filespace, issues</secondary>
1222 <primary>file tree</primary>
1224 <secondary>conventions</secondary>
1226 <tertiary>for configuring</tertiary>
1231 <sect1 id="HDRWQ41">
1232 <title>Configuring Your AFS Filespace</title>
1234 <para>This section summarizes the issues to consider when configuring
1235 your AFS filespace. For a discussion of creating volumes that
1236 correspond most efficiently to the filespace's directory structure,
1237 see <link linkend="HDRWQ44">Creating Volumes to Simplify
1238 Administration</link>.</para>
1241 <para><emphasis role="bold">For Windows users:</emphasis> Windows
1242 uses a backslash (<emphasis role="bold">\</emphasis>) rather than a
1243 forward slash (<emphasis role="bold">/</emphasis>) to separate the
1244 elements in a pathname. The hierarchical organization of the
1245 filespace is however the same as on a UNIX machine.</para>
1248 <para>AFS pathnames must follow a few conventions so the AFS global
1249 namespace looks the same from any AFS client machine. There are
1250 corresponding conventions to follow in building your file tree, not
1251 just because pathnames reflect the structure of a file tree, but also
1252 because the AFS Cache Manager expects a certain configuration.</para>
1255 <primary>AFS</primary>
1257 <secondary>root directory (/afs)</secondary>
1259 <tertiary>in cell filespace</tertiary>
1263 <primary>directories</primary>
1265 <secondary>/afs</secondary>
1268 <sect2 id="Header_51">
1269 <title>The Top /afs Level</title>
1271 <para>The first convention is that the top level in your file tree
1272 be called the <emphasis role="bold">/afs</emphasis> directory. If
1273 you name it something else, then you must use the <emphasis
1274 role="bold">-mountdir</emphasis> argument with the <emphasis
1275 role="bold">afsd</emphasis> program to get Cache Managers to mount
1276 AFS properly. You cannot participate in the AFS global namespace in
1280 <primary>cell</primary>
1282 <secondary>name</secondary>
1284 <tertiary>at second level in file tree</tertiary>
1288 <primary>directories</primary>
1290 <secondary>/afs/<emphasis>cellname</emphasis></secondary>
1294 <primary>symbolic link</primary>
1296 <secondary>at second level of AFS pathname</secondary>
1300 <sect2 id="HDRWQ42">
1301 <title>The Second (Cellname) Level</title>
1303 <para>The second convention is that just below the <emphasis
1304 role="bold">/afs</emphasis> directory you place directories
1305 corresponding to each cell whose file tree is visible and accessible
1306 from the local cell. Minimally, there must be a directory for the
1307 local cell. Each such directory is a mount point to the indicated
1308 cell's <emphasis role="bold">root.cell</emphasis> volume. For
1309 example, in the Example Corporation cell, <emphasis
1310 role="bold">/afs/example.com</emphasis> is a mount point for the cell's
1311 own <emphasis role="bold">root.cell</emphasis> volume and <emphasis
1312 role="bold">example.org</emphasis> is a mount point for the Example
1313 Organization cell's <emphasis role="bold">root.cell</emphasis>
1314 volume. The <emphasis role="bold">fs lsmount</emphasis> command
1315 displays the mount points.</para>
1318 % <emphasis role="bold">fs lsmount /afs/example.com</emphasis>
1319 '/afs/example.com' is a mount point for volume '#root.cell'
1320 % <emphasis role="bold">fs lsmount /afs/example.org</emphasis>
1321 '/afs/example.org' is a mount point for volume '#example.org:root.cell'
1324 <para>To reduce the amount of typing necessary in pathnames, you can
1325 create a symbolic link with an abbreviated name to the mount point
1326 of each cell your users frequently access (particularly the home
1327 cell). In the Example Corporation cell, for instance, <emphasis
1328 role="bold">/afs/example</emphasis> is a symbolic link to the <emphasis
1329 role="bold">/afs/example.com</emphasis> mount point, as the <emphasis
1330 role="bold">fs lsmount</emphasis> command reveals.</para>
1333 % <emphasis role="bold">fs lsmount /afs/example</emphasis>
1334 '/afs/example' is a symbolic link, leading to a mount point for volume
1335 '#root.cell' </programlisting>
1338 <primary>file tree</primary>
1340 <secondary>conventions</secondary>
1342 <tertiary>third level</tertiary>
1346 <primary>directories</primary>
1348 <secondary>conventional under /afs/cellname</secondary>
1352 <sect2 id="HDRWQ43">
1353 <title>The Third Level</title>
1355 <para>You can organize the third level of your cell's file tree any
1356 way you wish. The following list describes directories that appear
1357 at this level in the conventional configuration:
1360 <term><emphasis role="bold">common</emphasis></term>
1363 <para>This directory contains programs and files needed by
1364 users working on machines of all system types, such as text
1365 editors, online documentation files, and so on. Its
1366 <emphasis role="bold">/etc</emphasis> subdirectory is a
1367 logical place to keep the central update sources for files
1368 used on all of your cell's client machines, such as the
1369 <emphasis role="bold">ThisCell</emphasis> and <emphasis
1370 role="bold">CellServDB</emphasis> files.</para>
1375 <term><emphasis role="bold">public</emphasis></term>
1378 <para>A directory accessible to anyone who can access your
1379 filespace, because its ACL grants the <emphasis
1380 role="bold">l</emphasis> (<emphasis
1381 role="bold">lookup</emphasis>) and <emphasis
1382 role="bold">r</emphasis> (<emphasis
1383 role="bold">read</emphasis>) permissions to the <emphasis
1384 role="bold">system:anyuser</emphasis> group. It is useful if
1385 you want to enable your users to make selected information
1386 available to everyone, but do not want to grant foreign
1387 users access to the contents of the <emphasis
1388 role="bold">usr</emphasis> directory which houses user home
1389 directories (and is also at this level). It is conventional
1390 to create a subdirectory for each of your cell's
1396 <term><emphasis role="bold">service</emphasis></term>
1399 <para>This directory contains files and subdirectories that
1400 help cells coordinate resource sharing. For a list of the
1401 proposed standard files and subdirectories to create, call
1402 or write to AFS Product Support.</para>
1404 <para>As an example, files that other cells expect to find
1405 in this directory's <emphasis role="bold">etc</emphasis>
1406 subdirectory can include the following: <itemizedlist>
1409 role="bold">CellServDB.export</emphasis>, a list of
1410 database server machines for many cells</para>
1415 role="bold">CellServDB.local</emphasis>, a list of the
1416 cell's own database server machines</para>
1420 <para><emphasis role="bold">passwd</emphasis>, a copy
1421 of the local password file (<emphasis
1422 role="bold">/etc/passwd</emphasis> or equivalent) kept
1423 on the local disk of the cell's client machines</para>
1427 <para><emphasis role="bold">group</emphasis>, a copy
1428 of the local groups file (<emphasis
1429 role="bold">/etc/group</emphasis> or equivalent) kept
1430 on the local disk of the cell's client machines</para>
1438 <term><emphasis>sys_type</emphasis></term>
1441 <para>A separate directory for storing the server and client
1442 binaries for each system type you use in the cell.
1443 Configuration is simplest if you use the system type names
1444 assigned in the AFS distribution, particularly if you wish
1445 to use the <emphasis role="bold">@sys</emphasis> variable in
1446 pathnames (see <link linkend="HDRWQ56">Using the @sys
1447 Variable in Pathnames</link>). The <emphasis>OpenAFS Release
1448 Notes</emphasis> lists the conventional name for each
1449 supported system type.</para>
1451 <para>Within each such directory, create directories named
1452 <emphasis role="bold">bin</emphasis>, <emphasis
1453 role="bold">etc</emphasis>, <emphasis
1454 role="bold">usr</emphasis>, and so on, to store the programs
1455 normally kept in the <emphasis role="bold">/bin</emphasis>,
1456 <emphasis role="bold">/etc</emphasis> and <emphasis
1457 role="bold">/usr</emphasis> directories on a local
1458 disk. Then create symbolic links from the local directories
1459 on client machines into AFS; see <link
1460 linkend="HDRWQ55">Configuring the Local Disk</link>. Even if
1461 you do not choose to use symbolic links in this way, it can
1462 be convenient to have central copies of system binaries in
1463 AFS. If binaries are accidentally removed from a machine,
1464 you can recopy them onto the local disk from AFS rather than
1465 having to recover them from tape</para>
1470 <term><emphasis role="bold">usr</emphasis></term>
1473 <para>This directory contains home directories for your
1474 local users. As discussed in the previous entry for the
1475 <emphasis role="bold">public</emphasis> directory, it is
1476 often practical to protect this directory so that only
1477 locally authenticated users can access it. This keeps the
1478 contents of your user's home directories as secure as
1481 <para>If your cell is quite large, directory lookup can be
1482 slowed if you put all home directories in a single <emphasis
1483 role="bold">usr</emphasis> directory. For suggestions on
1484 distributing user home directories among multiple grouping
1485 directories, see <link linkend="HDRWQ59">Grouping Home
1486 Directories</link>.</para>
1487 </listitem> </varlistentry>
1490 <term><emphasis role="bold">wsadmin</emphasis></term>
1493 <para>This directory contains prototype, configuration and
1494 library files for use with the <emphasis
1495 role="bold">package</emphasis> program. See <link
1496 linkend="HDRWQ419">Configuring Client Machines with the
1497 package Program</link>.</para>
1504 <primary>volume name</primary>
1506 <secondary>conventions for</secondary>
1510 <primary>conventions</primary>
1512 <secondary>volume names</secondary>
1516 <primary>volume</primary>
1518 <secondary>separate for each top level directory</secondary>
1522 <primary>file tree</primary>
1524 <secondary>creating volumes to match top level
1525 directories</secondary>
1530 <sect1 id="HDRWQ44">
1531 <title>Creating Volumes to Simplify Administration</title>
1533 <para>This section discusses how to create volumes in ways that make
1534 administering your system easier.</para>
1536 <para>At the top levels of your file tree (at least through the third
1537 level), each directory generally corresponds to a separate
1538 volume. Some cells also configure the subdirectories of some third
1539 level directories as separate volumes. Common examples are the
1541 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1542 role="bold">/common</emphasis> and <emphasis
1543 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1544 role="bold">/usr</emphasis> directories.</para>
1546 <para>You do not have to create a separate volume for every directory
1547 level in a tree, but the advantage is that each volume tends to be
1548 smaller and easier to move for load balancing. The overhead for a
1549 mount point is no greater than for a standard directory, nor does the
1550 volume structure itself require much disk space. Most cells find that
1551 below the fourth level in the tree, using a separate volume for each
1552 directory is no longer efficient. For instance, while each user's home
1553 directory (at the fourth level in the tree) corresponds to a separate
1554 volume, all of the subdirectories in the home directory normally
1555 reside in the same volume.</para>
1557 <para>Keep in mind that only one volume can be mounted at a given
1558 directory location in the tree. In contrast, a volume can be mounted
1559 at several locations, though this is not recommended because it
1560 distorts the hierarchical nature of the file tree, potentially causing
1564 <primary>volume name</primary>
1566 <secondary>restrictions</secondary>
1570 <primary>restrictions</primary>
1572 <secondary>on volume names</secondary>
1576 <primary>volume name</primary>
1578 <secondary>two required</secondary>
1582 <primary>volume</primary>
1584 <secondary>root (root.afs and root.cell)</secondary>
1588 <primary>root volumes (root.afs and root.cell)</primary>
1591 <sect2 id="Header_55">
1592 <title>Assigning Volume Names</title>
1594 <para>You can name your volumes anything you choose, subject to a
1598 <para>Read/write volume names can be up to 22 characters in
1599 length. The maximum length for volume names is 31 characters,
1600 and there must be room to add the <emphasis
1601 role="bold">.readonly</emphasis> extension on read-only
1606 <para>Do not add the <emphasis
1607 role="bold">.readonly</emphasis> and <emphasis
1608 role="bold">.backup</emphasis> extensions to volume names
1609 yourself, even if they are appropriate. The Volume Server adds
1610 them automatically as it creates a read-only or backup version
1615 <para>There must be volumes named <emphasis
1616 role="bold">root.afs</emphasis> and <emphasis
1617 role="bold">root.cell</emphasis>, mounted respectively at the
1618 top (<emphasis role="bold">/afs</emphasis>) level in the
1619 filespace and just below that level, at the cell's name (for
1620 example, at <emphasis role="bold">/afs/example.com</emphasis> in
1621 the Example Corporation cell).</para>
1623 <para>Deviating from these names only creates confusion and
1624 extra work. Changing the name of the <emphasis
1625 role="bold">root.afs</emphasis> volume, for instance, means
1626 that you must use the <emphasis
1627 role="bold">-rootvol</emphasis> argument to the <emphasis
1628 role="bold">afsd</emphasis> program on every client machine,
1629 to name the alternate volume.</para>
1631 <para>Similarly, changing the <emphasis
1632 role="bold">root.cell</emphasis> volume name prevents users in
1633 foreign cells from accessing your filespace, if the mount
1634 point for your cell in their filespace refers to the
1635 conventional <emphasis role="bold">root.cell</emphasis>
1636 name. Of course, this is one way to make your cell invisible
1637 to other cells.</para>
1642 <para>It is best to assign volume names that indicate the type of
1643 data they contain, and to use similar names for volumes with similar
1644 contents. It is also helpful if the volume name is similar to (or at
1645 least has elements in common with) the name of the directory at
1646 which it is mounted. Understanding the pattern then enables you
1647 accurately to guess what a volume contains and where it is
1650 <para>Many cells find that the most effective volume naming scheme
1651 puts a common prefix on the names of all related volumes. <link
1652 linkend="TBLVOL-PREFIX">Table 1</link> describes the recommended
1653 prefixing scheme.</para>
1655 <table id="TBLVOL-PREFIX" label="1">
1656 <title>Suggested volume prefixes</title>
1659 <colspec colwidth="14*" />
1661 <colspec colwidth="28*" />
1663 <colspec colwidth="22*" />
1665 <colspec colwidth="36*" />
1669 <entry><emphasis role="bold">Prefix</emphasis></entry>
1671 <entry><emphasis role="bold">Contents</emphasis></entry>
1673 <entry><emphasis role="bold">Example Name</emphasis></entry>
1675 <entry><emphasis role="bold">Example Mount
1676 Point</emphasis></entry>
1682 <entry><emphasis role="bold">common.</emphasis></entry>
1684 <entry>popular programs and files</entry>
1686 <entry><emphasis role="bold">common.etc</emphasis></entry>
1689 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1690 role="bold">/common/etc</emphasis></entry>
1694 <entry><emphasis role="bold">src.</emphasis></entry>
1696 <entry>source code</entry>
1698 <entry><emphasis role="bold">src.afs</emphasis></entry>
1701 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1702 role="bold">/src/afs</emphasis></entry>
1706 <entry><emphasis role="bold">proj.</emphasis></entry>
1708 <entry>project data</entry>
1710 <entry><emphasis role="bold">proj.portafs</emphasis></entry>
1713 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1714 role="bold">/proj/portafs</emphasis></entry>
1718 <entry><emphasis role="bold">test.</emphasis></entry>
1720 <entry>testing or other temporary data</entry>
1722 <entry><emphasis role="bold">test.smith</emphasis></entry>
1725 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1726 role="bold">/usr/smith/test</emphasis></entry>
1730 <entry><emphasis role="bold">user.</emphasis></entry>
1732 <entry>user home directory data</entry>
1734 <entry><emphasis role="bold">user.terry</emphasis></entry>
1737 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1738 role="bold">/usr/terry</emphasis></entry>
1742 <entry>sys_type<emphasis role="bold">.</emphasis></entry>
1744 <entry>programs compiled for an operating system
1747 <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
1750 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1751 role="bold">/rs_aix42/bin</emphasis></entry>
1757 <para><link linkend="TBLPREFIX-EXAMPLE">Table 2</link> is a more
1758 specific example for a cell's <emphasis
1759 role="bold">rs_aix42</emphasis> system volumes and
1762 <table id="TBLPREFIX-EXAMPLE" label="2">
1763 <title>Example volume-prefixing scheme</title>
1766 <colspec colwidth="14*" />
1768 <colspec colwidth="28*" />
1770 <colspec colwidth="22*" />
1772 <colspec colwidth="36*" />
1776 <entry><emphasis role="bold">Example Name</emphasis></entry>
1778 <entry><emphasis role="bold">Example Mount
1779 Point</emphasis></entry>
1785 <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
1788 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1789 role="bold">/rs_aix42/bin</emphasis>, <emphasis
1790 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1791 role="bold">/rs_aix42/bin</emphasis></entry>
1795 <entry><emphasis role="bold">rs_aix42.etc</emphasis></entry>
1798 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1799 role="bold">/rs_aix42/etc</emphasis></entry>
1803 <entry><emphasis role="bold">rs_aix42.usr</emphasis></entry>
1806 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1807 role="bold">/rs_aix42/usr</emphasis></entry>
1812 role="bold">rs_aix42.usr.afsws</emphasis></entry>
1815 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1816 role="bold">/rs_aix42/usr/afsws</emphasis></entry>
1821 role="bold">rs_aix42.usr.lib</emphasis></entry>
1824 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1825 role="bold">/rs_aix42/usr/lib</emphasis></entry>
1830 role="bold">rs_aix42.usr.bin</emphasis></entry>
1833 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1834 role="bold">/rs_aix42/usr/bin</emphasis></entry>
1839 role="bold">rs_aix42.usr.etc</emphasis></entry>
1842 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1843 role="bold">/rs_aix42/usr/etc</emphasis></entry>
1848 role="bold">rs_aix42.usr.inc</emphasis></entry>
1851 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1852 role="bold">/rs_aix42/usr/inc</emphasis></entry>
1857 role="bold">rs_aix42.usr.man</emphasis></entry>
1860 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1861 role="bold">/rs_aix42/usr/man</emphasis></entry>
1866 role="bold">rs_aix42.usr.sys</emphasis></entry>
1869 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1870 role="bold">/rs_aix42/usr/sys</emphasis></entry>
1875 role="bold">rs_aix42.usr.local</emphasis></entry>
1878 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1879 role="bold">/rs_aix42/usr/local</emphasis></entry>
1885 <para>There are several advantages to this scheme:
1888 <para>The volume name is similar to the mount point name in
1889 the filespace. In all of the entries in <link
1890 linkend="TBLPREFIX-EXAMPLE">Table 2</link>, for example, the
1891 only difference between the volume and mount point name is
1892 that the former uses periods as separators and the latter uses
1893 slashes. Another advantage is that the volume name indicates
1894 the contents, or at least suggests the directory on which to
1895 issue the <emphasis role="bold">ls</emphasis> command to learn
1896 the contents.</para>
1900 <para>It makes it easy to manipulate groups of related volumes
1901 at one time. In particular, the <emphasis role="bold">vos
1902 backupsys</emphasis> command's <emphasis
1903 role="bold">-prefix</emphasis> argument enables you to create
1904 a backup version of every volume whose name starts with the
1905 same string of characters. Making a backup version of each
1906 volume is one of the first steps in backing up a volume with
1907 the AFS Backup System, and doing it for many volumes with one
1908 command saves you a good deal of typing. For instructions for
1909 creating backup volumes, see <link linkend="HDRWQ201">Creating
1910 Backup Volumes</link>, For information on the AFS Backup
1911 System, see <link linkend="HDRWQ248">Configuring the AFS
1912 Backup System</link> and <link linkend="HDRWQ283">Backing Up
1913 and Restoring AFS Data</link>.</para>
1917 <para>It makes it easy to group related volumes together on a
1918 partition. Grouping related volumes together has several
1919 advantages of its own, discussed in <link
1920 linkend="HDRWQ49">Grouping Related Volumes on a
1921 Partition</link>.</para>
1927 <primary>volume</primary>
1929 <secondary>grouping related on same partition</secondary>
1933 <primary>disk partition</primary>
1935 <secondary>grouping related volumes on</secondary>
1939 <sect2 id="HDRWQ49">
1940 <title>Grouping Related Volumes on a Partition</title>
1942 <para>If your cell is large enough to make it practical, consider
1943 grouping related volumes together on a partition. In general, you
1944 need at least three file server machines for volume grouping to be
1945 effective. Grouping has several advantages, which are most obvious
1946 when the file server machine becomes inaccessible:
1949 <para>If you keep a hardcopy record of the volumes on a
1950 partition, you know which volumes are unavailable. You can
1951 keep such a record without grouping related volumes, but a
1952 list composed of unrelated volumes is much harder to maintain.
1953 Note that the record must be on paper, because the outage can
1954 prevent you from accessing an online copy or from issuing the
1955 <emphasis role="bold">vos listvol</emphasis> command, which
1956 gives you the same information.</para>
1960 <para>The effect of an outage is more localized. For example,
1961 if all of the binaries for a given system type are on one
1962 partition, then only users of that system type are
1963 affected. If a partition houses binary volumes from several
1964 system types, then an outage can affect more people,
1965 particularly if the binaries that remain available are
1966 interdependent with those that are not available.</para>
1971 <para>The advantages of grouping related volumes on a partition do
1972 not necessarily extend to the grouping of all related volumes on one
1973 file server machine. For instance, it is probably unwise in a cell
1974 with two file server machines to put all system volumes on one
1975 machine and all user volumes on the other. An outage of either
1976 machine probably affects everyone.</para>
1978 <para>Admittedly, the need to move volumes for load balancing
1979 purposes can limit the practicality of grouping related volumes.
1980 You need to weigh the complementary advantages case by case.</para>
1983 <primary>replication</primary>
1985 <secondary>appropriate volumes</secondary>
1989 <primary>volume</primary>
1991 <secondary>type to replicate</secondary>
1995 <primary>volume</primary>
1997 <secondary>where to place replicated</secondary>
2001 <primary>read-only volume</primary>
2003 <secondary>selecting site</secondary>
2007 <sect2 id="HDRWQ50">
2008 <title>When to Replicate Volumes</title>
2010 <para>As discussed in <link linkend="HDRWQ15">Replication</link>,
2011 replication refers to making a copy, or clone, of a read/write
2012 source volume and then placing the copy on one or more additional
2013 file server machines. Replicating a volume can increase the
2014 availability of the contents. If one file server machine housing the
2015 volume becomes inaccessible, users can still access the copy of the
2016 volume stored on a different machine. No one machine is likely to
2017 become overburdened with requests for a popular file, either,
2018 because the file is available from several machines.</para>
2020 <para>However, replication is not appropriate for all cells. If a
2021 cell does not have much disk space, replication can be unduly
2022 expensive, because each clone not on the same partition as the
2023 read/write source takes up as much disk space as its source volume
2024 did at the time the clone was made. Also, if you have only one file
2025 server machine, replication uses up disk space without increasing
2026 availability.</para>
2028 <para>Replication is also not appropriate for volumes that change
2029 frequently. You must issue the <emphasis role="bold">vos
2030 release</emphasis> command every time you need to update a read-only
2031 volume to reflect changes in its read/write source.</para>
2033 <para>For both of these reasons, replication is appropriate only for
2034 popular volumes whose contents do not change very often, such as
2035 system binaries and other volumes mounted at the upper levels of
2036 your filespace. User volumes usually exist only in a read/write
2037 version since they change so often.</para>
2039 <para>If you are replicating any volumes, you must replicate the
2040 <emphasis role="bold">root.afs</emphasis> and <emphasis
2041 role="bold">root.cell</emphasis> volumes, preferably at two or three
2042 sites each (even if your cell only has two or three file server
2043 machines). The Cache Manager needs to pass through the directories
2044 corresponding to the <emphasis role="bold">root.afs</emphasis> and
2045 <emphasis role="bold">root.cell</emphasis> volumes as it interprets
2046 any pathname. The unavailability of these volumes makes all other
2047 volumes unavailable too, even if the file server machines storing
2048 the other volumes are still functioning.</para>
2050 <para>Another reason to replicate the <emphasis
2051 role="bold">root.afs</emphasis> volume is that it can lessen the
2052 load on the File Server machine. The Cache Manager has a bias to
2053 access a read-only version of the <emphasis
2054 role="bold">root.afs</emphasis> volume if it is replicate, which
2055 puts the Cache Manager onto the <emphasis>read-only path</emphasis>
2056 through the AFS filespace. While on the read-only path, the Cache
2057 Manager attempts to access a read-only copy of replicated
2058 volumes. The File Server needs to track only one callback per Cache
2059 Manager for all of the data in a read-only volume, rather than the
2060 one callback per file it must track for read/write volumes. Fewer
2061 callbacks translate into a smaller load on the File Server.</para>
2063 <para>If the <emphasis role="bold">root.afs</emphasis> volume is not
2064 replicated, the Cache Manager follows a read/write path through the
2065 filespace, accessing the read/write version of each volume. The File
2066 Server distributes and tracks a separate callback for each file in a
2067 read/write volume, imposing a greater load on it.</para>
2069 <para>For more on read/write and read-only paths, see <link
2070 linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para>
2072 <para>It also makes sense to replicate system binary volumes in many
2073 cases, as well as the volume corresponding to the <emphasis
2074 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2075 role="bold">/usr</emphasis> directory and the volumes corresponding
2077 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2078 role="bold">/common</emphasis> directory and its
2079 subdirectories.</para>
2081 <para>It is a good idea to place a replica on the same partition as
2082 the read/write source. In this case, the read-only volume is a clone
2083 (like a backup volume): it is a copy of the source volume's vnode
2084 index, rather than a full copy of the volume contents. Only if the
2085 read/write volume moves to another partition or changes
2086 substantially does the read-only volume consume significant disk
2087 space. Read-only volumes kept on other servers' partitions always
2088 consume the full amount of disk space that the read/write source
2089 consumed when the read-only volume was created.</para>
2091 <para>You cannot have a replica volume on a different partition of
2092 the same server hosting the read/write volume. "Cheap" read-only
2093 volumes must be on the same partition as the read/write; all other
2094 read-only volumes must be on different servers.</para>
2097 <sect2 id="Header_58">
2098 <title>The Default Quota and ACL on a New Volume</title>
2100 <para>Every AFS volume has associated with it a quota that limits
2101 the amount of disk space the volume is allowed to use. To set and
2102 change quota, use the commands described in <link
2103 linkend="HDRWQ234">Setting and Displaying Volume Quota and Current
2106 <para>By default, every new volume is assigned a space quota of 5000
2107 KB blocks unless you include the <emphasis
2108 role="bold">-maxquota</emphasis> argument to the <emphasis
2109 role="bold">vos create</emphasis> command. Also by default, the ACL
2110 on the root directory of every new volume grants all permissions to
2111 the members of the <emphasis
2112 role="bold">system:administrators</emphasis> group. To learn how to
2113 change these values when creating an account with individual
2114 commands, see <link linkend="HDRWQ503">To create one user account
2115 with individual commands</link>. When using <emphasis
2116 role="bold">uss</emphasis> commands to create accounts, you can
2117 specify alternate ACL and quota values in the template file's
2118 <emphasis role="bold">V</emphasis> instruction; see <link
2119 linkend="HDRWQ473">Creating a Volume with the V
2120 Instruction</link>.</para>
2123 <primary>server machine</primary>
2125 <secondary>configuration issues</secondary>
2129 <primary>configuring</primary>
2131 <secondary>file server machine, issues</secondary>
2135 <primary>roles for server machine</primary>
2137 <secondary>summary</secondary>
2141 <primary>server machine</primary>
2143 <secondary>roles for</secondary>
2145 <tertiary>summary</tertiary>
2149 <primary>server machine</primary>
2151 <secondary>first installed</secondary>
2156 <sect1 id="HDRWQ51">
2157 <title>Configuring Server Machines</title>
2159 <para>This section discusses some issues to consider when configuring
2160 server machines, which store AFS data, transfer it to client machines
2161 on request, and house the AFS administrative databases. To learn about
2162 client machines, see <link linkend="HDRWQ54">Configuring Client
2163 Machines</link>.</para>
2165 <para>If your cell has more than one AFS server machine, you can
2166 configure them to perform specialized functions. A machine can assume
2167 one or more of the roles described in the following list. For more
2168 details, see <link linkend="HDRWQ90">The Four Roles for File Server
2172 <para>A <emphasis>simple file server</emphasis> machine runs
2173 only the processes that store and deliver AFS files to client
2174 machines. You can run as many simple file server machines as you
2175 need to satisfy your cell's performance and disk space
2176 requirements.</para>
2180 <para>A <emphasis>database server machine</emphasis> runs the
2181 four database server processes that maintain AFS's replicated
2182 administrative databases: the Authentication, Backup,
2183 Protection, and Volume Location (VL) Server processes.</para>
2187 <para>A <emphasis>binary distribution machine</emphasis>
2188 distributes the AFS server binaries for its system type to all
2189 other server machines of that system type.</para>
2193 <para>The single <emphasis>system control machine</emphasis>
2194 distributes common server configuration files to all other
2195 server machines in the cell, in a cell that runs the United
2196 States edition of AFS (cells that use the international edition
2197 of AFS must not use the system control machine for this
2198 purpose). The machine conventionally also serves as the time
2199 synchronization source for the cell, adjusting its clock
2200 according to a time source outside the cell.</para>
2205 <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how
2206 to configure your cell's first file server machine to assume all four
2207 roles. The <emphasis>OpenAFS Quick Beginnings</emphasis> chapter on
2208 installing additional server machines also explains how to configure
2209 them to perform one or more roles.</para>
2212 <primary>database server machine</primary>
2214 <secondary>reason to run three</secondary>
2218 <primary>distribution</primary>
2220 <secondary>of databases</secondary>
2224 <primary>databases, distributed</primary>
2228 <primary>distributed databases</primary>
2231 <sect2 id="HDRWQ52">
2232 <title>Replicating the OpenAFS Administrative Databases</title>
2234 <para>The AFS administrative databases are housed on database server
2235 machines and store information that is crucial for correct cell
2236 functioning. Both server processes and Cache Managers access the
2237 information frequently:
2240 <para>Every time a Cache Manager fetches a file from a
2241 directory that it has not previously accessed, it must look up
2242 the file's location in the Volume Location Database
2247 <para>Every time a user obtains an AFS token from the
2248 Authentication Server, the server looks up the user's password
2249 in the Authentication Database.</para>
2253 <para>The first time that a user accesses a volume housed on a
2254 specific file server machine, the File Server contacts the
2255 Protection Server for a list of the user's group memberships
2256 as recorded in the Protection Database.</para>
2260 <para>Every time you back up a volume using the AFS Backup
2261 System, the Backup Server creates records for it in the Backup
2267 <para>Maintaining your cell is simplest if the first machine has the
2268 lowest IP address of any machine you plan to use as a database
2269 server machine. If you later decide to use a machine with a lower IP
2270 address as a database server machine, you must update the <emphasis
2271 role="bold">CellServDB</emphasis> file on all clients before
2272 introducing the new machine.</para>
2274 <para>If your cell has more than one server machine, it is best to
2275 run more than one as a database server machine (but more than three
2276 are rarely necessary). Replicating the administrative databases in
2277 this way yields the same benefits as replicating volumes: increased
2278 availability and reliability. If one database server machine or
2279 process stops functioning, the information in the database is still
2280 available from others. The load of requests for database information
2281 is spread across multiple machines, preventing any one from becoming
2284 <para>Unlike replicated volumes, however, replicated databases do
2285 change frequently. Consistent system performance demands that all
2286 copies of the database always be identical, so it is not acceptable
2287 to record changes in only some of them. To synchronize the copies of
2288 a database, the database server processes use AFS's distributed
2289 database technology, Ubik. See <link linkend="HDRWQ102">Replicating
2290 the OpenAFS Administrative Databases</link>.</para>
2292 <para>If your cell has only one file server machine, it must also
2293 serve as a database server machine. If you cell has two file server
2294 machines, it is not always advantageous to run both as database
2295 server machines. If a server, process, or network failure interrupts
2296 communications between the database server processes on the two
2297 machines, it can become impossible to update the information in the
2298 database because neither of them can alone elect itself as the
2299 synchronization site.</para>
2302 <primary>server machine</primary>
2304 <secondary>protecting directories on local disk</secondary>
2308 <primary>local disk</primary>
2310 <secondary>protecting on file server machine</secondary>
2314 <sect2 id="HDRWQ53">
2315 <title>AFS Files on the Local Disk</title>
2317 <para>It is generally simplest to store the binaries for all AFS
2318 server processes in the <emphasis
2319 role="bold">/usr/afs/bin</emphasis> directory on every file server
2320 machine, even if some processes do not actively run on the
2321 machine. This makes it easier to reconfigure a machine to fill a new
2324 <para>For security reasons, the <emphasis
2325 role="bold">/usr/afs</emphasis> directory on a file server machine
2326 and all of its subdirectories and files must be owned by the local
2327 superuser <emphasis role="bold">root</emphasis> and have only the
2328 first <emphasis role="bold">w</emphasis> (<emphasis
2329 role="bold">write</emphasis>) mode bit turned on. Some files even
2330 have only the first <emphasis role="bold">r</emphasis> (<emphasis
2331 role="bold">read</emphasis>) mode bit turned on (for example, the
2332 <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file, which
2333 lists the AFS server encryption keys). Each time the BOS Server
2334 starts, it checks that the mode bits on certain files and
2335 directories match the expected values. For a list, see the
2336 <emphasis>OpenAFS Quick Beginnings</emphasis> section about
2337 protecting sensitive AFS directories, or the discussion of the
2338 output from the <emphasis role="bold">bos status</emphasis> command
2339 in <link linkend="HDRWQ159">To display the status of server
2340 processes and their BosConfig entries</link>.</para>
2342 <para>For a description of the contents of all AFS directories on a
2343 file server machine's local disk, see <link
2344 linkend="HDRWQ80">Administering Server Machines</link>.</para>
2347 <sect2 id="Header_62">
2348 <title>Configuring Partitions to Store AFS Data</title>
2350 <para>The partitions that house AFS volumes on a file server machine
2351 must be mounted at directories named</para>
2354 role="bold">/vicep</emphasis><emphasis>index</emphasis></para>
2356 <para>where <emphasis>index</emphasis> is one or two lowercase
2357 letters. By convention, the first AFS partition created is mounted
2358 at the <emphasis role="bold">/vicepa</emphasis> directory, the
2359 second at the <emphasis role="bold">/vicepb</emphasis> directory,
2360 and so on through the <emphasis role="bold">/vicepz</emphasis>
2361 directory. The names then continue with <emphasis
2362 role="bold">/vicepaa</emphasis> through <emphasis
2363 role="bold">/vicepaz</emphasis>, <emphasis
2364 role="bold">/vicepba</emphasis> through <emphasis
2365 role="bold">/vicepbz</emphasis>, and so on, up to the maximum
2366 supported number of server partitions, which is specified in the
2367 OpenAFS Release Notes.</para>
2369 <para>Each <emphasis role="bold">/vicep</emphasis>x directory must
2370 correspond to an entire partition or logical volume, and must be a
2371 subdirectory of the root directory (/). It is not acceptable to
2372 configure part of (for example) the <emphasis
2373 role="bold">/usr</emphasis> partition as an AFS server partition and
2374 mount it on a directory called <emphasis
2375 role="bold">/usr/vicepa</emphasis>.</para>
2377 <para>Also, do not store non-AFS files on AFS server partitions. The
2378 File Server and Volume Server expect to have available all of the
2379 space on the partition. Sharing space also creates competition
2380 between AFS and the local UNIX file system for access to the
2381 partition, particularly if the UNIX files are frequently
2385 <primary>server machine</primary>
2387 <secondary>monitoring</secondary>
2391 <primary>file server machine</primary>
2393 <secondary>rebooting, about</secondary>
2397 <primary>rebooting</primary>
2399 <secondary>file server machine, limiting</secondary>
2403 <primary>weekly restart of BOS Server (automatic)</primary>
2405 <secondary>about</secondary>
2409 <primary>restart times for BOS Server</primary>
2411 <secondary>about</secondary>
2415 <sect2 id="Header_63">
2416 <title>Monitoring, Rebooting and Automatic Process Restarts</title>
2418 <para>AFS provides several tools for monitoring the File Server,
2419 including the <emphasis role="bold">scout</emphasis> and <emphasis
2420 role="bold">afsmonitor</emphasis> programs. You can configure them
2421 to alert you when certain threshold values are exceeded, for example
2422 when a server partition is more than 95% full. See <link
2423 linkend="HDRWQ323">Monitoring and Auditing AFS
2424 Performance</link>.</para>
2426 <para>Rebooting a file server machine requires shutting down the AFS
2427 processes and so inevitably causes a service outage. Reboot file
2428 server machines as infrequently as possible. For instructions, see
2429 <link linkend="HDRWQ139">Rebooting a Server Machine</link>.</para>
2431 <para>The BOS Server checks each morning at 5:00 a.m. for any newly
2432 installed binary files in the <emphasis
2433 role="bold">/usr/afs/bin</emphasis> directory. It compares the
2434 timestamp on each binary file to the time at which the corresponding
2435 process last restarted. If the timestamp on the binary is later, the
2436 BOS Server restarts the corresponding process to start using
2439 <para>The BOS server also supports performing a weekly restart of
2440 all AFS server processes, including itself. This functionality is
2441 disabled on new installs, but historically it was set to 4:00am on
2442 Sunday. Administrators may find that installations predating OpenAFS
2443 1.6.0 have weekly restarts enabled.</para>
2445 <para>The default times are in the early morning hours when the
2446 outage that results from restarting a process is likely to disturb
2447 the fewest number of people. You can display the restart times for
2448 each machine with the <emphasis role="bold">bos
2449 getrestart</emphasis> command, and set them with the <emphasis
2450 role="bold">bos setrestart</emphasis> command. The latter command
2451 enables you to disable automatic restarts entirely, by setting the
2452 time to <emphasis role="bold">never</emphasis>. See <link
2453 linkend="HDRWQ171">Setting the BOS Server's Restart
2454 Times</link>.</para>
2457 <primary>client machine</primary>
2459 <secondary>configuration issues</secondary>
2463 <primary>configuring</primary>
2465 <secondary>client machine, issues</secondary>
2470 <sect1 id="HDRWQ54">
2471 <title>Configuring Client Machines</title>
2473 <para>This section summarizes issues to consider as you install and
2474 configure client machines in your cell.</para>
2477 <primary>client machine</primary>
2479 <secondary>files required on local disk</secondary>
2483 <primary>local disk</primary>
2485 <secondary>files required on client machine</secondary>
2489 <primary>file</primary>
2491 <secondary>required on client machine local disk</secondary>
2494 <sect2 id="HDRWQ55">
2495 <title>Configuring the Local Disk</title>
2497 <para>You can often free up significant amounts of local disk space
2498 on AFS client machines by storing standard UNIX files in AFS and
2499 creating symbolic links to them from the local disk. The <emphasis
2500 role="bold">@sys</emphasis> pathname variable can be useful in links
2501 to system-specific files; see <link linkend="HDRWQ56">Using the @sys
2502 Variable in Pathnames</link>.</para>
2504 <para>There are two types of files that must actually reside on the
2505 local disk: boot sequence files needed before the <emphasis
2506 role="bold">afsd</emphasis> program is invoked, and files that can
2507 be helpful during file server machine outages.</para>
2509 <para>During a reboot, AFS is inaccessible until the <emphasis
2510 role="bold">afsd</emphasis> program executes and initializes the
2511 Cache Manager. (In the conventional configuration, the AFS
2512 initialization file is included in the machine's initialization
2513 sequence and invokes the <emphasis role="bold">afsd</emphasis>
2514 program.) Files needed during reboot prior to that point must reside
2515 on the local disk. They include the following, but this list is not
2516 necessarily exhaustive.
2519 <para>Standard UNIX utilities including the following or their
2523 <para>Machine initialization files (stored in the
2524 <emphasis role="bold">/etc</emphasis> or <emphasis
2525 role="bold">/sbin</emphasis> directory on many system
2530 <para>The <emphasis role="bold">fstab</emphasis>
2535 <para>The <emphasis role="bold">mount</emphasis> command
2540 <para>The <emphasis role="bold">umount</emphasis>
2541 command binary</para>
2548 <para>All subdirectories and files in the <emphasis
2549 role="bold">/usr/vice</emphasis> directory, including the
2554 role="bold">/usr/vice/cache</emphasis> directory</para>
2559 role="bold">/usr/vice/etc/afsd</emphasis> command
2565 role="bold">/usr/vice/etc/cacheinfo</emphasis> file</para>
2570 role="bold">/usr/vice/etc/CellServDB</emphasis>
2576 role="bold">/usr/vice/etc/ThisCell</emphasis> file</para>
2581 <para>For more information on these files, see <link
2582 linkend="HDRWQ391">Configuration and Cache-Related Files on
2583 the Local Disk</link>.</para>
2588 <para>The other type of files and programs to retain on the local
2589 disk are those you need when diagnosing and fixing problems caused
2590 by a file server outage, because the outage can make inaccessible
2591 the copies stored in AFS. Examples include the binaries for a text
2592 editor (such as <emphasis role="bold">ed</emphasis> or <emphasis
2593 role="bold">vi</emphasis>) and for the <emphasis
2594 role="bold">fs</emphasis> and <emphasis role="bold">bos</emphasis>
2595 commands. Store copies of AFS command binaries in the <emphasis
2596 role="bold">/usr/vice/etc</emphasis> directory as well as including
2597 them in the <emphasis role="bold">/usr/afsws</emphasis> directory,
2598 which is normally a link into AFS. Then place the <emphasis
2599 role="bold">/usr/afsws</emphasis> directory before the <emphasis
2600 role="bold">/usr/vice/etc</emphasis> directory in users'
2601 <envar>PATH</envar> environment variable definition. When AFS is
2602 functioning normally, users access the copy in the <emphasis
2603 role="bold">/usr/afsws</emphasis> directory, which is more likely to
2604 be current than a local copy.</para>
2606 <para>You can automate the configuration of client machine local
2607 disks by using the <emphasis role="bold">package</emphasis> program,
2608 which updates the contents of the local disk to match a
2609 configuration file. See <link linkend="HDRWQ419">Configuring Client
2610 Machines with the package Program</link>.</para>
2613 <sect2 id="Header_66">
2614 <title>Enabling Access to Foreign Cells</title>
2617 <primary>client machine</primary>
2619 <secondary>enabling access to foreign cell</secondary>
2622 <para>As detailed in <link linkend="HDRWQ39">Making Other Cells
2623 Visible in Your Cell</link>, you enable the Cache Manager to access
2624 a cell's AFS filespace by storing a list of the cell's database
2625 server machines in the local <emphasis
2626 role="bold">/usr/vice/etc/CellServDB</emphasis> file. The Cache
2627 Manager reads the list into kernel memory at reboot for faster
2628 retrieval. You can change the list in kernel memory between reboots
2629 by using the <emphasis role="bold">fs newcell</emphasis> command. It
2630 is often practical to store a central version of the <emphasis
2631 role="bold">CellServDB</emphasis> file in AFS and use the <emphasis
2632 role="bold">package</emphasis> program periodically to update each
2633 client's version with the source copy. See <link
2634 linkend="HDRWQ406">Maintaining Knowledge of Database Server
2635 Machines</link>.</para>
2637 <para>Because each client machine maintains its own copy of the
2638 <emphasis role="bold">CellServDB</emphasis> file, you can in theory
2639 enable access to different foreign cells on different client
2640 machines. This is not usually practical, however, especially if
2641 users do not always work on the same machine.</para>
2644 <primary>at-sys (@sys) variable in pathnames</primary>
2648 <primary>sys (@sys) variable in pathnames</primary>
2652 <primary>variables</primary>
2654 <secondary>@sys in pathnames</secondary>
2658 <sect2 id="HDRWQ56">
2659 <title>Using the @sys Variable in Pathnames</title>
2661 <para>When creating symbolic links into AFS on the local disk, it is
2662 often practical to use the @sys variable in pathnames. The Cache
2663 Manager automatically substitutes the local machine's AFS system
2664 name (CPU/operating system type) for the @sys variable. This means
2665 you can place the same links on machines of various system types and
2666 still have each machine access the binaries for its system type. For
2667 example, the Cache Manager on a machine running AIX 4.2 converts
2668 <emphasis role="bold">/afs/example.com/@sys</emphasis> to <emphasis
2669 role="bold">/afs/example.com/rs_aix42</emphasis>, whereas a machine
2670 running Solaris 10 converts it to <emphasis
2671 role="bold">/afs/example.com/sun4x_510</emphasis>.</para>
2673 <para>If you want to use the @sys variable, it is simplest to use
2674 the conventional AFS system type names as specified in the OpenAFS
2675 Release Notes. The Cache Manager records the local machine's system
2676 type name in kernel memory during initialization. If you do not use
2677 the conventional names, you must use the <emphasis role="bold">fs
2678 sysname</emphasis> command to change the value in kernel memory from
2679 its default just after Cache Manager initialization, on every client
2680 machine of the relevant system type. The <emphasis role="bold">fs
2681 sysname</emphasis> command also displays the current value; see
2682 <link linkend="HDRWQ417">Displaying and Setting the System Type
2685 <para>In pathnames in the AFS filespace itself, use the @sys
2686 variable carefully and sparingly, because it can lead to unexpected
2687 results. It is generally best to restrict its use to only one level
2688 in the filespace. The third level is a common choice, because that
2689 is where many cells store the binaries for different machine
2692 <para>Multiple instances of the @sys variable in a pathname are
2693 especially dangerous to people who must explicitly change
2694 directories (with the <emphasis role="bold">cd</emphasis> command,
2695 for example) into directories that store binaries for system types
2696 other than the machine on which they are working, such as
2697 administrators or developers who maintain those directories. After
2698 changing directories, it is recommended that such people verify they
2699 are in the desired directory.</para>
2702 <sect2 id="Header_68">
2703 <title>Setting Server Preferences</title>
2705 <para>The Cache Manager stores a table of preferences for file
2706 server machines in kernel memory. A preference rank pairs a file
2707 server machine interface's IP address with an integer in the range
2708 from 1 to 65,534. When it needs to access a file, the Cache Manager
2709 compares the ranks for the interfaces of all machines that house the
2710 file, and first attempts to access the file via the interface with
2711 the best rank. As it initializes, the Cache Manager sets default
2712 ranks that bias it to access files via interfaces that are close to
2713 it in terms of network topology. You can adjust the preference ranks
2714 to improve performance if you wish.</para>
2716 <para>The Cache Manager also uses similar preferences for Volume
2717 Location (VL) Server machines. Use the <emphasis role="bold">fs
2718 getserverprefs</emphasis> command to display preference ranks and
2719 the <emphasis role="bold">fs setserverprefs</emphasis> command to
2720 set them. See <link linkend="HDRWQ414">Maintaining Server Preference
2721 Ranks</link>.</para>
2724 <primary>user account</primary>
2726 <secondary>configuration issues</secondary>
2730 <sect1 id="HDRWQ57">
2731 <title>Configuring AFS User Accounts</title>
2733 <para>This section discusses some of the issues to consider when
2734 configuring AFS user accounts. Because AFS is separate from the UNIX
2735 file system, a user's AFS account is separate from her UNIX
2738 <para>The preferred method for creating a user account is with the
2739 <emphasis role="bold">uss</emphasis> suite of commands. With a single
2740 command, you can create all the components of one or many accounts,
2741 after you have prepared a template file that guides the account
2742 creation. See <link linkend="HDRWQ449">Creating and Deleting User
2743 Accounts with the uss Command Suite</link>.</para>
2745 <para>Alternatively, you can issue the individual commands that create
2746 each component of an account. For instructions, along with
2747 instructions for removing user accounts and changing user passwords,
2748 user volume quotas and usernames, see <link
2749 linkend="HDRWQ491">Administering User Accounts</link>.</para>
2751 <para>When users leave your system, it is often good policy to remove
2752 their accounts. Instructions appear in <link
2753 linkend="HDRWQ486">Deleting Individual Accounts with the uss delete
2754 Command</link> and <link linkend="HDRWQ524">Removing a User
2755 Account</link>.</para>
2757 <para>An AFS user account consists of the following components, which
2758 are described in greater detail in <link linkend="HDRWQ494">The
2759 Components of an AFS User Account</link>.
2762 <para>A Protection Database entry</para>
2766 <para>An Authentication Database entry</para>
2770 <para>A volume</para>
2774 <para>A home directory at which the volume is mounted</para>
2778 <para>Ownership of the home directory and full permissions on
2783 <para>An entry in the local password file (<emphasis
2784 role="bold">/etc/passwd</emphasis> or equivalent) of each
2785 machine the user needs to log into</para>
2789 <para>Optionally, standard files and subdirectories that make
2790 the account more useful</para>
2795 <para>By creating some components but not others, you can create
2796 accounts at different levels of functionality, using either <emphasis
2797 role="bold">uss</emphasis> commands as described in <link
2798 linkend="HDRWQ449">Creating and Deleting User Accounts with the uss
2799 Command Suite</link> or individual commands as described in <link
2800 linkend="HDRWQ491">Administering User Accounts</link>. The levels of
2801 functionality include the following
2804 <para>An authentication-only account enables the user to obtain
2805 AFS tokens and so to access protected AFS data and to issue
2806 privileged commands. It consists only of entries in the
2807 Authentication and Protection Database. This type of account is
2808 suitable for administrative accounts and for users from foreign
2809 cells who need to access protected data. Local users generally
2810 also need a volume and home directory.</para>
2814 <para>A basic user account includes a volume for the user, in
2815 addition to Authentication and Protection Database entries. The
2816 volume is mounted in the AFS filespace as the user's home
2817 directory, and provides a repository for the user's personal
2822 <para>A full account adds configuration files for basic
2823 functions such as logging in, printing, and mail delivery to a
2824 basic account, making it more convenient and useful. For a
2825 discussion of some useful types of configuration files, see
2826 <link linkend="HDRWQ60">Creating Standard Files in New AFS
2827 Accounts</link>.</para>
2832 <para>If your users have UNIX user accounts that predate the
2833 introduction of AFS in the cell, you possibly want to convert them
2834 into AFS accounts. There are three main issues to consider:
2837 <para>Making UNIX and AFS UIDs match</para> </listitem>
2840 <para>Setting the password field in the local password file
2841 appropriately</para>
2845 <para>Moving files from the UNIX file system into AFS</para>
2850 <para>For further discussion, see <link linkend="HDRWQ459">Converting
2851 Existing UNIX Accounts with uss</link> or <link
2852 linkend="HDRWQ498">Converting Existing UNIX Accounts</link>.</para>
2855 <primary>username</primary>
2857 <secondary>choosing</secondary>
2861 <primary>user</primary>
2863 <secondary>name</secondary>
2869 <primary>choosing</primary>
2871 <secondary>name</secondary>
2873 <tertiary>user</tertiary>
2877 <primary>anonymous user</primary>
2879 <secondary>AFS UID reserved</secondary>
2883 <primary>AFS UID</primary>
2885 <secondary>reserved</secondary>
2887 <tertiary>anonymous user</tertiary>
2890 <sect2 id="HDRWQ58">
2891 <title>Choosing Usernames and Naming Other Account
2894 <para>This section suggests schemes for choosing usernames, AFS
2895 UIDs, user volume names and mount point names, and also outlines
2896 some restrictions on your choices.</para>
2899 <title>Usernames</title>
2901 <para>AFS imposes very few restrictions on the form of
2902 usernames. It is best to keep usernames short, both because many
2903 utilities and applications can handle usernames of no more than
2904 eight characters and because by convention many components of and
2905 AFS account incorporate the name. These include the entries in the
2906 Protection and Authentication Databases, the volume, and the mount
2907 point. Depending on your electronic mail delivery system, the
2908 username can become part of the user's mailing address. The
2909 username is also the string that the user types when logging in to
2910 a client machine.</para>
2913 <para>Some common choices for usernames are last names, first names,
2914 initials, or a combination, with numbers sometimes added. It is
2915 also best to avoid using the following characters, many of which
2916 have special meanings to the command shell.
2919 <para>The comma (<emphasis role="bold">,</emphasis>)</para>
2923 <para>The colon (<emphasis role="bold">:</emphasis>), because
2924 AFS reserves it as a field separator in protection group
2925 names; see <link linkend="HDRWQ62">The Two Types of
2926 User-Defined Groups</link></para>
2930 <para>The semicolon (<emphasis
2931 role="bold">;</emphasis>)</para>
2935 <para>The "at-sign" (<emphasis role="bold">@</emphasis>); this
2936 character is reserved for Internet mailing addresses</para>
2944 <para>The newline character</para>
2948 <para>The period (<emphasis role="bold">.</emphasis>); it is
2949 conventional to use this character only in the special
2950 username that an administrator adopts while performing
2951 privileged tasks, such as <emphasis
2952 role="bold">pat.admin</emphasis></para>
2958 <title>AFS UIDs and UNIX UIDs</title>
2960 <para>AFS associates a unique identification number, the AFS UID,
2961 with every username, recording the mapping in the user's
2962 Protection Database entry. The AFS UID functions within AFS much
2963 as the UNIX UID does in the local file system: the AFS server
2964 processes and the Cache Manager use it internally to identify a
2965 user, rather than the username.</para>
2968 <para>Every AFS user also must have a UNIX UID recorded in the local
2969 password file (<emphasis role="bold">/etc/passwd</emphasis> or
2970 equivalent) of each client machine they log onto. Both
2971 administration and a user's AFS access are simplest if the AFS UID
2972 and UNIX UID match. One important consequence of matching UIDs is
2973 that the owner reported by the <emphasis role="bold">ls
2974 -l</emphasis> command matches the AFS username.</para>
2976 <para>It is usually best to allow the Protection Server to allocate
2977 the AFS UID as it creates the Protection Database entry. However,
2978 both the <emphasis role="bold">pts createuser</emphasis> command and
2979 the <emphasis role="bold">uss</emphasis> commands that create user
2980 accounts enable you to assign AFS UIDs explicitly. This is
2981 appropriate in two cases:
2984 <para>You wish to group together the AFS UIDs of related
2989 <para>You are converting an existing UNIX account into an AFS
2990 account and want to make the AFS UID match the existing UNIX
2996 <para>After the Protection Server initializes for the first time on
2997 a cell's first file server machine, it starts assigning AFS UIDs at
2998 a default value. To change the default before creating any user
2999 accounts, or at any time, use the <emphasis role="bold">pts
3000 setmax</emphasis> command to reset the <computeroutput>max user id
3001 counter</computeroutput>. To display the counter, use the <emphasis
3002 role="bold">pts listmax</emphasis> command. See <link
3003 linkend="HDRWQ560">Displaying and Setting the AFS UID and GID
3004 Counters</link>.</para>
3006 <para>AFS reserves one AFS UID, 32766, for the user <emphasis
3007 role="bold">anonymous</emphasis>. The AFS server processes assign
3008 this identity and AFS UID to any user who does not possess a token
3009 for the local cell. Do not assign this AFS UID to any other user or
3010 hardcode its current value into any programs or a file's owner
3011 field, because it is subject to change in future releases.</para>
3014 <primary>username</primary>
3016 <secondary>part of volume name</secondary>
3020 <primary>choosing</primary>
3022 <secondary>name</secondary>
3024 <tertiary>user volume</tertiary>
3028 <title>User Volume Names</title>
3030 <para>Like any volume name, a user volume's base (read/write) name
3031 cannot exceed 22 characters in length or include the <emphasis
3032 role="bold">.readonly</emphasis> or <emphasis
3033 role="bold">.backup</emphasis> extension. See <link
3034 linkend="HDRWQ44">Creating Volumes to Simplify
3035 Administration</link>. By convention, user volume names have the
3036 format <emphasis role="bold">user.</emphasis>username. Using the
3037 <emphasis role="bold">user.</emphasis> prefix not only makes it
3038 easy to identify the volume's contents, but also to create a
3039 backup version of all user volumes by issuing a single <emphasis
3040 role="bold">vos backupsys</emphasis> command.</para>
3044 <primary>mount point</primary>
3046 <secondary>choosing name for user volume</secondary>
3050 <primary>choosing</primary>
3052 <secondary>name</secondary>
3054 <tertiary>user volume mount point</tertiary>
3058 <title>Mount Point Names</title>
3060 <para>By convention, the mount point for a user's volume is named
3061 after the username. Many cells follow the convention of mounting
3062 user volumes in the <emphasis
3063 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
3064 role="bold">/usr</emphasis> directory, as discussed in <link
3065 linkend="HDRWQ43">The Third Level</link>. Very large cells
3066 sometimes find that mounting all user volumes in the same
3067 directory slows directory lookup, however; for suggested
3068 alternatives, see the following section.</para>
3072 <primary>directories</primary>
3074 <secondary>for grouping user home directories</secondary>
3078 <primary>user account</primary>
3080 <secondary>suggestions for grouping home directories</secondary>
3084 <sect2 id="HDRWQ59">
3085 <title>Grouping Home Directories</title>
3087 <para>Mounting user volumes in the <emphasis
3088 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
3089 role="bold">/usr</emphasis> directory is an AFS-appropriate
3090 variation on the standard UNIX practice of putting user home
3091 directories under the <emphasis role="bold">/usr</emphasis>
3092 subdirectory. However, cells with more than a few hundred users
3093 sometimes find that mounting all user volumes in a single directory
3094 results in slow directory lookup. The solution is to distribute user
3095 volume mount points into several directories; there are a number of
3096 alternative methods to accomplish this.
3099 <para>Distribute user home directories into multiple
3100 directories that reflect organizational divisions, such as
3101 academic or corporate departments. For example, a company can
3102 create group directories called <emphasis
3103 role="bold">usr/marketing</emphasis>, <emphasis
3104 role="bold">usr/research</emphasis>, <emphasis
3105 role="bold">usr/finance</emphasis>. A good feature of this
3106 scheme is that knowing a user's department is enough to find
3107 the user's home directory. Also, it makes it easy to set the
3108 ACL to limit access to members of the department only. A
3109 potential drawback arises if departments are of sufficiently
3110 unequal size that users in large departments experience slower
3111 lookup than users in small departments. This scheme is also
3112 not appropriate in cells where users frequently change between
3117 <para>Distribute home directories into alphabetic
3118 subdirectories of the <emphasis role="bold">usr</emphasis>
3119 directory (the <emphasis role="bold">usr/a</emphasis>
3120 subdirectory, the <emphasis role="bold">usr/b</emphasis>
3121 subdirectory, and so on), based on the first letter of the
3122 username. If the cell is very large, create subdirectories
3123 under each letter that correspond to the second letter in the
3124 user name. This scheme has the same advantages and
3125 disadvantages of a department-based scheme. Anyone who knows
3126 the user's username can find the user's home directory, but
3127 users with names that begin with popular letters sometimes
3128 experience slower lookup.</para>
3132 <para>Distribute home directories randomly but evenly into
3133 more than one grouping directory. One cell that uses this
3134 scheme has over twenty such directories called the <emphasis
3135 role="bold">usr1</emphasis> directory, the <emphasis
3136 role="bold">usr2</emphasis> directory, and so on. This scheme
3137 is especially appropriate in cells where the other two schemes
3138 do not seem feasible. It eliminates the potential problem of
3139 differences in lookup speed, because all directories are about
3140 the same size. Its disadvantage is that there is no way to
3141 guess which directory a given user's volume is mounted in, but
3142 a solution is to create a symbolic link in the regular
3143 <emphasis role="bold">usr</emphasis> directory that references
3144 the actual mount point. For example, if user <emphasis
3145 role="bold">smith</emphasis>'s volume is mounted at the
3147 role="bold">/afs/bigcell.example.com/usr17/smith</emphasis>
3148 directory, then the <emphasis
3149 role="bold">/afs/bigcell.example.com/usr/smith</emphasis>
3150 directory is a symbolic link to the <emphasis
3151 role="bold">../usr17/smith</emphasis> directory. This way, if
3152 someone does not know which directory the user <emphasis
3153 role="bold">smith</emphasis> is in, he or she can access it
3154 through the link called <emphasis
3155 role="bold">usr/smith</emphasis>; people who do know the
3156 appropriate directory save lookup time by specifying
3162 <para>For instructions on how to implement the various schemes when
3163 using the <emphasis role="bold">uss</emphasis> program to create
3164 user accounts, see <link linkend="HDRWQ472">Evenly Distributing User
3165 Home Directories with the G Instruction</link> and <link
3166 linkend="HDRWQ473">Creating a Volume with the V
3167 Instruction</link>.</para>
3170 <sect2 id="Header_72">
3171 <title>Making a Backup Version of User Volumes Available</title>
3173 <para>Mounting the backup version of a user's volume is a simple way
3174 to enable users themselves to restore data they have accidentally
3175 removed or deleted. It is conventional to mount the backup version
3176 at a subdirectory of the user's home directory (called perhaps the
3177 <emphasis role="bold">OldFiles</emphasis> subdirectory), but other
3178 schemes are possible. Once per day you create a new backup version
3179 to capture the changes made that day, overwriting the previous day's
3180 backup version with the new one. Users can always retrieve the
3181 previous day's copy of a file without your assistance, freeing you
3182 to deal with more pressing tasks.</para>
3184 <para>Users sometimes want to delete the mount point to their backup
3185 volume, because they erroneously believe that the backup volume's
3186 contents count against their quota. Remind them that the backup
3187 volume is separate, so the only space it uses in the user volume is
3188 the amount needed for the mount point.</para>
3190 <para>For further discussion of backup volumes, see <link
3191 linkend="HDRWQ77">Backing Up AFS Data</link> and <link
3192 linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
3195 <primary>file</primary>
3197 <secondary>creating standard ones in new user account</secondary>
3201 <primary>user account</primary>
3203 <secondary>creating</secondary>
3205 <tertiary>standard files in</tertiary>
3209 <primary>creating</primary>
3211 <secondary>standard files in new user account</secondary>
3215 <sect2 id="HDRWQ60">
3216 <title>Creating Standard Files in New AFS Accounts</title>
3218 <para>From your experience as a UNIX administrator, you are probably
3219 familiar with the use of login and shell initialization files (such
3220 as the <emphasis role="bold">.login</emphasis> and <emphasis
3221 role="bold">.cshrc</emphasis> files) to make an account easier to
3224 <para>It is often practical to add some AFS-specific directories to
3225 the definition of the user's <envar>PATH</envar> environment
3226 variable, including the following:
3229 <para>The path to a <emphasis role="bold">bin</emphasis>
3230 subdirectory in the user's home directory for binaries the
3231 user has created (that is, <emphasis
3232 role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
3233 role="bold">/usr/</emphasis><replaceable>username</replaceable><emphasis
3234 role="bold">/bin</emphasis>)</para>
3238 <para>The <emphasis role="bold">/usr/afsws/bin</emphasis>
3239 path, which conventionally includes programs like <emphasis
3240 role="bold">fs</emphasis>, <emphasis
3241 role="bold">klog</emphasis>, <emphasis
3242 role="bold">kpasswd</emphasis>, <emphasis
3243 role="bold">pts</emphasis>, <emphasis
3244 role="bold">tokens</emphasis>, and <emphasis
3245 role="bold">unlog</emphasis></para>
3249 <para>The <emphasis role="bold">/usr/afsws/etc</emphasis>
3250 path, if the user is an administrator; it usually houses the
3251 AFS command suites that require privilege (the <emphasis
3252 role="bold">backup</emphasis>, <emphasis
3253 role="bold">butc</emphasis>, <emphasis
3254 role="bold">kas</emphasis>, <emphasis
3255 role="bold">uss</emphasis>, <emphasis
3256 role="bold">vos</emphasis> commands), the <emphasis
3257 role="bold">package</emphasis> program, and others</para>
3262 <para>If you are not using an AFS-modified login utility, it can be
3263 helpful to users to invoke the <emphasis role="bold">klog</emphasis>
3264 command in their <emphasis role="bold">.login</emphasis> file so
3265 that they obtain AFS tokens as part of logging in. In the following
3266 example command sequence, the first line echoes the string
3267 <computeroutput>klog</computeroutput> to the standard output stream,
3268 so that the user understands the purpose of the
3269 <computeroutput>Password:</computeroutput> prompt that appears when
3270 the second line is executed. The <emphasis
3271 role="bold">-setpag</emphasis> flag associates the new tokens with a
3272 process authentication group (PAG), which is discussed further in
3273 <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
3276 echo -n "klog " klog -setpag
3279 <para>The following sequence of commands has a similar effect,
3280 except that the <emphasis role="bold">pagsh</emphasis> command forks
3281 a new shell with which the PAG and tokens are associated.</para>
3284 pagsh echo -n "klog " klog
3287 <para>If you use an AFS-modified login utility, this sequence is not
3288 necessary, because such utilities both log a user in locally and
3289 obtain AFS tokens.</para>
3292 <primary>group</primary>
3294 <secondary>AFS GID</secondary>
3298 <primary>group</primary>
3300 <secondary>restrictions</secondary>
3304 <primary>group</primary>
3306 <secondary>privacy flags</secondary>
3310 <primary>privacy flags on Protection Database entry</primary>
3315 <sect1 id="HDRWQ61">
3316 <title>Using AFS Protection Groups</title>
3318 <para>AFS enables users to define their own groups of other users or
3319 machines. The groups are placed on ACLs to grant the same permissions
3320 to many users without listing each user individually. For group
3321 creation instructions, see <link linkend="HDRWQ531">Administering the
3322 Protection Database</link>.</para>
3324 <para>Groups have AFS ID numbers, just as users do, but an AFS group
3325 ID (GID) is a negative integer whereas a user's AFS UID is a positive
3326 integer. By default, the Protection Server allocates a new group's AFS
3327 GID automatically, but members of the <emphasis
3328 role="bold">system:administrators</emphasis> group can assign a GID
3329 when issuing the <emphasis role="bold">pts creategroup</emphasis>
3330 command. Before explicitly assigning a GID, it is best to verify that
3331 it is not already in use.</para>
3333 <para>A group cannot belong to another group, but it can own another
3334 group or even itself as long as it (the owning group) has at least one
3335 member. The current owner of a group can transfer ownership of the
3336 group to another user or group, even without the new owner's
3337 permission. At that point the former owner loses administrative
3338 control over the group.</para>
3340 <para>By default, each user can create 20 groups. A system
3341 administrator can increase or decrease this group creation quota with
3342 the <emphasis role="bold">pts setfields</emphasis> command.</para>
3344 <para>Each Protection Database entry (group or user) is protected by a
3345 set of five privacy flagswhich limit who can administer the entry and
3346 what they can do. The default privacy flags are fairly restrictive,
3347 especially for user entries. See <link linkend="HDRWQ559">Setting the
3348 Privacy Flags on Database Entries</link>.</para>
3351 <primary>system:administrators group</primary>
3353 <secondary>about</secondary>
3357 <primary>system:anyuser group</primary>
3359 <secondary>about</secondary>
3363 <primary>system:authuser group</primary>
3365 <secondary>about</secondary>
3369 <primary>group</primary>
3371 <secondary>system-defined</secondary>
3374 <sect2 id="Header_75">
3375 <title>The Three System Groups</title>
3377 <para>As the Protection Server initializes for the first time on a
3378 cell's first database server machine, it automatically creates three
3379 group entries: the <emphasis role="bold">system:anyuser</emphasis>,
3380 <emphasis role="bold">system:authuser</emphasis>, and <emphasis
3381 role="bold">system:administrators</emphasis> groups.</para>
3384 <primary>AFS UID</primary>
3386 <secondary>reserved</secondary>
3388 <tertiary>system-defined groups</tertiary>
3391 <para>The first two system groups are unlike any other groups in the
3392 Protection Database in that they do not have a stable membership:
3395 <para>The <emphasis role="bold">system:anyuser</emphasis>
3396 group includes everyone who can access a cell's AFS filespace:
3397 users who have tokens for the local cell, users who have
3398 logged in on a local AFS client machine but not obtained
3399 tokens (such as the local superuser <emphasis
3400 role="bold">root</emphasis>), and users who have connected to
3401 a local machine from outside the cell. Placing the <emphasis
3402 role="bold">system:anyuser</emphasis> group on an ACL grants
3403 access to the widest possible range of users. It is the only
3404 way to extend access to users from foreign AFS cells that do
3405 not have local accounts.</para>
3409 <para>The <emphasis role="bold">system:authuser</emphasis>
3410 group includes everyone who has a valid token obtained from
3411 the cell's AFS authentication service.</para>
3416 <para>Because the groups do not have a stable membership, the
3417 <emphasis role="bold">pts membership</emphasis> command produces no
3418 output for them. Similarly, they do not appear in the list of groups
3419 to which a user belongs.</para>
3421 <para>The <emphasis role="bold">system:administrators</emphasis>
3422 group does have a stable membership, consisting of the cell's
3423 privileged administrators. Members of this group can issue any
3424 <emphasis role="bold">pts</emphasis> command, and are the only ones
3425 who can issue several other restricted commands (such as the
3426 <emphasis role="bold">chown</emphasis> command on AFS files). By
3427 default, they also implicitly have the <emphasis
3428 role="bold">a</emphasis> (<emphasis
3429 role="bold">administer</emphasis>) and <emphasis
3430 role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
3431 permissions on every ACL in the filespace. For information about
3432 changing this default, see <link linkend="HDRWQ586">Administering
3433 the system:administrators Group</link>.</para>
3435 <para>For a discussion of how to use system groups effectively on
3436 ACLs, see <link linkend="HDRWQ571">Using Groups on
3440 <sect2 id="HDRWQ62">
3441 <title>The Two Types of User-Defined Groups</title>
3443 <para>All users can create regular groups. A regular group name has
3444 two fields separated by a colon, the first of which must indicate
3445 the group's ownership. The Protection Server refuses to create or
3446 change the name of a group if the result does not accurately
3447 indicate the ownership.</para>
3449 <para>Members of the <emphasis
3450 role="bold">system:administrators</emphasis> group can create
3451 prefix-less groups whose names do not have the first field that
3452 indicates ownership. For suggestions on using the two types of
3453 groups effectively, see <link linkend="HDRWQ545">Using Groups
3454 Effectively</link>.</para>
3457 <primary>authentication</primary>
3459 <secondary>AFS separate from UNIX</secondary>
3463 <primary>AFS</primary>
3465 <secondary>authentication separate from UNIX</secondary>
3470 <sect1 id="HDRWQ63">
3471 <title>Login and Authentication in AFS</title>
3473 <para>As explained in <link linkend="HDRWQ31">Differences in
3474 Authentication</link>, AFS authentication is separate from UNIX
3475 authentication because the two file systems are separate. The
3476 separation has two practical implications:
3479 <para>To access AFS files, users must both log into the local
3480 file system and authenticate with the AFS authentication
3481 service. (Logging into the local file system is necessary
3482 because the only way to access the AFS filespace is through a
3483 Cache Manager, which resides in the local machine's
3488 <para>Passwords are stored in two separate places: in the
3489 Kerberos Database for AFS and in the each machine's local
3490 password file (the <emphasis role="bold">/etc/passwd</emphasis>
3491 file or equivalent) for the local file system.</para>
3496 <para>When a user successfully authenticates, the AFS authentication
3497 service passes a token to the user's Cache Manager. The token is a
3498 small collection of data that certifies that the user has correctly
3499 provided the password associated with a particular AFS identity. The
3500 Cache Manager presents the token to AFS server processes along with
3501 service requests, as proof that the user is genuine. To learn about
3502 the mutual authentication procedure they use to establish identity,
3503 see <link linkend="HDRWQ75">A More Detailed Look at Mutual
3504 Authentication</link>.</para>
3506 <para>The Cache Manager stores tokens in the user's credential
3507 structure in kernel memory. To distinguish one user's credential
3508 structure from another's, the Cache Manager identifies each one either
3509 by the user's UNIX UID or by a process authentication group (PAG),
3510 which is an identification number guaranteed to be unique in the
3511 cell. For further discussion, see <link linkend="HDRWQ64">Identifying
3512 AFS Tokens by PAG</link>.</para>
3515 <primary>tokens</primary>
3517 <secondary>one-per-cell rule</secondary>
3520 <para>A user can have only one token per cell in each separately
3521 identified credential structure. To obtain a second token for the same
3522 cell, the user must either log into a different machine or obtain
3523 another credential structure with a different identifier than any
3524 existing credential structure, which is most easily accomplished by
3525 issuing the <emphasis role="bold">pagsh</emphasis> command (see <link
3526 linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>). In a single
3527 credential structure, a user can have one token for each of many cells
3528 at the same time. As this implies, authentication status on one
3529 machine or PAG is independent of authentication status on another
3530 machine or PAG, which can be very useful to a user or system
3531 administrator.</para>
3533 <para>The AFS distribution includes library files that enable each
3534 system type's login utility to authenticate users with AFS and log
3535 them into the local file system in one step. If you do not configure
3536 an AFS-modified login utility on a client machine, its users must
3537 issue the <emphasis role="bold">klog</emphasis> command to
3538 authenticate with AFS after logging in.</para>
3541 <para>The AFS-modified libraries do not necessarily support all
3542 features available in an operating system's proprietary login
3543 utility. In some cases, it is not possible to support a utility at
3544 all. For more information about the supported utilities in each AFS
3545 version, see the OpenAFS Release Notes.</para>
3549 <primary>commands</primary>
3551 <secondary>pagsh</secondary>
3555 <primary>pagsh command</primary>
3559 <primary>commands</primary>
3561 <secondary>klog with -setpag flag</secondary>
3565 <primary>klog command</primary>
3567 <secondary>with -setpag flag</secondary>
3571 <primary>PAG</primary>
3573 <secondary>creating with klog or pagsh command</secondary>
3577 <primary>creating</primary>
3579 <secondary>PAG with klog or pagsh command</secondary>
3583 <primary>process authentication group</primary>
3585 <secondary></secondary>
3590 <sect2 id="HDRWQ64">
3591 <title>Identifying AFS Tokens by PAG</title>
3593 <para>As noted, the Cache Manager identifies user credential
3594 structures either by UNIX UID or by PAG. Using a PAG is preferable
3595 because it guaranteed to be unique: the Cache Manager allocates it
3596 based on a counter that increments with each use. In contrast,
3597 multiple users on a machine can share or assume the same UNIX UID,
3598 which creates potential security problems. The following are two
3599 common such situations:
3602 <para>The local superuser <emphasis
3603 role="bold">root</emphasis> can always assume any other user's
3604 UNIX UID simply by issuing the <emphasis
3605 role="bold">su</emphasis> command, without providing the
3606 user's password. If the credential structure is associated
3607 with the user's UNIX UID, then assuming the UID means
3608 inheriting the AFS tokens.</para>
3612 <para>Two users working on different NFS client machines can
3613 have the same UNIX UID in their respective local file
3614 systems. If they both access the same NFS/AFS Translator
3615 machine, and the Cache Manager there identifies them by their
3616 UNIX UID, they become indistinguishable. To eliminate this
3617 problem, the Cache Manager on a translator machine
3618 automatically generates a PAG for each user and uses it,
3619 rather than the UNIX UID, to tell users apart.</para>
3624 <para>Yet another advantage of PAGs over UIDs is that processes
3625 spawned by the user inherit the PAG and so share the token; thus
3626 they gain access to AFS as the authenticated user. In many
3627 environments, for example, printer and other daemons run under
3628 identities (such as the local superuser <emphasis
3629 role="bold">root</emphasis>) that the AFS server processes recognize
3630 only as the <emphasis role="bold">anonymous</emphasis> user. Unless
3631 PAGs are used, such daemons cannot access files for which the
3632 <emphasis role="bold">system:anyuser</emphasis> group does not have
3633 the necessary ACL permissions.</para>
3635 <para>Once a user has a PAG, any new tokens the user obtains are
3636 associated with the PAG. The PAG expires two hours after any
3637 associated tokens expire or are discarded. If the user issues the
3638 <emphasis role="bold">klog</emphasis> command before the PAG
3639 expires, the new token is associated with the existing PAG (the PAG
3640 is said to be recycled in this case).</para>
3642 <para>AFS-modified login utilities automatically generate a PAG, as
3643 described in the following section. If you use a standard login
3644 utility, your users must issue the <emphasis
3645 role="bold">pagsh</emphasis> command before the <emphasis
3646 role="bold">klog</emphasis> command, or include the latter command's
3647 <emphasis role="bold">-setpag</emphasis> flag. For instructions, see
3648 <link linkend="HDRWQ69">Using Two-Step Login and
3649 Authentication</link>.</para>
3651 <para>Users can also use either command at any time to create a new
3652 PAG. The difference between the two commands is that the <emphasis
3653 role="bold">klog</emphasis> command replaces the PAG associated with
3654 the current command shell and tokens. The <emphasis
3655 role="bold">pagsh</emphasis> command initializes a new command shell
3656 before creating a new PAG. If the user already had a PAG, any
3657 running processes or jobs continue to use the tokens associated with
3658 the old PAG whereas any new jobs or processes use the new PAG and
3659 its associated tokens. When you exit the new shell (by pressing
3660 <<emphasis role="bold">Ctrl-d</emphasis>>, for example), you
3661 return to the original PAG and shell. By default, the <emphasis
3662 role="bold">pagsh</emphasis> command initializes a Bourne shell, but
3663 you can include the <emphasis role="bold">-c</emphasis> argument to
3664 initialize a C shell (the <emphasis role="bold">/bin/csh</emphasis>
3665 program on many system types) or Korn shell (the <emphasis
3666 role="bold">/bin/ksh</emphasis> program) instead.</para>
3669 <primary>login utility</primary>
3671 <secondary>AFS version</secondary>
3675 <sect2 id="HDRWQ65">
3676 <title>Using an AFS-modified login Utility</title>
3678 <para>As previously mentioned, an AFS-modified login utility
3679 simultaneously obtains an AFS token and logs the user into the local
3680 file system. This section outlines the login and authentication
3681 process and its interaction with the value in the password field of
3682 the local password file.</para>
3684 <para>An AFS-modified login utility performs a sequence of steps
3685 similar to the following; details can vary for different operating
3689 <para>It checks the user's entry in the local password file
3690 (the <emphasis role="bold">/etc/passwd</emphasis> file or
3695 <para>If no entry exists, or if an asterisk
3696 (<computeroutput>*</computeroutput>) appears in the entry's
3697 password field, the login attempt fails. If the entry exists,
3698 the attempt proceeds to the next step.</para>
3701 <listitem id="LIWQ66">
3702 <para>The utility obtains a PAG.</para>
3705 <listitem id="LIWQ67">
3706 <para>The utility converts the password
3707 provided by the user into an encryption key and encrypts a
3708 packet of data with the key. It sends the packet to the AFS
3709 authentication service (the AFS Authentication Server in the
3710 conventional configuration).</para>
3714 <para>The authentication service decrypts the packet and,
3715 depending on the success of the decryption, judges the
3716 password to be correct or incorrect. (For more details, see
3717 <link linkend="HDRWQ75">A More Detailed Look at Mutual
3718 Authentication</link>.)
3721 <para>If the authentication service judges the password
3722 incorrect, the user does not receive an AFS token. The
3723 PAG is retained, ready to be associated with any tokens
3724 obtained later. The attempt proceeds to Step <link
3725 linkend="LIWQ68">6</link>.</para>
3729 <para>If the authentication service judges the password
3730 correct, it issues a token to the user as proof of AFS
3731 authentication. The login utility logs the user into the
3732 local UNIX file system. Some login utilities echo the
3733 following banner to the screen to alert the user to
3734 authentication with AFS. Step <link
3735 linkend="LIWQ68">6</link> is skipped.
3737 AFS(R) version Login
3745 <listitem id="LIWQ68">
3746 <para>If no AFS token was granted in
3747 Step <link linkend="LIWQ67">4</link>, the login utility
3748 attempts to log the user into the local file system, by
3749 comparing the password provided to the local password file.
3752 <para>If the password is incorrect or any value other
3753 than an encrypted 13-character string appears in the
3754 password field, the login attempt fails.</para>
3758 <para>If the password is correct, the user is logged
3759 into the local file system only.</para> </listitem>
3767 <primary>local password file</primary>
3769 <secondary>when using AFS--modified login utility</secondary>
3773 <primary>login utility</primary>
3775 <secondary>AFS version's interaction with local password
3780 <primary>password</primary>
3782 <secondary>local password file</secondary>
3785 <para>As indicated, when you use an AFS-modified login utility, the
3786 password field in the local password file is no longer the primary
3787 gate for access to your system. If the user provides the correct AFS
3788 password, then the program never consults the local password
3789 file. However, you can still use the password field to control
3790 access, in the following way:
3793 <para>To prevent both local login and AFS authentication,
3794 place an asterisk (<emphasis role="bold">*</emphasis>) in the
3795 field. This is useful mainly in emergencies, when you want to
3796 prevent a certain user from logging into the machine.</para>
3800 <para>To prevent login to the local file system if the user
3801 does not provide the correct AFS password, place a character
3802 string of any length other than the standard thirteen
3803 characters in the field. This is appropriate if you want to
3804 permit only people with local AFS accounts to login on your
3805 machines. A single <emphasis role="bold">X</emphasis> or other
3806 character is the most easily recognizable way to do
3811 <para>To enable a user to log into the local file system even
3812 after providing an incorrect AFS password, record a standard
3813 UNIX encrypted password in the field by issuing the standard
3814 UNIX password-setting command (<emphasis
3815 role="bold">passwd</emphasis> or equivalent).</para>
3820 <para>Systems that use a Pluggable Authentication Module (PAM) for
3821 login and AFS authentication do not necessarily consult the local
3822 password file at all, in which case they do not use the password
3823 field to control authentication and login attempts. Instead,
3824 instructions in the PAM configuration file (on many system types,
3825 <emphasis role="bold">/etc/pam.conf</emphasis>) fill the same
3826 function. See the instructions in the OpenAFS Quick Beginnings for
3827 installing AFS-modified login utilities.</para>
3830 <primary>local password file</primary>
3832 <secondary>when not using AFS-modified login utility</secondary>
3836 <sect2 id="HDRWQ69">
3837 <title>Using Two-Step Login and Authentication</title>
3839 <para>In cells that do not use an AFS-modified login utility, users
3840 must issue separate commands to login and authenticate, as detailed
3841 in the OpenAFS User Guide:
3844 <para>They use the standard <emphasis
3845 role="bold">login</emphasis> program to login to the local
3846 file system, providing the password listed in the local
3847 password file (the <emphasis
3848 role="bold">/etc/passwd</emphasis> file or equivalent).</para>
3852 <para>They must issue the <emphasis
3853 role="bold">klog</emphasis> command to authenticate with the
3854 AFS authentication service, including its <emphasis
3855 role="bold">-setpag</emphasis> flag to associate the new
3856 tokens with a process authentication group (PAG).</para>
3861 <para>As mentioned in <link linkend="HDRWQ60">Creating Standard
3862 Files in New AFS Accounts</link>, you can invoke the <emphasis
3863 role="bold">klog -setpag</emphasis> command in a user's <emphasis
3864 role="bold">.login</emphasis> file (or equivalent) so that the user
3865 does not have to remember to issue the command after logging in. The
3866 user still must type a password twice, once at the prompt generated
3867 by the login utility and once at the <emphasis
3868 role="bold">klog</emphasis> command's prompt. This implies that the
3869 two passwords can differ, but it is less confusing if they do
3872 <para>Another effect of not using an AFS-modified login utility is
3873 that the AFS servers recognize the standard <emphasis
3874 role="bold">login</emphasis> program as the <emphasis
3875 role="bold">anonymous</emphasis> user. If the <emphasis
3876 role="bold">login</emphasis> program needs to access any AFS files
3877 (such as the <emphasis role="bold">.login</emphasis> file in a
3878 user's home directory), then the ACL that protects the file must
3879 include an entry granting the <emphasis role="bold">l</emphasis>
3880 (<emphasis role="bold">lookup</emphasis>) and <emphasis
3881 role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>)
3882 permissions to the <emphasis role="bold">system:anyuser</emphasis>
3885 <para>When you do not use an AFS-modified login utility, an actual
3886 (scrambled) password must appear in the local password file for each
3887 user. Use the <emphasis role="bold">/bin/passwd</emphasis> file to
3888 insert or change these passwords. It is simpler if the password in
3889 the local password file matches the AFS password, but it is not
3893 <primary>tokens</primary>
3895 <secondary>displaying for user</secondary>
3899 <primary>tokens</primary>
3901 <secondary>command</secondary>
3905 <primary>commands</primary>
3907 <secondary>tokens</secondary>
3911 <primary>listing</primary>
3913 <secondary>tokens held by issuer</secondary>
3917 <primary>commands</primary>
3919 <secondary>klog</secondary>
3923 <primary>klog command</primary>
3927 <primary>server process</primary>
3929 <secondary>creating ticket (tokens) for</secondary>
3933 <primary>tickets</primary>
3935 <secondary></secondary>
3941 <primary>tokens</primary>
3943 <secondary>creating for server process</secondary>
3947 <primary>authenticated identity</primary>
3949 <secondary>acquiring with klog command</secondary>
3953 <primary>unlog command</primary>
3957 <primary>commands</primary>
3959 <secondary>unlog</secondary>
3963 <primary>discarding</primary>
3965 <secondary>tokens</secondary>
3969 <primary>tokens</primary>
3971 <secondary>discarding with unlog command</secondary>
3975 <sect2 id="Header_81">
3976 <title>Obtaining, Displaying, and Discarding Tokens</title>
3978 <para>Once logged in, a user can obtain a token at any time with the
3979 <emphasis role="bold">klog</emphasis> command. If a valid token
3980 already exists, the new one overwrites it. If a PAG already exists,
3981 the new token is associated with it.</para>
3983 <para>By default, the <emphasis role="bold">klog</emphasis> command
3984 authenticates the issuer using the identity currently logged in to
3985 the local file system. To authenticate as a different identity, use
3986 the <emphasis role="bold">-principal</emphasis> argument. To obtain
3987 a token for a foreign cell, use the <emphasis
3988 role="bold">-cell</emphasis> argument (it can be combined with the
3989 <emphasis role="bold">-principal</emphasis> argument). See the
3990 OpenAFS User Guide and the entry for the <emphasis
3991 role="bold">klog</emphasis> command in the OpenAFS Administration
3994 <para>To discard either all tokens or the token for a particular
3995 cell, issue the <emphasis role="bold">unlog</emphasis> command. The
3996 command affects only the tokens associated with the current command
3997 shell. See the OpenAFS User Guideand the entry for the <emphasis
3998 role="bold">unlog</emphasis> command in the OpenAFS Administration
4001 <para>To display the tokens associated with the current command
4002 shell, issue the <emphasis role="bold">tokens</emphasis>
4003 command. The following examples illustrate its output in various
4006 <para>If the issuer is not authenticated in any cell:</para>
4009 % <emphasis role="bold">tokens</emphasis>
4010 Tokens held by the Cache Manager:
4014 <para>The following shows the output for a user with AFS UID 1000 in
4015 the Example Corporation cell:</para>
4018 % <emphasis role="bold">tokens</emphasis>
4019 Tokens held by the Cache Manager:
4020 User's (AFS ID 1000) tokens for afs@example.com [Expires Jun 2 10:00]
4024 <para>The following shows the output for a user who is authenticated
4025 in Example Corporation cell, the Example Organization cell and the
4026 Example Network cell. The user has different AFS UIDs in the three
4027 cells. Tokens for the last cell are expired:</para>
4030 % <emphasis role="bold">tokens</emphasis>
4031 Tokens held by the Cache Manager:
4032 User's (AFS ID 1000) tokens for afs@example.com [Expires Jun 2 10:00]
4033 User's (AFS ID 4286) tokens for afs@example.org [Expires Jun 3 1:34]
4034 User's (AFS ID 22) tokens for afs@example.net [>>Expired<<]
4038 <para>The Kerberos version of the <emphasis
4039 role="bold">tokens</emphasis> command (the <emphasis
4040 role="bold">tokens.krb</emphasis> command), also reports information
4041 on the ticket-granting ticket, including the ticket's owner, the
4042 ticket-granting service, and the expiration date, as in the
4043 following example. Also see <link linkend="HDRWQ70">Support for
4044 Kerberos Authentication</link>.</para>
4047 % <emphasis role="bold">tokens.krb</emphasis>
4048 Tokens held by the Cache Manager:
4049 User's (AFS ID 1000) tokens for afs@example.com [Expires Jun 2 10:00]
4050 User smith's tokens for krbtgt.EXAMPLE.COM@example.com [Expires Jun 2 10:00]
4055 <sect2 id="Header_82">
4056 <title>Setting Default Token Lifetimes for Users</title>
4059 <primary>tokens</primary>
4061 <secondary>setting default lifetimes for users</secondary>
4064 <para>The maximum lifetime of a user token is the smallest of the
4065 ticket lifetimes recorded in the following three Authentication
4066 Database entries. The <emphasis role="bold">kas examine</emphasis>
4067 command reports the lifetime as <computeroutput>Max ticket
4068 lifetime</computeroutput>. Administrators who have the
4069 <computeroutput>ADMIN</computeroutput> flag on their Authentication
4070 Database entry can use the <emphasis
4071 role="bold">-lifetime</emphasis> argument to the <emphasis
4072 role="bold">kas setfields</emphasis> command to set an entry's
4076 <para>The <emphasis role="bold">afs</emphasis> entry, which
4077 corresponds to the AFS server processes. The default is 100
4082 <para>The <emphasis role="bold">krbtgt</emphasis>.cellname
4083 entry, which corresponds to the ticket-granting ticket used
4084 internally in generating the token. The default is 720 hours
4089 <para>The entry for the user of the AFS-modified login utility
4090 or issuer of the <emphasis role="bold">klog</emphasis>
4091 command. The default is 25 hours for user entries created
4092 using the AFS 3.1 or later version of the Authentication
4093 Server, and 100 hours for user entries created using the AFS
4094 3.0 version of the Authentication Server. A user can use the
4095 <emphasis role="bold">kas examine</emphasis> command to
4096 display his or her own Authentication Database entry.</para>
4102 <para>An AFS-modified login utility always grants a token with a
4103 lifetime calculated from the previously described three
4104 values. When issuing the <emphasis role="bold">klog</emphasis>
4105 command, a user can request a lifetime shorter than the default by
4106 using the <emphasis role="bold">-lifetime</emphasis> argument. For
4107 further information, see the OpenAFS User Guide and the <emphasis
4108 role="bold">klog</emphasis> reference page in the OpenAFS
4109 Administration Reference.</para>
4113 <sect2 id="Header_83">
4114 <title>Changing Passwords</title>
4117 <primary>password</primary>
4119 <secondary>changing in AFS</secondary>
4123 <primary>kpasswd command</primary>
4127 <primary>commands</primary>
4129 <secondary>kpasswd</secondary>
4133 <primary>kas commands</primary>
4135 <secondary>setpassword</secondary>
4139 <primary>commands</primary>
4141 <secondary>kas setpassword</secondary>
4144 <para>Regular AFS users can change their own passwords by using
4145 either the <emphasis role="bold">kpasswd</emphasis> or <emphasis
4146 role="bold">kas setpassword</emphasis> command. The commands prompt
4147 for the current password and then twice for the new password, to
4148 screen out typing errors.</para>
4150 <para>Administrators who have the
4151 <computeroutput>ADMIN</computeroutput> flag on their Authentication
4152 Database entries can change any user's password, either by using the
4153 <emphasis role="bold">kpasswd</emphasis> command (which requires
4154 knowing the current password) or the <emphasis role="bold">kas
4155 setpassword</emphasis> command.</para>
4157 <para>If your cell does not use an AFS-modified login utility,
4158 remember also to change the local password, using the operating
4159 system's password-changing command. For more instructions on
4160 changing passwords, see <link linkend="HDRWQ516">Changing AFS
4161 Passwords</link>.</para>
4164 <sect2 id="Header_84">
4165 <title>Imposing Restrictions on Passwords and Authentication
4168 <para>You can help to make your cell more secure by imposing
4169 restrictions on user passwords and authentication attempts. To
4170 impose the restrictions as you create an account, use the <emphasis
4171 role="bold">A</emphasis> instruction in the <emphasis
4172 role="bold">uss</emphasis> template file as described in <link
4173 linkend="HDRWQ478">Increasing Account Security with the A
4174 Instruction</link>. To set or change the values on an existing
4175 account, use the <emphasis role="bold">kas setfields</emphasis>
4176 command as described in <link linkend="HDRWQ515">Improving Password
4177 and Authentication Security</link>.</para>
4180 <primary>password</primary>
4182 <secondary>expiration</secondary>
4186 <primary>password</primary>
4188 <secondary>lifetime</secondary>
4192 <primary>kas commands</primary>
4194 <secondary>setfields</secondary>
4198 <primary>commands</primary>
4200 <secondary>kas setfields</secondary>
4204 <primary>Authentication Database</primary>
4206 <secondary>password lifetime, setting</secondary>
4210 <primary>password</primary>
4212 <secondary>restricting reuse</secondary>
4215 <para>By default, AFS passwords never expire. Limiting password
4216 lifetime can help improve security by decreasing the time the
4217 password is subject to cracking attempts. You can choose an lifetime
4218 from 1 to 254 days after the password was last changed. It
4219 automatically applies to each new password as it is set. When the
4220 user changes passwords, you can also insist that the new password is
4221 not similar to any of the 20 passwords previously used.</para>
4224 <primary>password</primary>
4226 <secondary>consequences of multiple failed authentication
4227 attempts</secondary>
4231 <primary>kas commands</primary>
4233 <secondary>setfields</secondary>
4237 <primary>commands</primary>
4239 <secondary>kas setfields</secondary>
4243 <primary>authentication</primary>
4245 <secondary>consequences of multiple failures</secondary>
4248 <para>Unscrupulous users can try to gain access to your AFS cell by
4249 guessing an authorized user's password. To protect against this type
4250 of attack, you can limit the number of times that a user can
4251 consecutively fail to provide the correct password. When the limit
4252 is exceeded, the authentication service refuses further
4253 authentication attempts for a specified period of time (the lockout
4254 time). To reenable authentication attempts before the lockout time
4255 expires, an administrator must issue the <emphasis role="bold">kas
4256 unlock</emphasis> command.</para>
4259 <primary>password</primary>
4261 <secondary>checking quality of</secondary>
4265 <primary>kpasswd command</primary>
4269 <primary>commands</primary>
4271 <secondary>kpasswd</secondary>
4275 <primary>kas commands</primary>
4277 <secondary>setpassword</secondary>
4281 <primary>kpwvalid program</primary>
4284 <para>In addition to settings on user's authentication accounts, you
4285 can improve security by automatically checking the quality of new
4286 user passwords. The <emphasis role="bold">kpasswd</emphasis> and
4287 <emphasis role="bold">kas setpassword</emphasis> commands pass the
4288 proposed password to a program or script called <emphasis
4289 role="bold">kpwvalid</emphasis>, if it exists. The <emphasis
4290 role="bold">kpwvalid</emphasis> performs quality checks and returns
4291 a code to indicate whether the password is acceptable. You can
4292 create your own program or modified the sample program included in
4293 the AFS distribution. See the <emphasis
4294 role="bold">kpwvalid</emphasis> reference page in the OpenAFS
4295 Administration Reference.</para>
4297 <para>There are several types of quality checks that can improve
4301 <para>The password is a minimum length</para>
4305 <para>The password is not a word</para>
4309 <para>The password contains both numbers and letters</para>
4315 <sect2 id="HDRWQ70">
4316 <title>Support for Kerberos Authentication</title>
4319 <primary>Kerberos</primary>
4321 <secondary>support for in AFS</secondary>
4325 <primary>commands</primary>
4327 <secondary>klog.krb</secondary>
4331 <primary>commands</primary>
4333 <secondary>pagsh.krb</secondary>
4337 <primary>commands</primary>
4339 <secondary>tokens.krb</secondary>
4343 <primary>klog.krb command</primary>
4347 <primary>pagsh.krb command</primary>
4351 <primary>tokens.krb command</primary>
4354 <para>If your site is using standard Kerberos authentication rather
4355 than the AFS Authentication Server, use the modified versions of the
4356 <emphasis role="bold">klog</emphasis>, <emphasis
4357 role="bold">pagsh</emphasis>, and <emphasis
4358 role="bold">tokens</emphasis> commands that support Kerberos
4359 authentication. The binaries for the modified version of these
4360 commands have the same name as the standard binaries with the
4361 addition of a <emphasis role="bold">.krb</emphasis>
4364 <para>Use either the Kerberos version or the standard command
4365 throughout the cell; do not mix the two versions. AFS Product
4366 Support can provide instructions on installing the Kerberos version
4367 of these four commands. For information on the differences between
4368 the two versions of these commands, see the OpenAFS Administration
4372 <sect1 id="HDRWQ71">
4373 <title>Security and Authorization in AFS</title>
4375 <para>AFS incorporates several features to ensure that only authorized
4376 users gain access to data. This section summarizes the most important
4377 of them and suggests methods for improving security in your
4380 <sect2 id="HDRWQ72">
4381 <title>Some Important Security Features</title>
4384 <primary>security</primary>
4386 <secondary>AFS features</secondary>
4390 <primary>AFS</primary>
4392 <secondary>security features</secondary>
4396 <title>ACLs on Directories</title>
4398 <para>Files in AFS are protected by the access control list (ACL)
4399 associated with their parent directory. The ACL defines which
4400 users or groups can access the data in the directory, and in what
4401 way. See <link linkend="HDRWQ562">Managing Access Control
4402 Lists</link>.</para>
4406 <title>Mutual Authentication Between Client and Server</title>
4408 <para>When an AFS client and server process communicate, each
4409 requires the other to prove its identity during mutual
4410 authentication, which involves the exchange of encrypted
4411 information that only valid parties can decrypt and respond
4412 to. For a detailed description of the mutual authentication
4413 process, see <link linkend="HDRWQ75">A More Detailed Look at
4414 Mutual Authentication</link>.</para>
4417 <para>AFS server processes mutually authenticate both with one
4418 another and with processes that represent human users. After mutual
4419 authentication is complete, the server and client have established
4420 an authenticated connection, across which they can communicate
4421 repeatedly without having to authenticate again until the connection
4422 expires or one of the parties closes it. Authenticated connections
4423 have varying lifetimes.</para>
4426 <title>Tokens</title>
4428 <para>In order to access AFS files, users must prove their
4429 identities to the AFS authentication service by providing the
4430 correct AFS password. If the password is correct, the
4431 authentication service sends the user a token as evidence of
4432 authenticated status. See <link linkend="HDRWQ63">Login and
4433 Authentication in AFS</link>.</para>
4436 <para>Servers assign the user identity <emphasis
4437 role="bold">anonymous</emphasis> to users and processes that do not
4438 have a valid token. The <emphasis role="bold">anonymous</emphasis>
4439 identity has only the access granted to the <emphasis
4440 role="bold">system:anyuser</emphasis> group on ACLs.</para>
4443 <title>Authorization Checking</title>
4445 <para>Mutual authentication establishes that two parties
4446 communicating with one another are actually who they claim to be.
4447 For many functions, AFS server processes also check that the
4448 client whose identity they have verified is also authorized to
4449 make the request. Different requests require different kinds of
4450 privilege. See <link linkend="HDRWQ73">Three Types of
4451 Privilege</link>.</para>
4455 <title>Encrypted Network Communications</title>
4458 <primary>network</primary>
4460 <secondary>encrypted communication in AFS</secondary>
4464 <primary>encrypted network communication</primary>
4468 <primary>security</primary>
4470 <secondary>encrypted network communication</secondary>
4473 <para>The AFS server processes encrypt particularly sensitive
4474 information before sending it back to clients. Even if an
4475 unauthorized party is able to eavesdrop on an authenticated
4476 connection, they cannot decipher encrypted data without the proper
4480 <para>The following AFS commands encrypt data because they involve
4481 server encryption keys and passwords:
4484 <para>The <emphasis role="bold">bos addkey</emphasis> command,
4485 which adds a server encryption key to the <emphasis
4486 role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
4490 <para>The <emphasis role="bold">bos listkeys</emphasis>
4491 command, which lists the server encryption keys from the
4492 <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis>
4497 <para>The <emphasis role="bold">kpasswd</emphasis> command,
4498 which changes a password in the Authentication Database</para>
4502 <para>Most commands in the <emphasis
4503 role="bold">kas</emphasis> command suite</para>
4508 <para>In addition, the United States edition of the Update Server
4509 encrypts sensitive information (such as the contents of <emphasis
4510 role="bold">KeyFile</emphasis>) when distributing it. Other commands
4511 in the <emphasis role="bold">bos</emphasis> suite and the commands
4512 in the <emphasis role="bold">fs</emphasis>, <emphasis
4513 role="bold">pts</emphasis> and <emphasis role="bold">vos</emphasis>
4514 suites do not encrypt data before transmitting it.</para>
4517 <sect2 id="HDRWQ73">
4518 <title>Three Types of Privilege</title>
4520 <para>AFS uses three separate types of privilege for the reasons
4521 discussed in <link linkend="HDRWQ585">The Reason for Separate
4525 <para>Membership in the <emphasis
4526 role="bold">system:administrators</emphasis> group. Members
4527 are entitled to issue any <emphasis role="bold">pts</emphasis>
4528 command and those <emphasis role="bold">fs</emphasis> commands
4529 that set volume quota. By default, they also implicitly have
4530 the <emphasis role="bold">a</emphasis> (<emphasis
4531 role="bold">administer</emphasis>) and <emphasis
4532 role="bold">l</emphasis> (<emphasis
4533 role="bold">lookup</emphasis>) permissions on every ACL in the
4534 file tree even if the ACL does not include an entry for
4539 <para>The <computeroutput>ADMIN</computeroutput> flag on the
4540 Authentication Database entry. An administrator with this flag
4541 can issue any <emphasis role="bold">kas</emphasis>
4546 <para>Inclusion in the <emphasis
4547 role="bold">/usr/afs/etc/UserList</emphasis> file. An
4548 administrator whose username appears in this file can issue
4549 any <emphasis role="bold">bos</emphasis>, <emphasis
4550 role="bold">vos</emphasis>, or <emphasis
4551 role="bold">backup</emphasis> command (although some <emphasis
4552 role="bold">backup</emphasis> commands require additional
4553 privilege as described in <link linkend="HDRWQ260">Granting
4554 Administrative Privilege to Backup Operators</link>).</para>
4560 <sect2 id="Header_89">
4561 <title>Authorization Checking versus Authentication</title>
4563 <para>AFS distinguishes between authentication and authorization
4564 checking. Authentication refers to the process of proving
4565 identity. Authorization checking refers to the process of verifying
4566 that an authenticated identity is allowed to perform a certain
4569 <para>AFS implements authentication at the level of
4570 connections. Each time two parties establish a new connection, they
4571 mutually authenticate. In general, each issue of an AFS command
4572 establishes a new connection between AFS server process and
4575 <para>AFS implements authorization checking at the level of server
4576 machines. If authorization checking is enabled on a server machine,
4577 then all of the server processes running on it provide services only
4578 to authorized users. If authorization checking is disabled on a
4579 server machine, then all of the server processes perform any action
4580 for anyone. Obviously, disabling authorization checking is an
4581 extreme security exposure. For more information, see <link
4582 linkend="HDRWQ123">Managing Authentication and Authorization
4583 Requirements</link>.</para>
4586 <sect2 id="HDRWQ74">
4587 <title>Improving Security in Your Cell</title>
4590 <primary>security</primary>
4592 <secondary>suggestions for improving</secondary>
4595 <para>You can improve the level of security in your cell by
4596 configuring user accounts, server machines, and system administrator
4597 accounts in the indicated way.</para>
4600 <title>User Accounts</title>
4605 <para>Use an AFS-modified login utility, or include the
4606 <emphasis role="bold">-setpag</emphasis> flag to the
4607 <emphasis role="bold">klog</emphasis> command, to associate
4608 the credential structure that houses tokens with a PAG
4609 rather than a UNIX UID. This prevents users from inheriting
4610 someone else's tokens by assuming their UNIX identity. For
4611 further discussion, see <link linkend="HDRWQ64">Identifying
4612 AFS Tokens by PAG</link>.</para>
4616 <para>Encourage users to issue the <emphasis
4617 role="bold">unlog</emphasis> command to destroy their tokens
4618 before logging out. This forestalls attempts to access
4619 tokens left behind kernel memory. Consider including the
4620 <emphasis role="bold">unlog</emphasis> command in every
4621 user's <emphasis role="bold">.logout</emphasis> file or
4629 <title>Server Machines</title>
4634 <para>Disable authorization checking only in emergencies or
4635 for very brief periods of time. It is best to work at the
4636 console of the affected machine during this time, to prevent
4637 anyone else from accessing the machine through the
4642 <para>Change the AFS server encryption key on a frequent and
4643 regular schedule. Make it difficult to guess (a long string
4644 including nonalphabetic characters, for instance). Unlike
4645 user passwords, the password from which the AFS key is
4646 derived can be longer than eight characters, because it is
4647 never used during login. The <emphasis role="bold">kas
4648 setpassword</emphasis> command accepts a password hundreds
4649 of characters long. For instructions, see <link
4650 linkend="HDRWQ355">Managing Server Encryption
4655 <para>As much as possible, limit the number of people who
4656 can login at a server machine's console or remotely.
4657 Imposing this limit is an extra security precaution rather
4658 than a necessity. The machine cannot serve as an AFS client
4659 in this case.</para>
4663 <para>Particularly limit access to the local superuser
4664 <emphasis role="bold">root</emphasis> account on a server
4665 machine. The local superuser <emphasis
4666 role="bold">root</emphasis> has free access to important
4667 administrative subdirectories of the <emphasis
4668 role="bold">/usr/afs</emphasis> directory, as described in
4669 <link linkend="HDRWQ53">AFS Files on the Local
4673 <primary>root superuser</primary>
4675 <secondary>limiting logins</secondary>
4680 <para>As in any computing environment, server machines must
4681 be located in a secured area. Any other security measures
4682 are effectively worthless if unauthorized people can access
4683 the computer hardware.</para>
4690 <title>System Administrators</title>
4695 <para>Limit the number of system administrators in your
4696 cell. Limit the use of system administrator accounts on
4697 publicly accessible workstations. Such machines are not
4698 secure, so unscrupulous users can install programs that try
4699 to steal tokens or passwords. If administrators must use
4700 publicly accessible workstations at times, they must issue
4701 the <emphasis role="bold">unlog</emphasis> command before
4702 leaving the machine.</para>
4706 <para>Create an administrative account for each
4707 administrator separate from the personal account, and assign
4708 AFS privileges only to the administrative account. The
4709 administrators must authenticate to the administrative
4710 accounts to perform duties that require privilege, which
4711 provides a useful audit trail as well.</para>
4715 <para>Administrators must not leave a machine unattended
4716 while they have valid tokens. Issue the <emphasis
4717 role="bold">unlog</emphasis> command before leaving.</para>
4721 <para>Use the <emphasis role="bold">-lifetime</emphasis>
4722 argument to the <emphasis role="bold">kas
4723 setfields</emphasis> command to set the token lifetime for
4724 administrative accounts to a fairly short amount of time.
4725 The default lifetime for AFS tokens is 25 hours, but 30 or
4726 60 minutes is possibly a more reasonable lifetime for
4727 administrative tokens. The tokens for administrators who
4728 initiate AFS Backup System operations must last somewhat
4729 longer, because it can take several hours to complete some
4730 dump operations, depending on the speed of the tape device
4731 and the network connecting it to the file server machines
4732 that house the volumes is it accessing.</para>
4736 <para>Limit administrators' use of the <emphasis
4737 role="bold">telnet</emphasis> program. It sends unencrypted
4738 passwords across the network. Similarly, limit use of other
4739 remote programs such as <emphasis role="bold">rsh</emphasis>
4740 and <emphasis role="bold">rcp</emphasis>, which send
4741 unencrypted tokens across the network.</para>
4748 <sect2 id="HDRWQ75">
4749 <title>A More Detailed Look at Mutual Authentication</title>
4752 <primary>mutual authentication</primary>
4756 <primary>distributed file system</primary>
4758 <secondary>security issues</secondary>
4762 <primary>shared secret</primary>
4766 <primary>server encryption key</primary>
4768 <secondary>defined</secondary>
4771 <para>As in any file system, security is a prime concern in AFS. A
4772 file system that makes file sharing easy is not useful if it makes
4773 file sharing mandatory, so AFS incorporates several features that
4774 prevent unauthorized users from accessing data. Security in a
4775 networked environment is difficult because almost all procedures
4776 require transmission of information across wires that almost anyone
4777 can tap into. Also, many machines on networks are powerful enough
4778 that unscrupulous users can monitor transactions or even intercept
4779 transmissions and fake the identity of one of the
4780 participants.</para>
4782 <para>The most effective precaution against eavesdropping and
4783 information theft or fakery is for servers and clients to accept the
4784 claimed identity of the other party only with sufficient proof. In
4785 other words, the nature of the network forces all parties on the
4786 network to assume that the other party in a transaction is not
4787 genuine until proven so. Mutual authentication is the means through
4788 which parties prove their genuineness.</para>
4790 <para>Because the measures needed to prevent fakery must be quite
4791 sophisticated, the implementation of mutual authentication
4792 procedures is complex. The underlying concept is simple, however:
4793 parties prove their identities by demonstrating knowledge of a
4794 shared secret. A shared secret is a piece of information known only
4795 to the parties who are mutually authenticating (they can sometimes
4796 learn it in the first place from a trusted third party or some other
4797 source). The party who originates the transaction presents the
4798 shared secret and refuses to accept the other party as valid until
4799 it shows that it knows the secret too.</para>
4801 <para>The most common form of shared secret in AFS transactions is
4802 the encryption key, also referred to simply as a key. The two
4803 parties use their shared key to encrypt the packets of information
4804 they send and to decrypt the ones they receive. Encryption using
4805 keys actually serves two related purposes. First, it protects
4806 messages as they cross the network, preventing anyone who does not
4807 know the key from eavesdropping. Second, ability to encrypt and
4808 decrypt messages successfully indicates that the parties are using
4809 the key (it is their shared secret). If they are using different
4810 keys, messages remain scrambled and unintelligible after
4813 <para>The following sections describe AFS's mutual authentication
4814 procedures in more detail. Feel free to skip these sections if you
4815 are not interested in the mutual authentication process.</para>
4817 <sect3 id="Header_92">
4818 <title>Simple Mutual Authentication</title>
4820 <para>Simple mutual authentication involves only one encryption
4821 key and two parties, generally a client and server. The client
4822 contacts the server by sending a challenge message encrypted with
4823 a key known only to the two of them. The server decrypts the
4824 message using its key, which is the same as the client's if they
4825 really do share the same secret. The server responds to the
4826 challenge and uses its key to encrypt its response. The client
4827 uses its key to decrypt the server's response, and if it is
4828 correct, then the client can be sure that the server is genuine:
4829 only someone who knows the same key as the client can decrypt the
4830 challenge and answer it correctly. On its side, the server
4831 concludes that the client is genuine because the challenge message
4832 made sense when the server decrypted it.</para>
4834 <para>AFS uses simple mutual authentication to verify user
4835 identities during the first part of the login procedure. In that
4836 case, the key is based on the user's password.</para>
4839 <sect3 id="HDRWQ76">
4840 <title>Complex Mutual Authentication</title>
4842 <para>Complex mutual authentication involves three encryption keys
4843 and three parties. All secure AFS transactions (except the first
4844 part of the login process) employ complex mutual
4845 authentication.</para>
4848 <primary>ticket-granter</primary>
4852 <primary>server encryption key</primary>
4856 <primary>tokens</primary>
4858 <secondary>data in</secondary>
4861 <para>When a client wishes to communicate with a server, it first
4862 contacts a third party called a ticket-granter. The ticket-granter
4863 and the client mutually authenticate using the simple
4864 procedure. When they finish, the ticket-granter gives the client a
4865 server ticket (or simply ticket) as proof that it (the
4866 ticket-granter) has preverified the identity of the client. The
4867 ticket-granter encrypts the ticket with the first of the three
4868 keys, called the server encryption key because it is known only to
4869 the ticket-granter and the server the client wants to contact. The
4870 client does not know this key.</para>
4872 <para>The ticket-granter sends several other pieces of information
4873 along with the ticket. They enable the client to use the ticket
4874 effectively despite being unable to decrypt the ticket
4875 itself. Along with the ticket, the items constitute a token:
4878 <para>A session key, which is the second encryption key
4879 involved in mutual authentication. The ticket-granter
4880 invents the session key at random as the shared secret
4881 between client and server. For reasons explained further
4882 below, the ticket-granter also puts a copy of the session
4883 key inside the ticket. The client and server use the session
4884 key to encrypt messages they send to one another during
4885 their transactions. The ticket-granter invents a different
4886 session key for each connection between a client and a
4887 server (there can be several transactions during a single
4891 <primary>session key</primary>
4896 <para>The name of the server for which the ticket is valid
4897 (and so which server encryption key encrypts the ticket
4902 <para>A ticket lifetime indicator. The default lifetime of
4903 AFS server tickets is 100 hours. If the client wants to
4904 contact the server again after the ticket expires, it must
4905 contact the ticket-granter to get a new ticket.</para>
4910 <para>The ticket-granter seals the entire token with the third key
4911 involved in complex mutual authentication--the key known only to
4912 it (the ticket-granter) and the client. In some cases, this third
4913 key is derived from the password of the human user whom the client
4916 <para>Now that the client has a valid server ticket, it is ready
4917 to contact the server. It sends the server two things:
4920 <para>The server ticket. This is encrypted with the server
4921 encryption key.</para>
4925 <para>Its request message, encrypted with the session
4926 key. Encrypting the message protects it as it crosses the
4927 network, since only the server/client pair for whom the
4928 ticket-granter invented the session key know it.</para>
4933 <para>At this point, the server does not know the session key,
4934 because the ticket-granter just created it. However, the
4935 ticket-granter put a copy of the session key inside the
4936 ticket. The server uses the server encryption key to decrypts the
4937 ticket and learns the session key. It then uses the session key to
4938 decrypt the client's request message. It generates a response and
4939 sends it to the client. It encrypts the response with the session
4940 key to protect it as it crosses the network.</para>
4942 <para>This step is the heart of mutual authentication between
4943 client and server, because it proves to both parties that they
4944 know the same secret:
4947 <para>The server concludes that the client is authorized to
4948 make a request because the request message makes sense when
4949 the server decrypts it using the session key. If the client
4950 uses a different session key than the one the server finds
4951 inside the ticket, then the request message remains
4952 unintelligible even after decryption. The two copies of the
4953 session key (the one inside the ticket and the one the
4954 client used) can only be the same if they both came from the
4955 ticket-granter. The client cannot fake knowledge of the
4956 session key because it cannot look inside the ticket, sealed
4957 as it is with the server encryption key known only to the
4958 server and the ticket-granter. The server trusts the
4959 ticket-granter to give tokens only to clients with whom it
4960 (the ticket-granter) has authenticated, so the server
4961 decides the client is legitimate.</para>
4963 <para>(Note that there is no direct communication between
4964 the ticket-granter and the server, even though their
4965 relationship is central to ticket-based mutual
4966 authentication. They interact only indirectly, via the
4967 client's possession of a ticket sealed with their shared
4972 <para>The client concludes that the server is genuine and
4973 trusts the response it gets back from the server, because
4974 the response makes sense after the client decrypts it using
4975 the session key. This indicates that the server encrypted
4976 the response with the same session key as the client
4977 knows. The only way for the server to learn that matching
4978 session key is to decrypt the ticket first. The server can
4979 only decrypt the ticket because it shares the secret of the
4980 server encryption key with the ticket-granter. The client
4981 trusts the ticket-granter to give out tickets only for
4982 legitimate servers, so the client accepts a server that can
4983 decrypt the ticket as genuine, and accepts its
4992 <sect1 id="HDRWQ77">
4993 <title>Backing Up AFS Data</title>
4995 <para>AFS provides two related facilities that help the administrator
4996 back up AFS data: backup volumes and the AFS Backup System.</para>
4998 <sect2 id="Header_95">
4999 <title>Backup Volumes</title>
5001 <para>The first facility is the backup volume, which you create by
5002 cloning a read/write volume. The backup volume is read-only and so
5003 preserves the state of the read/write volume at the time the clone
5006 <para>Backup volumes can ease administration if you mount them in
5007 the file system and make their contents available to users. For
5008 example, it often makes sense to mount the backup version of each
5009 user volume as a subdirectory of the user's home directory. A
5010 conventional name for this mount point is <emphasis
5011 role="bold">OldFiles</emphasis>. Create a new version of the backup
5012 volume (that is, reclone the read/write) once a day to capture any
5013 changes that were made since the previous backup. If a user
5014 accidentally removes or changes data, the user can restore it from
5015 the backup volume, rather than having to ask you to restore
5018 <para>The OpenAFS User Guide does not mention backup volumes, so
5019 regular users do not know about them if you decide not to use
5020 them. This implies that if you <emphasis role="bold">do</emphasis>
5021 make backup versions of user volumes, you need to tell your users
5022 about how the backup works and where you have mounted it.</para>
5024 <para>Users are often concerned that the data in a backup volume
5025 counts against their volume quota and some of them even want to
5026 remove the <emphasis role="bold">OldFiles</emphasis> mount point. It
5027 does not, because the backup volume is a separate volume. The only
5028 amount of space it uses in the user's volume is the amount needed
5029 for the mount point, which is about the same as the amount needed
5030 for a standard directory element.</para>
5032 <para>Backup volumes are discussed in detail in <link
5033 linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
5036 <sect2 id="Header_96">
5037 <title>The AFS Backup System</title>
5039 <para>Backup volumes can reduce restoration requests, but they
5040 reside on disk and so do not protect data from loss due to hardware
5041 failure. Like any file system, AFS is vulnerable to this sort of
5044 <para>To protect your cell's users from permanent loss of data, you
5045 are strongly urged to back up your file system to tape on a regular
5046 and frequent schedule. The AFS Backup System is available to ease
5047 the administration and performance of backups. For detailed
5048 information about the AFS Backup System, see <link
5049 linkend="HDRWQ248">Configuring the AFS Backup System</link> and
5050 <link linkend="HDRWQ283">Backing Up and Restoring AFS
5055 <sect1 id="HDRWQ79">
5056 <title>Accessing AFS through NFS</title>
5058 <para>Users of NFS client machines can access the AFS filespace by
5059 mounting the <emphasis role="bold">/afs</emphasis> directory of an AFS
5060 client machine that is running the NFS/AFS Translator. This is a
5061 particular advantage in cells already running NFS who want to access
5062 AFS using client machines for which AFS is not available. See <link
5063 linkend="HDRWQ595">Appendix A, Managing the NFS/AFS
5064 Translator</link>.</para>
git://git.openafs.org / openafs.git / blob