<?xml version="1.0" encoding="UTF-8"?>
+
<chapter id="HDRWQ29">
<title>Issues in Cell Configuration and Administration</title>
- <para>This chapter discusses many of the issues to consider when configuring and administering a cell, and directs you to detailed
- related information available elsewhere in this guide. It is assumed you are already familiar with the material in <link
- linkend="HDRWQ5">An Overview of OpenAFS Administration</link>.</para>
+ <para>This chapter discusses many of the issues to consider when
+ configuring and administering a cell, and directs you to detailed
+ related information available elsewhere in this guide. It is assumed you
+ are already familiar with the material in <link linkend="HDRWQ5">An
+ Overview of OpenAFS Administration</link>.</para>
- <para>It is best to read this chapter before installing your cell's first file server machine or performing any other
- administrative task.</para>
+ <para>It is best to read this chapter before installing your cell's
+ first file server machine or performing any other administrative
+ task.</para>
<indexterm>
<primary>AFS</primary>
<sect1 id="HDRWQ30">
<title>Differences between AFS and UNIX: A Summary</title>
- <para>AFS behaves like a standard UNIX file system in most respects, while also making file sharing easy within and between
- cells. This section describes some differences between AFS and the UNIX file system, referring you to more detailed information
- as appropriate.</para>
+ <para>AFS behaves like a standard UNIX file system in most respects,
+ while also making file sharing easy within and between cells. This
+ section describes some differences between AFS and the UNIX file
+ system, referring you to more detailed information as
+ appropriate.</para>
<indexterm>
<primary>protection</primary>
<sect2 id="Header_35">
<title>Differences in File and Directory Protection</title>
- <para>AFS augments the standard UNIX file protection mechanism in two ways: it associates an <emphasis>access control list
- (ACL)</emphasis> with each directory, and it enables users to define a large number of their own groups, which can be placed
- on ACLs.</para>
+ <para>AFS augments the standard UNIX file protection mechanism in
+ two ways: it associates an <emphasis>access control list
+ (ACL)</emphasis> with each directory, and it enables users to define
+ a large number of their own groups, which can be placed on
+ ACLs.</para>
- <para>AFS uses ACLs to protect files and directories, rather than relying exclusively on the mode bits. This has several
- implications, which are discussed further in the indicated sections: <itemizedlist>
+ <para>AFS uses ACLs to protect files and directories, rather than
+ relying exclusively on the mode bits. This has several implications,
+ which are discussed further in the indicated sections:
+ <itemizedlist>
<listitem>
- <para>AFS ACLs use seven access permissions rather than the three UNIX mode bits. See <link linkend="HDRWQ567">The AFS
- ACL Permissions</link>.</para>
+ <para>AFS ACLs use seven access permissions rather than the
+ three UNIX mode bits. See <link linkend="HDRWQ567">The AFS ACL
+ Permissions</link>.</para>
</listitem>
<listitem>
- <para>For directories, AFS ignores the UNIX mode bits. For files, AFS uses only the first set of mode bits (the
- <emphasis role="bold">owner</emphasis> bits) , and their meaning interacts with permissions on the directory's ACL. See
- <link linkend="HDRWQ580">How AFS Interprets the UNIX Mode Bits</link>.</para>
+ <para>For directories, AFS ignores the UNIX mode bits. For
+ files, AFS uses only the first set of mode bits (the <emphasis
+ role="bold">owner</emphasis> bits) , and their meaning
+ interacts with permissions on the directory's ACL. See <link
+ linkend="HDRWQ580">How AFS Interprets the UNIX Mode
+ Bits</link>.</para>
</listitem>
<listitem>
- <para>A directory's ACL protects all of the files in a directory in the same manner. To apply a more restrictive set of
- AFS permissions to certain file, place it in directory with a different ACL.</para>
+ <para>A directory's ACL protects all of the files in a
+ directory in the same manner. To apply a more restrictive set
+ of AFS permissions to certain file, place it in directory with
+ a different ACL.</para>
</listitem>
<listitem>
- <para>Moving a file to a different directory changes its protection. See <link linkend="HDRWQ566">Differences Between
+ <para>Moving a file to a different directory changes its
+ protection. See <link linkend="HDRWQ566">Differences Between
UFS and AFS Data Protection</link>.</para>
</listitem>
<listitem>
- <para>An ACL can include about 20 entries granting different combinations of permissions to different users or groups,
- rather than only the three UNIX entities represented by the three sets of mode bits. See <link
- linkend="HDRWQ566">Differences Between UFS and AFS Data Protection</link>.</para>
+ <para>An ACL can include about 20 entries granting different
+ combinations of permissions to different users or groups,
+ rather than only the three UNIX entities represented by the
+ three sets of mode bits. See <link
+ linkend="HDRWQ566">Differences Between UFS and AFS Data
+ Protection</link>.</para>
</listitem>
<listitem>
- <para>You can designate an AFS file as write-only as in the UNIX file system, by setting only the <emphasis
- role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit. You cannot designate an AFS directory as
- write-only, because AFS ignores the mode bits on a directory. See <link linkend="HDRWQ580">How AFS Interprets the UNIX
- Mode Bits</link>.</para>
+ <para>You can designate an AFS file as write-only as in the
+ UNIX file system, by setting only the <emphasis
+ role="bold">w</emphasis> (<emphasis
+ role="bold">write</emphasis>) mode bit. You cannot designate
+ an AFS directory as write-only, because AFS ignores the mode
+ bits on a directory. See <link linkend="HDRWQ580">How AFS
+ Interprets the UNIX Mode Bits</link>.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>AFS enables users to define the groups of other users. Placing these groups on ACLs extends the same permissions to a
- number of exactly specified users at the same time, which is much more convenient than placing the individuals on the ACLs
- directly. See <link linkend="HDRWQ531">Administering the Protection Database</link>.</para>
+ <para>AFS enables users to define the groups of other users. Placing
+ these groups on ACLs extends the same permissions to a number of
+ exactly specified users at the same time, which is much more
+ convenient than placing the individuals on the ACLs directly. See
+ <link linkend="HDRWQ531">Administering the Protection
+ Database</link>.</para>
- <para>There are also system-defined groups, <emphasis role="bold">system:anyuser</emphasis> and <emphasis
- role="bold">system:authuser</emphasis>, whose presence on an ACL extends access to a wide range of users at once. See <link
- linkend="HDRWQ535">The System Groups</link> and <link linkend="HDRWQ571">Using Groups on ACLs</link>.</para>
+ <para>There are also system-defined groups, <emphasis
+ role="bold">system:anyuser</emphasis> and <emphasis
+ role="bold">system:authuser</emphasis>, whose presence on an ACL
+ extends access to a wide range of users at once. See <link
+ linkend="HDRWQ535">The System Groups</link> and <link
+ linkend="HDRWQ571">Using Groups on ACLs</link>.</para>
<indexterm>
<primary>authentication</primary>
<sect2 id="HDRWQ31">
<title>Differences in Authentication</title>
- <para>Just as the AFS filespace is distinct from each machine's local file system, AFS authentication is separate from local
- login. This has two practical implications, which are discussed further in <link linkend="HDRWQ65">Using an AFS-modified login
+ <para>Just as the AFS filespace is distinct from each machine's
+ local file system, AFS authentication is separate from local
+ login. This has two practical implications, which are discussed
+ further in <link linkend="HDRWQ65">Using an AFS-modified login
Utility</link>. <itemizedlist>
<listitem>
- <para>To access AFS files, users must both log into the local machine's UNIX file system and authenticate with the AFS
- authentication service. (Logging into the local UNIX file system is necessary because the AFS filespace is accessed
- through the Cache Manager, which resides in the local machine's kernel.)</para>
-
- <para>AFS provides a modified login utility for each system type that accomplishes both local login and AFS
- authentication in one step, based on a single password. If you choose not to use the AFS-modified login utility, your
- users must login and authenticate in separate steps, as detailed in the <emphasis>OpenAFS User Guide</emphasis>.</para>
+ <para>To access AFS files, users must both log into the local
+ machine's UNIX file system and authenticate with the AFS
+ authentication service. (Logging into the local UNIX file
+ system is necessary because the AFS filespace is accessed
+ through the Cache Manager, which resides in the local
+ machine's kernel.)</para>
+
+ <para>AFS provides a modified login utility for each system
+ type that accomplishes both local login and AFS authentication
+ in one step, based on a single password. If you choose not to
+ use the AFS-modified login utility, your users must login and
+ authenticate in separate steps, as detailed in the
+ <emphasis>OpenAFS User Guide</emphasis>.</para>
</listitem>
<listitem>
- <para>Passwords may be stored in two separate places: the Kerberos Server and, optionally, each machine's local password
- file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) for the UNIX file system. A user's passwords in the
- two places can differ if desired, though the resulting behavior depends on whether and how the cell is using an
+ <para>Passwords may be stored in two separate places: the
+ Kerberos Server and, optionally, each machine's local password
+ file (<emphasis role="bold">/etc/passwd</emphasis> or
+ equivalent) for the UNIX file system. A user's passwords in
+ the two places can differ if desired, though the resulting
+ behavior depends on whether and how the cell is using an
AFS-modified login utility.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</sect2>
<sect2 id="Header_37">
- <title>Differences in the Semantics of Standard UNIX Commands</title>
+ <title>Differences in the Semantics of Standard UNIX
+ Commands</title>
- <para>This section summarizes how AFS modifies the functionality of some UNIX commands. <variablelist>
+ <para>This section summarizes how AFS modifies the functionality of
+ some UNIX commands. <variablelist>
<indexterm>
<primary>chmod command</primary>
</indexterm>
<varlistentry>
- <term><emphasis role="bold">The chmod command</emphasis></term>
+ <term><emphasis role="bold">The chmod
+ command</emphasis></term>
<listitem>
- <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can use this command to turn on
- the setuid, setgid or sticky mode bits on AFS files. For more information, see <link linkend="HDRWQ409">Determining if
- a Client Can Run Setuid Programs</link>.</para>
+ <para>Only members of the <emphasis
+ role="bold">system:administrators</emphasis> group can use
+ this command to turn on the setuid, setgid or sticky mode
+ bits on AFS files. For more information, see <link
+ linkend="HDRWQ409">Determining if a Client Can Run Setuid
+ Programs</link>.</para>
<indexterm>
<primary>chown command</primary>
</varlistentry>
<varlistentry>
- <term><emphasis role="bold">The chown command</emphasis></term>
+ <term><emphasis role="bold">The chown
+ command</emphasis></term>
<listitem>
- <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can issue this command on AFS
- files.</para>
+ <para>Only members of the <emphasis
+ role="bold">system:administrators</emphasis> group can issue
+ this command on AFS files.</para>
<indexterm>
<primary>chgrp command</primary>
</varlistentry>
<varlistentry>
- <term><emphasis role="bold">The chgrp command</emphasis></term>
+ <term><emphasis role="bold">The chgrp
+ command</emphasis></term>
<listitem>
- <para>Only members of the <emphasis role="bold">system:administrators</emphasis> can issue this command on AFS files
- and directories.</para>
+ <para>Only members of the <emphasis
+ role="bold">system:administrators</emphasis> can issue this
+ command on AFS files and directories.</para>
<indexterm>
<primary>groups command</primary>
</varlistentry>
<varlistentry>
- <term><emphasis role="bold">The groups command</emphasis></term>
+ <term><emphasis role="bold">The groups
+ command</emphasis></term>
<listitem>
- <para>If the user's AFS tokens are associated with a process authentication group (PAG), the output of this command
- can include one or two large numbers. To learn about PAGs, see <link linkend="HDRWQ64">Identifying AFS Tokens by
+ <para>If the user's AFS tokens are associated with a process
+ authentication group (PAG), the output of this command can
+ include one or two large numbers. To learn about PAGs, see
+ <link linkend="HDRWQ64">Identifying AFS Tokens by
PAG</link>.</para>
<indexterm>
<secondary>login (AFS compared to UNIX)</secondary>
</indexterm>
-
+
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="bold">The login utility</emphasis></term>
+ <term><emphasis role="bold">The login
+ utility</emphasis></term>
<listitem>
- <para>AFS-modified login utilities both log the issuer into the local file system and authenticate the user with the
- AFS authentication service. See <link linkend="HDRWQ65">Using an AFS-modified login Utility</link>.</para>
+ <para>AFS-modified login utilities both log the issuer into
+ the local file system and authenticate the user with the AFS
+ authentication service. See <link linkend="HDRWQ65">Using an
+ AFS-modified login Utility</link>.</para>
<indexterm>
<primary>ln command</primary>
<term><emphasis role="bold">The ln command</emphasis></term>
<listitem>
- <para>This command cannot create hard links between files in different AFS directories. See <link
+ <para>This command cannot create hard links between files in
+ different AFS directories. See <link
linkend="HDRWQ32">Creating Hard Links</link>.</para>
<indexterm>
<term><emphasis role="bold">The sshd daemon</emphasis></term>
<listitem>
- <para>The <ulink url="http://www.openssh.org/">OpenSSH project</ulink> provides an sshd daemon that uses the GSSAPI protocol to pass Kerberos tickets between machines.</para>
+ <para>The <ulink url="http://www.openssh.org/">OpenSSH
+ project</ulink> provides an sshd daemon that uses the GSSAPI
+ protocol to pass Kerberos tickets between machines.</para>
<indexterm>
<primary>ssh command</primary>
</indexterm>
</listitem>
</varlistentry>
- </variablelist></para>
+ </variablelist>
+ </para>
<indexterm>
<primary>fsck command</primary>
</sect2>
<sect2 id="Header_38">
- <title>The AFS version of the fsck Command and inode-based fileservers</title>
+ <title>The AFS version of the fsck Command and inode-based
+ fileservers</title>
<sidebar>
<para>The fileserver uses either of two formats for storing data
for the fileserver binaries and all vice partitions on a given
fileserver machine.</para>
</sidebar>
-
- <important><para>This section on fsck advice only applies to the inode-based fileserver binaries. On servers using namei-based binaries, the vendor-supplied fsck is required.</para></important>
- <para>If you are using AFS fileserver binaries compiled with the inode-based format, never run the standard UNIX <emphasis role="bold">fsck</emphasis> command on an AFS file server machine. It does not
- understand how the File Server organizes volume data on disk, and so moves all AFS data into the <emphasis
+ <important><para>This section on fsck advice only applies to the
+ inode-based fileserver binaries. On servers using namei-based
+ binaries, the vendor-supplied fsck is required.</para></important>
+
+ <para>If you are using AFS fileserver binaries compiled with the
+ inode-based format, never run the standard UNIX <emphasis
+ role="bold">fsck</emphasis> command on an AFS file server
+ machine. It does not understand how the File Server organizes volume
+ data on disk, and so moves all AFS data into the <emphasis
role="bold">lost+found</emphasis> directory on the partition.</para>
- <para>Instead, use the version of the <emphasis role="bold">fsck</emphasis> program that is included in the AFS distribution.
- The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to replace the vendor-supplied <emphasis
- role="bold">fsck</emphasis> program with the AFS version as you install each server machine.</para>
+ <para>Instead, use the version of the <emphasis
+ role="bold">fsck</emphasis> program that is included in the AFS
+ distribution. The <emphasis>OpenAFS Quick Beginnings</emphasis>
+ explains how to replace the vendor-supplied <emphasis
+ role="bold">fsck</emphasis> program with the AFS version as you
+ install each server machine.</para>
- <para>The AFS version functions like the standard <emphasis role="bold">fsck</emphasis> program on data stored on both UFS and
- AFS partitions. The appearance of a banner like the following as the <emphasis role="bold">fsck</emphasis> program initializes
- confirms that you are running the correct one:</para>
+ <para>The AFS version functions like the standard <emphasis
+ role="bold">fsck</emphasis> program on data stored on both UFS and
+ AFS partitions. The appearance of a banner like the following as the
+ <emphasis role="bold">fsck</emphasis> program initializes confirms
+ that you are running the correct one:</para>
- <programlisting>
+<programlisting>
--- AFS (R) version fsck---
</programlisting>
- <para>where <emphasis>version</emphasis> is the AFS version. For correct results, it must match the AFS version of the server
+ <para>where <emphasis>version</emphasis> is the AFS version. For
+ correct results, it must match the AFS version of the server
binaries in use on the machine.</para>
- <para>If you ever accidentally run the standard version of the program, contact your AFS support provider or refer to the <ulink url="http://www.openafs.org/support.html">OpenAFS support web page</ulink> for support options. It is
- sometimes possible to recover volume data from the <emphasis role="bold">lost+found</emphasis> directory. If the data is not recoverabled, then restoring from backup is recommended.</para>
+ <para>If you ever accidentally run the standard version of the
+ program, contact your AFS support provider or refer to the <ulink
+ url="http://www.openafs.org/support.html">OpenAFS support web
+ page</ulink> for support options. It is sometimes possible to
+ recover volume data from the <emphasis
+ role="bold">lost+found</emphasis> directory. If the data is not
+ recoverabled, then restoring from backup is recommended.</para>
+
+ <warning><para>Running the fsck binary supplied by the operating
+ system vendor on an fileserver using inode-based binaries will
+ result in data corruption!</para></warning>
- <warning><para>Running the fsck binary supplied by the operating system vendor on an fileserver using inode-based binaries will result in data corruption!</para></warning>
-
<indexterm>
<primary>hard link</primary>
<sect2 id="HDRWQ32">
<title>Creating Hard Links</title>
- <para>AFS does not allow hard links (created with the UNIX <emphasis role="bold">ln</emphasis> command) between files that
- reside in different directories, because in that case it is unclear which of the directory's ACLs to associate with the
- link.</para>
+ <para>AFS does not allow hard links (created with the UNIX <emphasis
+ role="bold">ln</emphasis> command) between files that reside in
+ different directories, because in that case it is unclear which of
+ the directory's ACLs to associate with the link.</para>
- <para>AFS also does not allow hard links to directories, in order to keep the file system organized as a tree.</para>
+ <para>AFS also does not allow hard links to directories, in order to
+ keep the file system organized as a tree.</para>
- <para>It is possible to create symbolic links (with the UNIX <emphasis role="bold">ln -s</emphasis> command) between elements
- in two different AFS directories, or even between an element in AFS and one in a machine's local UNIX file system. Do not
- create a symbolic link to a file whose name begins with either a number sign (<emphasis role="bold">#</emphasis>) or a percent
- sign (<emphasis role="bold">%</emphasis>), however. The Cache Manager interprets such links as a mount point to a regular or
- read/write volume, respectively.</para>
+ <para>It is possible to create symbolic links (with the UNIX
+ <emphasis role="bold">ln -s</emphasis> command) between elements in
+ two different AFS directories, or even between an element in AFS and
+ one in a machine's local UNIX file system. Do not create a symbolic
+ link to a file whose name begins with either a number sign
+ (<emphasis role="bold">#</emphasis>) or a percent sign (<emphasis
+ role="bold">%</emphasis>), however. The Cache Manager interprets
+ such links as a mount point to a regular or read/write volume,
+ respectively.</para>
<indexterm>
<primary>fsync system call</primary>
<sect2 id="HDRWQ33">
<title>AFS Implements Save on Close</title>
- <para>When an application issues the UNIX <emphasis role="bold">close</emphasis> system call on a file, the Cache Manager
- performs a synchronous write of the data to the File Server that maintains the central copy of the file. It does not return
- control to the application until the File Server has acknowledged receipt of the data. For the <emphasis
- role="bold">fsync</emphasis> system call, control does not return to the application until the File Server indicates that it
- has written the data to non-volatile storage on the file server machine.</para>
-
- <para>When an application issues the UNIX <emphasis role="bold">write</emphasis> system call, the Cache Manager writes
- modifications to the local AFS client cache only. If the local machine crashes or an application program exits without issuing
- the <emphasis role="bold">close</emphasis> system call, it is possible that the modifications are not recorded in the central
- copy of the file maintained by the File Server. The Cache Manager does sometimes write this type of modified data from the
- cache to the File Server without receiving the <emphasis role="bold">close</emphasis> or <emphasis
- role="bold">fsync</emphasis> system call, for example if it needs to free cache chunks for new data. However, it is not
- generally possible to predict when the Cache Manager transfers modified data to the File Server in this way.</para>
-
- <para>The implication is that if an application's <emphasis role="bold">Save</emphasis> option invokes the <emphasis
- role="bold">write</emphasis> system call rather than <emphasis role="bold">close</emphasis> or <emphasis
- role="bold">fsync</emphasis>, the changes are not necessarily stored permanently on the File Server machine. Most application
- programs issue the <emphasis role="bold">close</emphasis> system call for save operations, as well as when they finish
- handling a file and when they exit.</para>
+ <para>When an application issues the UNIX <emphasis
+ role="bold">close</emphasis> system call on a file, the Cache
+ Manager performs a synchronous write of the data to the File Server
+ that maintains the central copy of the file. It does not return
+ control to the application until the File Server has acknowledged
+ receipt of the data. For the <emphasis role="bold">fsync</emphasis>
+ system call, control does not return to the application until the
+ File Server indicates that it has written the data to non-volatile
+ storage on the file server machine.</para>
+
+ <para>When an application issues the UNIX <emphasis
+ role="bold">write</emphasis> system call, the Cache Manager writes
+ modifications to the local AFS client cache only. If the local
+ machine crashes or an application program exits without issuing the
+ <emphasis role="bold">close</emphasis> system call, it is possible
+ that the modifications are not recorded in the central copy of the
+ file maintained by the File Server. The Cache Manager does sometimes
+ write this type of modified data from the cache to the File Server
+ without receiving the <emphasis role="bold">close</emphasis> or
+ <emphasis role="bold">fsync</emphasis> system call, for example if
+ it needs to free cache chunks for new data. However, it is not
+ generally possible to predict when the Cache Manager transfers
+ modified data to the File Server in this way.</para>
+
+ <para>The implication is that if an application's <emphasis
+ role="bold">Save</emphasis> option invokes the <emphasis
+ role="bold">write</emphasis> system call rather than <emphasis
+ role="bold">close</emphasis> or <emphasis
+ role="bold">fsync</emphasis>, the changes are not necessarily stored
+ permanently on the File Server machine. Most application programs
+ issue the <emphasis role="bold">close</emphasis> system call for
+ save operations, as well as when they finish handling a file and
+ when they exit.</para>
</sect2>
<sect2 id="Header_41">
<secondary>restrictions on</secondary>
</indexterm>
- <para>Set the UNIX setuid bit only for the local superuser <emphasis role="bold">root</emphasis>; this does not present an
- automatic security risk: the local superuser has no special privilege in AFS, but only in the local machine's UNIX file system
- and kernel.</para>
+ <para>Set the UNIX setuid bit only for the local superuser <emphasis
+ role="bold">root</emphasis>; this does not present an automatic
+ security risk: the local superuser has no special privilege in AFS,
+ but only in the local machine's UNIX file system and kernel.</para>
- <para>Any file can be marked with the setuid bit, but only members of the <emphasis
- role="bold">system:administrators</emphasis> group can issue the <emphasis role="bold">chown</emphasis> system call or the
- <emphasis role="bold">chown</emphasis> command.</para>
+ <para>Any file can be marked with the setuid bit, but only members
+ of the <emphasis role="bold">system:administrators</emphasis> group
+ can issue the <emphasis role="bold">chown</emphasis> system call or
+ the <emphasis role="bold">chown</emphasis> command.</para>
- <para>The <emphasis role="bold">fs setcell</emphasis> command determines whether setuid programs that originate in a foreign
- cell can run on a given client machine. See <link linkend="HDRWQ409">Determining if a Client Can Run Setuid
+ <para>The <emphasis role="bold">fs setcell</emphasis> command
+ determines whether setuid programs that originate in a foreign cell
+ can run on a given client machine. See <link
+ linkend="HDRWQ409">Determining if a Client Can Run Setuid
Programs</link>.</para>
<indexterm>
<sect1 id="HDRWQ34">
<title>Choosing a Cell Name</title>
- <para>This section explains how to choose a cell name and explains why choosing an appropriate cell name is important.</para>
-
- <para>Your cell name must distinguish your cell from all others in the AFS global namespace. By conventions, the cell name is
- the second element in any AFS pathname; therefore, a unique cell name guarantees that every AFS pathname uniquely identifies a
- file, even if cells use the same directory names at lower levels in their local AFS filespace. For example, both the ABC
- Corporation cell and the State University cell can have a home directory for the user <emphasis role="bold">pat</emphasis>,
- because the pathnames are distinct: <emphasis role="bold">/afs/abc.com/usr/pat</emphasis> and <emphasis
+ <para>This section explains how to choose a cell name and explains why
+ choosing an appropriate cell name is important.</para>
+
+ <para>Your cell name must distinguish your cell from all others in the
+ AFS global namespace. By conventions, the cell name is the second
+ element in any AFS pathname; therefore, a unique cell name guarantees
+ that every AFS pathname uniquely identifies a file, even if cells use
+ the same directory names at lower levels in their local AFS
+ filespace. For example, both the ABC Corporation cell and the State
+ University cell can have a home directory for the user <emphasis
+ role="bold">pat</emphasis>, because the pathnames are distinct:
+ <emphasis role="bold">/afs/abc.com/usr/pat</emphasis> and <emphasis
role="bold">/afs/stateu.edu/usr/pat</emphasis>.</para>
- <para>By convention, cell names follow the ARPA Internet Domain System conventions for site names. If you are already an
- Internet site, then it is simplest to choose your Internet domain name as the cellname.</para>
+ <para>By convention, cell names follow the ARPA Internet Domain System
+ conventions for site names. If you are already an Internet site, then
+ it is simplest to choose your Internet domain name as the
+ cellname.</para>
- <para>If you are not an Internet site, it is best to choose a unique Internet-style name, particularly if you plan to connect to
- the Internet in the future. There are a few
- constraints on AFS cell names: <itemizedlist>
+ <para>If you are not an Internet site, it is best to choose a unique
+ Internet-style name, particularly if you plan to connect to the
+ Internet in the future. There are a few constraints on AFS cell names:
+ <itemizedlist>
<listitem>
- <para>It can contain as many as 64 characters, but shorter names are better because the cell name frequently is part of
- machine and file names. If your cell name is long, you can reduce pathname length by creating a symbolic link to the
- complete cell name, at the second level in your file tree. See <link linkend="HDRWQ42">The Second (Cellname)
- Level</link>.</para>
+ <para>It can contain as many as 64 characters, but shorter names
+ are better because the cell name frequently is part of machine
+ and file names. If your cell name is long, you can reduce
+ pathname length by creating a symbolic link to the complete cell
+ name, at the second level in your file tree. See <link
+ linkend="HDRWQ42">The Second (Cellname) Level</link>.</para>
</listitem>
<listitem>
- <para>To guarantee it is suitable for different operating system types, the cell name can contain only lowercase
- characters, numbers, underscores, dashes, and periods. Do not include command shell metacharacters.</para>
+ <para>To guarantee it is suitable for different operating system
+ types, the cell name can contain only lowercase characters,
+ numbers, underscores, dashes, and periods. Do not include
+ command shell metacharacters.</para>
</listitem>
<listitem>
- <para>It can include any number of fields, which are conventionally separated by periods (see the examples below).</para>
+ <para>It can include any number of fields, which are
+ conventionally separated by periods (see the examples
+ below).</para>
</listitem>
<listitem>
- <para>It must end in a suffix that indicates the type of institution it is, or the country in which it is situated. The
- following are some of the standard suffixes: <variablelist>
+ <para>It must end in a suffix that indicates the type of
+ institution it is, or the country in which it is situated. The
+ following are some of the standard suffixes:
+ <variablelist>
<varlistentry>
<term><emphasis role="bold">.com</emphasis></term>
<listitem>
- <para>For businesses and other commercial organizations. Example: <emphasis role="bold">abc.com</emphasis> for the
- ABC Corporation cell.</para>
- </listitem>
- </varlistentry>
+ <para>For businesses and other commercial
+ organizations. Example: <emphasis
+ role="bold">abc.com</emphasis> for the ABC Corporation
+ cell.</para>
+ </listitem> </varlistentry>
<varlistentry>
<term><emphasis role="bold">.edu</emphasis></term>
<listitem>
- <para>For educational institutions such as universities. Example: <emphasis role="bold">stateu.edu</emphasis> for
- the State University cell.</para>
- </listitem>
- </varlistentry>
+ <para>For educational institutions such as
+ universities. Example: <emphasis
+ role="bold">stateu.edu</emphasis> for the State
+ University cell.</para>
+ </listitem> </varlistentry>
<varlistentry>
<term><emphasis role="bold">.gov</emphasis></term>
<para>For United States military installations.</para>
</listitem>
</varlistentry>
- </variablelist></para>
+ </variablelist>
+ </para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
<indexterm>
<primary>Internet</primary>
<sect2 id="Header_43">
<title>How to Set the Cell Name</title>
- <para>The cell name is recorded in two files on the local disk of each file server and client machine. Among other functions,
- these files define the machine's cell membership and so affect how programs and processes run on the machine; see <link
- linkend="HDRWQ35">Why Choosing the Appropriate Cell Name is Important</link>. The procedure for setting the cell name is
+ <para>The cell name is recorded in two files on the local disk of
+ each file server and client machine. Among other functions, these
+ files define the machine's cell membership and so affect how
+ programs and processes run on the machine; see <link
+ linkend="HDRWQ35">Why Choosing the Appropriate Cell Name is
+ Important</link>. The procedure for setting the cell name is
different for the two types of machines.</para>
- <para>For file server machines, the two files that record the cell name are the <emphasis
- role="bold">/usr/afs/etc/ThisCell</emphasis> and <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> files. As described
- more explicitly in the <emphasis>OpenAFS Quick Beginnings</emphasis>, you set the cell name in both by issuing the <emphasis
- role="bold">bos setcellname</emphasis> command on the first file server machine you install in your cell. It is not usually
- necessary to issue the command again. If you use the Update Server, it distributes
- its copy of the <emphasis role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files to additional
- server machines that you install. If you do not use the Update Server, the <emphasis>OpenAFS Quick
- Beginnings</emphasis> explains how to copy the files manually.</para>
-
- <para>For client machines, the two files that record the cell name are the <emphasis
- role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> files. You create
- these files on a per-client basis, either with a text editor or by copying them onto the machine from a central source in AFS.
- See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link> for details.</para>
-
- <para>Change the cell name in these files only when you want to transfer the machine to a different cell (it can only belong
- to one cell at a time). If the machine is a file server, follow the complete set of instructions in the <emphasis>OpenAFS
- Quick Beginnings</emphasis> for configuring a new cell. If the machine is a client, all you need to do is change the files
- appropriately and reboot the machine. The next section explains further the negative consequences of changing the name of an
- existing cell.</para>
-
- <para>To set the default cell name used by most AFS commands without changing the local <emphasis
- role="bold">/usr/vice/etc/ThisCell</emphasis> file, set the AFSCELL environment variable in the command shell. It is worth
- setting this variable if you need to complete significant administrative work in a foreign cell.</para>
+ <para>For file server machines, the two files that record the cell
+ name are the <emphasis role="bold">/usr/afs/etc/ThisCell</emphasis>
+ and <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>
+ files. As described more explicitly in the <emphasis>OpenAFS Quick
+ Beginnings</emphasis>, you set the cell name in both by issuing the
+ <emphasis role="bold">bos setcellname</emphasis> command on the
+ first file server machine you install in your cell. It is not
+ usually necessary to issue the command again. If you use the Update
+ Server, it distributes its copy of the <emphasis
+ role="bold">ThisCell</emphasis> and <emphasis
+ role="bold">CellServDB</emphasis> files to additional server
+ machines that you install. If you do not use the Update Server, the
+ <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to copy
+ the files manually.</para>
+
+ <para>For client machines, the two files that record the cell name
+ are the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and
+ <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> files. You
+ create these files on a per-client basis, either with a text editor
+ or by copying them onto the machine from a central source in AFS.
+ See <link linkend="HDRWQ406">Maintaining Knowledge of Database
+ Server Machines</link> for details.</para>
+
+ <para>Change the cell name in these files only when you want to
+ transfer the machine to a different cell (it can only belong to one
+ cell at a time). If the machine is a file server, follow the
+ complete set of instructions in the <emphasis>OpenAFS Quick
+ Beginnings</emphasis> for configuring a new cell. If the machine is
+ a client, all you need to do is change the files appropriately and
+ reboot the machine. The next section explains further the negative
+ consequences of changing the name of an existing cell.</para>
+
+ <para>To set the default cell name used by most AFS commands without
+ changing the local <emphasis
+ role="bold">/usr/vice/etc/ThisCell</emphasis> file, set the AFSCELL
+ environment variable in the command shell. It is worth setting this
+ variable if you need to complete significant administrative work in
+ a foreign cell.</para>
<note>
- <para>The <emphasis role="bold">fs checkservers</emphasis> and <emphasis role="bold">fs mkmount</emphasis> commands do not
- use the AFSCELL variable. The <emphasis role="bold">fs checkservers</emphasis> command always defaults to the cell named in
- the <emphasis role="bold">ThisCell</emphasis> file, unless the <emphasis role="bold">-cell</emphasis> argument is used. The
- <emphasis role="bold">fs mkmount</emphasis> command defaults to the cell in which the parent directory of the new mount
- point resides.</para>
+ <para>The <emphasis role="bold">fs checkservers</emphasis> and
+ <emphasis role="bold">fs mkmount</emphasis> commands do not use
+ the AFSCELL variable. The <emphasis role="bold">fs
+ checkservers</emphasis> command always defaults to the cell named
+ in the <emphasis role="bold">ThisCell</emphasis> file, unless the
+ <emphasis role="bold">-cell</emphasis> argument is used. The
+ <emphasis role="bold">fs mkmount</emphasis> command defaults to
+ the cell in which the parent directory of the new mount point
+ resides.</para>
</note>
<indexterm>
<sect2 id="HDRWQ35">
<title>Why Choosing the Appropriate Cell Name is Important</title>
- <para>Take care to select a cell name that is suitable for long-term use. Changing a cell name later is complicated. An
- appropriate cell name is important because it is the second element in the pathname of all files in a cell's file tree.
- Because each cell name is unique, its presence in an AFS pathname makes the pathname unique in the AFS global namespace, even
- if multiple cells use similar filespace organization at lower levels. For instance, it means that every cell can have a home
- directory called <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
- role="bold">/usr/pat</emphasis> without causing a conflict. The presence of the cell name in pathnames also means that users
- in every cell use the same pathname to access a file, whether the file resides in their local cell or in a foreign
+ <para>Take care to select a cell name that is suitable for long-term
+ use. Changing a cell name later is complicated. An appropriate cell
+ name is important because it is the second element in the pathname
+ of all files in a cell's file tree. Because each cell name is
+ unique, its presence in an AFS pathname makes the pathname unique in
+ the AFS global namespace, even if multiple cells use similar
+ filespace organization at lower levels. For instance, it means that
+ every cell can have a home directory called <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/usr/pat</emphasis> without causing a conflict. The
+ presence of the cell name in pathnames also means that users in
+ every cell use the same pathname to access a file, whether the file
+ resides in their local cell or in a foreign cell.</para>
+
+ <para>Another reason to choose the correct cell name early in the
+ process of installing your cell is that the cell membership defined
+ in each machine's <emphasis role="bold">ThisCell</emphasis> file
+ affects the performance of many programs and processes running on
+ the machine. For instance, AFS commands (<emphasis
+ role="bold">fs</emphasis>, <emphasis role="bold">kas</emphasis>,
+ <emphasis role="bold">pts</emphasis> and <emphasis
+ role="bold">vos</emphasis> commands) by default execute in the cell
+ of the machine on which they are issued. The command interpreters
+ check the <emphasis role="bold">ThisCell</emphasis> file on the
+ local disk and then contact the database server machines listed in
+ the <emphasis role="bold">CellServDB</emphasis> file for the
+ indicated cell (the <emphasis role="bold">bos</emphasis> commands
+ work differently because the issuer always has to name of the
+ machine on which to run the command).</para> <para>The <emphasis
+ role="bold">ThisCell</emphasis> file also determines the cell for
+ which a user receives an AFS token when he or she logs in to a
+ machine.</para> <para>This method of converting passwords into
+ encryption keys means that the same password results in different
+ keys in different cells. Even if a user uses the same password in
+ multiple cells, obtaining a user's token from one cell does not
+ enable unauthorized access to the user's account in another
cell.</para>
- <para>Another reason to choose the correct cell name early in the process of installing your cell is that the cell membership
- defined in each machine's <emphasis role="bold">ThisCell</emphasis> file affects the performance of many programs and
- processes running on the machine. For instance, AFS commands (<emphasis role="bold">fs</emphasis>, <emphasis
- role="bold">kas</emphasis>, <emphasis role="bold">pts</emphasis> and <emphasis role="bold">vos</emphasis> commands) by default
- execute in the cell of the machine on which they are issued. The command interpreters check the <emphasis
- role="bold">ThisCell</emphasis> file on the local disk and then contact the database server machines listed in the <emphasis
- role="bold">CellServDB</emphasis> file for the indicated cell (the <emphasis role="bold">bos</emphasis> commands work
- differently because the issuer always has to name of the machine on which to run the command).</para>
- <para>The <emphasis role="bold">ThisCell</emphasis> file also determines the cell for which a
-user receives an AFS token when
- he or she logs in to a machine.</para>
- <para>This method of converting passwords into encryption keys means that the same password results in different keys in
- different cells. Even if a user uses the same password in multiple cells, obtaining a user's token from one cell does not
- enable unauthorized access to the user's account in another cell.</para>
-
- <para>If you change the cell name, you must change the <emphasis role="bold">ThisCell</emphasis> and <emphasis
- role="bold">CellServDB</emphasis> files on every server and client machine. Failure to change them all can prevent login,
- because the encryption keys produced by the login utility do not match the keys stored in the Authentication Database. In
- addition, many commands from the AFS suites do not work as expected.</para>
+ <para>If you change the cell name, you must change the <emphasis
+ role="bold">ThisCell</emphasis> and <emphasis
+ role="bold">CellServDB</emphasis> files on every server and client
+ machine. Failure to change them all can prevent login, because the
+ encryption keys produced by the login utility do not match the keys
+ stored in the Authentication Database. In addition, many commands
+ from the AFS suites do not work as expected.</para>
<indexterm>
<primary>participation</primary>
<sect1 id="HDRWQ36">
<title>Participating in the AFS Global Namespace</title>
- <para>Participating in the AFS global namespace makes your cell's local file tree visible to AFS users in foreign cells and
- makes other cells' file trees visible to your local users. It makes file sharing across cells just as easy as sharing within a
- cell. This section outlines the procedures necessary for participating in the global namespace. <itemizedlist>
+ <para>Participating in the AFS global namespace makes your cell's
+ local file tree visible to AFS users in foreign cells and makes other
+ cells' file trees visible to your local users. It makes file sharing
+ across cells just as easy as sharing within a cell. This section
+ outlines the procedures necessary for participating in the global
+ namespace. <itemizedlist>
<listitem>
- <para>Participation in the global namespace is not mandatory. Some cells use AFS primarily to facilitate file sharing
- within the cell, and are not interested in providing their users with access to foreign cells.</para>
+ <para>Participation in the global namespace is not
+ mandatory. Some cells use AFS primarily to facilitate file
+ sharing within the cell, and are not interested in providing
+ their users with access to foreign cells.</para>
</listitem>
<listitem>
- <para>Making your file tree visible does not mean making it vulnerable. You control how foreign users access your cell
- using the same protection mechanisms that control local users' access. See <link linkend="HDRWQ40">Granting and Denying
- Foreign Users Access to Your Cell</link>.</para>
+ <para>Making your file tree visible does not mean making it
+ vulnerable. You control how foreign users access your cell using
+ the same protection mechanisms that control local users'
+ access. See <link linkend="HDRWQ40">Granting and Denying Foreign
+ Users Access to Your Cell</link>.</para>
</listitem>
<listitem>
- <para>The two aspects of participation are independent. A cell can make its file tree visible without allowing its users
- to see foreign cells' file trees, or can enable its users to see other file trees without advertising its own.</para>
+ <para>The two aspects of participation are independent. A cell
+ can make its file tree visible without allowing its users to see
+ foreign cells' file trees, or can enable its users to see other
+ file trees without advertising its own.</para>
</listitem>
<listitem>
- <para>You make your cell visible to others by advertising your database server machines. See <link
- linkend="HDRWQ38">Making Your Cell Visible to Others</link>.</para>
+ <para>You make your cell visible to others by advertising your
+ database server machines. See <link linkend="HDRWQ38">Making
+ Your Cell Visible to Others</link>.</para>
</listitem>
<listitem>
- <para>You control access to foreign cells on a per-client machine basis. In other words, it is possible to make a foreign
- cell accessible from one client machine in your cell but not another. See <link linkend="HDRWQ39">Making Other Cells
- Visible in Your Cell</link>.</para>
+ <para>You control access to foreign cells on a per-client
+ machine basis. In other words, it is possible to make a foreign
+ cell accessible from one client machine in your cell but not
+ another. See <link linkend="HDRWQ39">Making Other Cells Visible
+ in Your Cell</link>.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
<indexterm>
<primary>conventions</primary>
<sect2 id="HDRWQ37">
<title>What the Global Namespace Looks Like</title>
- <para>The AFS global namespace appears the same to all AFS cells that participate in it, because they all agree to follow a
- small set of conventions in constructing pathnames.</para>
+ <para>The AFS global namespace appears the same to all AFS cells
+ that participate in it, because they all agree to follow a small set
+ of conventions in constructing pathnames.</para>
- <para>The first convention is that all AFS pathnames begin with the string <emphasis role="bold">/afs</emphasis> to indicate
- that they belong to the AFS global namespace.</para>
+ <para>The first convention is that all AFS pathnames begin with the
+ string <emphasis role="bold">/afs</emphasis> to indicate that they
+ belong to the AFS global namespace.</para>
- <para>The second convention is that the cell name is the second element in an AFS pathname; it indicates where the file
- resides (that is, the cell in which a file server machine houses the file). As noted, the presence of a cell name in pathnames
- makes the global namespace possible, because it guarantees that all AFS pathnames are unique even if cells use the same
- directory names at lower levels in their AFS filespace.</para>
+ <para>The second convention is that the cell name is the second
+ element in an AFS pathname; it indicates where the file resides
+ (that is, the cell in which a file server machine houses the
+ file). As noted, the presence of a cell name in pathnames makes the
+ global namespace possible, because it guarantees that all AFS
+ pathnames are unique even if cells use the same directory names at
+ lower levels in their AFS filespace.</para>
- <para>What appears at the third and lower levels in an AFS pathname depends on how a cell has chosen to arrange its filespace.
- There are some suggested conventional directories at the third level; see <link linkend="HDRWQ43">The Third
- Level</link>.</para>
+ <para>What appears at the third and lower levels in an AFS pathname
+ depends on how a cell has chosen to arrange its filespace. There
+ are some suggested conventional directories at the third level; see
+ <link linkend="HDRWQ43">The Third Level</link>.</para>
<indexterm>
<primary>cell</primary>
<sect2 id="HDRWQ38">
<title>Making Your Cell Visible to Others</title>
- <para>You make your cell visible to others by advertising your cell name and database server machines. Just like client
- machines in the local cell, the Cache Manager on machines in foreign cells use the information to reach your cell's Volume
- Location (VL) Servers when they need volume and file location information. For authenticated access, foreign clients
- must be configured with the necessary Kerberos v5 domain-to-realm mappings and Key Distribution Center location information for both the local and remote Kerberos v5 realms.</para>
-
- <para>There are two places you can make this information available: <itemizedlist>
+ <para>You make your cell visible to others by advertising your cell
+ name and database server machines. Just like client machines in the
+ local cell, the Cache Manager on machines in foreign cells use the
+ information to reach your cell's Volume Location (VL) Servers when
+ they need volume and file location information. For authenticated
+ access, foreign clients must be configured with the necessary
+ Kerberos v5 domain-to-realm mappings and Key Distribution Center
+ location information for both the local and remote Kerberos v5
+ realms.</para>
+
+ <para>There are two places you can make this information available:
+ <itemizedlist>
<indexterm>
<primary>files</primary>
</indexterm>
<indexterm>
- <primary>CellServDB file maintained by the AFS Registrar</primary>
+ <primary>CellServDB file maintained by the AFS
+ Registrar</primary>
<secondary>as global update source</secondary>
</indexterm>
<listitem>
- <para>In the
- global <emphasis role="bold">CellServDB</emphasis> file
- maintained by the AFS Registrar. This file lists the name and
- database server machines of every cell that has agreed to make
- this information available to other cells. This file is
- available
- at <ulink url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink></para>
+ <para>In the global <emphasis
+ role="bold">CellServDB</emphasis> file maintained by the AFS
+ Registrar. This file lists the name and database server
+ machines of every cell that has agreed to make this
+ information available to other cells. This file is available
+ at <ulink
+ url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink></para>
<para>To add or change your cell's listing in this file,
- follow the instructions at
- <ulink url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink>.
+ follow the instructions at <ulink
+ url="http://grand.central.org/csdb.html">http://grand.central.org/csdb.html</ulink>.
It is a good policy to check the file for changes on a
regular schedule. An updated copy of this file is included
with new releases of OpenAFS.</para>
</listitem>
<listitem>
- <para>A file called <emphasis role="bold">CellServDB.local</emphasis> in the <emphasis
- role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/service/etc</emphasis> directory
- of your cell's filespace. List only your cell's database server machines.</para>
+ <para>A file called <emphasis
+ role="bold">CellServDB.local</emphasis> in the <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/service/etc</emphasis> directory of your cell's
+ filespace. List only your cell's database server
+ machines.</para>
</listitem>
- </itemizedlist></para>
-
- <para>Update the files whenever you change the identity of your cell's database server machines. Also update the copies of the
- <emphasis role="bold">CellServDB</emphasis> files on all of your server machines (in the <emphasis
- role="bold">/usr/afs/etc</emphasis> directory) and client machines (in the <emphasis role="bold">/usr/vice/etc</emphasis>
- directory). For instructions, see <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and <link
- linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
-
- <para>Once you have advertised your database server machines, it can be difficult to make your cell invisible again. You can
- remove the <emphasis role="bold">CellServDB.local</emphasis> file and ask the AFS Registrar to remove your entry from the
- global <emphasis role="bold">CellServDB</emphasis> file, but other cells probably have an entry for your cell in their local
- <emphasis role="bold">CellServDB</emphasis> files already. To make those entries invalid, you must change the names or IP
- addresses of your database server machines.</para>
+ </itemizedlist>
+ </para>
- <para>Your cell does not have to be invisible to be inaccessible, however. To make your cell completely inaccessible to
- foreign users, remove the <emphasis role="bold">system:anyuser</emphasis> group from all ACLs at the top three levels of your
- filespace; see <link linkend="HDRWQ40">Granting and Denying Foreign Users Access to Your Cell</link>.</para>
+ <para>Update the files whenever you change the identity of your
+ cell's database server machines. Also update the copies of the
+ <emphasis role="bold">CellServDB</emphasis> files on all of your
+ server machines (in the <emphasis
+ role="bold">/usr/afs/etc</emphasis> directory) and client machines
+ (in the <emphasis role="bold">/usr/vice/etc</emphasis>
+ directory). For instructions, see <link
+ linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and
+ <link linkend="HDRWQ406">Maintaining Knowledge of Database Server
+ Machines</link>.</para>
+
+ <para>Once you have advertised your database server machines, it can
+ be difficult to make your cell invisible again. You can remove the
+ <emphasis role="bold">CellServDB.local</emphasis> file and ask the
+ AFS Registrar to remove your entry from the global <emphasis
+ role="bold">CellServDB</emphasis> file, but other cells probably
+ have an entry for your cell in their local <emphasis
+ role="bold">CellServDB</emphasis> files already. To make those
+ entries invalid, you must change the names or IP addresses of your
+ database server machines.</para>
+
+ <para>Your cell does not have to be invisible to be inaccessible,
+ however. To make your cell completely inaccessible to foreign users,
+ remove the <emphasis role="bold">system:anyuser</emphasis> group
+ from all ACLs at the top three levels of your filespace; see <link
+ linkend="HDRWQ40">Granting and Denying Foreign Users Access to Your
+ Cell</link>.</para>
<indexterm>
<primary>cell</primary>
<title>Making Other Cells Visible in Your Cell</title>
<para>To make a foreign cell's filespace visible on a client machine
- in your cell that is not configured
- for <emphasis role="bold">Freelance Mode</emphasis>
- or <emphasis role="bold">Dynamic Root</emphasis> mode, perform the
- following three steps:
+ in your cell that is not configured for <emphasis
+ role="bold">Freelance Mode</emphasis> or <emphasis
+ role="bold">Dynamic Root</emphasis> mode, perform the following
+ three steps:
<orderedlist>
<listitem>
- <para>Mount the cell's <emphasis role="bold">root.cell</emphasis> volume at the second level in your cell's filespace
- just below the <emphasis role="bold">/afs</emphasis> directory. Use the <emphasis role="bold">fs mkmount</emphasis>
- command with the <emphasis role="bold">-cell</emphasis> argument as instructed in <link linkend="HDRWQ213">To create a
- cellular mount point</link>.</para>
+ <para>Mount the cell's <emphasis
+ role="bold">root.cell</emphasis> volume at the second level in
+ your cell's filespace just below the <emphasis
+ role="bold">/afs</emphasis> directory. Use the <emphasis
+ role="bold">fs mkmount</emphasis> command with the <emphasis
+ role="bold">-cell</emphasis> argument as instructed in <link
+ linkend="HDRWQ213">To create a cellular mount
+ point</link>.</para>
</listitem>
<listitem>
- <para>Mount AFS at the <emphasis role="bold">/afs</emphasis> directory on the client machine. The <emphasis
- role="bold">afsd</emphasis> program, which initializes the Cache Manager, performs the mount automatically at the
- directory named in the first field of the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file or by the
- command's <emphasis role="bold">-mountdir</emphasis> argument. Mounting AFS at an alternate location makes it impossible
- to reach the filespace of any cell that mounts its <emphasis role="bold">root.afs</emphasis> and <emphasis
- role="bold">root.cell</emphasis> volumes at the conventional locations. See <link linkend="HDRWQ395">Displaying and
- Setting the Cache Size and Location</link>.</para>
+ <para>Mount AFS at the <emphasis role="bold">/afs</emphasis>
+ directory on the client machine. The <emphasis
+ role="bold">afsd</emphasis> program, which initializes the
+ Cache Manager, performs the mount automatically at the
+ directory named in the first field of the local <emphasis
+ role="bold">/usr/vice/etc/cacheinfo</emphasis> file or by the
+ command's <emphasis role="bold">-mountdir</emphasis>
+ argument. Mounting AFS at an alternate location makes it
+ impossible to reach the filespace of any cell that mounts its
+ <emphasis role="bold">root.afs</emphasis> and <emphasis
+ role="bold">root.cell</emphasis> volumes at the conventional
+ locations. See <link linkend="HDRWQ395">Displaying and Setting
+ the Cache Size and Location</link>.</para>
</listitem>
<listitem>
- <para>Create an entry for the cell in the list of database server machines which the Cache Manager maintains in kernel
+ <para>Create an entry for the cell in the list of database
+ server machines which the Cache Manager maintains in kernel
memory.</para>
- <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on every client machine's local disk lists the
- database server machines for the local and foreign cells. The <emphasis role="bold">afsd</emphasis> program reads the
- contents of the <emphasis role="bold">CellServDB</emphasis> file into kernel memory as it initializes the Cache Manager.
- You can also use the <emphasis role="bold">fs newcell</emphasis> command to add or alter entries in kernel memory
- directly between reboots of the machine. See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server
- Machines</link>.</para>
- </listitem>
- </orderedlist></para>
-
- <para>Non-windows client machines may
- enable <emphasis role="bold">Dynamic Root Mode</emphasis> by using
- the <emphasis role="bold">-dynroot</emphasis> option
- to <emphasis role="bold">afsd</emphasis>. When this option is
- enabled, all cells listed in
- the <emphasis role="bold">CellServDB</emphasis> file will appear in
- the <emphasis role="bold">/afs</emphasis> directory. The contents of
- the <emphasis role="bold">root.afs</emphasis> volume will be ignored.
+ <para>The <emphasis
+ role="bold">/usr/vice/etc/CellServDB</emphasis> file on every
+ client machine's local disk lists the database server machines
+ for the local and foreign cells. The <emphasis
+ role="bold">afsd</emphasis> program reads the contents of the
+ <emphasis role="bold">CellServDB</emphasis> file into kernel
+ memory as it initializes the Cache Manager. You can also use
+ the <emphasis role="bold">fs newcell</emphasis> command to add
+ or alter entries in kernel memory directly between reboots of
+ the machine. See <link linkend="HDRWQ406">Maintaining
+ Knowledge of Database Server Machines</link>.</para>
+ </listitem>
+ </orderedlist>
</para>
- <para>Windows client machines may
- enable <emphasis role="bold">Freelance Mode</emphasis> during client
- installation or by setting
- the <emphasis role="bold">FreelanceClient</emphasis> setting
- under <emphasis role="bold">Service Parameters</emphasis> in the
- Windows Registry as mentioned in
- the <ulink url="http://docs.openafs.org/ReleaseNotesWindows/">Release
- Notes</ulink>. When this option is enabled,
- the <emphasis role="bold">root.afs</emphasis> volume is ignored and
- a mounpoint for each cell is automatically created in the
- the <emphasis role="bold">\\AFS</emphasis> directory when the
- folder <emphasis role="bold">\\AFS\<replaceable>cellname</replaceable></emphasis>
- is accessed and the foreign Volume Location servers can be reached.
- </para>
- <para>Note that making a foreign cell visible to client machines does not guarantee that your users can access its filespace.
- The ACLs in the foreign cell must also grant them the necessary permissions.</para>
+ <para>Non-windows client machines may enable <emphasis
+ role="bold">Dynamic Root Mode</emphasis> by using the <emphasis
+ role="bold">-dynroot</emphasis> option to <emphasis
+ role="bold">afsd</emphasis>. When this option is enabled, all cells
+ listed in the <emphasis role="bold">CellServDB</emphasis> file will
+ appear in the <emphasis role="bold">/afs</emphasis> directory. The
+ contents of the <emphasis role="bold">root.afs</emphasis> volume
+ will be ignored. </para>
+
+ <para>Windows client machines may enable <emphasis
+ role="bold">Freelance Mode</emphasis> during client installation or
+ by setting the <emphasis role="bold">FreelanceClient</emphasis>
+ setting under <emphasis role="bold">Service Parameters</emphasis> in
+ the Windows Registry as mentioned in the <ulink
+ url="http://docs.openafs.org/ReleaseNotesWindows/">Release
+ Notes</ulink>. When this option is enabled, the <emphasis
+ role="bold">root.afs</emphasis> volume is ignored and a mounpoint
+ for each cell is automatically created in the the <emphasis
+ role="bold">\\AFS</emphasis> directory when the folder <emphasis
+ role="bold">\\AFS\<replaceable>cellname</replaceable></emphasis> is
+ accessed and the foreign Volume Location servers can be reached.
+ </para> <para>Note that making a foreign cell visible to client
+ machines does not guarantee that your users can access its
+ filespace. The ACLs in the foreign cell must also grant them the
+ necessary permissions.</para>
<indexterm>
<primary>cell</primary>
</sect2>
<sect2 id="HDRWQ40">
- <title>Granting and Denying Foreign Users Access to Your Cell</title>
-
- <para>Making your cell visible in the AFS global namespace does not take away your control over the way in which users from
- foreign cells access your file tree.</para>
-
- <para>By default, foreign users access your cell as the user <emphasis role="bold">anonymous</emphasis>, which means they have
- only the permissions granted to the <emphasis role="bold">system:anyuser</emphasis> group on each directory's ACL. Normally
- these permissions are limited to the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and
- <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permissions.</para>
-
- <para>There are three ways to grant wider access to foreign users: <itemizedlist>
+ <title>Granting and Denying Foreign Users Access to Your
+ Cell</title>
+
+ <para>Making your cell visible in the AFS global namespace does not
+ take away your control over the way in which users from foreign
+ cells access your file tree.</para>
+
+ <para>By default, foreign users access your cell as the user
+ <emphasis role="bold">anonymous</emphasis>, which means they have
+ only the permissions granted to the <emphasis
+ role="bold">system:anyuser</emphasis> group on each directory's
+ ACL. Normally these permissions are limited to the <emphasis
+ role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
+ and <emphasis role="bold">r</emphasis> (<emphasis
+ role="bold">read</emphasis>) permissions.</para>
+
+ <para>There are three ways to grant wider access to foreign users:
+ <itemizedlist>
<listitem>
- <para>Grant additional permissions to the <emphasis role="bold">system:anyuser</emphasis> group on certain ACLs. Keep in
- mind, however, that all users can then access that directory in the indicated way (not just specific foreign users you
- have in mind).</para>
+ <para>Grant additional permissions to the <emphasis
+ role="bold">system:anyuser</emphasis> group on certain
+ ACLs. Keep in mind, however, that all users can then access
+ that directory in the indicated way (not just specific foreign
+ users you have in mind).</para>
</listitem>
<listitem>
<para>Enable automatic registration for users in the foreign
- cell. This may be done by creating a cross-realm trust in
- the <emphasis role="bold">Kerberos Database</emphasis>. Then
- add a PTS group
- named <emphasis role="bold">system:authuser<replaceable>@FOREIGN.REALM</replaceable></emphasis>
+ cell. This may be done by creating a cross-realm trust in the
+ <emphasis role="bold">Kerberos Database</emphasis>. Then add a
+ PTS group named <emphasis
+ role="bold">system:authuser<replaceable>@FOREIGN.REALM</replaceable></emphasis>
and give it a group quota greater than the number of foreign
users expected to be registered. After the cross-realm trust
- and the PTS group are created,
- the <ulink url="http://docs.openafs.org/Reference/1/aklog.html">aklog</ulink>
+ and the PTS group are created, the <ulink
+ url="http://docs.openafs.org/Reference/1/aklog.html">aklog</ulink>
command will automatically register foreign users as
- needed. Consult the documentation for
- your <emphasis role="bold">Kerberos Server</emphasis> for
- instructions on how to establish a cross-realm trust.
- </para>
+ needed. Consult the documentation for your <emphasis
+ role="bold">Kerberos Server</emphasis> for instructions on how
+ to establish a cross-realm trust. </para>
</listitem>
<listitem>
foreign users, by creating entries in the Protection Database,
the Kerberos Database, and the local password file.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
<indexterm>
<primary>cell</primary>
<sect1 id="HDRWQ41">
<title>Configuring Your AFS Filespace</title>
- <para>This section summarizes the issues to consider when configuring your AFS filespace. For a discussion of creating volumes
- that correspond most efficiently to the filespace's directory structure, see <link linkend="HDRWQ44">Creating Volumes to
- Simplify Administration</link>.</para>
+ <para>This section summarizes the issues to consider when configuring
+ your AFS filespace. For a discussion of creating volumes that
+ correspond most efficiently to the filespace's directory structure,
+ see <link linkend="HDRWQ44">Creating Volumes to Simplify
+ Administration</link>.</para>
<note>
- <para><emphasis role="bold">For Windows users:</emphasis> Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather
- than a forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname. The hierarchical
- organization of the filespace is however the same as on a UNIX machine.</para>
+ <para><emphasis role="bold">For Windows users:</emphasis> Windows
+ uses a backslash (<emphasis role="bold">\</emphasis>) rather than a
+ forward slash (<emphasis role="bold">/</emphasis>) to separate the
+ elements in a pathname. The hierarchical organization of the
+ filespace is however the same as on a UNIX machine.</para>
</note>
- <para>AFS pathnames must follow a few conventions so the AFS global namespace looks the same from any AFS client machine. There
- are corresponding conventions to follow in building your file tree, not just because pathnames reflect the structure of a file
- tree, but also because the AFS Cache Manager expects a certain configuration.</para>
+ <para>AFS pathnames must follow a few conventions so the AFS global
+ namespace looks the same from any AFS client machine. There are
+ corresponding conventions to follow in building your file tree, not
+ just because pathnames reflect the structure of a file tree, but also
+ because the AFS Cache Manager expects a certain configuration.</para>
<indexterm>
<primary>AFS</primary>
<sect2 id="Header_51">
<title>The Top /afs Level</title>
- <para>The first convention is that the top level in your file tree be called the <emphasis role="bold">/afs</emphasis>
- directory. If you name it something else, then you must use the <emphasis role="bold">-mountdir</emphasis> argument with the
- <emphasis role="bold">afsd</emphasis> program to get Cache Managers to mount AFS properly. You cannot participate in the AFS
- global namespace in that case.</para>
+ <para>The first convention is that the top level in your file tree
+ be called the <emphasis role="bold">/afs</emphasis> directory. If
+ you name it something else, then you must use the <emphasis
+ role="bold">-mountdir</emphasis> argument with the <emphasis
+ role="bold">afsd</emphasis> program to get Cache Managers to mount
+ AFS properly. You cannot participate in the AFS global namespace in
+ that case.</para>
<indexterm>
<primary>cell</primary>
<sect2 id="HDRWQ42">
<title>The Second (Cellname) Level</title>
- <para>The second convention is that just below the <emphasis role="bold">/afs</emphasis> directory you place directories
- corresponding to each cell whose file tree is visible and accessible from the local cell. Minimally, there must be a directory
- for the local cell. Each such directory is a mount point to the indicated cell's <emphasis role="bold">root.cell</emphasis>
- volume. For example, in the ABC Corporation cell, <emphasis role="bold">/afs/abc.com</emphasis> is a mount point for the
- cell's own <emphasis role="bold">root.cell</emphasis> volume and <emphasis role="bold">stateu.edu</emphasis> is a mount point
- for the State University cell's <emphasis role="bold">root.cell</emphasis> volume. The <emphasis role="bold">fs
- lsmount</emphasis> command displays the mount points.</para>
-
- <programlisting>
- % <emphasis role="bold">fs lsmount /afs/abc.com</emphasis>
+ <para>The second convention is that just below the <emphasis
+ role="bold">/afs</emphasis> directory you place directories
+ corresponding to each cell whose file tree is visible and accessible
+ from the local cell. Minimally, there must be a directory for the
+ local cell. Each such directory is a mount point to the indicated
+ cell's <emphasis role="bold">root.cell</emphasis> volume. For
+ example, in the ABC Corporation cell, <emphasis
+ role="bold">/afs/abc.com</emphasis> is a mount point for the cell's
+ own <emphasis role="bold">root.cell</emphasis> volume and <emphasis
+ role="bold">stateu.edu</emphasis> is a mount point for the State
+ University cell's <emphasis role="bold">root.cell</emphasis>
+ volume. The <emphasis role="bold">fs lsmount</emphasis> command
+ displays the mount points.</para>
+
+<programlisting>
+ % <emphasis role="bold">fs lsmount /afs/abc.com</emphasis>
'/afs/abc.com' is a mount point for volume '#root.cell'
% <emphasis role="bold">fs lsmount /afs/stateu.edu</emphasis>
'/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
</programlisting>
- <para>To reduce the amount of typing necessary in pathnames, you can create a symbolic link with an abbreviated name to the
- mount point of each cell your users frequently access (particularly the home cell). In the ABC Corporation cell, for instance,
- <emphasis role="bold">/afs/abc</emphasis> is a symbolic link to the <emphasis role="bold">/afs/abc.com</emphasis> mount point,
- as the <emphasis role="bold">fs lsmount</emphasis> command reveals.</para>
+ <para>To reduce the amount of typing necessary in pathnames, you can
+ create a symbolic link with an abbreviated name to the mount point
+ of each cell your users frequently access (particularly the home
+ cell). In the ABC Corporation cell, for instance, <emphasis
+ role="bold">/afs/abc</emphasis> is a symbolic link to the <emphasis
+ role="bold">/afs/abc.com</emphasis> mount point, as the <emphasis
+ role="bold">fs lsmount</emphasis> command reveals.</para>
- <programlisting>
+<programlisting>
% <emphasis role="bold">fs lsmount /afs/abc</emphasis>
- '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
-</programlisting>
+ '/afs/abc' is a symbolic link, leading to a mount point for volume
+'#root.cell' </programlisting>
<indexterm>
<primary>file tree</primary>
<sect2 id="HDRWQ43">
<title>The Third Level</title>
- <para>You can organize the third level of your cell's file tree any way you wish. The following list describes directories
- that appear at this level in the conventional configuration: <variablelist>
+ <para>You can organize the third level of your cell's file tree any
+ way you wish. The following list describes directories that appear
+ at this level in the conventional configuration:
+ <variablelist>
<varlistentry>
<term><emphasis role="bold">common</emphasis></term>
<listitem>
- <para>This directory contains programs and files needed by users working on machines of all system types, such as text
- editors, online documentation files, and so on. Its <emphasis role="bold">/etc</emphasis> subdirectory is a logical
- place to keep the central update sources for files used on all of your cell's client machines, such as the <emphasis
- role="bold">ThisCell</emphasis> and <emphasis role="bold">CellServDB</emphasis> files.</para>
+ <para>This directory contains programs and files needed by
+ users working on machines of all system types, such as text
+ editors, online documentation files, and so on. Its
+ <emphasis role="bold">/etc</emphasis> subdirectory is a
+ logical place to keep the central update sources for files
+ used on all of your cell's client machines, such as the
+ <emphasis role="bold">ThisCell</emphasis> and <emphasis
+ role="bold">CellServDB</emphasis> files.</para>
</listitem>
</varlistentry>
<term><emphasis role="bold">public</emphasis></term>
<listitem>
- <para>A directory accessible to anyone who can access your filespace, because its ACL grants the <emphasis
- role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
- role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group. It is useful if
- you want to enable your users to make selected information available to everyone, but do not want to grant foreign
- users access to the contents of the <emphasis role="bold">usr</emphasis> directory which houses user home directories
- (and is also at this level). It is conventional to create a subdirectory for each of your cell's users.</para>
+ <para>A directory accessible to anyone who can access your
+ filespace, because its ACL grants the <emphasis
+ role="bold">l</emphasis> (<emphasis
+ role="bold">lookup</emphasis>) and <emphasis
+ role="bold">r</emphasis> (<emphasis
+ role="bold">read</emphasis>) permissions to the <emphasis
+ role="bold">system:anyuser</emphasis> group. It is useful if
+ you want to enable your users to make selected information
+ available to everyone, but do not want to grant foreign
+ users access to the contents of the <emphasis
+ role="bold">usr</emphasis> directory which houses user home
+ directories (and is also at this level). It is conventional
+ to create a subdirectory for each of your cell's
+ users.</para>
</listitem>
</varlistentry>
<term><emphasis role="bold">service</emphasis></term>
<listitem>
- <para>This directory contains files and subdirectories that help cells coordinate resource sharing. For a list of the
- proposed standard files and subdirectories to create, call or write to AFS Product Support.</para>
+ <para>This directory contains files and subdirectories that
+ help cells coordinate resource sharing. For a list of the
+ proposed standard files and subdirectories to create, call
+ or write to AFS Product Support.</para>
- <para>As an example, files that other cells expect to find in this directory's <emphasis role="bold">etc</emphasis>
+ <para>As an example, files that other cells expect to find
+ in this directory's <emphasis role="bold">etc</emphasis>
subdirectory can include the following: <itemizedlist>
<listitem>
- <para><emphasis role="bold">CellServDB.export</emphasis>, a list of database server machines for many
- cells</para>
+ <para><emphasis
+ role="bold">CellServDB.export</emphasis>, a list of
+ database server machines for many cells</para>
</listitem>
<listitem>
- <para><emphasis role="bold">CellServDB.local</emphasis>, a list of the cell's own database server
- machines</para>
+ <para><emphasis
+ role="bold">CellServDB.local</emphasis>, a list of the
+ cell's own database server machines</para>
</listitem>
<listitem>
- <para><emphasis role="bold">passwd</emphasis>, a copy of the local password file (<emphasis
- role="bold">/etc/passwd</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
+ <para><emphasis role="bold">passwd</emphasis>, a copy
+ of the local password file (<emphasis
+ role="bold">/etc/passwd</emphasis> or equivalent) kept
+ on the local disk of the cell's client machines</para>
</listitem>
<listitem>
- <para><emphasis role="bold">group</emphasis>, a copy of the local groups file (<emphasis
- role="bold">/etc/group</emphasis> or equivalent) kept on the local disk of the cell's client machines</para>
+ <para><emphasis role="bold">group</emphasis>, a copy
+ of the local groups file (<emphasis
+ role="bold">/etc/group</emphasis> or equivalent) kept
+ on the local disk of the cell's client machines</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</listitem>
</varlistentry>
<term><emphasis>sys_type</emphasis></term>
<listitem>
- <para>A separate directory for storing the server and client binaries for each system type you use in the cell.
- Configuration is simplest if you use the system type names assigned in the AFS distribution, particularly if you wish
- to use the <emphasis role="bold">@sys</emphasis> variable in pathnames (see <link linkend="HDRWQ56">Using the @sys
- Variable in Pathnames</link>). The <emphasis>OpenAFS Release Notes</emphasis> lists the conventional name for each
+ <para>A separate directory for storing the server and client
+ binaries for each system type you use in the cell.
+ Configuration is simplest if you use the system type names
+ assigned in the AFS distribution, particularly if you wish
+ to use the <emphasis role="bold">@sys</emphasis> variable in
+ pathnames (see <link linkend="HDRWQ56">Using the @sys
+ Variable in Pathnames</link>). The <emphasis>OpenAFS Release
+ Notes</emphasis> lists the conventional name for each
supported system type.</para>
- <para>Within each such directory, create directories named <emphasis role="bold">bin</emphasis>, <emphasis
- role="bold">etc</emphasis>, <emphasis role="bold">usr</emphasis>, and so on, to store the programs normally kept in
- the <emphasis role="bold">/bin</emphasis>, <emphasis role="bold">/etc</emphasis> and <emphasis
- role="bold">/usr</emphasis> directories on a local disk. Then create symbolic links from the local directories on
- client machines into AFS; see <link linkend="HDRWQ55">Configuring the Local Disk</link>. Even if you do not choose to
- use symbolic links in this way, it can be convenient to have central copies of system binaries in AFS. If binaries are
- accidentally removed from a machine, you can recopy them onto the local disk from AFS rather than having to recover
- them from tape</para>
+ <para>Within each such directory, create directories named
+ <emphasis role="bold">bin</emphasis>, <emphasis
+ role="bold">etc</emphasis>, <emphasis
+ role="bold">usr</emphasis>, and so on, to store the programs
+ normally kept in the <emphasis role="bold">/bin</emphasis>,
+ <emphasis role="bold">/etc</emphasis> and <emphasis
+ role="bold">/usr</emphasis> directories on a local
+ disk. Then create symbolic links from the local directories
+ on client machines into AFS; see <link
+ linkend="HDRWQ55">Configuring the Local Disk</link>. Even if
+ you do not choose to use symbolic links in this way, it can
+ be convenient to have central copies of system binaries in
+ AFS. If binaries are accidentally removed from a machine,
+ you can recopy them onto the local disk from AFS rather than
+ having to recover them from tape</para>
</listitem>
</varlistentry>
<term><emphasis role="bold">usr</emphasis></term>
<listitem>
- <para>This directory contains home directories for your local users. As discussed in the previous entry for the
- <emphasis role="bold">public</emphasis> directory, it is often practical to protect this directory so that only
- locally authenticated users can access it. This keeps the contents of your user's home directories as secure as
+ <para>This directory contains home directories for your
+ local users. As discussed in the previous entry for the
+ <emphasis role="bold">public</emphasis> directory, it is
+ often practical to protect this directory so that only
+ locally authenticated users can access it. This keeps the
+ contents of your user's home directories as secure as
possible.</para>
- <para>If your cell is quite large, directory lookup can be slowed if you put all home directories in a single
- <emphasis role="bold">usr</emphasis> directory. For suggestions on distributing user home directories among multiple
- grouping directories, see <link linkend="HDRWQ59">Grouping Home Directories</link>.</para>
- </listitem>
- </varlistentry>
+ <para>If your cell is quite large, directory lookup can be
+ slowed if you put all home directories in a single <emphasis
+ role="bold">usr</emphasis> directory. For suggestions on
+ distributing user home directories among multiple grouping
+ directories, see <link linkend="HDRWQ59">Grouping Home
+ Directories</link>.</para>
+ </listitem> </varlistentry>
<varlistentry>
<term><emphasis role="bold">wsadmin</emphasis></term>
<listitem>
- <para>This directory contains prototype, configuration and library files for use with the <emphasis
- role="bold">package</emphasis> program. See <link linkend="HDRWQ419">Configuring Client Machines with the package
- Program</link>.</para>
+ <para>This directory contains prototype, configuration and
+ library files for use with the <emphasis
+ role="bold">package</emphasis> program. See <link
+ linkend="HDRWQ419">Configuring Client Machines with the
+ package Program</link>.</para>
</listitem>
</varlistentry>
- </variablelist></para>
+ </variablelist>
+ </para>
<indexterm>
<primary>volume name</primary>
<indexterm>
<primary>file tree</primary>
- <secondary>creating volumes to match top level directories</secondary>
+ <secondary>creating volumes to match top level
+ directories</secondary>
</indexterm>
</sect2>
</sect1>
<sect1 id="HDRWQ44">
<title>Creating Volumes to Simplify Administration</title>
- <para>This section discusses how to create volumes in ways that make administering your system easier.</para>
-
- <para>At the top levels of your file tree (at least through the third level), each directory generally corresponds to a separate
- volume. Some cells also configure the subdirectories of some third level directories as separate volumes. Common examples are
- the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/common</emphasis> and
- <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis>
- directories.</para>
-
- <para>You do not have to create a separate volume for every directory level in a tree, but the advantage is that each volume
- tends to be smaller and easier to move for load balancing. The overhead for a mount point is no greater than for a standard
- directory, nor does the volume structure itself require much disk space. Most cells find that below the fourth level in the
- tree, using a separate volume for each directory is no longer efficient. For instance, while each user's home directory (at the
- fourth level in the tree) corresponds to a separate volume, all of the subdirectories in the home directory normally reside in
- the same volume.</para>
-
- <para>Keep in mind that only one volume can be mounted at a given directory location in the tree. In contrast, a volume can be
- mounted at several locations, though this is not recommended because it distorts the hierarchical nature of the file tree,
- potentially causing confusion.</para>
+ <para>This section discusses how to create volumes in ways that make
+ administering your system easier.</para>
+
+ <para>At the top levels of your file tree (at least through the third
+ level), each directory generally corresponds to a separate
+ volume. Some cells also configure the subdirectories of some third
+ level directories as separate volumes. Common examples are the
+ <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/common</emphasis> and <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/usr</emphasis> directories.</para>
+
+ <para>You do not have to create a separate volume for every directory
+ level in a tree, but the advantage is that each volume tends to be
+ smaller and easier to move for load balancing. The overhead for a
+ mount point is no greater than for a standard directory, nor does the
+ volume structure itself require much disk space. Most cells find that
+ below the fourth level in the tree, using a separate volume for each
+ directory is no longer efficient. For instance, while each user's home
+ directory (at the fourth level in the tree) corresponds to a separate
+ volume, all of the subdirectories in the home directory normally
+ reside in the same volume.</para>
+
+ <para>Keep in mind that only one volume can be mounted at a given
+ directory location in the tree. In contrast, a volume can be mounted
+ at several locations, though this is not recommended because it
+ distorts the hierarchical nature of the file tree, potentially causing
+ confusion.</para>
<indexterm>
<primary>volume name</primary>
<sect2 id="Header_55">
<title>Assigning Volume Names</title>
- <para>You can name your volumes anything you choose, subject to a few restrictions: <itemizedlist>
+ <para>You can name your volumes anything you choose, subject to a
+ few restrictions:
+ <itemizedlist>
<listitem>
- <para>Read/write volume names can be up to 22 characters in length. The maximum length for volume names is 31
- characters, and there must be room to add the <emphasis role="bold">.readonly</emphasis> extension on read-only
+ <para>Read/write volume names can be up to 22 characters in
+ length. The maximum length for volume names is 31 characters,
+ and there must be room to add the <emphasis
+ role="bold">.readonly</emphasis> extension on read-only
volumes.</para>
</listitem>
<listitem>
- <para>Do not add the <emphasis role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extensions
- to volume names yourself, even if they are appropriate. The Volume Server adds them automatically as it creates a
- read-only or backup version of a volume.</para>
+ <para>Do not add the <emphasis
+ role="bold">.readonly</emphasis> and <emphasis
+ role="bold">.backup</emphasis> extensions to volume names
+ yourself, even if they are appropriate. The Volume Server adds
+ them automatically as it creates a read-only or backup version
+ of a volume.</para>
</listitem>
<listitem>
- <para>There must be volumes named <emphasis role="bold">root.afs</emphasis> and <emphasis
- role="bold">root.cell</emphasis>, mounted respectively at the top (<emphasis role="bold">/afs</emphasis>) level in the
- filespace and just below that level, at the cell's name (for example, at <emphasis role="bold">/afs/abc.com</emphasis>
- in the ABC Corporation cell).</para>
-
- <para>Deviating from these names only creates confusion and extra work. Changing the name of the <emphasis
- role="bold">root.afs</emphasis> volume, for instance, means that you must use the <emphasis
- role="bold">-rootvol</emphasis> argument to the <emphasis role="bold">afsd</emphasis> program on every client machine,
+ <para>There must be volumes named <emphasis
+ role="bold">root.afs</emphasis> and <emphasis
+ role="bold">root.cell</emphasis>, mounted respectively at the
+ top (<emphasis role="bold">/afs</emphasis>) level in the
+ filespace and just below that level, at the cell's name (for
+ example, at <emphasis role="bold">/afs/abc.com</emphasis> in
+ the ABC Corporation cell).</para>
+
+ <para>Deviating from these names only creates confusion and
+ extra work. Changing the name of the <emphasis
+ role="bold">root.afs</emphasis> volume, for instance, means
+ that you must use the <emphasis
+ role="bold">-rootvol</emphasis> argument to the <emphasis
+ role="bold">afsd</emphasis> program on every client machine,
to name the alternate volume.</para>
- <para>Similarly, changing the <emphasis role="bold">root.cell</emphasis> volume name prevents users in foreign cells
- from accessing your filespace, if the mount point for your cell in their filespace refers to the conventional <emphasis
- role="bold">root.cell</emphasis> name. Of course, this is one way to make your cell invisible to other cells.</para>
+ <para>Similarly, changing the <emphasis
+ role="bold">root.cell</emphasis> volume name prevents users in
+ foreign cells from accessing your filespace, if the mount
+ point for your cell in their filespace refers to the
+ conventional <emphasis role="bold">root.cell</emphasis>
+ name. Of course, this is one way to make your cell invisible
+ to other cells.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>It is best to assign volume names that indicate the type of data they contain, and to use similar names for volumes with
- similar contents. It is also helpful if the volume name is similar to (or at least has elements in common with) the name of
- the directory at which it is mounted. Understanding the pattern then enables you accurately to guess what a volume contains
- and where it is mounted.</para>
+ <para>It is best to assign volume names that indicate the type of
+ data they contain, and to use similar names for volumes with similar
+ contents. It is also helpful if the volume name is similar to (or at
+ least has elements in common with) the name of the directory at
+ which it is mounted. Understanding the pattern then enables you
+ accurately to guess what a volume contains and where it is
+ mounted.</para>
- <para>Many cells find that the most effective volume naming scheme puts a common prefix on the names of all related volumes.
- <link linkend="TBLVOL-PREFIX">Table 1</link> describes the recommended prefixing scheme.</para>
+ <para>Many cells find that the most effective volume naming scheme
+ puts a common prefix on the names of all related volumes. <link
+ linkend="TBLVOL-PREFIX">Table 1</link> describes the recommended
+ prefixing scheme.</para>
<table id="TBLVOL-PREFIX" label="1">
<title>Suggested volume prefixes</title>
<entry><emphasis role="bold">Example Name</emphasis></entry>
- <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
+ <entry><emphasis role="bold">Example Mount
+ Point</emphasis></entry>
</row>
</thead>
<entry><emphasis role="bold">common.etc</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/common/etc</emphasis></entry>
</row>
<entry><emphasis role="bold">src.afs</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/src/afs</emphasis></entry>
</row>
<entry><emphasis role="bold">proj.portafs</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/proj/portafs</emphasis></entry>
</row>
<entry><emphasis role="bold">test.smith</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/usr/smith/test</emphasis></entry>
</row>
<entry><emphasis role="bold">user.terry</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/usr/terry</emphasis></entry>
</row>
<row>
<entry>sys_type<emphasis role="bold">.</emphasis></entry>
- <entry>programs compiled for an operating system type</entry>
+ <entry>programs compiled for an operating system
+ type</entry>
<entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/bin</emphasis></entry>
</row>
</tbody>
</tgroup>
</table>
- <para><link linkend="TBLPREFIX-EXAMPLE">Table 2</link> is a more specific example for a cell's <emphasis
- role="bold">rs_aix42</emphasis> system volumes and directories:</para>
+ <para><link linkend="TBLPREFIX-EXAMPLE">Table 2</link> is a more
+ specific example for a cell's <emphasis
+ role="bold">rs_aix42</emphasis> system volumes and
+ directories:</para>
<table id="TBLPREFIX-EXAMPLE" label="2">
<title>Example volume-prefixing scheme</title>
<row>
<entry><emphasis role="bold">Example Name</emphasis></entry>
- <entry><emphasis role="bold">Example Mount Point</emphasis></entry>
+ <entry><emphasis role="bold">Example Mount
+ Point</emphasis></entry>
</row>
</thead>
<row>
<entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/bin</emphasis>, <emphasis
- role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/rs_aix42/bin</emphasis></entry>
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/rs_aix42/bin</emphasis></entry>
</row>
<row>
<entry><emphasis role="bold">rs_aix42.etc</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/etc</emphasis></entry>
</row>
<row>
<entry><emphasis role="bold">rs_aix42.usr</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr</emphasis></entry>
</row>
<row>
- <entry><emphasis role="bold">rs_aix42.usr.afsws</emphasis></entry>
+ <entry><emphasis
+ role="bold">rs_aix42.usr.afsws</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr/afsws</emphasis></entry>
</row>
<row>
- <entry><emphasis role="bold">rs_aix42.usr.lib</emphasis></entry>
+ <entry><emphasis
+ role="bold">rs_aix42.usr.lib</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr/lib</emphasis></entry>
</row>
<row>
- <entry><emphasis role="bold">rs_aix42.usr.bin</emphasis></entry>
+ <entry><emphasis
+ role="bold">rs_aix42.usr.bin</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr/bin</emphasis></entry>
</row>
<row>
- <entry><emphasis role="bold">rs_aix42.usr.etc</emphasis></entry>
+ <entry><emphasis
+ role="bold">rs_aix42.usr.etc</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr/etc</emphasis></entry>
</row>
<row>
- <entry><emphasis role="bold">rs_aix42.usr.inc</emphasis></entry>
+ <entry><emphasis
+ role="bold">rs_aix42.usr.inc</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr/inc</emphasis></entry>
</row>
<row>
- <entry><emphasis role="bold">rs_aix42.usr.man</emphasis></entry>
+ <entry><emphasis
+ role="bold">rs_aix42.usr.man</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr/man</emphasis></entry>
</row>
<row>
- <entry><emphasis role="bold">rs_aix42.usr.sys</emphasis></entry>
+ <entry><emphasis
+ role="bold">rs_aix42.usr.sys</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr/sys</emphasis></entry>
</row>
<row>
- <entry><emphasis role="bold">rs_aix42.usr.local</emphasis></entry>
+ <entry><emphasis
+ role="bold">rs_aix42.usr.local</emphasis></entry>
- <entry><emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <entry><emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/rs_aix42/usr/local</emphasis></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>There are several advantages to this scheme: <itemizedlist>
+ <para>There are several advantages to this scheme:
+ <itemizedlist>
<listitem>
- <para>The volume name is similar to the mount point name in the filespace. In all of the entries in <link
- linkend="TBLPREFIX-EXAMPLE">Table 2</link>, for example, the only difference between the volume and mount point name is
- that the former uses periods as separators and the latter uses slashes. Another advantage is that the volume name
- indicates the contents, or at least suggests the directory on which to issue the <emphasis role="bold">ls</emphasis>
- command to learn the contents.</para>
+ <para>The volume name is similar to the mount point name in
+ the filespace. In all of the entries in <link
+ linkend="TBLPREFIX-EXAMPLE">Table 2</link>, for example, the
+ only difference between the volume and mount point name is
+ that the former uses periods as separators and the latter uses
+ slashes. Another advantage is that the volume name indicates
+ the contents, or at least suggests the directory on which to
+ issue the <emphasis role="bold">ls</emphasis> command to learn
+ the contents.</para>
</listitem>
<listitem>
- <para>It makes it easy to manipulate groups of related volumes at one time. In particular, the <emphasis role="bold">vos
- backupsys</emphasis> command's <emphasis role="bold">-prefix</emphasis> argument enables you to create a backup version
- of every volume whose name starts with the same string of characters. Making a backup version of each volume is one of
- the first steps in backing up a volume with the AFS Backup System, and doing it for many volumes with one command saves
- you a good deal of typing. For instructions for creating backup volumes, see <link linkend="HDRWQ201">Creating Backup
- Volumes</link>, For information on the AFS Backup System, see <link linkend="HDRWQ248">Configuring the AFS Backup
- System</link> and <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
+ <para>It makes it easy to manipulate groups of related volumes
+ at one time. In particular, the <emphasis role="bold">vos
+ backupsys</emphasis> command's <emphasis
+ role="bold">-prefix</emphasis> argument enables you to create
+ a backup version of every volume whose name starts with the
+ same string of characters. Making a backup version of each
+ volume is one of the first steps in backing up a volume with
+ the AFS Backup System, and doing it for many volumes with one
+ command saves you a good deal of typing. For instructions for
+ creating backup volumes, see <link linkend="HDRWQ201">Creating
+ Backup Volumes</link>, For information on the AFS Backup
+ System, see <link linkend="HDRWQ248">Configuring the AFS
+ Backup System</link> and <link linkend="HDRWQ283">Backing Up
+ and Restoring AFS Data</link>.</para>
</listitem>
<listitem>
- <para>It makes it easy to group related volumes together on a partition. Grouping related volumes together has several
- advantages of its own, discussed in <link linkend="HDRWQ49">Grouping Related Volumes on a Partition</link>.</para>
+ <para>It makes it easy to group related volumes together on a
+ partition. Grouping related volumes together has several
+ advantages of its own, discussed in <link
+ linkend="HDRWQ49">Grouping Related Volumes on a
+ Partition</link>.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
<indexterm>
<primary>volume</primary>
<sect2 id="HDRWQ49">
<title>Grouping Related Volumes on a Partition</title>
- <para>If your cell is large enough to make it practical, consider grouping related volumes together on a partition. In
- general, you need at least three file server machines for volume grouping to be effective. Grouping has several advantages,
- which are most obvious when the file server machine becomes inaccessible: <itemizedlist>
+ <para>If your cell is large enough to make it practical, consider
+ grouping related volumes together on a partition. In general, you
+ need at least three file server machines for volume grouping to be
+ effective. Grouping has several advantages, which are most obvious
+ when the file server machine becomes inaccessible:
+ <itemizedlist>
<listitem>
- <para>If you keep a hardcopy record of the volumes on a partition, you know which volumes are unavailable. You can keep
- such a record without grouping related volumes, but a list composed of unrelated volumes is much harder to maintain.
- Note that the record must be on paper, because the outage can prevent you from accessing an online copy or from issuing
- the <emphasis role="bold">vos listvol</emphasis> command, which gives you the same information.</para>
+ <para>If you keep a hardcopy record of the volumes on a
+ partition, you know which volumes are unavailable. You can
+ keep such a record without grouping related volumes, but a
+ list composed of unrelated volumes is much harder to maintain.
+ Note that the record must be on paper, because the outage can
+ prevent you from accessing an online copy or from issuing the
+ <emphasis role="bold">vos listvol</emphasis> command, which
+ gives you the same information.</para>
</listitem>
<listitem>
- <para>The effect of an outage is more localized. For example, if all of the binaries for a given system type are on one
- partition, then only users of that system type are affected. If a partition houses binary volumes from several system
- types, then an outage can affect more people, particularly if the binaries that remain available are interdependent with
- those that are not available.</para>
+ <para>The effect of an outage is more localized. For example,
+ if all of the binaries for a given system type are on one
+ partition, then only users of that system type are
+ affected. If a partition houses binary volumes from several
+ system types, then an outage can affect more people,
+ particularly if the binaries that remain available are
+ interdependent with those that are not available.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>The advantages of grouping related volumes on a partition do not necessarily extend to the grouping of all related
- volumes on one file server machine. For instance, it is probably unwise in a cell with two file server machines to put all
- system volumes on one machine and all user volumes on the other. An outage of either machine probably affects everyone.</para>
+ <para>The advantages of grouping related volumes on a partition do
+ not necessarily extend to the grouping of all related volumes on one
+ file server machine. For instance, it is probably unwise in a cell
+ with two file server machines to put all system volumes on one
+ machine and all user volumes on the other. An outage of either
+ machine probably affects everyone.</para>
- <para>Admittedly, the need to move volumes for load balancing purposes can limit the practicality of grouping related volumes.
+ <para>Admittedly, the need to move volumes for load balancing
+ purposes can limit the practicality of grouping related volumes.
You need to weigh the complementary advantages case by case.</para>
<indexterm>
<sect2 id="HDRWQ50">
<title>When to Replicate Volumes</title>
- <para>As discussed in <link linkend="HDRWQ15">Replication</link>, replication refers to making a copy, or clone, of a
- read/write source volume and then placing the copy on one or more additional file server machines. Replicating a volume can
- increase the availability of the contents. If one file server machine housing the volume becomes inaccessible, users can still
- access the copy of the volume stored on a different machine. No one machine is likely to become overburdened with requests for
- a popular file, either, because the file is available from several machines.</para>
-
- <para>However, replication is not appropriate for all cells. If a cell does not have much disk space, replication can be
- unduly expensive, because each clone not on the same partition as the read/write source takes up as much disk space as its
- source volume did at the time the clone was made. Also, if you have only one file server machine, replication uses up disk
- space without increasing availability.</para>
-
- <para>Replication is also not appropriate for volumes that change frequently. You must issue the <emphasis role="bold">vos
- release</emphasis> command every time you need to update a read-only volume to reflect changes in its read/write
- source.</para>
-
- <para>For both of these reasons, replication is appropriate only for popular volumes whose contents do not change very often,
- such as system binaries and other volumes mounted at the upper levels of your filespace. User volumes usually exist only in a
- read/write version since they change so often.</para>
-
- <para>If you are replicating any volumes, you must replicate the <emphasis role="bold">root.afs</emphasis> and <emphasis
- role="bold">root.cell</emphasis> volumes, preferably at two or three sites each (even if your cell only has two or three file
- server machines). The Cache Manager needs to pass through the directories corresponding to the <emphasis
- role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes as it interprets any pathname. The
- unavailability of these volumes makes all other volumes unavailable too, even if the file server machines storing the other
- volumes are still functioning.</para>
-
- <para>Another reason to replicate the <emphasis role="bold">root.afs</emphasis> volume is that it can lessen the load on the
- File Server machine. The Cache Manager has a bias to access a read-only version of the <emphasis
- role="bold">root.afs</emphasis> volume if it is replicate, which puts the Cache Manager onto the <emphasis>read-only
- path</emphasis> through the AFS filespace. While on the read-only path, the Cache Manager attempts to access a read-only copy
- of replicated volumes. The File Server needs to track only one callback per Cache Manager for all of the data in a read-only
- volume, rather than the one callback per file it must track for read/write volumes. Fewer callbacks translate into a smaller
- load on the File Server.</para>
-
- <para>If the <emphasis role="bold">root.afs</emphasis> volume is not replicated, the Cache Manager follows a read/write path
- through the filespace, accessing the read/write version of each volume. The File Server distributes and tracks a separate
- callback for each file in a read/write volume, imposing a greater load on it.</para>
-
- <para>For more on read/write and read-only paths, see <link linkend="HDRWQ209">The Rules of Mount Point
- Traversal</link>.</para>
-
- <para>It also makes sense to replicate system binary volumes in many cases, as well as the volume corresponding to the
- <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/usr</emphasis> directory and
- the volumes corresponding to the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
- role="bold">/common</emphasis> directory and its subdirectories.</para>
-
- <para>It is a good idea to place a replica on the same partition as the read/write source. In this case, the read-only volume
- is a clone (like a backup volume): it is a copy of the source volume's vnode index, rather than a full copy of the volume
- contents. Only if the read/write volume moves to another partition or changes substantially does the read-only volume consume
- significant disk space. Read-only volumes kept on other partitions always consume the full amount of disk space that the
- read/write source consumed when the read-only volume was created.</para>
+ <para>As discussed in <link linkend="HDRWQ15">Replication</link>,
+ replication refers to making a copy, or clone, of a read/write
+ source volume and then placing the copy on one or more additional
+ file server machines. Replicating a volume can increase the
+ availability of the contents. If one file server machine housing the
+ volume becomes inaccessible, users can still access the copy of the
+ volume stored on a different machine. No one machine is likely to
+ become overburdened with requests for a popular file, either,
+ because the file is available from several machines.</para>
+
+ <para>However, replication is not appropriate for all cells. If a
+ cell does not have much disk space, replication can be unduly
+ expensive, because each clone not on the same partition as the
+ read/write source takes up as much disk space as its source volume
+ did at the time the clone was made. Also, if you have only one file
+ server machine, replication uses up disk space without increasing
+ availability.</para>
+
+ <para>Replication is also not appropriate for volumes that change
+ frequently. You must issue the <emphasis role="bold">vos
+ release</emphasis> command every time you need to update a read-only
+ volume to reflect changes in its read/write source.</para>
+
+ <para>For both of these reasons, replication is appropriate only for
+ popular volumes whose contents do not change very often, such as
+ system binaries and other volumes mounted at the upper levels of
+ your filespace. User volumes usually exist only in a read/write
+ version since they change so often.</para>
+
+ <para>If you are replicating any volumes, you must replicate the
+ <emphasis role="bold">root.afs</emphasis> and <emphasis
+ role="bold">root.cell</emphasis> volumes, preferably at two or three
+ sites each (even if your cell only has two or three file server
+ machines). The Cache Manager needs to pass through the directories
+ corresponding to the <emphasis role="bold">root.afs</emphasis> and
+ <emphasis role="bold">root.cell</emphasis> volumes as it interprets
+ any pathname. The unavailability of these volumes makes all other
+ volumes unavailable too, even if the file server machines storing
+ the other volumes are still functioning.</para>
+
+ <para>Another reason to replicate the <emphasis
+ role="bold">root.afs</emphasis> volume is that it can lessen the
+ load on the File Server machine. The Cache Manager has a bias to
+ access a read-only version of the <emphasis
+ role="bold">root.afs</emphasis> volume if it is replicate, which
+ puts the Cache Manager onto the <emphasis>read-only path</emphasis>
+ through the AFS filespace. While on the read-only path, the Cache
+ Manager attempts to access a read-only copy of replicated
+ volumes. The File Server needs to track only one callback per Cache
+ Manager for all of the data in a read-only volume, rather than the
+ one callback per file it must track for read/write volumes. Fewer
+ callbacks translate into a smaller load on the File Server.</para>
+
+ <para>If the <emphasis role="bold">root.afs</emphasis> volume is not
+ replicated, the Cache Manager follows a read/write path through the
+ filespace, accessing the read/write version of each volume. The File
+ Server distributes and tracks a separate callback for each file in a
+ read/write volume, imposing a greater load on it.</para>
+
+ <para>For more on read/write and read-only paths, see <link
+ linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para>
+
+ <para>It also makes sense to replicate system binary volumes in many
+ cases, as well as the volume corresponding to the <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/usr</emphasis> directory and the volumes corresponding
+ to the <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/common</emphasis> directory and its
+ subdirectories.</para>
+
+ <para>It is a good idea to place a replica on the same partition as
+ the read/write source. In this case, the read-only volume is a clone
+ (like a backup volume): it is a copy of the source volume's vnode
+ index, rather than a full copy of the volume contents. Only if the
+ read/write volume moves to another partition or changes
+ substantially does the read-only volume consume significant disk
+ space. Read-only volumes kept on other partitions always consume the
+ full amount of disk space that the read/write source consumed when
+ the read-only volume was created.</para>
</sect2>
<sect2 id="Header_58">
<title>The Default Quota and ACL on a New Volume</title>
- <para>Every AFS volume has associated with it a quota that limits the amount of disk space the volume is allowed to use. To
- set and change quota, use the commands described in <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current
+ <para>Every AFS volume has associated with it a quota that limits
+ the amount of disk space the volume is allowed to use. To set and
+ change quota, use the commands described in <link
+ linkend="HDRWQ234">Setting and Displaying Volume Quota and Current
Size</link>.</para>
- <para>By default, every new volume is assigned a space quota of 5000 KB blocks unless you include the <emphasis
- role="bold">-maxquota</emphasis> argument to the <emphasis role="bold">vos create</emphasis> command. Also by default, the ACL
- on the root directory of every new volume grants all permissions to the members of the <emphasis
- role="bold">system:administrators</emphasis> group. To learn how to change these values when creating an account with
- individual commands, see <link linkend="HDRWQ503">To create one user account with individual commands</link>. When using
- <emphasis role="bold">uss</emphasis> commands to create accounts, you can specify alternate ACL and quota values in the
- template file's <emphasis role="bold">V</emphasis> instruction; see <link linkend="HDRWQ473">Creating a Volume with the V
+ <para>By default, every new volume is assigned a space quota of 5000
+ KB blocks unless you include the <emphasis
+ role="bold">-maxquota</emphasis> argument to the <emphasis
+ role="bold">vos create</emphasis> command. Also by default, the ACL
+ on the root directory of every new volume grants all permissions to
+ the members of the <emphasis
+ role="bold">system:administrators</emphasis> group. To learn how to
+ change these values when creating an account with individual
+ commands, see <link linkend="HDRWQ503">To create one user account
+ with individual commands</link>. When using <emphasis
+ role="bold">uss</emphasis> commands to create accounts, you can
+ specify alternate ACL and quota values in the template file's
+ <emphasis role="bold">V</emphasis> instruction; see <link
+ linkend="HDRWQ473">Creating a Volume with the V
Instruction</link>.</para>
<indexterm>
<sect1 id="HDRWQ51">
<title>Configuring Server Machines</title>
- <para>This section discusses some issues to consider when configuring server machines, which store AFS data, transfer it to
- client machines on request, and house the AFS administrative databases. To learn about client machines, see <link
- linkend="HDRWQ54">Configuring Client Machines</link>.</para>
-
- <para>If your cell has more than one AFS server machine, you can configure them to perform specialized functions. A machine can
- assume one or more of the roles described in the following list. For more details, see <link linkend="HDRWQ90">The Four Roles
- for File Server Machines</link>. <itemizedlist>
+ <para>This section discusses some issues to consider when configuring
+ server machines, which store AFS data, transfer it to client machines
+ on request, and house the AFS administrative databases. To learn about
+ client machines, see <link linkend="HDRWQ54">Configuring Client
+ Machines</link>.</para>
+
+ <para>If your cell has more than one AFS server machine, you can
+ configure them to perform specialized functions. A machine can assume
+ one or more of the roles described in the following list. For more
+ details, see <link linkend="HDRWQ90">The Four Roles for File Server
+ Machines</link>.
+ <itemizedlist>
<listitem>
- <para>A <emphasis>simple file server</emphasis> machine runs only the processes that store and deliver AFS files to client
- machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
+ <para>A <emphasis>simple file server</emphasis> machine runs
+ only the processes that store and deliver AFS files to client
+ machines. You can run as many simple file server machines as you
+ need to satisfy your cell's performance and disk space
requirements.</para>
</listitem>
<listitem>
- <para>A <emphasis>database server machine</emphasis> runs the four database server processes that maintain AFS's
- replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
- processes.</para>
+ <para>A <emphasis>database server machine</emphasis> runs the
+ four database server processes that maintain AFS's replicated
+ administrative databases: the Authentication, Backup,
+ Protection, and Volume Location (VL) Server processes.</para>
</listitem>
<listitem>
- <para>A <emphasis>binary distribution machine</emphasis> distributes the AFS server binaries for its system type to all
+ <para>A <emphasis>binary distribution machine</emphasis>
+ distributes the AFS server binaries for its system type to all
other server machines of that system type.</para>
</listitem>
<listitem>
- <para>The single <emphasis>system control machine</emphasis> distributes common server configuration files to all other
- server machines in the cell, in a cell that runs the United States edition of AFS (cells that use the international
- edition of AFS must not use the system control machine for this purpose). The machine conventionally also serves as the
- time synchronization source for the cell, adjusting its clock according to a time source outside the cell.</para>
+ <para>The single <emphasis>system control machine</emphasis>
+ distributes common server configuration files to all other
+ server machines in the cell, in a cell that runs the United
+ States edition of AFS (cells that use the international edition
+ of AFS must not use the system control machine for this
+ purpose). The machine conventionally also serves as the time
+ synchronization source for the cell, adjusting its clock
+ according to a time source outside the cell.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to configure your cell's first file server machine to
- assume all four roles. The <emphasis>OpenAFS Quick Beginnings</emphasis> chapter on installing additional server machines also
- explains how to configure them to perform one or more roles.</para>
+ <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how
+ to configure your cell's first file server machine to assume all four
+ roles. The <emphasis>OpenAFS Quick Beginnings</emphasis> chapter on
+ installing additional server machines also explains how to configure
+ them to perform one or more roles.</para>
<indexterm>
<primary>database server machine</primary>
<sect2 id="HDRWQ52">
<title>Replicating the OpenAFS Administrative Databases</title>
- <para>The AFS administrative databases are housed on database server machines and store information that is crucial for
- correct cell functioning. Both server processes and Cache Managers access the information frequently: <itemizedlist>
+ <para>The AFS administrative databases are housed on database server
+ machines and store information that is crucial for correct cell
+ functioning. Both server processes and Cache Managers access the
+ information frequently:
+ <itemizedlist>
<listitem>
- <para>Every time a Cache Manager fetches a file from a directory that it has not previously accessed, it must look up
- the file's location in the Volume Location Database (VLDB).</para>
+ <para>Every time a Cache Manager fetches a file from a
+ directory that it has not previously accessed, it must look up
+ the file's location in the Volume Location Database
+ (VLDB).</para>
</listitem>
<listitem>
- <para>Every time a user obtains an AFS token from the Authentication Server, the server looks up the user's password in
- the Authentication Database.</para>
+ <para>Every time a user obtains an AFS token from the
+ Authentication Server, the server looks up the user's password
+ in the Authentication Database.</para>
</listitem>
<listitem>
- <para>The first time that a user accesses a volume housed on a specific file server machine, the File Server contacts
- the Protection Server for a list of the user's group memberships as recorded in the Protection Database.</para>
+ <para>The first time that a user accesses a volume housed on a
+ specific file server machine, the File Server contacts the
+ Protection Server for a list of the user's group memberships
+ as recorded in the Protection Database.</para>
</listitem>
<listitem>
- <para>Every time you back up a volume using the AFS Backup System, the Backup Server creates records for it in the
- Backup Database.</para>
+ <para>Every time you back up a volume using the AFS Backup
+ System, the Backup Server creates records for it in the Backup
+ Database.</para>
</listitem>
- </itemizedlist></para>
-
- <para>Maintaining your cell is simplest if the first machine has the lowest IP address of any machine you plan to use as a
- database server machine. If you later decide to use a machine with a lower IP address as a database server machine, you must
- update the <emphasis role="bold">CellServDB</emphasis> file on all clients before introducing the new machine.</para>
-
- <para>If your cell has more than one server machine, it is best to run more than one as a database server machine (but more
- than three are rarely necessary). Replicating the administrative databases in this way yields the same benefits as replicating
- volumes: increased availability and reliability. If one database server machine or process stops functioning, the information
- in the database is still available from others. The load of requests for database information is spread across multiple
- machines, preventing any one from becoming overloaded.</para>
-
- <para>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
- that all copies of the database always be identical, so it is not acceptable to record changes in only some of them. To
- synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <link
- linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
+ </itemizedlist>
+ </para>
- <para>If your cell has only one file server machine, it must also serve as a database server machine. If you cell has two file
- server machines, it is not always advantageous to run both as database server machines. If a server, process, or network
- failure interrupts communications between the database server processes on the two machines, it can become impossible to
- update the information in the database because neither of them can alone elect itself as the synchronization site.</para>
+ <para>Maintaining your cell is simplest if the first machine has the
+ lowest IP address of any machine you plan to use as a database
+ server machine. If you later decide to use a machine with a lower IP
+ address as a database server machine, you must update the <emphasis
+ role="bold">CellServDB</emphasis> file on all clients before
+ introducing the new machine.</para>
+
+ <para>If your cell has more than one server machine, it is best to
+ run more than one as a database server machine (but more than three
+ are rarely necessary). Replicating the administrative databases in
+ this way yields the same benefits as replicating volumes: increased
+ availability and reliability. If one database server machine or
+ process stops functioning, the information in the database is still
+ available from others. The load of requests for database information
+ is spread across multiple machines, preventing any one from becoming
+ overloaded.</para>
+
+ <para>Unlike replicated volumes, however, replicated databases do
+ change frequently. Consistent system performance demands that all
+ copies of the database always be identical, so it is not acceptable
+ to record changes in only some of them. To synchronize the copies of
+ a database, the database server processes use AFS's distributed
+ database technology, Ubik. See <link linkend="HDRWQ102">Replicating
+ the OpenAFS Administrative Databases</link>.</para>
+
+ <para>If your cell has only one file server machine, it must also
+ serve as a database server machine. If you cell has two file server
+ machines, it is not always advantageous to run both as database
+ server machines. If a server, process, or network failure interrupts
+ communications between the database server processes on the two
+ machines, it can become impossible to update the information in the
+ database because neither of them can alone elect itself as the
+ synchronization site.</para>
<indexterm>
<primary>server machine</primary>
<sect2 id="HDRWQ53">
<title>AFS Files on the Local Disk</title>
- <para>It is generally simplest to store the binaries for all AFS server processes in the <emphasis
- role="bold">/usr/afs/bin</emphasis> directory on every file server machine, even if some processes do not actively run on the
- machine. This makes it easier to reconfigure a machine to fill a new role.</para>
-
- <para>For security reasons, the <emphasis role="bold">/usr/afs</emphasis> directory on a file server machine and all of its
- subdirectories and files must be owned by the local superuser <emphasis role="bold">root</emphasis> and have only the first
- <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit turned on. Some files even have only the
- first <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) mode bit turned on (for example, the
- <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file, which lists the AFS server encryption keys). Each time the BOS
- Server starts, it checks that the mode bits on certain files and directories match the expected values. For a list, see the
- <emphasis>OpenAFS Quick Beginnings</emphasis> section about protecting sensitive AFS directories, or the discussion of the
- output from the <emphasis role="bold">bos status</emphasis> command in <link linkend="HDRWQ159">To display the status of
- server processes and their BosConfig entries</link>.</para>
-
- <para>For a description of the contents of all AFS directories on a file server machine's local disk, see <link
+ <para>It is generally simplest to store the binaries for all AFS
+ server processes in the <emphasis
+ role="bold">/usr/afs/bin</emphasis> directory on every file server
+ machine, even if some processes do not actively run on the
+ machine. This makes it easier to reconfigure a machine to fill a new
+ role.</para>
+
+ <para>For security reasons, the <emphasis
+ role="bold">/usr/afs</emphasis> directory on a file server machine
+ and all of its subdirectories and files must be owned by the local
+ superuser <emphasis role="bold">root</emphasis> and have only the
+ first <emphasis role="bold">w</emphasis> (<emphasis
+ role="bold">write</emphasis>) mode bit turned on. Some files even
+ have only the first <emphasis role="bold">r</emphasis> (<emphasis
+ role="bold">read</emphasis>) mode bit turned on (for example, the
+ <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file, which
+ lists the AFS server encryption keys). Each time the BOS Server
+ starts, it checks that the mode bits on certain files and
+ directories match the expected values. For a list, see the
+ <emphasis>OpenAFS Quick Beginnings</emphasis> section about
+ protecting sensitive AFS directories, or the discussion of the
+ output from the <emphasis role="bold">bos status</emphasis> command
+ in <link linkend="HDRWQ159">To display the status of server
+ processes and their BosConfig entries</link>.</para>
+
+ <para>For a description of the contents of all AFS directories on a
+ file server machine's local disk, see <link
linkend="HDRWQ80">Administering Server Machines</link>.</para>
</sect2>
<sect2 id="Header_62">
<title>Configuring Partitions to Store AFS Data</title>
- <para>The partitions that house AFS volumes on a file server machine must be mounted at directories named</para>
-
- <para><emphasis role="bold">/vicep</emphasis><emphasis>index</emphasis></para>
-
- <para>where <emphasis>index</emphasis> is one or two lowercase letters. By convention, the first AFS partition created is
- mounted at the <emphasis role="bold">/vicepa</emphasis> directory, the second at the <emphasis role="bold">/vicepb</emphasis>
- directory, and so on through the <emphasis role="bold">/vicepz</emphasis> directory. The names then continue with <emphasis
- role="bold">/vicepaa</emphasis> through <emphasis role="bold">/vicepaz</emphasis>, <emphasis role="bold">/vicepba</emphasis>
- through <emphasis role="bold">/vicepbz</emphasis>, and so on, up to the maximum supported number of server partitions, which
- is specified in the OpenAFS Release Notes.</para>
-
- <para>Each <emphasis role="bold">/vicep</emphasis>x directory must correspond to an entire partition or logical volume, and
- must be a subdirectory of the root directory (/). It is not acceptable to configure part of (for example) the <emphasis
- role="bold">/usr</emphasis> partition as an AFS server partition and mount it on a directory called <emphasis
+ <para>The partitions that house AFS volumes on a file server machine
+ must be mounted at directories named</para>
+
+ <para><emphasis
+ role="bold">/vicep</emphasis><emphasis>index</emphasis></para>
+
+ <para>where <emphasis>index</emphasis> is one or two lowercase
+ letters. By convention, the first AFS partition created is mounted
+ at the <emphasis role="bold">/vicepa</emphasis> directory, the
+ second at the <emphasis role="bold">/vicepb</emphasis> directory,
+ and so on through the <emphasis role="bold">/vicepz</emphasis>
+ directory. The names then continue with <emphasis
+ role="bold">/vicepaa</emphasis> through <emphasis
+ role="bold">/vicepaz</emphasis>, <emphasis
+ role="bold">/vicepba</emphasis> through <emphasis
+ role="bold">/vicepbz</emphasis>, and so on, up to the maximum
+ supported number of server partitions, which is specified in the
+ OpenAFS Release Notes.</para>
+
+ <para>Each <emphasis role="bold">/vicep</emphasis>x directory must
+ correspond to an entire partition or logical volume, and must be a
+ subdirectory of the root directory (/). It is not acceptable to
+ configure part of (for example) the <emphasis
+ role="bold">/usr</emphasis> partition as an AFS server partition and
+ mount it on a directory called <emphasis
role="bold">/usr/vicepa</emphasis>.</para>
- <para>Also, do not store non-AFS files on AFS server partitions. The File Server and Volume Server expect to have available
- all of the space on the partition. Sharing space also creates competition between AFS and the local UNIX file system for
- access to the partition, particularly if the UNIX files are frequently used.</para>
+ <para>Also, do not store non-AFS files on AFS server partitions. The
+ File Server and Volume Server expect to have available all of the
+ space on the partition. Sharing space also creates competition
+ between AFS and the local UNIX file system for access to the
+ partition, particularly if the UNIX files are frequently
+ used.</para>
<indexterm>
<primary>server machine</primary>
<sect2 id="Header_63">
<title>Monitoring, Rebooting and Automatic Process Restarts</title>
- <para>AFS provides several tools for monitoring the File Server, including the <emphasis role="bold">scout</emphasis> and
- <emphasis role="bold">afsmonitor</emphasis> programs. You can configure them to alert you when certain threshold values are
- exceeded, for example when a server partition is more than 95% full. See <link linkend="HDRWQ323">Monitoring and Auditing AFS
+ <para>AFS provides several tools for monitoring the File Server,
+ including the <emphasis role="bold">scout</emphasis> and <emphasis
+ role="bold">afsmonitor</emphasis> programs. You can configure them
+ to alert you when certain threshold values are exceeded, for example
+ when a server partition is more than 95% full. See <link
+ linkend="HDRWQ323">Monitoring and Auditing AFS
Performance</link>.</para>
- <para>Rebooting a file server machine requires shutting down the AFS processes and so inevitably causes a service outage.
- Reboot file server machines as infrequently as possible. For instructions, see <link linkend="HDRWQ139">Rebooting a Server
- Machine</link>.</para>
-
- <para>By default, the BOS Server on each file server machine stops and immediately restarts all AFS server processes on the
- machine (including itself) once a week, at 4:00 a.m. on Sunday. This reduces the potential for the core leaks that can develop
- as any process runs for an extended time.</para>
-
- <para>The BOS Server also checks each morning at 5:00 a.m. for any newly installed binary files in the <emphasis
- role="bold">/usr/afs/bin</emphasis> directory. It compares the timestamp on each binary file to the time at which the
- corresponding process last restarted. If the timestamp on the binary is later, the BOS Server restarts the corresponding
- process to start using it.</para>
-
- <para>The default times are in the early morning hours when the outage that results from restarting a process is likely to
- disturb the fewest number of people. You can display the restart times for each machine with the <emphasis role="bold">bos
- getrestart</emphasis> command, and set them with the <emphasis role="bold">bos setrestart</emphasis> command. The latter
- command enables you to disable automatic restarts entirely, by setting the time to <emphasis role="bold">never</emphasis>. See
- <link linkend="HDRWQ171">Setting the BOS Server's Restart Times</link>.</para>
+ <para>Rebooting a file server machine requires shutting down the AFS
+ processes and so inevitably causes a service outage. Reboot file
+ server machines as infrequently as possible. For instructions, see
+ <link linkend="HDRWQ139">Rebooting a Server Machine</link>.</para>
+
+ <para>The BOS Server checks each morning at 5:00 a.m. for any newly
+ installed binary files in the <emphasis
+ role="bold">/usr/afs/bin</emphasis> directory. It compares the
+ timestamp on each binary file to the time at which the corresponding
+ process last restarted. If the timestamp on the binary is later, the
+ BOS Server restarts the corresponding process to start using
+ it.</para>
+
+ <para>The BOS server also supports performing a weekly restart of
+ all AFS server processes, including itself. This functionality is
+ disabled on new installs, but historically it was set to 4:00am on
+ Sunday. Administrators may find that installations predating OpenAFS
+ 1.6.0 have weekly restarts enabled.</para>
+
+ <para>The default times are in the early morning hours when the
+ outage that results from restarting a process is likely to disturb
+ the fewest number of people. You can display the restart times for
+ each machine with the <emphasis role="bold">bos
+ getrestart</emphasis> command, and set them with the <emphasis
+ role="bold">bos setrestart</emphasis> command. The latter command
+ enables you to disable automatic restarts entirely, by setting the
+ time to <emphasis role="bold">never</emphasis>. See <link
+ linkend="HDRWQ171">Setting the BOS Server's Restart
+ Times</link>.</para>
<indexterm>
<primary>client machine</primary>
<sect1 id="HDRWQ54">
<title>Configuring Client Machines</title>
- <para>This section summarizes issues to consider as you install and configure client machines in your cell.</para>
+ <para>This section summarizes issues to consider as you install and
+ configure client machines in your cell.</para>
<indexterm>
<primary>client machine</primary>
<sect2 id="HDRWQ55">
<title>Configuring the Local Disk</title>
- <para>You can often free up significant amounts of local disk space on AFS client machines by storing standard UNIX files in
- AFS and creating symbolic links to them from the local disk. The <emphasis role="bold">@sys</emphasis> pathname variable can
- be useful in links to system-specific files; see <link linkend="HDRWQ56">Using the @sys Variable in Pathnames</link>.</para>
-
- <para>There are two types of files that must actually reside on the local disk: boot sequence files needed before the
- <emphasis role="bold">afsd</emphasis> program is invoked, and files that can be helpful during file server machine
- outages.</para>
-
- <para>During a reboot, AFS is inaccessible until the <emphasis role="bold">afsd</emphasis> program executes and initializes
- the Cache Manager. (In the conventional configuration, the AFS initialization file is included in the machine's initialization
- sequence and invokes the <emphasis role="bold">afsd</emphasis> program.) Files needed during reboot prior to that point must
- reside on the local disk. They include the following, but this list is not necessarily exhaustive. <itemizedlist>
+ <para>You can often free up significant amounts of local disk space
+ on AFS client machines by storing standard UNIX files in AFS and
+ creating symbolic links to them from the local disk. The <emphasis
+ role="bold">@sys</emphasis> pathname variable can be useful in links
+ to system-specific files; see <link linkend="HDRWQ56">Using the @sys
+ Variable in Pathnames</link>.</para>
+
+ <para>There are two types of files that must actually reside on the
+ local disk: boot sequence files needed before the <emphasis
+ role="bold">afsd</emphasis> program is invoked, and files that can
+ be helpful during file server machine outages.</para>
+
+ <para>During a reboot, AFS is inaccessible until the <emphasis
+ role="bold">afsd</emphasis> program executes and initializes the
+ Cache Manager. (In the conventional configuration, the AFS
+ initialization file is included in the machine's initialization
+ sequence and invokes the <emphasis role="bold">afsd</emphasis>
+ program.) Files needed during reboot prior to that point must reside
+ on the local disk. They include the following, but this list is not
+ necessarily exhaustive.
+ <itemizedlist>
<listitem>
- <para>Standard UNIX utilities including the following or their equivalents: <itemizedlist>
+ <para>Standard UNIX utilities including the following or their
+ equivalents:
+ <itemizedlist>
<listitem>
- <para>Machine initialization files (stored in the <emphasis role="bold">/etc</emphasis> or <emphasis
- role="bold">/sbin</emphasis> directory on many system types)</para>
+ <para>Machine initialization files (stored in the
+ <emphasis role="bold">/etc</emphasis> or <emphasis
+ role="bold">/sbin</emphasis> directory on many system
+ types)</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">fstab</emphasis> file</para>
+ <para>The <emphasis role="bold">fstab</emphasis>
+ file</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">mount</emphasis> command binary</para>
+ <para>The <emphasis role="bold">mount</emphasis> command
+ binary</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">umount</emphasis> command binary</para>
+ <para>The <emphasis role="bold">umount</emphasis>
+ command binary</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</listitem>
<listitem>
- <para>All subdirectories and files in the <emphasis role="bold">/usr/vice</emphasis> directory, including the following:
+ <para>All subdirectories and files in the <emphasis
+ role="bold">/usr/vice</emphasis> directory, including the
+ following:
<itemizedlist>
<listitem>
- <para>The <emphasis role="bold">/usr/vice/cache</emphasis> directory</para>
+ <para>The <emphasis
+ role="bold">/usr/vice/cache</emphasis> directory</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">/usr/vice/etc/afsd</emphasis> command binary</para>
+ <para>The <emphasis
+ role="bold">/usr/vice/etc/afsd</emphasis> command
+ binary</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file</para>
+ <para>The <emphasis
+ role="bold">/usr/vice/etc/cacheinfo</emphasis> file</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file</para>
+ <para>The <emphasis
+ role="bold">/usr/vice/etc/CellServDB</emphasis>
+ file</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file</para>
+ <para>The <emphasis
+ role="bold">/usr/vice/etc/ThisCell</emphasis> file</para>
</listitem>
- </itemizedlist></para>
-
- <para>For more information on these files, see <link linkend="HDRWQ391">Configuration and Cache-Related Files on the
- Local Disk</link>.</para>
- </listitem>
- </itemizedlist></para>
-
- <para>The other type of files and programs to retain on the local disk are those you need when diagnosing and fixing problems
- caused by a file server outage, because the outage can make inaccessible the copies stored in AFS. Examples include the
- binaries for a text editor (such as <emphasis role="bold">ed</emphasis> or <emphasis role="bold">vi</emphasis>) and for the
- <emphasis role="bold">fs</emphasis> and <emphasis role="bold">bos</emphasis> commands. Store copies of AFS command binaries in
- the <emphasis role="bold">/usr/vice/etc</emphasis> directory as well as including them in the <emphasis
- role="bold">/usr/afsws</emphasis> directory, which is normally a link into AFS. Then place the <emphasis
- role="bold">/usr/afsws</emphasis> directory before the <emphasis role="bold">/usr/vice/etc</emphasis> directory in users'
- <envar>PATH</envar> environment variable definition. When AFS is functioning normally, users access the copy in the <emphasis
- role="bold">/usr/afsws</emphasis> directory, which is more likely to be current than a local copy.</para>
-
- <para>You can automate the configuration of client machine local disks by using the <emphasis role="bold">package</emphasis>
- program, which updates the contents of the local disk to match a configuration file. See <link linkend="HDRWQ419">Configuring
- Client Machines with the package Program</link>.</para>
+ </itemizedlist>
+ </para>
+
+ <para>For more information on these files, see <link
+ linkend="HDRWQ391">Configuration and Cache-Related Files on
+ the Local Disk</link>.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>The other type of files and programs to retain on the local
+ disk are those you need when diagnosing and fixing problems caused
+ by a file server outage, because the outage can make inaccessible
+ the copies stored in AFS. Examples include the binaries for a text
+ editor (such as <emphasis role="bold">ed</emphasis> or <emphasis
+ role="bold">vi</emphasis>) and for the <emphasis
+ role="bold">fs</emphasis> and <emphasis role="bold">bos</emphasis>
+ commands. Store copies of AFS command binaries in the <emphasis
+ role="bold">/usr/vice/etc</emphasis> directory as well as including
+ them in the <emphasis role="bold">/usr/afsws</emphasis> directory,
+ which is normally a link into AFS. Then place the <emphasis
+ role="bold">/usr/afsws</emphasis> directory before the <emphasis
+ role="bold">/usr/vice/etc</emphasis> directory in users'
+ <envar>PATH</envar> environment variable definition. When AFS is
+ functioning normally, users access the copy in the <emphasis
+ role="bold">/usr/afsws</emphasis> directory, which is more likely to
+ be current than a local copy.</para>
+
+ <para>You can automate the configuration of client machine local
+ disks by using the <emphasis role="bold">package</emphasis> program,
+ which updates the contents of the local disk to match a
+ configuration file. See <link linkend="HDRWQ419">Configuring Client
+ Machines with the package Program</link>.</para>
</sect2>
<sect2 id="Header_66">
<secondary>enabling access to foreign cell</secondary>
</indexterm>
- <para>As detailed in <link linkend="HDRWQ39">Making Other Cells Visible in Your Cell</link>, you enable the Cache Manager to
- access a cell's AFS filespace by storing a list of the cell's database server machines in the local <emphasis
- role="bold">/usr/vice/etc/CellServDB</emphasis> file. The Cache Manager reads the list into kernel memory at reboot for faster
- retrieval. You can change the list in kernel memory between reboots by using the <emphasis role="bold">fs newcell</emphasis>
- command. It is often practical to store a central version of the <emphasis role="bold">CellServDB</emphasis> file in AFS and
- use the <emphasis role="bold">package</emphasis> program periodically to update each client's version with the source copy.
- See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
-
- <para>Because each client machine maintains its own copy of the <emphasis role="bold">CellServDB</emphasis> file, you can in
- theory enable access to different foreign cells on different client machines. This is not usually practical, however,
- especially if users do not always work on the same machine.</para>
+ <para>As detailed in <link linkend="HDRWQ39">Making Other Cells
+ Visible in Your Cell</link>, you enable the Cache Manager to access
+ a cell's AFS filespace by storing a list of the cell's database
+ server machines in the local <emphasis
+ role="bold">/usr/vice/etc/CellServDB</emphasis> file. The Cache
+ Manager reads the list into kernel memory at reboot for faster
+ retrieval. You can change the list in kernel memory between reboots
+ by using the <emphasis role="bold">fs newcell</emphasis> command. It
+ is often practical to store a central version of the <emphasis
+ role="bold">CellServDB</emphasis> file in AFS and use the <emphasis
+ role="bold">package</emphasis> program periodically to update each
+ client's version with the source copy. See <link
+ linkend="HDRWQ406">Maintaining Knowledge of Database Server
+ Machines</link>.</para>
+
+ <para>Because each client machine maintains its own copy of the
+ <emphasis role="bold">CellServDB</emphasis> file, you can in theory
+ enable access to different foreign cells on different client
+ machines. This is not usually practical, however, especially if
+ users do not always work on the same machine.</para>
<indexterm>
<primary>at-sys (@sys) variable in pathnames</primary>
<sect2 id="HDRWQ56">
<title>Using the @sys Variable in Pathnames</title>
- <para>When creating symbolic links into AFS on the local disk, it is often practical to use the @sys variable in pathnames.
- The Cache Manager automatically substitutes the local machine's AFS system name (CPU/operating system type) for the @sys
- variable. This means you can place the same links on machines of various system types and still have each machine access the
- binaries for its system type. For example, the Cache Manager on a machine running AIX 4.2 converts <emphasis
- role="bold">/afs/abc.com/@sys</emphasis> to <emphasis role="bold">/afs/abc.com/rs_aix42</emphasis>, whereas a machine running
- Solaris 7 converts it to <emphasis role="bold">/afs/abc.com/sun4x_57</emphasis>.</para>
-
- <para>If you want to use the @sys variable, it is simplest to use the conventional AFS system type names as specified in the
- OpenAFS Release Notes. The Cache Manager records the local machine's system type name in kernel memory during initialization.
- If you do not use the conventional names, you must use the <emphasis role="bold">fs sysname</emphasis> command to change the
- value in kernel memory from its default just after Cache Manager initialization, on every client machine of the relevant
- system type. The <emphasis role="bold">fs sysname</emphasis> command also displays the current value; see <link
- linkend="HDRWQ417">Displaying and Setting the System Type Name</link>.</para>
-
- <para>In pathnames in the AFS filespace itself, use the @sys variable carefully and sparingly, because it can lead to
- unexpected results. It is generally best to restrict its use to only one level in the filespace. The third level is a common
- choice, because that is where many cells store the binaries for different machine types.</para>
-
- <para>Multiple instances of the @sys variable in a pathname are especially dangerous to people who must explicitly change
- directories (with the <emphasis role="bold">cd</emphasis> command, for example) into directories that store binaries for
- system types other than the machine on which they are working, such as administrators or developers who maintain those
- directories. After changing directories, it is recommended that such people verify they are in the desired directory.</para>
+ <para>When creating symbolic links into AFS on the local disk, it is
+ often practical to use the @sys variable in pathnames. The Cache
+ Manager automatically substitutes the local machine's AFS system
+ name (CPU/operating system type) for the @sys variable. This means
+ you can place the same links on machines of various system types and
+ still have each machine access the binaries for its system type. For
+ example, the Cache Manager on a machine running AIX 4.2 converts
+ <emphasis role="bold">/afs/abc.com/@sys</emphasis> to <emphasis
+ role="bold">/afs/abc.com/rs_aix42</emphasis>, whereas a machine
+ running Solaris 7 converts it to <emphasis
+ role="bold">/afs/abc.com/sun4x_57</emphasis>.</para>
+
+ <para>If you want to use the @sys variable, it is simplest to use
+ the conventional AFS system type names as specified in the OpenAFS
+ Release Notes. The Cache Manager records the local machine's system
+ type name in kernel memory during initialization. If you do not use
+ the conventional names, you must use the <emphasis role="bold">fs
+ sysname</emphasis> command to change the value in kernel memory from
+ its default just after Cache Manager initialization, on every client
+ machine of the relevant system type. The <emphasis role="bold">fs
+ sysname</emphasis> command also displays the current value; see
+ <link linkend="HDRWQ417">Displaying and Setting the System Type
+ Name</link>.</para>
+
+ <para>In pathnames in the AFS filespace itself, use the @sys
+ variable carefully and sparingly, because it can lead to unexpected
+ results. It is generally best to restrict its use to only one level
+ in the filespace. The third level is a common choice, because that
+ is where many cells store the binaries for different machine
+ types.</para>
+
+ <para>Multiple instances of the @sys variable in a pathname are
+ especially dangerous to people who must explicitly change
+ directories (with the <emphasis role="bold">cd</emphasis> command,
+ for example) into directories that store binaries for system types
+ other than the machine on which they are working, such as
+ administrators or developers who maintain those directories. After
+ changing directories, it is recommended that such people verify they
+ are in the desired directory.</para>
</sect2>
<sect2 id="Header_68">
<title>Setting Server Preferences</title>
- <para>The Cache Manager stores a table of preferences for file server machines in kernel memory. A preference rank pairs a
- file server machine interface's IP address with an integer in the range from 1 to 65,534. When it needs to access a file, the
- Cache Manager compares the ranks for the interfaces of all machines that house the file, and first attempts to access the file
- via the interface with the best rank. As it initializes, the Cache Manager sets default ranks that bias it to access files via
- interfaces that are close to it in terms of network topology. You can adjust the preference ranks to improve performance if
- you wish.</para>
-
- <para>The Cache Manager also uses similar preferences for Volume Location (VL) Server machines. Use the <emphasis
- role="bold">fs getserverprefs</emphasis> command to display preference ranks and the <emphasis role="bold">fs
- setserverprefs</emphasis> command to set them. See <link linkend="HDRWQ414">Maintaining Server Preference Ranks</link>.</para>
+ <para>The Cache Manager stores a table of preferences for file
+ server machines in kernel memory. A preference rank pairs a file
+ server machine interface's IP address with an integer in the range
+ from 1 to 65,534. When it needs to access a file, the Cache Manager
+ compares the ranks for the interfaces of all machines that house the
+ file, and first attempts to access the file via the interface with
+ the best rank. As it initializes, the Cache Manager sets default
+ ranks that bias it to access files via interfaces that are close to
+ it in terms of network topology. You can adjust the preference ranks
+ to improve performance if you wish.</para>
+
+ <para>The Cache Manager also uses similar preferences for Volume
+ Location (VL) Server machines. Use the <emphasis role="bold">fs
+ getserverprefs</emphasis> command to display preference ranks and
+ the <emphasis role="bold">fs setserverprefs</emphasis> command to
+ set them. See <link linkend="HDRWQ414">Maintaining Server Preference
+ Ranks</link>.</para>
<indexterm>
<primary>user account</primary>
<secondary>configuration issues</secondary>
</indexterm>
- </sect2>
- </sect1>
+ </sect2> </sect1>
<sect1 id="HDRWQ57">
<title>Configuring AFS User Accounts</title>
- <para>This section discusses some of the issues to consider when configuring AFS user accounts. Because AFS is separate from the
- UNIX file system, a user's AFS account is separate from her UNIX account.</para>
-
- <para>The preferred method for creating a user account is with the <emphasis role="bold">uss</emphasis> suite of commands. With
- a single command, you can create all the components of one or many accounts, after you have prepared a template file that guides
- the account creation. See <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>.</para>
-
- <para>Alternatively, you can issue the individual commands that create each component of an account. For instructions, along
- with instructions for removing user accounts and changing user passwords, user volume quotas and usernames, see <link
+ <para>This section discusses some of the issues to consider when
+ configuring AFS user accounts. Because AFS is separate from the UNIX
+ file system, a user's AFS account is separate from her UNIX
+ account.</para>
+
+ <para>The preferred method for creating a user account is with the
+ <emphasis role="bold">uss</emphasis> suite of commands. With a single
+ command, you can create all the components of one or many accounts,
+ after you have prepared a template file that guides the account
+ creation. See <link linkend="HDRWQ449">Creating and Deleting User
+ Accounts with the uss Command Suite</link>.</para>
+
+ <para>Alternatively, you can issue the individual commands that create
+ each component of an account. For instructions, along with
+ instructions for removing user accounts and changing user passwords,
+ user volume quotas and usernames, see <link
linkend="HDRWQ491">Administering User Accounts</link>.</para>
- <para>When users leave your system, it is often good policy to remove their accounts. Instructions appear in <link
- linkend="HDRWQ486">Deleting Individual Accounts with the uss delete Command</link> and <link linkend="HDRWQ524">Removing a User
+ <para>When users leave your system, it is often good policy to remove
+ their accounts. Instructions appear in <link
+ linkend="HDRWQ486">Deleting Individual Accounts with the uss delete
+ Command</link> and <link linkend="HDRWQ524">Removing a User
Account</link>.</para>
- <para>An AFS user account consists of the following components, which are described in greater detail in <link
- linkend="HDRWQ494">The Components of an AFS User Account</link>. <itemizedlist>
+ <para>An AFS user account consists of the following components, which
+ are described in greater detail in <link linkend="HDRWQ494">The
+ Components of an AFS User Account</link>.
+ <itemizedlist>
<listitem>
<para>A Protection Database entry</para>
</listitem>
</listitem>
<listitem>
- <para>Ownership of the home directory and full permissions on its ACL</para>
+ <para>Ownership of the home directory and full permissions on
+ its ACL</para>
</listitem>
<listitem>
- <para>An entry in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of each machine the
- user needs to log into</para>
+ <para>An entry in the local password file (<emphasis
+ role="bold">/etc/passwd</emphasis> or equivalent) of each
+ machine the user needs to log into</para>
</listitem>
<listitem>
- <para>Optionally, standard files and subdirectories that make the account more useful</para>
+ <para>Optionally, standard files and subdirectories that make
+ the account more useful</para>
</listitem>
- </itemizedlist></para>
-
- <para>By creating some components but not others, you can create accounts at different levels of functionality, using either
- <emphasis role="bold">uss</emphasis> commands as described in <link linkend="HDRWQ449">Creating and Deleting User Accounts with
- the uss Command Suite</link> or individual commands as described in <link linkend="HDRWQ491">Administering User Accounts</link>.
- The levels of functionality include the following <itemizedlist>
+ </itemizedlist>
+ </para>
+
+ <para>By creating some components but not others, you can create
+ accounts at different levels of functionality, using either <emphasis
+ role="bold">uss</emphasis> commands as described in <link
+ linkend="HDRWQ449">Creating and Deleting User Accounts with the uss
+ Command Suite</link> or individual commands as described in <link
+ linkend="HDRWQ491">Administering User Accounts</link>. The levels of
+ functionality include the following
+ <itemizedlist>
<listitem>
- <para>An authentication-only account enables the user to obtain AFS tokens and so to access protected AFS data and to
- issue privileged commands. It consists only of entries in the Authentication and Protection Database. This type of account
- is suitable for administrative accounts and for users from foreign cells who need to access protected data. Local users
- generally also need a volume and home directory.</para>
+ <para>An authentication-only account enables the user to obtain
+ AFS tokens and so to access protected AFS data and to issue
+ privileged commands. It consists only of entries in the
+ Authentication and Protection Database. This type of account is
+ suitable for administrative accounts and for users from foreign
+ cells who need to access protected data. Local users generally
+ also need a volume and home directory.</para>
</listitem>
<listitem>
- <para>A basic user account includes a volume for the user, in addition to Authentication and Protection Database entries.
- The volume is mounted in the AFS filespace as the user's home directory, and provides a repository for the user's personal
+ <para>A basic user account includes a volume for the user, in
+ addition to Authentication and Protection Database entries. The
+ volume is mounted in the AFS filespace as the user's home
+ directory, and provides a repository for the user's personal
files.</para>
</listitem>
<listitem>
- <para>A full account adds configuration files for basic functions such as logging in, printing, and mail delivery to a
- basic account, making it more convenient and useful. For a discussion of some useful types of configuration files, see
- <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>.</para>
+ <para>A full account adds configuration files for basic
+ functions such as logging in, printing, and mail delivery to a
+ basic account, making it more convenient and useful. For a
+ discussion of some useful types of configuration files, see
+ <link linkend="HDRWQ60">Creating Standard Files in New AFS
+ Accounts</link>.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>If your users have UNIX user accounts that predate the introduction of AFS in the cell, you possibly want to convert them
- into AFS accounts. There are three main issues to consider: <itemizedlist>
+ <para>If your users have UNIX user accounts that predate the
+ introduction of AFS in the cell, you possibly want to convert them
+ into AFS accounts. There are three main issues to consider:
+ <itemizedlist>
<listitem>
- <para>Making UNIX and AFS UIDs match</para>
- </listitem>
+ <para>Making UNIX and AFS UIDs match</para> </listitem>
<listitem>
- <para>Setting the password field in the local password file appropriately</para>
+ <para>Setting the password field in the local password file
+ appropriately</para>
</listitem>
<listitem>
<para>Moving files from the UNIX file system into AFS</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>For further discussion, see <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link> or <link
+ <para>For further discussion, see <link linkend="HDRWQ459">Converting
+ Existing UNIX Accounts with uss</link> or <link
linkend="HDRWQ498">Converting Existing UNIX Accounts</link>.</para>
<indexterm>
</indexterm>
<sect2 id="HDRWQ58">
- <title>Choosing Usernames and Naming Other Account Components</title>
+ <title>Choosing Usernames and Naming Other Account
+ Components</title>
- <para>This section suggests schemes for choosing usernames, AFS UIDs, user volume names and mount point names, and also
- outlines some restrictions on your choices.</para>
+ <para>This section suggests schemes for choosing usernames, AFS
+ UIDs, user volume names and mount point names, and also outlines
+ some restrictions on your choices.</para>
<formalpara>
<title>Usernames</title>
- <para>AFS imposes very few restrictions on the form of usernames. It is best to keep usernames short, both because many
- utilities and applications can handle usernames of no more than eight characters and because by convention many components
- of and AFS account incorporate the name. These include the entries in the Protection and Authentication Databases, the
- volume, and the mount point. Depending on your electronic mail delivery system, the username can become part of the user's
- mailing address. The username is also the string that the user types when logging in to a client machine.</para>
+ <para>AFS imposes very few restrictions on the form of
+ usernames. It is best to keep usernames short, both because many
+ utilities and applications can handle usernames of no more than
+ eight characters and because by convention many components of and
+ AFS account incorporate the name. These include the entries in the
+ Protection and Authentication Databases, the volume, and the mount
+ point. Depending on your electronic mail delivery system, the
+ username can become part of the user's mailing address. The
+ username is also the string that the user types when logging in to
+ a client machine.</para>
</formalpara>
- <para>Some common choices for usernames are last names, first names, initials, or a combination, with numbers sometimes added.
- It is also best to avoid using the following characters, many of which have special meanings to the command shell.
+ <para>Some common choices for usernames are last names, first names,
+ initials, or a combination, with numbers sometimes added. It is
+ also best to avoid using the following characters, many of which
+ have special meanings to the command shell.
<itemizedlist>
<listitem>
<para>The comma (<emphasis role="bold">,</emphasis>)</para>
</listitem>
<listitem>
- <para>The colon (<emphasis role="bold">:</emphasis>), because AFS reserves it as a field separator in protection group
- names; see <link linkend="HDRWQ62">The Two Types of User-Defined Groups</link></para>
+ <para>The colon (<emphasis role="bold">:</emphasis>), because
+ AFS reserves it as a field separator in protection group
+ names; see <link linkend="HDRWQ62">The Two Types of
+ User-Defined Groups</link></para>
</listitem>
<listitem>
- <para>The semicolon (<emphasis role="bold">;</emphasis>)</para>
+ <para>The semicolon (<emphasis
+ role="bold">;</emphasis>)</para>
</listitem>
<listitem>
- <para>The "at-sign" (<emphasis role="bold">@</emphasis>); this character is reserved for Internet mailing
- addresses</para>
+ <para>The "at-sign" (<emphasis role="bold">@</emphasis>); this
+ character is reserved for Internet mailing addresses</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para>The period (<emphasis role="bold">.</emphasis>); it is conventional to use this character only in the special
- username that an administrator adopts while performing privileged tasks, such as <emphasis
+ <para>The period (<emphasis role="bold">.</emphasis>); it is
+ conventional to use this character only in the special
+ username that an administrator adopts while performing
+ privileged tasks, such as <emphasis
role="bold">pat.admin</emphasis></para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
<formalpara>
<title>AFS UIDs and UNIX UIDs</title>
- <para>AFS associates a unique identification number, the AFS UID, with every username, recording the mapping in the user's
- Protection Database entry. The AFS UID functions within AFS much as the UNIX UID does in the local file system: the AFS
- server processes and the Cache Manager use it internally to identify a user, rather than the username.</para>
+ <para>AFS associates a unique identification number, the AFS UID,
+ with every username, recording the mapping in the user's
+ Protection Database entry. The AFS UID functions within AFS much
+ as the UNIX UID does in the local file system: the AFS server
+ processes and the Cache Manager use it internally to identify a
+ user, rather than the username.</para>
</formalpara>
- <para>Every AFS user also must have a UNIX UID recorded in the local password file (<emphasis
- role="bold">/etc/passwd</emphasis> or equivalent) of each client machine they log onto. Both administration and a user's AFS
- access are simplest if the AFS UID and UNIX UID match. One important consequence of matching UIDs is that the owner reported
- by the <emphasis role="bold">ls -l</emphasis> command matches the AFS username.</para>
-
- <para>It is usually best to allow the Protection Server to allocate the AFS UID as it creates the Protection Database entry.
- However, both the <emphasis role="bold">pts createuser</emphasis> command and the <emphasis role="bold">uss</emphasis>
- commands that create user accounts enable you to assign AFS UIDs explicitly. This is appropriate in two cases: <itemizedlist>
+ <para>Every AFS user also must have a UNIX UID recorded in the local
+ password file (<emphasis role="bold">/etc/passwd</emphasis> or
+ equivalent) of each client machine they log onto. Both
+ administration and a user's AFS access are simplest if the AFS UID
+ and UNIX UID match. One important consequence of matching UIDs is
+ that the owner reported by the <emphasis role="bold">ls
+ -l</emphasis> command matches the AFS username.</para>
+
+ <para>It is usually best to allow the Protection Server to allocate
+ the AFS UID as it creates the Protection Database entry. However,
+ both the <emphasis role="bold">pts createuser</emphasis> command and
+ the <emphasis role="bold">uss</emphasis> commands that create user
+ accounts enable you to assign AFS UIDs explicitly. This is
+ appropriate in two cases:
+ <itemizedlist>
<listitem>
- <para>You wish to group together the AFS UIDs of related users</para>
+ <para>You wish to group together the AFS UIDs of related
+ users</para>
</listitem>
<listitem>
- <para>You are converting an existing UNIX account into an AFS account and want to make the AFS UID match the existing
- UNIX UID</para>
+ <para>You are converting an existing UNIX account into an AFS
+ account and want to make the AFS UID match the existing UNIX
+ UID</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>After the Protection Server initializes for the first time on a cell's first file server machine, it starts assigning
- AFS UIDs at a default value. To change the default before creating any user accounts, or at any time, use the <emphasis
- role="bold">pts setmax</emphasis> command to reset the <computeroutput>max user id counter</computeroutput>. To display the
- counter, use the <emphasis role="bold">pts listmax</emphasis> command. See <link linkend="HDRWQ560">Displaying and Setting the
- AFS UID and GID Counters</link>.</para>
+ <para>After the Protection Server initializes for the first time on
+ a cell's first file server machine, it starts assigning AFS UIDs at
+ a default value. To change the default before creating any user
+ accounts, or at any time, use the <emphasis role="bold">pts
+ setmax</emphasis> command to reset the <computeroutput>max user id
+ counter</computeroutput>. To display the counter, use the <emphasis
+ role="bold">pts listmax</emphasis> command. See <link
+ linkend="HDRWQ560">Displaying and Setting the AFS UID and GID
+ Counters</link>.</para>
- <para>AFS reserves one AFS UID, 32766, for the user <emphasis role="bold">anonymous</emphasis>. The AFS server processes
- assign this identity and AFS UID to any user who does not possess a token for the local cell. Do not assign this AFS UID to
- any other user or hardcode its current value into any programs or a file's owner field, because it is subject to change in
- future releases.</para>
+ <para>AFS reserves one AFS UID, 32766, for the user <emphasis
+ role="bold">anonymous</emphasis>. The AFS server processes assign
+ this identity and AFS UID to any user who does not possess a token
+ for the local cell. Do not assign this AFS UID to any other user or
+ hardcode its current value into any programs or a file's owner
+ field, because it is subject to change in future releases.</para>
<indexterm>
<primary>username</primary>
<formalpara>
<title>User Volume Names</title>
- <para>Like any volume name, a user volume's base (read/write) name cannot exceed 22 characters in length or include the
- <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension. See <link
- linkend="HDRWQ44">Creating Volumes to Simplify Administration</link>. By convention, user volume names have the format
- <emphasis role="bold">user.</emphasis>username. Using the <emphasis role="bold">user.</emphasis> prefix not only makes it
- easy to identify the volume's contents, but also to create a backup version of all user volumes by issuing a single
- <emphasis role="bold">vos backupsys</emphasis> command.</para>
+ <para>Like any volume name, a user volume's base (read/write) name
+ cannot exceed 22 characters in length or include the <emphasis
+ role="bold">.readonly</emphasis> or <emphasis
+ role="bold">.backup</emphasis> extension. See <link
+ linkend="HDRWQ44">Creating Volumes to Simplify
+ Administration</link>. By convention, user volume names have the
+ format <emphasis role="bold">user.</emphasis>username. Using the
+ <emphasis role="bold">user.</emphasis> prefix not only makes it
+ easy to identify the volume's contents, but also to create a
+ backup version of all user volumes by issuing a single <emphasis
+ role="bold">vos backupsys</emphasis> command.</para>
</formalpara>
<indexterm>
<formalpara>
<title>Mount Point Names</title>
- <para>By convention, the mount point for a user's volume is named after the username. Many cells follow the convention of
- mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
- role="bold">/usr</emphasis> directory, as discussed in <link linkend="HDRWQ43">The Third Level</link>. Very large cells
- sometimes find that mounting all user volumes in the same directory slows directory lookup, however; for suggested
+ <para>By convention, the mount point for a user's volume is named
+ after the username. Many cells follow the convention of mounting
+ user volumes in the <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/usr</emphasis> directory, as discussed in <link
+ linkend="HDRWQ43">The Third Level</link>. Very large cells
+ sometimes find that mounting all user volumes in the same
+ directory slows directory lookup, however; for suggested
alternatives, see the following section.</para>
</formalpara>
<sect2 id="HDRWQ59">
<title>Grouping Home Directories</title>
- <para>Mounting user volumes in the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
- role="bold">/usr</emphasis> directory is an AFS-appropriate variation on the standard UNIX practice of putting user home
- directories under the <emphasis role="bold">/usr</emphasis> subdirectory. However, cells with more than a few hundred users
- sometimes find that mounting all user volumes in a single directory results in slow directory lookup. The solution is to
- distribute user volume mount points into several directories; there are a number of alternative methods to accomplish this.
+ <para>Mounting user volumes in the <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/usr</emphasis> directory is an AFS-appropriate
+ variation on the standard UNIX practice of putting user home
+ directories under the <emphasis role="bold">/usr</emphasis>
+ subdirectory. However, cells with more than a few hundred users
+ sometimes find that mounting all user volumes in a single directory
+ results in slow directory lookup. The solution is to distribute user
+ volume mount points into several directories; there are a number of
+ alternative methods to accomplish this.
<itemizedlist>
<listitem>
- <para>Distribute user home directories into multiple directories that reflect organizational divisions, such as academic
- or corporate departments. For example, a company can create group directories called <emphasis
- role="bold">usr/marketing</emphasis>, <emphasis role="bold">usr/research</emphasis>, <emphasis
- role="bold">usr/finance</emphasis>. A good feature of this scheme is that knowing a user's department is enough to find
- the user's home directory. Also, it makes it easy to set the ACL to limit access to members of the department only. A
- potential drawback arises if departments are of sufficiently unequal size that users in large departments experience
- slower lookup than users in small departments. This scheme is also not appropriate in cells where users frequently
- change between divisions.</para>
+ <para>Distribute user home directories into multiple
+ directories that reflect organizational divisions, such as
+ academic or corporate departments. For example, a company can
+ create group directories called <emphasis
+ role="bold">usr/marketing</emphasis>, <emphasis
+ role="bold">usr/research</emphasis>, <emphasis
+ role="bold">usr/finance</emphasis>. A good feature of this
+ scheme is that knowing a user's department is enough to find
+ the user's home directory. Also, it makes it easy to set the
+ ACL to limit access to members of the department only. A
+ potential drawback arises if departments are of sufficiently
+ unequal size that users in large departments experience slower
+ lookup than users in small departments. This scheme is also
+ not appropriate in cells where users frequently change between
+ divisions.</para>
</listitem>
<listitem>
- <para>Distribute home directories into alphabetic subdirectories of the <emphasis role="bold">usr</emphasis> directory
- (the <emphasis role="bold">usr/a</emphasis> subdirectory, the <emphasis role="bold">usr/b</emphasis> subdirectory, and
- so on), based on the first letter of the username. If the cell is very large, create subdirectories under each letter
- that correspond to the second letter in the user name. This scheme has the same advantages and disadvantages of a
- department-based scheme. Anyone who knows the user's username can find the user's home directory, but users with names
- that begin with popular letters sometimes experience slower lookup.</para>
+ <para>Distribute home directories into alphabetic
+ subdirectories of the <emphasis role="bold">usr</emphasis>
+ directory (the <emphasis role="bold">usr/a</emphasis>
+ subdirectory, the <emphasis role="bold">usr/b</emphasis>
+ subdirectory, and so on), based on the first letter of the
+ username. If the cell is very large, create subdirectories
+ under each letter that correspond to the second letter in the
+ user name. This scheme has the same advantages and
+ disadvantages of a department-based scheme. Anyone who knows
+ the user's username can find the user's home directory, but
+ users with names that begin with popular letters sometimes
+ experience slower lookup.</para>
</listitem>
<listitem>
- <para>Distribute home directories randomly but evenly into more than one grouping directory. One cell that uses this
- scheme has over twenty such directories called the <emphasis role="bold">usr1</emphasis> directory, the <emphasis
- role="bold">usr2</emphasis> directory, and so on. This scheme is especially appropriate in cells where the other two
- schemes do not seem feasible. It eliminates the potential problem of differences in lookup speed, because all
- directories are about the same size. Its disadvantage is that there is no way to guess which directory a given user's
- volume is mounted in, but a solution is to create a symbolic link in the regular <emphasis role="bold">usr</emphasis>
- directory that references the actual mount point. For example, if user <emphasis role="bold">smith</emphasis>'s volume
- is mounted at the <emphasis role="bold">/afs/bigcell.com/usr17/smith</emphasis> directory, then the <emphasis
- role="bold">/afs/bigcell.com/usr/smith</emphasis> directory is a symbolic link to the <emphasis
- role="bold">../usr17/smith</emphasis> directory. This way, if someone does not know which directory the user <emphasis
- role="bold">smith</emphasis> is in, he or she can access it through the link called <emphasis
- role="bold">usr/smith</emphasis>; people who do know the appropriate directory save lookup time by specifying it.</para>
+ <para>Distribute home directories randomly but evenly into
+ more than one grouping directory. One cell that uses this
+ scheme has over twenty such directories called the <emphasis
+ role="bold">usr1</emphasis> directory, the <emphasis
+ role="bold">usr2</emphasis> directory, and so on. This scheme
+ is especially appropriate in cells where the other two schemes
+ do not seem feasible. It eliminates the potential problem of
+ differences in lookup speed, because all directories are about
+ the same size. Its disadvantage is that there is no way to
+ guess which directory a given user's volume is mounted in, but
+ a solution is to create a symbolic link in the regular
+ <emphasis role="bold">usr</emphasis> directory that references
+ the actual mount point. For example, if user <emphasis
+ role="bold">smith</emphasis>'s volume is mounted at the
+ <emphasis role="bold">/afs/bigcell.com/usr17/smith</emphasis>
+ directory, then the <emphasis
+ role="bold">/afs/bigcell.com/usr/smith</emphasis> directory is
+ a symbolic link to the <emphasis
+ role="bold">../usr17/smith</emphasis> directory. This way, if
+ someone does not know which directory the user <emphasis
+ role="bold">smith</emphasis> is in, he or she can access it
+ through the link called <emphasis
+ role="bold">usr/smith</emphasis>; people who do know the
+ appropriate directory save lookup time by specifying
+ it.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>For instructions on how to implement the various schemes when using the <emphasis role="bold">uss</emphasis> program to
- create user accounts, see <link linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link> and
- <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
+ <para>For instructions on how to implement the various schemes when
+ using the <emphasis role="bold">uss</emphasis> program to create
+ user accounts, see <link linkend="HDRWQ472">Evenly Distributing User
+ Home Directories with the G Instruction</link> and <link
+ linkend="HDRWQ473">Creating a Volume with the V
+ Instruction</link>.</para>
</sect2>
<sect2 id="Header_72">
<title>Making a Backup Version of User Volumes Available</title>
- <para>Mounting the backup version of a user's volume is a simple way to enable users themselves to restore data they have
- accidentally removed or deleted. It is conventional to mount the backup version at a subdirectory of the user's home directory
- (called perhaps the <emphasis role="bold">OldFiles</emphasis> subdirectory), but other schemes are possible. Once per day you
- create a new backup version to capture the changes made that day, overwriting the previous day's backup version with the new
- one. Users can always retrieve the previous day's copy of a file without your assistance, freeing you to deal with more
- pressing tasks.</para>
-
- <para>Users sometimes want to delete the mount point to their backup volume, because they erroneously believe that the backup
- volume's contents count against their quota. Remind them that the backup volume is separate, so the only space it uses in the
- user volume is the amount needed for the mount point.</para>
-
- <para>For further discussion of backup volumes, see <link linkend="HDRWQ77">Backing Up AFS Data</link> and <link
+ <para>Mounting the backup version of a user's volume is a simple way
+ to enable users themselves to restore data they have accidentally
+ removed or deleted. It is conventional to mount the backup version
+ at a subdirectory of the user's home directory (called perhaps the
+ <emphasis role="bold">OldFiles</emphasis> subdirectory), but other
+ schemes are possible. Once per day you create a new backup version
+ to capture the changes made that day, overwriting the previous day's
+ backup version with the new one. Users can always retrieve the
+ previous day's copy of a file without your assistance, freeing you
+ to deal with more pressing tasks.</para>
+
+ <para>Users sometimes want to delete the mount point to their backup
+ volume, because they erroneously believe that the backup volume's
+ contents count against their quota. Remind them that the backup
+ volume is separate, so the only space it uses in the user volume is
+ the amount needed for the mount point.</para>
+
+ <para>For further discussion of backup volumes, see <link
+ linkend="HDRWQ77">Backing Up AFS Data</link> and <link
linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
<indexterm>
<sect2 id="HDRWQ60">
<title>Creating Standard Files in New AFS Accounts</title>
- <para>From your experience as a UNIX administrator, you are probably familiar with the use of login and shell initialization
- files (such as the <emphasis role="bold">.login</emphasis> and <emphasis role="bold">.cshrc</emphasis> files) to make an
- account easier to use.</para>
+ <para>From your experience as a UNIX administrator, you are probably
+ familiar with the use of login and shell initialization files (such
+ as the <emphasis role="bold">.login</emphasis> and <emphasis
+ role="bold">.cshrc</emphasis> files) to make an account easier to
+ use.</para>
- <para>It is often practical to add some AFS-specific directories to the definition of the user's <envar>PATH</envar>
- environment variable, including the following: <itemizedlist>
+ <para>It is often practical to add some AFS-specific directories to
+ the definition of the user's <envar>PATH</envar> environment
+ variable, including the following:
+ <itemizedlist>
<listitem>
- <para>The path to a <emphasis role="bold">bin</emphasis> subdirectory in the user's home directory for binaries the user
- has created (that is, <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
- role="bold">/usr/</emphasis><replaceable>username</replaceable><emphasis role="bold">/bin</emphasis>)</para>
+ <para>The path to a <emphasis role="bold">bin</emphasis>
+ subdirectory in the user's home directory for binaries the
+ user has created (that is, <emphasis
+ role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ role="bold">/usr/</emphasis><replaceable>username</replaceable><emphasis
+ role="bold">/bin</emphasis>)</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">/usr/afsws/bin</emphasis> path, which conventionally includes programs like <emphasis
- role="bold">fs</emphasis>, <emphasis role="bold">klog</emphasis>, <emphasis role="bold">kpasswd</emphasis>, <emphasis
- role="bold">pts</emphasis>, <emphasis role="bold">tokens</emphasis>, and <emphasis role="bold">unlog</emphasis></para>
+ <para>The <emphasis role="bold">/usr/afsws/bin</emphasis>
+ path, which conventionally includes programs like <emphasis
+ role="bold">fs</emphasis>, <emphasis
+ role="bold">klog</emphasis>, <emphasis
+ role="bold">kpasswd</emphasis>, <emphasis
+ role="bold">pts</emphasis>, <emphasis
+ role="bold">tokens</emphasis>, and <emphasis
+ role="bold">unlog</emphasis></para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">/usr/afsws/etc</emphasis> path, if the user is an administrator; it usually houses the
- AFS command suites that require privilege (the <emphasis role="bold">backup</emphasis>, <emphasis
- role="bold">butc</emphasis>, <emphasis role="bold">kas</emphasis>, <emphasis role="bold">uss</emphasis>, <emphasis
- role="bold">vos</emphasis> commands), the <emphasis role="bold">package</emphasis> program, and others</para>
+ <para>The <emphasis role="bold">/usr/afsws/etc</emphasis>
+ path, if the user is an administrator; it usually houses the
+ AFS command suites that require privilege (the <emphasis
+ role="bold">backup</emphasis>, <emphasis
+ role="bold">butc</emphasis>, <emphasis
+ role="bold">kas</emphasis>, <emphasis
+ role="bold">uss</emphasis>, <emphasis
+ role="bold">vos</emphasis> commands), the <emphasis
+ role="bold">package</emphasis> program, and others</para>
</listitem>
- </itemizedlist></para>
-
- <para>If you are not using an AFS-modified login utility, it can be helpful to users to invoke the <emphasis
- role="bold">klog</emphasis> command in their <emphasis role="bold">.login</emphasis> file so that they obtain AFS tokens as
- part of logging in. In the following example command sequence, the first line echoes the string
- <computeroutput>klog</computeroutput> to the standard output stream, so that the user understands the purpose of the
- <computeroutput>Password:</computeroutput> prompt that appears when the second line is executed. The <emphasis
- role="bold">-setpag</emphasis> flag associates the new tokens with a process authentication group (PAG), which is discussed
- further in <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
+ </itemizedlist>
+ </para>
- <programlisting>
- echo -n "klog "
- klog -setpag
+ <para>If you are not using an AFS-modified login utility, it can be
+ helpful to users to invoke the <emphasis role="bold">klog</emphasis>
+ command in their <emphasis role="bold">.login</emphasis> file so
+ that they obtain AFS tokens as part of logging in. In the following
+ example command sequence, the first line echoes the string
+ <computeroutput>klog</computeroutput> to the standard output stream,
+ so that the user understands the purpose of the
+ <computeroutput>Password:</computeroutput> prompt that appears when
+ the second line is executed. The <emphasis
+ role="bold">-setpag</emphasis> flag associates the new tokens with a
+ process authentication group (PAG), which is discussed further in
+ <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
+
+<programlisting>
+ echo -n "klog " klog -setpag
</programlisting>
- <para>The following sequence of commands has a similar effect, except that the <emphasis role="bold">pagsh</emphasis> command
- forks a new shell with which the PAG and tokens are associated.</para>
+ <para>The following sequence of commands has a similar effect,
+ except that the <emphasis role="bold">pagsh</emphasis> command forks
+ a new shell with which the PAG and tokens are associated.</para>
- <programlisting>
- pagsh
- echo -n "klog "
- klog
+<programlisting>
+ pagsh echo -n "klog " klog
</programlisting>
- <para>If you use an AFS-modified login utility, this sequence is not necessary, because such utilities both log a user in
- locally and obtain AFS tokens.</para>
+ <para>If you use an AFS-modified login utility, this sequence is not
+ necessary, because such utilities both log a user in locally and
+ obtain AFS tokens.</para>
<indexterm>
<primary>group</primary>
<sect1 id="HDRWQ61">
<title>Using AFS Protection Groups</title>
- <para>AFS enables users to define their own groups of other users or machines. The groups are placed on ACLs to grant the same
- permissions to many users without listing each user individually. For group creation instructions, see <link
- linkend="HDRWQ531">Administering the Protection Database</link>.</para>
-
- <para>Groups have AFS ID numbers, just as users do, but an AFS group ID (GID) is a negative integer whereas a user's AFS UID is
- a positive integer. By default, the Protection Server allocates a new group's AFS GID automatically, but members of the
- <emphasis role="bold">system:administrators</emphasis> group can assign a GID when issuing the <emphasis role="bold">pts
- creategroup</emphasis> command. Before explicitly assigning a GID, it is best to verify that it is not already in use.</para>
-
- <para>A group cannot belong to another group, but it can own another group or even itself as long as it (the owning group) has
- at least one member. The current owner of a group can transfer ownership of the group to another user or group, even without the
- new owner's permission. At that point the former owner loses administrative control over the group.</para>
-
- <para>By default, each user can create 20 groups. A system administrator can increase or decrease this group creation quota with
+ <para>AFS enables users to define their own groups of other users or
+ machines. The groups are placed on ACLs to grant the same permissions
+ to many users without listing each user individually. For group
+ creation instructions, see <link linkend="HDRWQ531">Administering the
+ Protection Database</link>.</para>
+
+ <para>Groups have AFS ID numbers, just as users do, but an AFS group
+ ID (GID) is a negative integer whereas a user's AFS UID is a positive
+ integer. By default, the Protection Server allocates a new group's AFS
+ GID automatically, but members of the <emphasis
+ role="bold">system:administrators</emphasis> group can assign a GID
+ when issuing the <emphasis role="bold">pts creategroup</emphasis>
+ command. Before explicitly assigning a GID, it is best to verify that
+ it is not already in use.</para>
+
+ <para>A group cannot belong to another group, but it can own another
+ group or even itself as long as it (the owning group) has at least one
+ member. The current owner of a group can transfer ownership of the
+ group to another user or group, even without the new owner's
+ permission. At that point the former owner loses administrative
+ control over the group.</para>
+
+ <para>By default, each user can create 20 groups. A system
+ administrator can increase or decrease this group creation quota with
the <emphasis role="bold">pts setfields</emphasis> command.</para>
- <para>Each Protection Database entry (group or user) is protected by a set of five privacy flagswhich limit who can administer
- the entry and what they can do. The default privacy flags are fairly restrictive, especially for user entries. See <link
- linkend="HDRWQ559">Setting the Privacy Flags on Database Entries</link>.</para>
+ <para>Each Protection Database entry (group or user) is protected by a
+ set of five privacy flagswhich limit who can administer the entry and
+ what they can do. The default privacy flags are fairly restrictive,
+ especially for user entries. See <link linkend="HDRWQ559">Setting the
+ Privacy Flags on Database Entries</link>.</para>
<indexterm>
<primary>system:administrators group</primary>
<sect2 id="Header_75">
<title>The Three System Groups</title>
- <para>As the Protection Server initializes for the first time on a cell's first database server machine, it automatically
- creates three group entries: the <emphasis role="bold">system:anyuser</emphasis>, <emphasis
- role="bold">system:authuser</emphasis>, and <emphasis role="bold">system:administrators</emphasis> groups.</para>
+ <para>As the Protection Server initializes for the first time on a
+ cell's first database server machine, it automatically creates three
+ group entries: the <emphasis role="bold">system:anyuser</emphasis>,
+ <emphasis role="bold">system:authuser</emphasis>, and <emphasis
+ role="bold">system:administrators</emphasis> groups.</para>
<indexterm>
<primary>AFS UID</primary>
<tertiary>system-defined groups</tertiary>
</indexterm>
- <para>The first two system groups are unlike any other groups in the Protection Database in that they do not have a stable
- membership: <itemizedlist>
+ <para>The first two system groups are unlike any other groups in the
+ Protection Database in that they do not have a stable membership:
+ <itemizedlist>
<listitem>
- <para>The <emphasis role="bold">system:anyuser</emphasis> group includes everyone who can access a cell's AFS filespace:
- users who have tokens for the local cell, users who have logged in on a local AFS client machine but not obtained tokens
- (such as the local superuser <emphasis role="bold">root</emphasis>), and users who have connected to a local machine
- from outside the cell. Placing the <emphasis role="bold">system:anyuser</emphasis> group on an ACL grants access to the
- widest possible range of users. It is the only way to extend access to users from foreign AFS cells that do not have
- local accounts.</para>
+ <para>The <emphasis role="bold">system:anyuser</emphasis>
+ group includes everyone who can access a cell's AFS filespace:
+ users who have tokens for the local cell, users who have
+ logged in on a local AFS client machine but not obtained
+ tokens (such as the local superuser <emphasis
+ role="bold">root</emphasis>), and users who have connected to
+ a local machine from outside the cell. Placing the <emphasis
+ role="bold">system:anyuser</emphasis> group on an ACL grants
+ access to the widest possible range of users. It is the only
+ way to extend access to users from foreign AFS cells that do
+ not have local accounts.</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">system:authuser</emphasis> group includes everyone who has a valid token obtained from
+ <para>The <emphasis role="bold">system:authuser</emphasis>
+ group includes everyone who has a valid token obtained from
the cell's AFS authentication service.</para>
</listitem>
- </itemizedlist></para>
-
- <para>Because the groups do not have a stable membership, the <emphasis role="bold">pts membership</emphasis> command produces
- no output for them. Similarly, they do not appear in the list of groups to which a user belongs.</para>
-
- <para>The <emphasis role="bold">system:administrators</emphasis> group does have a stable membership, consisting of the cell's
- privileged administrators. Members of this group can issue any <emphasis role="bold">pts</emphasis> command, and are the only
- ones who can issue several other restricted commands (such as the <emphasis role="bold">chown</emphasis> command on AFS
- files). By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
- role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
- permissions on every ACL in the filespace. For information about changing this default, see <link
- linkend="HDRWQ586">Administering the system:administrators Group</link>.</para>
+ </itemizedlist>
+ </para>
- <para>For a discussion of how to use system groups effectively on ACLs, see <link linkend="HDRWQ571">Using Groups on
+ <para>Because the groups do not have a stable membership, the
+ <emphasis role="bold">pts membership</emphasis> command produces no
+ output for them. Similarly, they do not appear in the list of groups
+ to which a user belongs.</para>
+
+ <para>The <emphasis role="bold">system:administrators</emphasis>
+ group does have a stable membership, consisting of the cell's
+ privileged administrators. Members of this group can issue any
+ <emphasis role="bold">pts</emphasis> command, and are the only ones
+ who can issue several other restricted commands (such as the
+ <emphasis role="bold">chown</emphasis> command on AFS files). By
+ default, they also implicitly have the <emphasis
+ role="bold">a</emphasis> (<emphasis
+ role="bold">administer</emphasis>) and <emphasis
+ role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
+ permissions on every ACL in the filespace. For information about
+ changing this default, see <link linkend="HDRWQ586">Administering
+ the system:administrators Group</link>.</para>
+
+ <para>For a discussion of how to use system groups effectively on
+ ACLs, see <link linkend="HDRWQ571">Using Groups on
ACLs</link>.</para>
</sect2>
<sect2 id="HDRWQ62">
<title>The Two Types of User-Defined Groups</title>
- <para>All users can create regular groups. A regular group name has two fields separated by a colon, the first of which must
- indicate the group's ownership. The Protection Server refuses to create or change the name of a group if the result does not
- accurately indicate the ownership.</para>
+ <para>All users can create regular groups. A regular group name has
+ two fields separated by a colon, the first of which must indicate
+ the group's ownership. The Protection Server refuses to create or
+ change the name of a group if the result does not accurately
+ indicate the ownership.</para>
- <para>Members of the <emphasis role="bold">system:administrators</emphasis> group can create prefix-less groups whose names do
- not have the first field that indicates ownership. For suggestions on using the two types of groups effectively, see <link
- linkend="HDRWQ545">Using Groups Effectively</link>.</para>
+ <para>Members of the <emphasis
+ role="bold">system:administrators</emphasis> group can create
+ prefix-less groups whose names do not have the first field that
+ indicates ownership. For suggestions on using the two types of
+ groups effectively, see <link linkend="HDRWQ545">Using Groups
+ Effectively</link>.</para>
<indexterm>
<primary>authentication</primary>
<sect1 id="HDRWQ63">
<title>Login and Authentication in AFS</title>
- <para>As explained in <link linkend="HDRWQ31">Differences in Authentication</link>, AFS authentication is separate from UNIX
- authentication because the two file systems are separate. The separation has two practical implications: <itemizedlist>
+ <para>As explained in <link linkend="HDRWQ31">Differences in
+ Authentication</link>, AFS authentication is separate from UNIX
+ authentication because the two file systems are separate. The
+ separation has two practical implications:
+ <itemizedlist>
<listitem>
- <para>To access AFS files, users must both log into the local file system and authenticate with the AFS authentication
- service. (Logging into the local file system is necessary because the only way to access the AFS filespace is through a
- Cache Manager, which resides in the local machine's kernel.)</para>
+ <para>To access AFS files, users must both log into the local
+ file system and authenticate with the AFS authentication
+ service. (Logging into the local file system is necessary
+ because the only way to access the AFS filespace is through a
+ Cache Manager, which resides in the local machine's
+ kernel.)</para>
</listitem>
<listitem>
- <para>Passwords are stored in two separate places: in the Kerberos Database for AFS and in the each machine's local
- password file (the <emphasis role="bold">/etc/passwd</emphasis> file or equivalent) for the local file system.</para>
+ <para>Passwords are stored in two separate places: in the
+ Kerberos Database for AFS and in the each machine's local
+ password file (the <emphasis role="bold">/etc/passwd</emphasis>
+ file or equivalent) for the local file system.</para>
</listitem>
- </itemizedlist></para>
-
- <para>When a user successfully authenticates, the AFS authentication service passes a token to the user's Cache Manager. The
- token is a small collection of data that certifies that the user has correctly provided the password associated with a
- particular AFS identity. The Cache Manager presents the token to AFS server processes along with service requests, as proof that
- the user is genuine. To learn about the mutual authentication procedure they use to establish identity, see <link
- linkend="HDRWQ75">A More Detailed Look at Mutual Authentication</link>.</para>
-
- <para>The Cache Manager stores tokens in the user's credential structure in kernel memory. To distinguish one user's credential
- structure from another's, the Cache Manager identifies each one either by the user's UNIX UID or by a process authentication
- group (PAG), which is an identification number guaranteed to be unique in the cell. For further discussion, see <link
- linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
+ </itemizedlist>
+ </para>
+
+ <para>When a user successfully authenticates, the AFS authentication
+ service passes a token to the user's Cache Manager. The token is a
+ small collection of data that certifies that the user has correctly
+ provided the password associated with a particular AFS identity. The
+ Cache Manager presents the token to AFS server processes along with
+ service requests, as proof that the user is genuine. To learn about
+ the mutual authentication procedure they use to establish identity,
+ see <link linkend="HDRWQ75">A More Detailed Look at Mutual
+ Authentication</link>.</para>
+
+ <para>The Cache Manager stores tokens in the user's credential
+ structure in kernel memory. To distinguish one user's credential
+ structure from another's, the Cache Manager identifies each one either
+ by the user's UNIX UID or by a process authentication group (PAG),
+ which is an identification number guaranteed to be unique in the
+ cell. For further discussion, see <link linkend="HDRWQ64">Identifying
+ AFS Tokens by PAG</link>.</para>
<indexterm>
<primary>tokens</primary>
<secondary>one-per-cell rule</secondary>
</indexterm>
- <para>A user can have only one token per cell in each separately identified credential structure. To obtain a second token for
- the same cell, the user must either log into a different machine or obtain another credential structure with a different
- identifier than any existing credential structure, which is most easily accomplished by issuing the <emphasis
- role="bold">pagsh</emphasis> command (see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>). In a single credential
- structure, a user can have one token for each of many cells at the same time. As this implies, authentication status on one
- machine or PAG is independent of authentication status on another machine or PAG, which can be very useful to a user or system
+ <para>A user can have only one token per cell in each separately
+ identified credential structure. To obtain a second token for the same
+ cell, the user must either log into a different machine or obtain
+ another credential structure with a different identifier than any
+ existing credential structure, which is most easily accomplished by
+ issuing the <emphasis role="bold">pagsh</emphasis> command (see <link
+ linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>). In a single
+ credential structure, a user can have one token for each of many cells
+ at the same time. As this implies, authentication status on one
+ machine or PAG is independent of authentication status on another
+ machine or PAG, which can be very useful to a user or system
administrator.</para>
- <para>The AFS distribution includes library files that enable each system type's login utility to authenticate users with AFS
- and log them into the local file system in one step. If you do not configure an AFS-modified login utility on a client machine,
- its users must issue the <emphasis role="bold">klog</emphasis> command to authenticate with AFS after logging in.</para>
+ <para>The AFS distribution includes library files that enable each
+ system type's login utility to authenticate users with AFS and log
+ them into the local file system in one step. If you do not configure
+ an AFS-modified login utility on a client machine, its users must
+ issue the <emphasis role="bold">klog</emphasis> command to
+ authenticate with AFS after logging in.</para>
<note>
- <para>The AFS-modified libraries do not necessarily support all features available in an operating system's proprietary login
- utility. In some cases, it is not possible to support a utility at all. For more information about the supported utilities in
- each AFS version, see the OpenAFS Release Notes.</para>
+ <para>The AFS-modified libraries do not necessarily support all
+ features available in an operating system's proprietary login
+ utility. In some cases, it is not possible to support a utility at
+ all. For more information about the supported utilities in each AFS
+ version, see the OpenAFS Release Notes.</para>
</note>
<indexterm>
<sect2 id="HDRWQ64">
<title>Identifying AFS Tokens by PAG</title>
- <para>As noted, the Cache Manager identifies user credential structures either by UNIX UID or by PAG. Using a PAG is
- preferable because it guaranteed to be unique: the Cache Manager allocates it based on a counter that increments with each
- use. In contrast, multiple users on a machine can share or assume the same UNIX UID, which creates potential security
- problems. The following are two common such situations: <itemizedlist>
+ <para>As noted, the Cache Manager identifies user credential
+ structures either by UNIX UID or by PAG. Using a PAG is preferable
+ because it guaranteed to be unique: the Cache Manager allocates it
+ based on a counter that increments with each use. In contrast,
+ multiple users on a machine can share or assume the same UNIX UID,
+ which creates potential security problems. The following are two
+ common such situations:
+ <itemizedlist>
<listitem>
- <para>The local superuser <emphasis role="bold">root</emphasis> can always assume any other user's UNIX UID simply by
- issuing the <emphasis role="bold">su</emphasis> command, without providing the user's password. If the credential
- structure is associated with the user's UNIX UID, then assuming the UID means inheriting the AFS tokens.</para>
+ <para>The local superuser <emphasis
+ role="bold">root</emphasis> can always assume any other user's
+ UNIX UID simply by issuing the <emphasis
+ role="bold">su</emphasis> command, without providing the
+ user's password. If the credential structure is associated
+ with the user's UNIX UID, then assuming the UID means
+ inheriting the AFS tokens.</para>
</listitem>
<listitem>
- <para>Two users working on different NFS client machines can have the same UNIX UID in their respective local file
- systems. If they both access the same NFS/AFS Translator machine, and the Cache Manager there identifies them by their
- UNIX UID, they become indistinguishable. To eliminate this problem, the Cache Manager on a translator machine
- automatically generates a PAG for each user and uses it, rather than the UNIX UID, to tell users apart.</para>
+ <para>Two users working on different NFS client machines can
+ have the same UNIX UID in their respective local file
+ systems. If they both access the same NFS/AFS Translator
+ machine, and the Cache Manager there identifies them by their
+ UNIX UID, they become indistinguishable. To eliminate this
+ problem, the Cache Manager on a translator machine
+ automatically generates a PAG for each user and uses it,
+ rather than the UNIX UID, to tell users apart.</para>
</listitem>
- </itemizedlist></para>
-
- <para>Yet another advantage of PAGs over UIDs is that processes spawned by the user inherit the PAG and so share the token;
- thus they gain access to AFS as the authenticated user. In many environments, for example, printer and other daemons run under
- identities (such as the local superuser <emphasis role="bold">root</emphasis>) that the AFS server processes recognize only as
- the <emphasis role="bold">anonymous</emphasis> user. Unless PAGs are used, such daemons cannot access files for which the
- <emphasis role="bold">system:anyuser</emphasis> group does not have the necessary ACL permissions.</para>
-
- <para>Once a user has a PAG, any new tokens the user obtains are associated with the PAG. The PAG expires two hours after any
- associated tokens expire or are discarded. If the user issues the <emphasis role="bold">klog</emphasis> command before the PAG
- expires, the new token is associated with the existing PAG (the PAG is said to be recycled in this case).</para>
-
- <para>AFS-modified login utilities automatically generate a PAG, as described in the following section. If you use a standard
- login utility, your users must issue the <emphasis role="bold">pagsh</emphasis> command before the <emphasis
- role="bold">klog</emphasis> command, or include the latter command's <emphasis role="bold">-setpag</emphasis> flag. For
- instructions, see <link linkend="HDRWQ69">Using Two-Step Login and Authentication</link>.</para>
+ </itemizedlist>
+ </para>
- <para>Users can also use either command at any time to create a new PAG. The difference between the two commands is that the
- <emphasis role="bold">klog</emphasis> command replaces the PAG associated with the current command shell and tokens. The
- <emphasis role="bold">pagsh</emphasis> command initializes a new command shell before creating a new PAG. If the user already
- had a PAG, any running processes or jobs continue to use the tokens associated with the old PAG whereas any new jobs or
- processes use the new PAG and its associated tokens. When you exit the new shell (by pressing <<emphasis
- role="bold">Ctrl-d</emphasis>>, for example), you return to the original PAG and shell. By default, the <emphasis
- role="bold">pagsh</emphasis> command initializes a Bourne shell, but you can include the <emphasis role="bold">-c</emphasis>
- argument to initialize a C shell (the <emphasis role="bold">/bin/csh</emphasis> program on many system types) or Korn shell
- (the <emphasis role="bold">/bin/ksh</emphasis> program) instead.</para>
+ <para>Yet another advantage of PAGs over UIDs is that processes
+ spawned by the user inherit the PAG and so share the token; thus
+ they gain access to AFS as the authenticated user. In many
+ environments, for example, printer and other daemons run under
+ identities (such as the local superuser <emphasis
+ role="bold">root</emphasis>) that the AFS server processes recognize
+ only as the <emphasis role="bold">anonymous</emphasis> user. Unless
+ PAGs are used, such daemons cannot access files for which the
+ <emphasis role="bold">system:anyuser</emphasis> group does not have
+ the necessary ACL permissions.</para>
+
+ <para>Once a user has a PAG, any new tokens the user obtains are
+ associated with the PAG. The PAG expires two hours after any
+ associated tokens expire or are discarded. If the user issues the
+ <emphasis role="bold">klog</emphasis> command before the PAG
+ expires, the new token is associated with the existing PAG (the PAG
+ is said to be recycled in this case).</para>
+
+ <para>AFS-modified login utilities automatically generate a PAG, as
+ described in the following section. If you use a standard login
+ utility, your users must issue the <emphasis
+ role="bold">pagsh</emphasis> command before the <emphasis
+ role="bold">klog</emphasis> command, or include the latter command's
+ <emphasis role="bold">-setpag</emphasis> flag. For instructions, see
+ <link linkend="HDRWQ69">Using Two-Step Login and
+ Authentication</link>.</para>
+
+ <para>Users can also use either command at any time to create a new
+ PAG. The difference between the two commands is that the <emphasis
+ role="bold">klog</emphasis> command replaces the PAG associated with
+ the current command shell and tokens. The <emphasis
+ role="bold">pagsh</emphasis> command initializes a new command shell
+ before creating a new PAG. If the user already had a PAG, any
+ running processes or jobs continue to use the tokens associated with
+ the old PAG whereas any new jobs or processes use the new PAG and
+ its associated tokens. When you exit the new shell (by pressing
+ <<emphasis role="bold">Ctrl-d</emphasis>>, for example), you
+ return to the original PAG and shell. By default, the <emphasis
+ role="bold">pagsh</emphasis> command initializes a Bourne shell, but
+ you can include the <emphasis role="bold">-c</emphasis> argument to
+ initialize a C shell (the <emphasis role="bold">/bin/csh</emphasis>
+ program on many system types) or Korn shell (the <emphasis
+ role="bold">/bin/ksh</emphasis> program) instead.</para>
<indexterm>
<primary>login utility</primary>
<sect2 id="HDRWQ65">
<title>Using an AFS-modified login Utility</title>
- <para>As previously mentioned, an AFS-modified login utility simultaneously obtains an AFS token and logs the user into the
- local file system. This section outlines the login and authentication process and its interaction with the value in the
- password field of the local password file.</para>
+ <para>As previously mentioned, an AFS-modified login utility
+ simultaneously obtains an AFS token and logs the user into the local
+ file system. This section outlines the login and authentication
+ process and its interaction with the value in the password field of
+ the local password file.</para>
- <para>An AFS-modified login utility performs a sequence of steps similar to the following; details can vary for different
- operating systems: <orderedlist>
+ <para>An AFS-modified login utility performs a sequence of steps
+ similar to the following; details can vary for different operating
+ systems:
+ <orderedlist>
<listitem>
- <para>It checks the user's entry in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
+ <para>It checks the user's entry in the local password file
+ (the <emphasis role="bold">/etc/passwd</emphasis> file or
equivalent).</para>
</listitem>
<listitem>
- <para>If no entry exists, or if an asterisk (<computeroutput>*</computeroutput>) appears in the entry's password field,
- the login attempt fails. If the entry exists, the attempt proceeds to the next step.</para>
+ <para>If no entry exists, or if an asterisk
+ (<computeroutput>*</computeroutput>) appears in the entry's
+ password field, the login attempt fails. If the entry exists,
+ the attempt proceeds to the next step.</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para><anchor id="LIWQ67" />The utility converts the password provided by the user into an encryption key and encrypts a
- packet of data with the key. It sends the packet to the AFS authentication service (the AFS Authentication Server in the
+ <para><anchor id="LIWQ67" />The utility converts the password
+ provided by the user into an encryption key and encrypts a
+ packet of data with the key. It sends the packet to the AFS
+ authentication service (the AFS Authentication Server in the
conventional configuration).</para>
</listitem>
<listitem>
- <para>The authentication service decrypts the packet and, depending on the success of the decryption, judges the
- password to be correct or incorrect. (For more details, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
- Authentication</link>.) <itemizedlist>
+ <para>The authentication service decrypts the packet and,
+ depending on the success of the decryption, judges the
+ password to be correct or incorrect. (For more details, see
+ <link linkend="HDRWQ75">A More Detailed Look at Mutual
+ Authentication</link>.)
+ <itemizedlist>
<listitem>
- <para>If the authentication service judges the password incorrect, the user does not receive an AFS token. The PAG
- is retained, ready to be associated with any tokens obtained later. The attempt proceeds to Step <link
+ <para>If the authentication service judges the password
+ incorrect, the user does not receive an AFS token. The
+ PAG is retained, ready to be associated with any tokens
+ obtained later. The attempt proceeds to Step <link
linkend="LIWQ68">6</link>.</para>
</listitem>
<listitem>
- <para>If the authentication service judges the password correct, it issues a token to the user as proof of AFS
- authentication. The login utility logs the user into the local UNIX file system. Some login utilities echo the
- following banner to the screen to alert the user to authentication with AFS. Step <link linkend="LIWQ68">6</link>
- is skipped. <programlisting>
- AFS(R) version Login
-</programlisting></para>
+ <para>If the authentication service judges the password
+ correct, it issues a token to the user as proof of AFS
+ authentication. The login utility logs the user into the
+ local UNIX file system. Some login utilities echo the
+ following banner to the screen to alert the user to
+ authentication with AFS. Step <link
+ linkend="LIWQ68">6</link> is skipped.
+<programlisting>
+ AFS(R) version Login
+</programlisting>
+ </para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</listitem>
<listitem>
- <para><anchor id="LIWQ68" />If no AFS token was granted in Step <link linkend="LIWQ67">4</link>, the login utility
- attempts to log the user into the local file system, by comparing the password provided to the local password file.
+ <para><anchor id="LIWQ68" />If no AFS token was granted in
+ Step <link linkend="LIWQ67">4</link>, the login utility
+ attempts to log the user into the local file system, by
+ comparing the password provided to the local password file.
<itemizedlist>
<listitem>
- <para>If the password is incorrect or any value other than an encrypted 13-character string appears in the
+ <para>If the password is incorrect or any value other
+ than an encrypted 13-character string appears in the
password field, the login attempt fails.</para>
</listitem>
<listitem>
- <para>If the password is correct, the user is logged into the local file system only.</para>
- </listitem>
- </itemizedlist></para>
+ <para>If the password is correct, the user is logged
+ into the local file system only.</para> </listitem>
+ </itemizedlist>
+ </para>
</listitem>
- </orderedlist></para>
+ </orderedlist>
+ </para>
<indexterm>
<primary>local password file</primary>
<indexterm>
<primary>login utility</primary>
- <secondary>AFS version's interaction with local password file</secondary>
+ <secondary>AFS version's interaction with local password
+ file</secondary>
</indexterm>
<indexterm>
<secondary>local password file</secondary>
</indexterm>
- <para>As indicated, when you use an AFS-modified login utility, the password field in the local password file is no longer the
- primary gate for access to your system. If the user provides the correct AFS password, then the program never consults the
- local password file. However, you can still use the password field to control access, in the following way: <itemizedlist>
+ <para>As indicated, when you use an AFS-modified login utility, the
+ password field in the local password file is no longer the primary
+ gate for access to your system. If the user provides the correct AFS
+ password, then the program never consults the local password
+ file. However, you can still use the password field to control
+ access, in the following way:
+ <itemizedlist>
<listitem>
- <para>To prevent both local login and AFS authentication, place an asterisk (<emphasis role="bold">*</emphasis>) in the
- field. This is useful mainly in emergencies, when you want to prevent a certain user from logging into the
- machine.</para>
+ <para>To prevent both local login and AFS authentication,
+ place an asterisk (<emphasis role="bold">*</emphasis>) in the
+ field. This is useful mainly in emergencies, when you want to
+ prevent a certain user from logging into the machine.</para>
</listitem>
<listitem>
- <para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
- string of any length other than the standard thirteen characters in the field. This is appropriate if you want to permit
- only people with local AFS accounts to login on your machines. A single <emphasis role="bold">X</emphasis> or other
- character is the most easily recognizable way to do this.</para>
+ <para>To prevent login to the local file system if the user
+ does not provide the correct AFS password, place a character
+ string of any length other than the standard thirteen
+ characters in the field. This is appropriate if you want to
+ permit only people with local AFS accounts to login on your
+ machines. A single <emphasis role="bold">X</emphasis> or other
+ character is the most easily recognizable way to do
+ this.</para>
</listitem>
<listitem>
- <para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
- standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
+ <para>To enable a user to log into the local file system even
+ after providing an incorrect AFS password, record a standard
+ UNIX encrypted password in the field by issuing the standard
+ UNIX password-setting command (<emphasis
role="bold">passwd</emphasis> or equivalent).</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>Systems that use a Pluggable Authentication Module (PAM) for login and AFS authentication do not necessarily consult the
- local password file at all, in which case they do not use the password field to control authentication and login attempts.
- Instead, instructions in the PAM configuration file (on many system types, <emphasis role="bold">/etc/pam.conf</emphasis>)
- fill the same function. See the instructions in the OpenAFS Quick Beginnings for installing AFS-modified login
- utilities.</para>
+ <para>Systems that use a Pluggable Authentication Module (PAM) for
+ login and AFS authentication do not necessarily consult the local
+ password file at all, in which case they do not use the password
+ field to control authentication and login attempts. Instead,
+ instructions in the PAM configuration file (on many system types,
+ <emphasis role="bold">/etc/pam.conf</emphasis>) fill the same
+ function. See the instructions in the OpenAFS Quick Beginnings for
+ installing AFS-modified login utilities.</para>
<indexterm>
<primary>local password file</primary>
<sect2 id="HDRWQ69">
<title>Using Two-Step Login and Authentication</title>
- <para>In cells that do not use an AFS-modified login utility, users must issue separate commands to login and authenticate, as
- detailed in the OpenAFS User Guide: <orderedlist>
+ <para>In cells that do not use an AFS-modified login utility, users
+ must issue separate commands to login and authenticate, as detailed
+ in the OpenAFS User Guide:
+ <orderedlist>
<listitem>
- <para>They use the standard <emphasis role="bold">login</emphasis> program to login to the local file system, providing
- the password listed in the local password file (the <emphasis role="bold">/etc/passwd</emphasis> file or
- equivalent).</para>
+ <para>They use the standard <emphasis
+ role="bold">login</emphasis> program to login to the local
+ file system, providing the password listed in the local
+ password file (the <emphasis
+ role="bold">/etc/passwd</emphasis> file or equivalent).</para>
</listitem>
<listitem>
- <para>They must issue the <emphasis role="bold">klog</emphasis> command to authenticate with the AFS authentication
- service, including its <emphasis role="bold">-setpag</emphasis> flag to associate the new tokens with a process
- authentication group (PAG).</para>
+ <para>They must issue the <emphasis
+ role="bold">klog</emphasis> command to authenticate with the
+ AFS authentication service, including its <emphasis
+ role="bold">-setpag</emphasis> flag to associate the new
+ tokens with a process authentication group (PAG).</para>
</listitem>
- </orderedlist></para>
-
- <para>As mentioned in <link linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>, you can invoke the <emphasis
- role="bold">klog -setpag</emphasis> command in a user's <emphasis role="bold">.login</emphasis> file (or equivalent) so that
- the user does not have to remember to issue the command after logging in. The user still must type a password twice, once at
- the prompt generated by the login utility and once at the <emphasis role="bold">klog</emphasis> command's prompt. This implies
- that the two passwords can differ, but it is less confusing if they do not.</para>
-
- <para>Another effect of not using an AFS-modified login utility is that the AFS servers recognize the standard <emphasis
- role="bold">login</emphasis> program as the <emphasis role="bold">anonymous</emphasis> user. If the <emphasis
- role="bold">login</emphasis> program needs to access any AFS files (such as the <emphasis role="bold">.login</emphasis> file
- in a user's home directory), then the ACL that protects the file must include an entry granting the <emphasis
- role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
- role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:anyuser</emphasis> group.</para>
+ </orderedlist>
+ </para>
- <para>When you do not use an AFS-modified login utility, an actual (scrambled) password must appear in the local password file
- for each user. Use the <emphasis role="bold">/bin/passwd</emphasis> file to insert or change these passwords. It is simpler if
- the password in the local password file matches the AFS password, but it is not required.</para>
+ <para>As mentioned in <link linkend="HDRWQ60">Creating Standard
+ Files in New AFS Accounts</link>, you can invoke the <emphasis
+ role="bold">klog -setpag</emphasis> command in a user's <emphasis
+ role="bold">.login</emphasis> file (or equivalent) so that the user
+ does not have to remember to issue the command after logging in. The
+ user still must type a password twice, once at the prompt generated
+ by the login utility and once at the <emphasis
+ role="bold">klog</emphasis> command's prompt. This implies that the
+ two passwords can differ, but it is less confusing if they do
+ not.</para>
+
+ <para>Another effect of not using an AFS-modified login utility is
+ that the AFS servers recognize the standard <emphasis
+ role="bold">login</emphasis> program as the <emphasis
+ role="bold">anonymous</emphasis> user. If the <emphasis
+ role="bold">login</emphasis> program needs to access any AFS files
+ (such as the <emphasis role="bold">.login</emphasis> file in a
+ user's home directory), then the ACL that protects the file must
+ include an entry granting the <emphasis role="bold">l</emphasis>
+ (<emphasis role="bold">lookup</emphasis>) and <emphasis
+ role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>)
+ permissions to the <emphasis role="bold">system:anyuser</emphasis>
+ group.</para>
+
+ <para>When you do not use an AFS-modified login utility, an actual
+ (scrambled) password must appear in the local password file for each
+ user. Use the <emphasis role="bold">/bin/passwd</emphasis> file to
+ insert or change these passwords. It is simpler if the password in
+ the local password file matches the AFS password, but it is not
+ required.</para>
<indexterm>
<primary>tokens</primary>
<sect2 id="Header_81">
<title>Obtaining, Displaying, and Discarding Tokens</title>
- <para>Once logged in, a user can obtain a token at any time with the <emphasis role="bold">klog</emphasis> command. If a valid
- token already exists, the new one overwrites it. If a PAG already exists, the new token is associated with it.</para>
-
- <para>By default, the <emphasis role="bold">klog</emphasis> command authenticates the issuer using the identity currently
- logged in to the local file system. To authenticate as a different identity, use the <emphasis
- role="bold">-principal</emphasis> argument. To obtain a token for a foreign cell, use the <emphasis
- role="bold">-cell</emphasis> argument (it can be combined with the <emphasis role="bold">-principal</emphasis> argument). See
- the OpenAFS User Guide and the entry for the <emphasis role="bold">klog</emphasis> command in the OpenAFS Administration
+ <para>Once logged in, a user can obtain a token at any time with the
+ <emphasis role="bold">klog</emphasis> command. If a valid token
+ already exists, the new one overwrites it. If a PAG already exists,
+ the new token is associated with it.</para>
+
+ <para>By default, the <emphasis role="bold">klog</emphasis> command
+ authenticates the issuer using the identity currently logged in to
+ the local file system. To authenticate as a different identity, use
+ the <emphasis role="bold">-principal</emphasis> argument. To obtain
+ a token for a foreign cell, use the <emphasis
+ role="bold">-cell</emphasis> argument (it can be combined with the
+ <emphasis role="bold">-principal</emphasis> argument). See the
+ OpenAFS User Guide and the entry for the <emphasis
+ role="bold">klog</emphasis> command in the OpenAFS Administration
Reference.</para>
- <para>To discard either all tokens or the token for a particular cell, issue the <emphasis role="bold">unlog</emphasis>
- command. The command affects only the tokens associated with the current command shell. See the OpenAFS User Guideand the
- entry for the <emphasis role="bold">unlog</emphasis> command in the OpenAFS Administration Reference.</para>
+ <para>To discard either all tokens or the token for a particular
+ cell, issue the <emphasis role="bold">unlog</emphasis> command. The
+ command affects only the tokens associated with the current command
+ shell. See the OpenAFS User Guideand the entry for the <emphasis
+ role="bold">unlog</emphasis> command in the OpenAFS Administration
+ Reference.</para>
- <para>To display the tokens associated with the current command shell, issue the <emphasis role="bold">tokens</emphasis>
- command. The following examples illustrate its output in various situations.</para>
+ <para>To display the tokens associated with the current command
+ shell, issue the <emphasis role="bold">tokens</emphasis>
+ command. The following examples illustrate its output in various
+ situations.</para>
<para>If the issuer is not authenticated in any cell:</para>
- <programlisting>
+<programlisting>
% <emphasis role="bold">tokens</emphasis>
Tokens held by the Cache Manager:
--End of list--
</programlisting>
- <para>The following shows the output for a user with AFS UID 1000 in the ABC Corporation cell:</para>
+ <para>The following shows the output for a user with AFS UID 1000 in
+ the ABC Corporation cell:</para>
- <programlisting>
+<programlisting>
% <emphasis role="bold">tokens</emphasis>
- Tokens held by the Cache Manager:
+ Tokens held by the Cache Manager:
User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun 2 10:00]
--End of list--
</programlisting>
- <para>The following shows the output for a user who is authenticated in ABC Corporation cell, the State University cell and
- the DEF Company cell. The user has different AFS UIDs in the three cells. Tokens for the last cell are expired:</para>
+ <para>The following shows the output for a user who is authenticated
+ in ABC Corporation cell, the State University cell and the DEF
+ Company cell. The user has different AFS UIDs in the three
+ cells. Tokens for the last cell are expired:</para>
- <programlisting>
+<programlisting>
% <emphasis role="bold">tokens</emphasis>
Tokens held by the Cache Manager:
User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun 2 10:00]
--End of list--
</programlisting>
- <para>The Kerberos version of the <emphasis role="bold">tokens</emphasis> command (the <emphasis
- role="bold">tokens.krb</emphasis> command), also reports information on the ticket-granting ticket, including the ticket's
- owner, the ticket-granting service, and the expiration date, as in the following example. Also see <link
- linkend="HDRWQ70">Support for Kerberos Authentication</link>.</para>
+ <para>The Kerberos version of the <emphasis
+ role="bold">tokens</emphasis> command (the <emphasis
+ role="bold">tokens.krb</emphasis> command), also reports information
+ on the ticket-granting ticket, including the ticket's owner, the
+ ticket-granting service, and the expiration date, as in the
+ following example. Also see <link linkend="HDRWQ70">Support for
+ Kerberos Authentication</link>.</para>
- <programlisting>
+<programlisting>
% <emphasis role="bold">tokens.krb</emphasis>
Tokens held by the Cache Manager:
User's (AFS ID 1000) tokens for afs@abc.com [Expires Jun 2 10:00]
<secondary>setting default lifetimes for users</secondary>
</indexterm>
- <para>The maximum lifetime of a user token is the smallest of the ticket lifetimes recorded in the following three
- Authentication Database entries. The <emphasis role="bold">kas examine</emphasis> command reports the lifetime as
- <computeroutput>Max ticket lifetime</computeroutput>. Administrators who have the <computeroutput>ADMIN</computeroutput> flag
- on their Authentication Database entry can use the <emphasis role="bold">-lifetime</emphasis> argument to the <emphasis
- role="bold">kas setfields</emphasis> command to set an entry's ticket lifetime. <itemizedlist>
+ <para>The maximum lifetime of a user token is the smallest of the
+ ticket lifetimes recorded in the following three Authentication
+ Database entries. The <emphasis role="bold">kas examine</emphasis>
+ command reports the lifetime as <computeroutput>Max ticket
+ lifetime</computeroutput>. Administrators who have the
+ <computeroutput>ADMIN</computeroutput> flag on their Authentication
+ Database entry can use the <emphasis
+ role="bold">-lifetime</emphasis> argument to the <emphasis
+ role="bold">kas setfields</emphasis> command to set an entry's
+ ticket lifetime.
+ <itemizedlist>
<listitem>
- <para>The <emphasis role="bold">afs</emphasis> entry, which corresponds to the AFS server processes. The default is 100
+ <para>The <emphasis role="bold">afs</emphasis> entry, which
+ corresponds to the AFS server processes. The default is 100
hours.</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">krbtgt</emphasis>.cellname entry, which corresponds to the ticket-granting ticket used
- internally in generating the token. The default is 720 hours (30 days).</para>
+ <para>The <emphasis role="bold">krbtgt</emphasis>.cellname
+ entry, which corresponds to the ticket-granting ticket used
+ internally in generating the token. The default is 720 hours
+ (30 days).</para>
</listitem>
<listitem>
- <para>The entry for the user of the AFS-modified login utility or issuer of the <emphasis role="bold">klog</emphasis>
- command. The default is 25 hours for user entries created using the AFS 3.1 or later version of the Authentication
- Server, and 100 hours for user entries created using the AFS 3.0 version of the Authentication Server. A user can use
- the <emphasis role="bold">kas examine</emphasis> command to display his or her own Authentication Database entry.</para>
+ <para>The entry for the user of the AFS-modified login utility
+ or issuer of the <emphasis role="bold">klog</emphasis>
+ command. The default is 25 hours for user entries created
+ using the AFS 3.1 or later version of the Authentication
+ Server, and 100 hours for user entries created using the AFS
+ 3.0 version of the Authentication Server. A user can use the
+ <emphasis role="bold">kas examine</emphasis> command to
+ display his or her own Authentication Database entry.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
<note>
- <para>An AFS-modified login utility always grants a token with a lifetime calculated from the previously described three
- values. When issuing the <emphasis role="bold">klog</emphasis> command, a user can request a lifetime shorter than the
- default by using the <emphasis role="bold">-lifetime</emphasis> argument. For further information, see the OpenAFS User
- Guide and the <emphasis role="bold">klog</emphasis> reference page in the OpenAFS Administration Reference.</para>
+ <para>An AFS-modified login utility always grants a token with a
+ lifetime calculated from the previously described three
+ values. When issuing the <emphasis role="bold">klog</emphasis>
+ command, a user can request a lifetime shorter than the default by
+ using the <emphasis role="bold">-lifetime</emphasis> argument. For
+ further information, see the OpenAFS User Guide and the <emphasis
+ role="bold">klog</emphasis> reference page in the OpenAFS
+ Administration Reference.</para>
</note>
</sect2>
<secondary>kas setpassword</secondary>
</indexterm>
- <para>Regular AFS users can change their own passwords by using either the <emphasis role="bold">kpasswd</emphasis> or
- <emphasis role="bold">kas setpassword</emphasis> command. The commands prompt for the current password and then twice for the
- new password, to screen out typing errors.</para>
+ <para>Regular AFS users can change their own passwords by using
+ either the <emphasis role="bold">kpasswd</emphasis> or <emphasis
+ role="bold">kas setpassword</emphasis> command. The commands prompt
+ for the current password and then twice for the new password, to
+ screen out typing errors.</para>
- <para>Administrators who have the <computeroutput>ADMIN</computeroutput> flag on their Authentication Database entries can
- change any user's password, either by using the <emphasis role="bold">kpasswd</emphasis> command (which requires knowing the
- current password) or the <emphasis role="bold">kas setpassword</emphasis> command.</para>
+ <para>Administrators who have the
+ <computeroutput>ADMIN</computeroutput> flag on their Authentication
+ Database entries can change any user's password, either by using the
+ <emphasis role="bold">kpasswd</emphasis> command (which requires
+ knowing the current password) or the <emphasis role="bold">kas
+ setpassword</emphasis> command.</para>
- <para>If your cell does not use an AFS-modified login utility, remember also to change the local password, using the operating
- system's password-changing command. For more instructions on changing passwords, see <link linkend="HDRWQ516">Changing AFS
+ <para>If your cell does not use an AFS-modified login utility,
+ remember also to change the local password, using the operating
+ system's password-changing command. For more instructions on
+ changing passwords, see <link linkend="HDRWQ516">Changing AFS
Passwords</link>.</para>
</sect2>
<sect2 id="Header_84">
- <title>Imposing Restrictions on Passwords and Authentication Attempts</title>
+ <title>Imposing Restrictions on Passwords and Authentication
+ Attempts</title>
- <para>You can help to make your cell more secure by imposing restrictions on user passwords and authentication attempts. To
- impose the restrictions as you create an account, use the <emphasis role="bold">A</emphasis> instruction in the <emphasis
- role="bold">uss</emphasis> template file as described in <link linkend="HDRWQ478">Increasing Account Security with the A
- Instruction</link>. To set or change the values on an existing account, use the <emphasis role="bold">kas setfields</emphasis>
- command as described in <link linkend="HDRWQ515">Improving Password and Authentication Security</link>.</para>
+ <para>You can help to make your cell more secure by imposing
+ restrictions on user passwords and authentication attempts. To
+ impose the restrictions as you create an account, use the <emphasis
+ role="bold">A</emphasis> instruction in the <emphasis
+ role="bold">uss</emphasis> template file as described in <link
+ linkend="HDRWQ478">Increasing Account Security with the A
+ Instruction</link>. To set or change the values on an existing
+ account, use the <emphasis role="bold">kas setfields</emphasis>
+ command as described in <link linkend="HDRWQ515">Improving Password
+ and Authentication Security</link>.</para>
<indexterm>
<primary>password</primary>
<secondary>restricting reuse</secondary>
</indexterm>
- <para>By default, AFS passwords never expire. Limiting password lifetime can help improve security by decreasing the time the
- password is subject to cracking attempts. You can choose an lifetime from 1 to 254 days after the password was last changed.
- It automatically applies to each new password as it is set. When the user changes passwords, you can also insist that the new
- password is not similar to any of the 20 passwords previously used.</para>
+ <para>By default, AFS passwords never expire. Limiting password
+ lifetime can help improve security by decreasing the time the
+ password is subject to cracking attempts. You can choose an lifetime
+ from 1 to 254 days after the password was last changed. It
+ automatically applies to each new password as it is set. When the
+ user changes passwords, you can also insist that the new password is
+ not similar to any of the 20 passwords previously used.</para>
<indexterm>
<primary>password</primary>
- <secondary>consequences of multiple failed authentication attempts</secondary>
+ <secondary>consequences of multiple failed authentication
+ attempts</secondary>
</indexterm>
<indexterm>
<secondary>consequences of multiple failures</secondary>
</indexterm>
- <para>Unscrupulous users can try to gain access to your AFS cell by guessing an authorized user's password. To protect against
- this type of attack, you can limit the number of times that a user can consecutively fail to provide the correct password.
- When the limit is exceeded, the authentication service refuses further authentication attempts for a specified period of time
- (the lockout time). To reenable authentication attempts before the lockout time expires, an administrator must issue the
- <emphasis role="bold">kas unlock</emphasis> command.</para>
+ <para>Unscrupulous users can try to gain access to your AFS cell by
+ guessing an authorized user's password. To protect against this type
+ of attack, you can limit the number of times that a user can
+ consecutively fail to provide the correct password. When the limit
+ is exceeded, the authentication service refuses further
+ authentication attempts for a specified period of time (the lockout
+ time). To reenable authentication attempts before the lockout time
+ expires, an administrator must issue the <emphasis role="bold">kas
+ unlock</emphasis> command.</para>
<indexterm>
<primary>password</primary>
<primary>kpwvalid program</primary>
</indexterm>
- <para>In addition to settings on user's authentication accounts, you can improve security by automatically checking the
- quality of new user passwords. The <emphasis role="bold">kpasswd</emphasis> and <emphasis role="bold">kas
- setpassword</emphasis> commands pass the proposed password to a program or script called <emphasis
- role="bold">kpwvalid</emphasis>, if it exists. The <emphasis role="bold">kpwvalid</emphasis> performs quality checks and
- returns a code to indicate whether the password is acceptable. You can create your own program or modified the sample program
- included in the AFS distribution. See the <emphasis role="bold">kpwvalid</emphasis> reference page in the OpenAFS
+ <para>In addition to settings on user's authentication accounts, you
+ can improve security by automatically checking the quality of new
+ user passwords. The <emphasis role="bold">kpasswd</emphasis> and
+ <emphasis role="bold">kas setpassword</emphasis> commands pass the
+ proposed password to a program or script called <emphasis
+ role="bold">kpwvalid</emphasis>, if it exists. The <emphasis
+ role="bold">kpwvalid</emphasis> performs quality checks and returns
+ a code to indicate whether the password is acceptable. You can
+ create your own program or modified the sample program included in
+ the AFS distribution. See the <emphasis
+ role="bold">kpwvalid</emphasis> reference page in the OpenAFS
Administration Reference.</para>
- <para>There are several types of quality checks that can improve password quality. <itemizedlist>
+ <para>There are several types of quality checks that can improve
+ password quality.
+ <itemizedlist>
<listitem>
<para>The password is a minimum length</para>
</listitem>
<listitem>
<para>The password contains both numbers and letters</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</sect2>
<sect2 id="HDRWQ70">
<primary>tokens.krb command</primary>
</indexterm>
- <para>If your site is using standard Kerberos authentication rather than the AFS Authentication Server, use the modified
- versions of the <emphasis role="bold">klog</emphasis>, <emphasis role="bold">pagsh</emphasis>, and <emphasis
- role="bold">tokens</emphasis> commands that support Kerberos authentication. The binaries for the modified version of these
- commands have the same name as the standard binaries with the addition of a <emphasis role="bold">.krb</emphasis>
+ <para>If your site is using standard Kerberos authentication rather
+ than the AFS Authentication Server, use the modified versions of the
+ <emphasis role="bold">klog</emphasis>, <emphasis
+ role="bold">pagsh</emphasis>, and <emphasis
+ role="bold">tokens</emphasis> commands that support Kerberos
+ authentication. The binaries for the modified version of these
+ commands have the same name as the standard binaries with the
+ addition of a <emphasis role="bold">.krb</emphasis>
extension.</para>
- <para>Use either the Kerberos version or the standard command throughout the cell; do not mix the two versions. AFS Product
- Support can provide instructions on installing the Kerberos version of these four commands. For information on the differences
- between the two versions of these commands, see the OpenAFS Administration Reference.</para>
- </sect2>
- </sect1>
+ <para>Use either the Kerberos version or the standard command
+ throughout the cell; do not mix the two versions. AFS Product
+ Support can provide instructions on installing the Kerberos version
+ of these four commands. For information on the differences between
+ the two versions of these commands, see the OpenAFS Administration
+ Reference.</para>
+ </sect2> </sect1>
<sect1 id="HDRWQ71">
<title>Security and Authorization in AFS</title>
- <para>AFS incorporates several features to ensure that only authorized users gain access to data. This section summarizes the
- most important of them and suggests methods for improving security in your cell.</para>
+ <para>AFS incorporates several features to ensure that only authorized
+ users gain access to data. This section summarizes the most important
+ of them and suggests methods for improving security in your
+ cell.</para>
<sect2 id="HDRWQ72">
<title>Some Important Security Features</title>
<formalpara>
<title>ACLs on Directories</title>
- <para>Files in AFS are protected by the access control list (ACL) associated with their parent directory. The ACL defines
- which users or groups can access the data in the directory, and in what way. See <link linkend="HDRWQ562">Managing Access
- Control Lists</link>.</para>
+ <para>Files in AFS are protected by the access control list (ACL)
+ associated with their parent directory. The ACL defines which
+ users or groups can access the data in the directory, and in what
+ way. See <link linkend="HDRWQ562">Managing Access Control
+ Lists</link>.</para>
</formalpara>
<formalpara>
<title>Mutual Authentication Between Client and Server</title>
- <para>When an AFS client and server process communicate, each requires the other to prove its identity during mutual
- authentication, which involves the exchange of encrypted information that only valid parties can decrypt and respond to. For
- a detailed description of the mutual authentication process, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
- Authentication</link>.</para>
+ <para>When an AFS client and server process communicate, each
+ requires the other to prove its identity during mutual
+ authentication, which involves the exchange of encrypted
+ information that only valid parties can decrypt and respond
+ to. For a detailed description of the mutual authentication
+ process, see <link linkend="HDRWQ75">A More Detailed Look at
+ Mutual Authentication</link>.</para>
</formalpara>
- <para>AFS server processes mutually authenticate both with one another and with processes that represent human users. After
- mutual authentication is complete, the server and client have established an authenticated connection, across which they can
- communicate repeatedly without having to authenticate again until the connection expires or one of the parties closes it.
- Authenticated connections have varying lifetimes.</para>
+ <para>AFS server processes mutually authenticate both with one
+ another and with processes that represent human users. After mutual
+ authentication is complete, the server and client have established
+ an authenticated connection, across which they can communicate
+ repeatedly without having to authenticate again until the connection
+ expires or one of the parties closes it. Authenticated connections
+ have varying lifetimes.</para>
<formalpara>
<title>Tokens</title>
- <para>In order to access AFS files, users must prove their identities to the AFS authentication service by providing the
- correct AFS password. If the password is correct, the authentication service sends the user a token as evidence of
- authenticated status. See <link linkend="HDRWQ63">Login and Authentication in AFS</link>.</para>
+ <para>In order to access AFS files, users must prove their
+ identities to the AFS authentication service by providing the
+ correct AFS password. If the password is correct, the
+ authentication service sends the user a token as evidence of
+ authenticated status. See <link linkend="HDRWQ63">Login and
+ Authentication in AFS</link>.</para>
</formalpara>
- <para>Servers assign the user identity <emphasis role="bold">anonymous</emphasis> to users and processes that do not have a
- valid token. The <emphasis role="bold">anonymous</emphasis> identity has only the access granted to the <emphasis
+ <para>Servers assign the user identity <emphasis
+ role="bold">anonymous</emphasis> to users and processes that do not
+ have a valid token. The <emphasis role="bold">anonymous</emphasis>
+ identity has only the access granted to the <emphasis
role="bold">system:anyuser</emphasis> group on ACLs.</para>
<formalpara>
<title>Authorization Checking</title>
- <para>Mutual authentication establishes that two parties communicating with one another are actually who they claim to be.
- For many functions, AFS server processes also check that the client whose identity they have verified is also authorized to
- make the request. Different requests require different kinds of privilege. See <link linkend="HDRWQ73">Three Types of
+ <para>Mutual authentication establishes that two parties
+ communicating with one another are actually who they claim to be.
+ For many functions, AFS server processes also check that the
+ client whose identity they have verified is also authorized to
+ make the request. Different requests require different kinds of
+ privilege. See <link linkend="HDRWQ73">Three Types of
Privilege</link>.</para>
</formalpara>
<secondary>encrypted network communication</secondary>
</indexterm>
- <para>The AFS server processes encrypt particularly sensitive information before sending it back to clients. Even if an
- unauthorized party is able to eavesdrop on an authenticated connection, they cannot decipher encrypted data without the
- proper key.</para>
+ <para>The AFS server processes encrypt particularly sensitive
+ information before sending it back to clients. Even if an
+ unauthorized party is able to eavesdrop on an authenticated
+ connection, they cannot decipher encrypted data without the proper
+ key.</para>
</formalpara>
- <para>The following AFS commands encrypt data because they involve server encryption keys and passwords: <itemizedlist>
+ <para>The following AFS commands encrypt data because they involve
+ server encryption keys and passwords:
+ <itemizedlist>
<listitem>
- <para>The <emphasis role="bold">bos addkey</emphasis> command, which adds a server encryption key to the <emphasis
+ <para>The <emphasis role="bold">bos addkey</emphasis> command,
+ which adds a server encryption key to the <emphasis
role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">bos listkeys</emphasis> command, which lists the server encryption keys from the
- <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file</para>
+ <para>The <emphasis role="bold">bos listkeys</emphasis>
+ command, which lists the server encryption keys from the
+ <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis>
+ file</para>
</listitem>
<listitem>
- <para>The <emphasis role="bold">kpasswd</emphasis> command, which changes a password in the Authentication
- Database</para>
+ <para>The <emphasis role="bold">kpasswd</emphasis> command,
+ which changes a password in the Authentication Database</para>
</listitem>
<listitem>
- <para>Most commands in the <emphasis role="bold">kas</emphasis> command suite</para>
+ <para>Most commands in the <emphasis
+ role="bold">kas</emphasis> command suite</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>In addition, the United States edition of the Update Server encrypts sensitive information (such as the contents of
- <emphasis role="bold">KeyFile</emphasis>) when distributing it. Other commands in the <emphasis role="bold">bos</emphasis>
- suite and the commands in the <emphasis role="bold">fs</emphasis>, <emphasis role="bold">pts</emphasis> and <emphasis
- role="bold">vos</emphasis> suites do not encrypt data before transmitting it.</para>
+ <para>In addition, the United States edition of the Update Server
+ encrypts sensitive information (such as the contents of <emphasis
+ role="bold">KeyFile</emphasis>) when distributing it. Other commands
+ in the <emphasis role="bold">bos</emphasis> suite and the commands
+ in the <emphasis role="bold">fs</emphasis>, <emphasis
+ role="bold">pts</emphasis> and <emphasis role="bold">vos</emphasis>
+ suites do not encrypt data before transmitting it.</para>
</sect2>
<sect2 id="HDRWQ73">
<title>Three Types of Privilege</title>
- <para>AFS uses three separate types of privilege for the reasons discussed in <link linkend="HDRWQ585">The Reason for Separate
- Privileges</link>. <itemizedlist>
+ <para>AFS uses three separate types of privilege for the reasons
+ discussed in <link linkend="HDRWQ585">The Reason for Separate
+ Privileges</link>.
+ <itemizedlist>
<listitem>
- <para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. Members are entitled to issue any
- <emphasis role="bold">pts</emphasis> command and those <emphasis role="bold">fs</emphasis> commands that set volume
- quota. By default, they also implicitly have the <emphasis role="bold">a</emphasis> (<emphasis
- role="bold">administer</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>)
- permissions on every ACL in the file tree even if the ACL does not include an entry for them.</para>
+ <para>Membership in the <emphasis
+ role="bold">system:administrators</emphasis> group. Members
+ are entitled to issue any <emphasis role="bold">pts</emphasis>
+ command and those <emphasis role="bold">fs</emphasis> commands
+ that set volume quota. By default, they also implicitly have
+ the <emphasis role="bold">a</emphasis> (<emphasis
+ role="bold">administer</emphasis>) and <emphasis
+ role="bold">l</emphasis> (<emphasis
+ role="bold">lookup</emphasis>) permissions on every ACL in the
+ file tree even if the ACL does not include an entry for
+ them.</para>
</listitem>
<listitem>
- <para>The <computeroutput>ADMIN</computeroutput> flag on the Authentication Database entry. An administrator with this
- flag can issue any <emphasis role="bold">kas</emphasis> command.</para>
+ <para>The <computeroutput>ADMIN</computeroutput> flag on the
+ Authentication Database entry. An administrator with this flag
+ can issue any <emphasis role="bold">kas</emphasis>
+ command.</para>
</listitem>
<listitem>
- <para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. An administrator whose username
- appears in this file can issue any <emphasis role="bold">bos</emphasis>, <emphasis role="bold">vos</emphasis>, or
- <emphasis role="bold">backup</emphasis> command (although some <emphasis role="bold">backup</emphasis> commands require
- additional privilege as described in <link linkend="HDRWQ260">Granting Administrative Privilege to Backup
- Operators</link>).</para>
+ <para>Inclusion in the <emphasis
+ role="bold">/usr/afs/etc/UserList</emphasis> file. An
+ administrator whose username appears in this file can issue
+ any <emphasis role="bold">bos</emphasis>, <emphasis
+ role="bold">vos</emphasis>, or <emphasis
+ role="bold">backup</emphasis> command (although some <emphasis
+ role="bold">backup</emphasis> commands require additional
+ privilege as described in <link linkend="HDRWQ260">Granting
+ Administrative Privilege to Backup Operators</link>).</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</sect2>
<sect2 id="Header_89">
<title>Authorization Checking versus Authentication</title>
- <para>AFS distinguishes between authentication and authorization checking. Authentication refers to the process of proving
- identity. Authorization checking refers to the process of verifying that an authenticated identity is allowed to perform a
- certain action.</para>
+ <para>AFS distinguishes between authentication and authorization
+ checking. Authentication refers to the process of proving
+ identity. Authorization checking refers to the process of verifying
+ that an authenticated identity is allowed to perform a certain
+ action.</para>
- <para>AFS implements authentication at the level of connections. Each time two parties establish a new connection, they
- mutually authenticate. In general, each issue of an AFS command establishes a new connection between AFS server process and
+ <para>AFS implements authentication at the level of
+ connections. Each time two parties establish a new connection, they
+ mutually authenticate. In general, each issue of an AFS command
+ establishes a new connection between AFS server process and
client.</para>
- <para>AFS implements authorization checking at the level of server machines. If authorization checking is enabled on a server
- machine, then all of the server processes running on it provide services only to authorized users. If authorization checking
- is disabled on a server machine, then all of the server processes perform any action for anyone. Obviously, disabling
- authorization checking is an extreme security exposure. For more information, see <link linkend="HDRWQ123">Managing
- Authentication and Authorization Requirements</link>.</para>
+ <para>AFS implements authorization checking at the level of server
+ machines. If authorization checking is enabled on a server machine,
+ then all of the server processes running on it provide services only
+ to authorized users. If authorization checking is disabled on a
+ server machine, then all of the server processes perform any action
+ for anyone. Obviously, disabling authorization checking is an
+ extreme security exposure. For more information, see <link
+ linkend="HDRWQ123">Managing Authentication and Authorization
+ Requirements</link>.</para>
</sect2>
<sect2 id="HDRWQ74">
<secondary>suggestions for improving</secondary>
</indexterm>
- <para>You can improve the level of security in your cell by configuring user accounts, server machines, and system
- administrator accounts in the indicated way.</para>
+ <para>You can improve the level of security in your cell by
+ configuring user accounts, server machines, and system administrator
+ accounts in the indicated way.</para>
<formalpara>
<title>User Accounts</title>
- <para><itemizedlist>
+ <para>
+ <itemizedlist>
<listitem>
- <para>Use an AFS-modified login utility, or include the <emphasis role="bold">-setpag</emphasis> flag to the <emphasis
- role="bold">klog</emphasis> command, to associate the credential structure that houses tokens with a PAG rather than a
- UNIX UID. This prevents users from inheriting someone else's tokens by assuming their UNIX identity. For further
- discussion, see <link linkend="HDRWQ64">Identifying AFS Tokens by PAG</link>.</para>
+ <para>Use an AFS-modified login utility, or include the
+ <emphasis role="bold">-setpag</emphasis> flag to the
+ <emphasis role="bold">klog</emphasis> command, to associate
+ the credential structure that houses tokens with a PAG
+ rather than a UNIX UID. This prevents users from inheriting
+ someone else's tokens by assuming their UNIX identity. For
+ further discussion, see <link linkend="HDRWQ64">Identifying
+ AFS Tokens by PAG</link>.</para>
</listitem>
<listitem>
- <para>Encourage users to issue the <emphasis role="bold">unlog</emphasis> command to destroy their tokens before
- logging out. This forestalls attempts to access tokens left behind kernel memory. Consider including the <emphasis
- role="bold">unlog</emphasis> command in every user's <emphasis role="bold">.logout</emphasis> file or
+ <para>Encourage users to issue the <emphasis
+ role="bold">unlog</emphasis> command to destroy their tokens
+ before logging out. This forestalls attempts to access
+ tokens left behind kernel memory. Consider including the
+ <emphasis role="bold">unlog</emphasis> command in every
+ user's <emphasis role="bold">.logout</emphasis> file or
equivalent.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</formalpara>
<formalpara>
<title>Server Machines</title>
- <para><itemizedlist>
+ <para>
+ <itemizedlist>
<listitem>
- <para>Disable authorization checking only in emergencies or for very brief periods of time. It is best to work at the
- console of the affected machine during this time, to prevent anyone else from accessing the machine through the
+ <para>Disable authorization checking only in emergencies or
+ for very brief periods of time. It is best to work at the
+ console of the affected machine during this time, to prevent
+ anyone else from accessing the machine through the
keyboard.</para>
</listitem>
<listitem>
- <para>Change the AFS server encryption key on a frequent and regular schedule. Make it difficult to guess (a long
- string including nonalphabetic characters, for instance). Unlike user passwords, the password from which the AFS key
- is derived can be longer than eight characters, because it is never used during login. The <emphasis role="bold">kas
- setpassword</emphasis> command accepts a password hundreds of characters long. For instructions, see <link
- linkend="HDRWQ355">Managing Server Encryption Keys</link>.</para>
+ <para>Change the AFS server encryption key on a frequent and
+ regular schedule. Make it difficult to guess (a long string
+ including nonalphabetic characters, for instance). Unlike
+ user passwords, the password from which the AFS key is
+ derived can be longer than eight characters, because it is
+ never used during login. The <emphasis role="bold">kas
+ setpassword</emphasis> command accepts a password hundreds
+ of characters long. For instructions, see <link
+ linkend="HDRWQ355">Managing Server Encryption
+ Keys</link>.</para>
</listitem>
<listitem>
- <para>As much as possible, limit the number of people who can login at a server machine's console or remotely.
- Imposing this limit is an extra security precaution rather than a necessity. The machine cannot serve as an AFS client
+ <para>As much as possible, limit the number of people who
+ can login at a server machine's console or remotely.
+ Imposing this limit is an extra security precaution rather
+ than a necessity. The machine cannot serve as an AFS client
in this case.</para>
</listitem>
<listitem>
- <para>Particularly limit access to the local superuser <emphasis role="bold">root</emphasis> account on a server
- machine. The local superuser <emphasis role="bold">root</emphasis> has free access to important administrative
- subdirectories of the <emphasis role="bold">/usr/afs</emphasis> directory, as described in <link linkend="HDRWQ53">AFS
- Files on the Local Disk</link>.</para>
+ <para>Particularly limit access to the local superuser
+ <emphasis role="bold">root</emphasis> account on a server
+ machine. The local superuser <emphasis
+ role="bold">root</emphasis> has free access to important
+ administrative subdirectories of the <emphasis
+ role="bold">/usr/afs</emphasis> directory, as described in
+ <link linkend="HDRWQ53">AFS Files on the Local
+ Disk</link>.</para>
<indexterm>
<primary>root superuser</primary>
</listitem>
<listitem>
- <para>As in any computing environment, server machines must be located in a secured area. Any other security measures
- are effectively worthless if unauthorized people can access the computer hardware.</para>
+ <para>As in any computing environment, server machines must
+ be located in a secured area. Any other security measures
+ are effectively worthless if unauthorized people can access
+ the computer hardware.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</formalpara>
<formalpara>
<title>System Administrators</title>
- <para><itemizedlist>
+ <para>
+ <itemizedlist>
<listitem>
- <para>Limit the number of system administrators in your cell. Limit the use of system administrator accounts on
- publicly accessible workstations. Such machines are not secure, so unscrupulous users can install programs that try to
- steal tokens or passwords. If administrators must use publicly accessible workstations at times, they must issue the
- <emphasis role="bold">unlog</emphasis> command before leaving the machine.</para>
+ <para>Limit the number of system administrators in your
+ cell. Limit the use of system administrator accounts on
+ publicly accessible workstations. Such machines are not
+ secure, so unscrupulous users can install programs that try
+ to steal tokens or passwords. If administrators must use
+ publicly accessible workstations at times, they must issue
+ the <emphasis role="bold">unlog</emphasis> command before
+ leaving the machine.</para>
</listitem>
<listitem>
- <para>Create an administrative account for each administrator separate from the personal account, and assign AFS
- privileges only to the administrative account. The administrators must authenticate to the administrative accounts to
- perform duties that require privilege, which provides a useful audit trail as well.</para>
+ <para>Create an administrative account for each
+ administrator separate from the personal account, and assign
+ AFS privileges only to the administrative account. The
+ administrators must authenticate to the administrative
+ accounts to perform duties that require privilege, which
+ provides a useful audit trail as well.</para>
</listitem>
<listitem>
- <para>Administrators must not leave a machine unattended while they have valid tokens. Issue the <emphasis
+ <para>Administrators must not leave a machine unattended
+ while they have valid tokens. Issue the <emphasis
role="bold">unlog</emphasis> command before leaving.</para>
</listitem>
<listitem>
- <para>Use the <emphasis role="bold">-lifetime</emphasis> argument to the <emphasis role="bold">kas
- setfields</emphasis> command to set the token lifetime for administrative accounts to a fairly short amount of time.
- The default lifetime for AFS tokens is 25 hours, but 30 or 60 minutes is possibly a more reasonable lifetime for
- administrative tokens. The tokens for administrators who initiate AFS Backup System operations must last somewhat
- longer, because it can take several hours to complete some dump operations, depending on the speed of the tape device
- and the network connecting it to the file server machines that house the volumes is it accessing.</para>
+ <para>Use the <emphasis role="bold">-lifetime</emphasis>
+ argument to the <emphasis role="bold">kas
+ setfields</emphasis> command to set the token lifetime for
+ administrative accounts to a fairly short amount of time.
+ The default lifetime for AFS tokens is 25 hours, but 30 or
+ 60 minutes is possibly a more reasonable lifetime for
+ administrative tokens. The tokens for administrators who
+ initiate AFS Backup System operations must last somewhat
+ longer, because it can take several hours to complete some
+ dump operations, depending on the speed of the tape device
+ and the network connecting it to the file server machines
+ that house the volumes is it accessing.</para>
</listitem>
<listitem>
- <para>Limit administrators' use of the <emphasis role="bold">telnet</emphasis> program. It sends unencrypted passwords
- across the network. Similarly, limit use of other remote programs such as <emphasis role="bold">rsh</emphasis> and
- <emphasis role="bold">rcp</emphasis>, which send unencrypted tokens across the network.</para>
+ <para>Limit administrators' use of the <emphasis
+ role="bold">telnet</emphasis> program. It sends unencrypted
+ passwords across the network. Similarly, limit use of other
+ remote programs such as <emphasis role="bold">rsh</emphasis>
+ and <emphasis role="bold">rcp</emphasis>, which send
+ unencrypted tokens across the network.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</formalpara>
</sect2>
<secondary>defined</secondary>
</indexterm>
- <para>As in any file system, security is a prime concern in AFS. A file system that makes file sharing easy is not useful if
- it makes file sharing mandatory, so AFS incorporates several features that prevent unauthorized users from accessing data.
- Security in a networked environment is difficult because almost all procedures require transmission of information across
- wires that almost anyone can tap into. Also, many machines on networks are powerful enough that unscrupulous users can monitor
- transactions or even intercept transmissions and fake the identity of one of the participants.</para>
-
- <para>The most effective precaution against eavesdropping and information theft or fakery is for servers and clients to accept
- the claimed identity of the other party only with sufficient proof. In other words, the nature of the network forces all
- parties on the network to assume that the other party in a transaction is not genuine until proven so. Mutual authentication
- is the means through which parties prove their genuineness.</para>
-
- <para>Because the measures needed to prevent fakery must be quite sophisticated, the implementation of mutual authentication
- procedures is complex. The underlying concept is simple, however: parties prove their identities by demonstrating knowledge of
- a shared secret. A shared secret is a piece of information known only to the parties who are mutually authenticating (they can
- sometimes learn it in the first place from a trusted third party or some other source). The party who originates the
- transaction presents the shared secret and refuses to accept the other party as valid until it shows that it knows the secret
- too.</para>
-
- <para>The most common form of shared secret in AFS transactions is the encryption key, also referred to simply as a key. The
- two parties use their shared key to encrypt the packets of information they send and to decrypt the ones they receive.
- Encryption using keys actually serves two related purposes. First, it protects messages as they cross the network, preventing
- anyone who does not know the key from eavesdropping. Second, ability to encrypt and decrypt messages successfully indicates
- that the parties are using the key (it is their shared secret). If they are using different keys, messages remain scrambled
- and unintelligible after decryption.</para>
-
- <para>The following sections describe AFS's mutual authentication procedures in more detail. Feel free to skip these sections
- if you are not interested in the mutual authentication process.</para>
+ <para>As in any file system, security is a prime concern in AFS. A
+ file system that makes file sharing easy is not useful if it makes
+ file sharing mandatory, so AFS incorporates several features that
+ prevent unauthorized users from accessing data. Security in a
+ networked environment is difficult because almost all procedures
+ require transmission of information across wires that almost anyone
+ can tap into. Also, many machines on networks are powerful enough
+ that unscrupulous users can monitor transactions or even intercept
+ transmissions and fake the identity of one of the
+ participants.</para>
+
+ <para>The most effective precaution against eavesdropping and
+ information theft or fakery is for servers and clients to accept the
+ claimed identity of the other party only with sufficient proof. In
+ other words, the nature of the network forces all parties on the
+ network to assume that the other party in a transaction is not
+ genuine until proven so. Mutual authentication is the means through
+ which parties prove their genuineness.</para>
+
+ <para>Because the measures needed to prevent fakery must be quite
+ sophisticated, the implementation of mutual authentication
+ procedures is complex. The underlying concept is simple, however:
+ parties prove their identities by demonstrating knowledge of a
+ shared secret. A shared secret is a piece of information known only
+ to the parties who are mutually authenticating (they can sometimes
+ learn it in the first place from a trusted third party or some other
+ source). The party who originates the transaction presents the
+ shared secret and refuses to accept the other party as valid until
+ it shows that it knows the secret too.</para>
+
+ <para>The most common form of shared secret in AFS transactions is
+ the encryption key, also referred to simply as a key. The two
+ parties use their shared key to encrypt the packets of information
+ they send and to decrypt the ones they receive. Encryption using
+ keys actually serves two related purposes. First, it protects
+ messages as they cross the network, preventing anyone who does not
+ know the key from eavesdropping. Second, ability to encrypt and
+ decrypt messages successfully indicates that the parties are using
+ the key (it is their shared secret). If they are using different
+ keys, messages remain scrambled and unintelligible after
+ decryption.</para>
+
+ <para>The following sections describe AFS's mutual authentication
+ procedures in more detail. Feel free to skip these sections if you
+ are not interested in the mutual authentication process.</para>
<sect3 id="Header_92">
<title>Simple Mutual Authentication</title>
- <para>Simple mutual authentication involves only one encryption key and two parties, generally a client and server. The
- client contacts the server by sending a challenge message encrypted with a key known only to the two of them. The server
- decrypts the message using its key, which is the same as the client's if they really do share the same secret. The server
- responds to the challenge and uses its key to encrypt its response. The client uses its key to decrypt the server's
- response, and if it is correct, then the client can be sure that the server is genuine: only someone who knows the same key
- as the client can decrypt the challenge and answer it correctly. On its side, the server concludes that the client is
- genuine because the challenge message made sense when the server decrypted it.</para>
-
- <para>AFS uses simple mutual authentication to verify user identities during the first part of the login procedure. In that
+ <para>Simple mutual authentication involves only one encryption
+ key and two parties, generally a client and server. The client
+ contacts the server by sending a challenge message encrypted with
+ a key known only to the two of them. The server decrypts the
+ message using its key, which is the same as the client's if they
+ really do share the same secret. The server responds to the
+ challenge and uses its key to encrypt its response. The client
+ uses its key to decrypt the server's response, and if it is
+ correct, then the client can be sure that the server is genuine:
+ only someone who knows the same key as the client can decrypt the
+ challenge and answer it correctly. On its side, the server
+ concludes that the client is genuine because the challenge message
+ made sense when the server decrypted it.</para>
+
+ <para>AFS uses simple mutual authentication to verify user
+ identities during the first part of the login procedure. In that
case, the key is based on the user's password.</para>
</sect3>
<sect3 id="HDRWQ76">
<title>Complex Mutual Authentication</title>
- <para>Complex mutual authentication involves three encryption keys and three parties. All secure AFS transactions (except
- the first part of the login process) employ complex mutual authentication.</para>
+ <para>Complex mutual authentication involves three encryption keys
+ and three parties. All secure AFS transactions (except the first
+ part of the login process) employ complex mutual
+ authentication.</para>
<indexterm>
<primary>ticket-granter</primary>
<secondary>data in</secondary>
</indexterm>
- <para>When a client wishes to communicate with a server, it first contacts a third party called a ticket-granter. The
- ticket-granter and the client mutually authenticate using the simple procedure. When they finish, the ticket-granter gives
- the client a server ticket (or simply ticket) as proof that it (the ticket-granter) has preverified the identity of the
- client. The ticket-granter encrypts the ticket with the first of the three keys, called the server encryption key because it
- is known only to the ticket-granter and the server the client wants to contact. The client does not know this key.</para>
-
- <para>The ticket-granter sends several other pieces of information along with the ticket. They enable the client to use the
- ticket effectively despite being unable to decrypt the ticket itself. Along with the ticket, the items constitute a token:
+ <para>When a client wishes to communicate with a server, it first
+ contacts a third party called a ticket-granter. The ticket-granter
+ and the client mutually authenticate using the simple
+ procedure. When they finish, the ticket-granter gives the client a
+ server ticket (or simply ticket) as proof that it (the
+ ticket-granter) has preverified the identity of the client. The
+ ticket-granter encrypts the ticket with the first of the three
+ keys, called the server encryption key because it is known only to
+ the ticket-granter and the server the client wants to contact. The
+ client does not know this key.</para>
+
+ <para>The ticket-granter sends several other pieces of information
+ along with the ticket. They enable the client to use the ticket
+ effectively despite being unable to decrypt the ticket
+ itself. Along with the ticket, the items constitute a token:
<itemizedlist>
<listitem>
- <para>A session key, which is the second encryption key involved in mutual authentication. The ticket-granter invents
- the session key at random as the shared secret between client and server. For reasons explained further below, the
- ticket-granter also puts a copy of the session key inside the ticket. The client and server use the session key to
- encrypt messages they send to one another during their transactions. The ticket-granter invents a different session
- key for each connection between a client and a server (there can be several transactions during a single
+ <para>A session key, which is the second encryption key
+ involved in mutual authentication. The ticket-granter
+ invents the session key at random as the shared secret
+ between client and server. For reasons explained further
+ below, the ticket-granter also puts a copy of the session
+ key inside the ticket. The client and server use the session
+ key to encrypt messages they send to one another during
+ their transactions. The ticket-granter invents a different
+ session key for each connection between a client and a
+ server (there can be several transactions during a single
connection).</para>
<indexterm>
</listitem>
<listitem>
- <para>The name of the server for which the ticket is valid (and so which server encryption key encrypts the ticket
+ <para>The name of the server for which the ticket is valid
+ (and so which server encryption key encrypts the ticket
itself).</para>
</listitem>
<listitem>
- <para>A ticket lifetime indicator. The default lifetime of AFS server tickets is 100 hours. If the client wants to
- contact the server again after the ticket expires, it must contact the ticket-granter to get a new ticket.</para>
+ <para>A ticket lifetime indicator. The default lifetime of
+ AFS server tickets is 100 hours. If the client wants to
+ contact the server again after the ticket expires, it must
+ contact the ticket-granter to get a new ticket.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>The ticket-granter seals the entire token with the third key involved in complex mutual authentication--the key known
- only to it (the ticket-granter) and the client. In some cases, this third key is derived from the password of the human user
- whom the client represents.</para>
+ <para>The ticket-granter seals the entire token with the third key
+ involved in complex mutual authentication--the key known only to
+ it (the ticket-granter) and the client. In some cases, this third
+ key is derived from the password of the human user whom the client
+ represents.</para>
- <para>Now that the client has a valid server ticket, it is ready to contact the server. It sends the server two things:
+ <para>Now that the client has a valid server ticket, it is ready
+ to contact the server. It sends the server two things:
<itemizedlist>
<listitem>
- <para>The server ticket. This is encrypted with the server encryption key.</para>
+ <para>The server ticket. This is encrypted with the server
+ encryption key.</para>
</listitem>
<listitem>
- <para>Its request message, encrypted with the session key. Encrypting the message protects it as it crosses the
- network, since only the server/client pair for whom the ticket-granter invented the session key know it.</para>
+ <para>Its request message, encrypted with the session
+ key. Encrypting the message protects it as it crosses the
+ network, since only the server/client pair for whom the
+ ticket-granter invented the session key know it.</para>
</listitem>
- </itemizedlist></para>
-
- <para>At this point, the server does not know the session key, because the ticket-granter just created it. However, the
- ticket-granter put a copy of the session key inside the ticket. The server uses the server encryption key to decrypts the
- ticket and learns the session key. It then uses the session key to decrypt the client's request message. It generates a
- response and sends it to the client. It encrypts the response with the session key to protect it as it crosses the
- network.</para>
-
- <para>This step is the heart of mutual authentication between client and server, because it proves to both parties that they
- know the same secret: <itemizedlist>
+ </itemizedlist>
+ </para>
+
+ <para>At this point, the server does not know the session key,
+ because the ticket-granter just created it. However, the
+ ticket-granter put a copy of the session key inside the
+ ticket. The server uses the server encryption key to decrypts the
+ ticket and learns the session key. It then uses the session key to
+ decrypt the client's request message. It generates a response and
+ sends it to the client. It encrypts the response with the session
+ key to protect it as it crosses the network.</para>
+
+ <para>This step is the heart of mutual authentication between
+ client and server, because it proves to both parties that they
+ know the same secret:
+ <itemizedlist>
<listitem>
- <para>The server concludes that the client is authorized to make a request because the request message makes sense
- when the server decrypts it using the session key. If the client uses a different session key than the one the server
- finds inside the ticket, then the request message remains unintelligible even after decryption. The two copies of the
- session key (the one inside the ticket and the one the client used) can only be the same if they both came from the
- ticket-granter. The client cannot fake knowledge of the session key because it cannot look inside the ticket, sealed
- as it is with the server encryption key known only to the server and the ticket-granter. The server trusts the
- ticket-granter to give tokens only to clients with whom it (the ticket-granter) has authenticated, so the server
+ <para>The server concludes that the client is authorized to
+ make a request because the request message makes sense when
+ the server decrypts it using the session key. If the client
+ uses a different session key than the one the server finds
+ inside the ticket, then the request message remains
+ unintelligible even after decryption. The two copies of the
+ session key (the one inside the ticket and the one the
+ client used) can only be the same if they both came from the
+ ticket-granter. The client cannot fake knowledge of the
+ session key because it cannot look inside the ticket, sealed
+ as it is with the server encryption key known only to the
+ server and the ticket-granter. The server trusts the
+ ticket-granter to give tokens only to clients with whom it
+ (the ticket-granter) has authenticated, so the server
decides the client is legitimate.</para>
- <para>(Note that there is no direct communication between the ticket-granter and the server, even though their
- relationship is central to ticket-based mutual authentication. They interact only indirectly, via the client's
- possession of a ticket sealed with their shared secret.)</para>
+ <para>(Note that there is no direct communication between
+ the ticket-granter and the server, even though their
+ relationship is central to ticket-based mutual
+ authentication. They interact only indirectly, via the
+ client's possession of a ticket sealed with their shared
+ secret.)</para>
</listitem>
<listitem>
- <para>The client concludes that the server is genuine and trusts the response it gets back from the server, because
- the response makes sense after the client decrypts it using the session key. This indicates that the server encrypted
- the response with the same session key as the client knows. The only way for the server to learn that matching session
- key is to decrypt the ticket first. The server can only decrypt the ticket because it shares the secret of the server
- encryption key with the ticket-granter. The client trusts the ticket-granter to give out tickets only for legitimate
- servers, so the client accepts a server that can decrypt the ticket as genuine, and accepts its response.</para>
+ <para>The client concludes that the server is genuine and
+ trusts the response it gets back from the server, because
+ the response makes sense after the client decrypts it using
+ the session key. This indicates that the server encrypted
+ the response with the same session key as the client
+ knows. The only way for the server to learn that matching
+ session key is to decrypt the ticket first. The server can
+ only decrypt the ticket because it shares the secret of the
+ server encryption key with the ticket-granter. The client
+ trusts the ticket-granter to give out tickets only for
+ legitimate servers, so the client accepts a server that can
+ decrypt the ticket as genuine, and accepts its
+ response.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</sect3>
</sect2>
</sect1>
<sect1 id="HDRWQ77">
<title>Backing Up AFS Data</title>
- <para>AFS provides two related facilities that help the administrator back up AFS data: backup volumes and the AFS Backup
- System.</para>
+ <para>AFS provides two related facilities that help the administrator
+ back up AFS data: backup volumes and the AFS Backup System.</para>
<sect2 id="Header_95">
<title>Backup Volumes</title>
- <para>The first facility is the backup volume, which you create by cloning a read/write volume. The backup volume is read-only
- and so preserves the state of the read/write volume at the time the clone is made.</para>
-
- <para>Backup volumes can ease administration if you mount them in the file system and make their contents available to users.
- For example, it often makes sense to mount the backup version of each user volume as a subdirectory of the user's home
- directory. A conventional name for this mount point is <emphasis role="bold">OldFiles</emphasis>. Create a new version of the
- backup volume (that is, reclone the read/write) once a day to capture any changes that were made since the previous backup. If
- a user accidentally removes or changes data, the user can restore it from the backup volume, rather than having to ask you to
- restore it.</para>
-
- <para>The OpenAFS User Guide does not mention backup volumes, so regular users do not know about them if you decide not to use
- them. This implies that if you <emphasis role="bold">do</emphasis> make backup versions of user volumes, you need to tell your
- users about how the backup works and where you have mounted it.</para>
-
- <para>Users are often concerned that the data in a backup volume counts against their volume quota and some of them even want
- to remove the <emphasis role="bold">OldFiles</emphasis> mount point. It does not, because the backup volume is a separate
- volume. The only amount of space it uses in the user's volume is the amount needed for the mount point, which is about the
- same as the amount needed for a standard directory element.</para>
-
- <para>Backup volumes are discussed in detail in <link linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
+ <para>The first facility is the backup volume, which you create by
+ cloning a read/write volume. The backup volume is read-only and so
+ preserves the state of the read/write volume at the time the clone
+ is made.</para>
+
+ <para>Backup volumes can ease administration if you mount them in
+ the file system and make their contents available to users. For
+ example, it often makes sense to mount the backup version of each
+ user volume as a subdirectory of the user's home directory. A
+ conventional name for this mount point is <emphasis
+ role="bold">OldFiles</emphasis>. Create a new version of the backup
+ volume (that is, reclone the read/write) once a day to capture any
+ changes that were made since the previous backup. If a user
+ accidentally removes or changes data, the user can restore it from
+ the backup volume, rather than having to ask you to restore
+ it.</para>
+
+ <para>The OpenAFS User Guide does not mention backup volumes, so
+ regular users do not know about them if you decide not to use
+ them. This implies that if you <emphasis role="bold">do</emphasis>
+ make backup versions of user volumes, you need to tell your users
+ about how the backup works and where you have mounted it.</para>
+
+ <para>Users are often concerned that the data in a backup volume
+ counts against their volume quota and some of them even want to
+ remove the <emphasis role="bold">OldFiles</emphasis> mount point. It
+ does not, because the backup volume is a separate volume. The only
+ amount of space it uses in the user's volume is the amount needed
+ for the mount point, which is about the same as the amount needed
+ for a standard directory element.</para>
+
+ <para>Backup volumes are discussed in detail in <link
+ linkend="HDRWQ201">Creating Backup Volumes</link>.</para>
</sect2>
<sect2 id="Header_96">
<title>The AFS Backup System</title>
- <para>Backup volumes can reduce restoration requests, but they reside on disk and so do not protect data from loss due to
- hardware failure. Like any file system, AFS is vulnerable to this sort of data loss.</para>
-
- <para>To protect your cell's users from permanent loss of data, you are strongly urged to back up your file system to tape on
- a regular and frequent schedule. The AFS Backup System is available to ease the administration and performance of backups. For
- detailed information about the AFS Backup System, see <link linkend="HDRWQ248">Configuring the AFS Backup System</link> and
- <link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
-
+ <para>Backup volumes can reduce restoration requests, but they
+ reside on disk and so do not protect data from loss due to hardware
+ failure. Like any file system, AFS is vulnerable to this sort of
+ data loss.</para>
+
+ <para>To protect your cell's users from permanent loss of data, you
+ are strongly urged to back up your file system to tape on a regular
+ and frequent schedule. The AFS Backup System is available to ease
+ the administration and performance of backups. For detailed
+ information about the AFS Backup System, see <link
+ linkend="HDRWQ248">Configuring the AFS Backup System</link> and
+ <link linkend="HDRWQ283">Backing Up and Restoring AFS
+ Data</link>.</para>
</sect2>
</sect1>
<sect1 id="HDRWQ79">
<title>Accessing AFS through NFS</title>
- <para>Users of NFS client machines can access the AFS filespace by mounting the <emphasis role="bold">/afs</emphasis> directory
- of an AFS client machine that is running the NFS/AFS Translator. This is a particular advantage in cells already running NFS who
- want to access AFS using client machines for which AFS is not available. See <link linkend="HDRWQ595">Appendix A, Managing the
- NFS/AFS Translator</link>.</para>
+ <para>Users of NFS client machines can access the AFS filespace by
+ mounting the <emphasis role="bold">/afs</emphasis> directory of an AFS
+ client machine that is running the NFS/AFS Translator. This is a
+ particular advantage in cells already running NFS who want to access
+ AFS using client machines for which AFS is not available. See <link
+ linkend="HDRWQ595">Appendix A, Managing the NFS/AFS
+ Translator</link>.</para>
</sect1>
</chapter>
git://git.openafs.org / openafs.git / blobdiff