<?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>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>

    <secondary>differences from UNIX summarized</secondary>
  </indexterm>

  <indexterm>
    <primary>UNIX</primary>

    <secondary>differences from AFS summarized</secondary>
  </indexterm>

  <indexterm>
    <primary>differences</primary>

    <secondary>between AFS and UNIX, summarized</secondary>
  </indexterm>

  <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>

    <indexterm>
      <primary>protection</primary>

      <secondary>AFS compared to UNIX</secondary>
    </indexterm>

    <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 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>
          </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>
          </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. If a directory must contain files with
            different permissions, use symbolic links to point to files
            stored in directories with different ACLs.</para>
          </listitem>

          <listitem>
            <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>
          </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>
          </listitem>
      </itemizedlist>
      </para>

      <para>AFS enables users to create groups and add other users to
      those groups. 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>

      <indexterm>
        <primary>authentication</primary>

        <secondary>AFS compared to UNIX</secondary>
      </indexterm>

      <indexterm>
        <primary>password</primary>

        <secondary>AFS compared to UNIX</secondary>
      </indexterm>
    </sect2>

    <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 will already be
      familiar to users and system administrators who use Kerberos for
      authentication.
        <itemizedlist>
          <listitem>
            <para>To access AFS files, users must log into the local
            machine as normal, obtain Kerberos tickets, and then obtain
            AFS tokens. This process can often be automated through the
            system authentication configuration so that the user logs into
            the system as normal and obtains Kerberos tickets and AFS
            tokens transparently. If you cannot or chose not to configure
            the system this way, 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 KDC and, optionally, each machine's local user
            database (<emphasis role="bold">/etc/passwd</emphasis> or
            equivalent) for the local system. A user's passwords in the
            two places can differ if desired.</para>
          </listitem>
        </itemizedlist>
      </para>
    </sect2>

    <sect2 id="Header_37">
      <title>Differences in the Semantics of Standard UNIX
      Commands</title>

      <para>This section summarizes how AFS modifies the functionality of
      some UNIX commands.
        <variablelist>
          <varlistentry>
            <term><emphasis role="bold">The chmod
            command</emphasis></term>

            <listitem>
              <indexterm>
                <primary>chmod command</primary>
                <secondary>AFS compared to UNIX</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>
                <secondary>chmod (AFS compared to UNIX)</secondary>
              </indexterm>

              <indexterm>
                <primary>setuid programs</primary>
                <secondary>setting mode bits</secondary>
              </indexterm>

              <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>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">The chown
            command</emphasis></term>

            <listitem>
              <indexterm>
                <primary>chown command</primary>
                <secondary>AFS compared to UNIX</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>
                <secondary>chown (AFS compared to UNIX)</secondary>
              </indexterm>

              <para>Only members of the <emphasis
              role="bold">system:administrators</emphasis> group can issue
              this command on AFS files.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">The chgrp
            command</emphasis></term>

            <listitem>
              <indexterm>
                <primary>chgrp command</primary>
                <secondary>AFS compared to UNIX</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>
                <secondary>chgrp (AFS compared to UNIX)</secondary>
              </indexterm>

              <para>Only members of the <emphasis
              role="bold">system:administrators</emphasis> can issue this
              command on AFS files and directories.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">The groups and id
            commands</emphasis></term>

            <listitem>
              <indexterm>
                <primary>groups command</primary>
                <secondary>AFS compared to UNIX</secondary>
              </indexterm>

              <indexterm>
                <primary>id command</primary>
                <secondary>AFS compared to UNIX</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>
                <secondary>groups (AFS compared to UNIX)</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>
                <secondary>id (AFS compared to UNIX)</secondary>
              </indexterm>

              <para>If the user's AFS tokens are associated with a process
              authentication group (PAG), the output of these commands may
              include one or two large numbers. These are artificial
              groups used by the OpenAFS Cache Manager to track the PAG on
              some platforms. Other platforms may use other methods, such
              as native kernel support for a PAG or a similar concept, in
              which case the large GIDs may not appear. To learn about
              PAGs, see <link linkend="HDRWQ64">Identifying AFS Tokens by
              PAG</link>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">The ln command</emphasis></term>

            <listitem>
              <indexterm>
                <primary>ln command</primary>
                <secondary>AFS compared to UNIX</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>
                <secondary>ln (AFS compared to UNIX)</secondary>
              </indexterm>

              <para>This command cannot create hard links between files in
              different AFS directories. See <link
              linkend="HDRWQ32">Creating Hard Links</link>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">The sshd daemon and ssh
            command</emphasis></term>

            <listitem>
              <indexterm>
                <primary>sshd command</primary>
                <secondary>AFS compared to UNIX</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>
                <secondary>sshd (AFS compared to UNIX)</secondary>
              </indexterm>

              <indexterm>
                <primary>ssh command</primary>
                <secondary>AFS compared to UNIX</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>
                <secondary>ssh (AFS compared to UNIX)</secondary>
              </indexterm>

              <para>In order for a user to have access to files stored in
              AFS, that user needs to have Kerberos tickets and an AFS token
              on the system from which they're accessing AFS. This has an
              implication for users who log in remotely via protocols such
              as Secure Shell (SSH): that log-in process must create local
              Kerberos tickets and an AFS token on the system, or the user
              will have to separately authenticate to Kerberos and AFS
              after logging in.</para>

              <para>The <ulink url="http://www.openssh.org/">OpenSSH
              project</ulink> provides an SSH client and server that uses
              the GSS-API protocol to pass Kerberos tickets between
              machines. With a suitable SSH client, this allows users to
              delegate their Kerberos tickets to the remote machine, and
              that machine to store those tickets and obtain AFS tokens as
              part of the log-in process.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>

      <indexterm>
        <primary>fsck command</primary>

        <secondary>AFS compared to UNIX</secondary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>
        <secondary>inode-based</secondary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>
        <secondary>namei-based</secondary>
      </indexterm>

      <indexterm>
        <primary>namei</primary>
        <secondary>definition</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>fsck (AFS compared to UNIX)</secondary>
      </indexterm>

      <indexterm>
        <primary>fsck command</primary>

        <secondary>AFS version</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>fsck (AFS version)</secondary>
      </indexterm>

      <indexterm>
        <primary>directories</primary>

        <secondary>lost+found</secondary>
      </indexterm>

      <indexterm>
        <primary>lost+found directory</primary>
      </indexterm>
    </sect2>

    <sect2 id="Header_38">
      <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
        on disk. The inode-based format uses a combination of regular
        files and extra fields stored in the inode data structures that
        are normally reserved for use by the operating system. The namei
        format uses normal file storage and does not use special
        structures. The choice of storage formats is chosen at compile
        time and the two formats are incompatible. The inode format is
        only available on certain platforms. The storage format must be
        consistent for the fileserver binaries and all vice partitions on
        a given file server 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 can be used as normal.</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 Start Guide</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>

<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
      binaries in use on the machine.</para>

      <para>If you ever accidentally run the standard version of the
      program, contact your AFS support provider, contact the OpenAFS
      mailing lists, 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 file storage will result
        in data corruption!</para>
      </warning>
    </sect2>

    <sect2 id="HDRWQ32">
      <title>Creating Hard Links</title>

      <indexterm>
        <primary>hard link</primary>

        <secondary>AFS restrictions on</secondary>
      </indexterm>

      <indexterm>
        <primary>restrictions</primary>

        <secondary>on hard links in AFS</secondary>
      </indexterm>

      <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>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 in AFS 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>
    </sect2>

    <sect2 id="HDRWQ33">
      <title>AFS Implements Save on Close</title>

      <indexterm>
        <primary>fsync system call</primary>

        <secondary>for files saved on AFS client</secondary>
      </indexterm>

      <indexterm>
        <primary>close system call</primary>

        <secondary>for files saved on AFS client</secondary>
      </indexterm>

      <indexterm>
        <primary>write</primary>

        <secondary>system call for files saved on AFS client</secondary>
      </indexterm>

      <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, such as when 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">
      <title>Setuid Programs</title>

      <indexterm>
        <primary>setuid programs</primary>

        <secondary>restrictions on</secondary>
      </indexterm>

      <para>The UNIX setuid bit is ignored by default for programs run
      from AFS, but can be enabled by the system administrator on a client
      machine. The <emphasis role="bold">fs setcell</emphasis> command
      determines whether setuid programs that originate in a particular
      cell can run on a given client machine. Running setuid binaries from
      AFS poses a security risk due to weaknesses in the integrity checks
      of the AFS protocol and should normally not be permitted. See <link
      linkend="HDRWQ409">Determining if a Client Can Run Setuid
      Programs</link>.</para>

      <para>Set the UNIX setuid bit only for files whose owner is UID 0
      (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. Setting the UNIX setuid bit for files owned
      with a different UID will have unpredictable resuilts, since that
      UID will be interpreted as possibly different users on each AFS
      client machine.</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, or issue the
      <emphasis role="bold">chmod</emphasis> system call or the <emphasis
      role="bold">chmod</emphasis> command to set the setuid bit.</para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ34">
    <title>Choosing a Cell Name</title>

      <indexterm>
        <primary>cell</primary>

        <secondary>name</secondary>

        <tertiary>choosing</tertiary>
      </indexterm>

      <indexterm>
        <primary>choosing</primary>

        <secondary>name</secondary>

        <tertiary>cell</tertiary>
      </indexterm>

      <indexterm>
        <primary>conventions</primary>

        <secondary>cell name</secondary>
      </indexterm>

      <indexterm>
        <primary>Internet</primary>

        <secondary>conventions for cell name</secondary>
      </indexterm>

    <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 convention, 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 Domain Name System (DNS)
    conventions for domain names. If you are already an Internet site,
    then it is simplest and strongly recommended to choose your Internet
    domain name as the cell name.</para>

    <para>If you are not an Internet site, it is best to choose a unique
    DNS-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 either by creating a symbolic link to the
          complete cell name, at the second level in your file tree or by
          using the <emphasis role="bold">CellAlias</emphasis>
          configuration file on a client machine. 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>
        </listitem>

        <listitem>
          <para>It can include any number of fields, which are
          conventionally separated by periods (see the examples
          below).</para>
        </listitem>
      </itemizedlist>
    </para>

    <sect2 id="Header_43">
      <title>How to Set the Cell Name</title>

      <indexterm>
        <primary>setting</primary>
        <secondary>cell name</secondary>
      </indexterm>

      <indexterm>
        <primary>cell</primary>
        <secondary>name</secondary>
        <tertiary>setting</tertiary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>
        <secondary>setting home cell</secondary>
      </indexterm>

      <indexterm>
        <primary>client machine</primary>
        <secondary>setting home cell</secondary>
      </indexterm>

      <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
      Start Guide</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 Start Guide</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 (client machines can only
      have one default cell at a time and server machines 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 Start
      Guide</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>
      </note>
    </sect2>

    <sect2 id="HDRWQ35">
      <title>Why Choosing the Appropriate Cell Name is Important</title>

      <indexterm>
        <primary>ThisCell file (client)</primary>
        <secondary>how used by programs</secondary>
      </indexterm>

      <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">pts</emphasis>, and
      <emphasis role="bold">vos</emphasis> commands, for example) 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 or configured in DNS 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
      normally determines the cell for which a user receives an AFS token
      when he or she logs in to a machine.</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 will cause many commands from
      the AFS suites to not work as expected.</para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ36">
    <title>Participating in the AFS Global Namespace</title>

    <indexterm>
      <primary>participation</primary>
      <secondary>in AFS global namespace</secondary>
    </indexterm>

    <indexterm>
      <primary>AFS</primary>
      <secondary>global namespace</secondary>
    </indexterm>

    <indexterm>
      <primary>global namespace</primary>
    </indexterm>

    <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>
        </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>
        </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>
        </listitem>

        <listitem>
          <para>You make your cell visible to others by advertising your
          database server machines and allowing users at other sites to
          access your database server and file 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>
        </listitem>
      </itemizedlist>
    </para>

    <sect2 id="HDRWQ37">
      <title>What the Global Namespace Looks Like</title>

      <indexterm>
        <primary>conventions</primary>
        <secondary>AFS pathnames</secondary>
      </indexterm>

      <indexterm>
        <primary>AFS</primary>
        <secondary>root directory (/afs)</secondary>
        <tertiary>on client machine</tertiary>
      </indexterm>

      <indexterm>
        <primary>directories</primary>
        <secondary>/afs</secondary>
      </indexterm>

      <indexterm>
        <primary>directories</primary>
        <secondary>/afs/<emphasis>cellname</emphasis></secondary>
      </indexterm>

      <indexterm>
        <primary>cell</primary>
        <secondary>name</secondary>
        <tertiary>at second level in file tree</tertiary>
      </indexterm>

      <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 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>
    </sect2>

    <sect2 id="HDRWQ38">
      <title>Making Your Cell Visible to Others</title>

      <indexterm>
        <primary>cell</primary>
        <secondary>making local visible to foreign</secondary>
      </indexterm>

      <indexterm>
        <primary>local cell</primary>
        <secondary>making visible to foreign cells</secondary>
      </indexterm>

      <indexterm>
        <primary>foreign cell</primary>
        <secondary>making local cell visible</secondary>
      </indexterm>

      <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 version 5 domain-to-realm mappings and Key Distribution
      Center (KDC) location information for both the local and remote
      Kerberos version 5 realms.</para>

      <para>There are two places you can make this information available:
      <itemizedlist>
          <indexterm>
            <primary>files</primary>

            <secondary>global CellServDB</secondary>
          </indexterm>

          <indexterm>
            <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>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>.
              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>

            <indexterm>
              <primary>files</primary>

              <secondary>CellServDB.local</secondary>
            </indexterm>

            <indexterm>
              <primary>CellServDB.local file</primary>
            </indexterm>
          </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>
          </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>

      <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>

        <secondary>making foreign visible to local</secondary>
      </indexterm>

      <indexterm>
        <primary>local cell</primary>

        <secondary>making foreign cells visible in</secondary>
      </indexterm>

      <indexterm>
        <primary>foreign cell</primary>

        <secondary>making visible in local cell</secondary>
      </indexterm>

      <indexterm>
        <primary>client machine</primary>

        <secondary>making foreign cell visible</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ39">
      <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:
      <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>
          </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>
          </listitem>

          <listitem>
            <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>

      <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>

        <secondary>granting local access to foreign users</secondary>
      </indexterm>

      <indexterm>
        <primary>local cell</primary>

        <secondary>granting foreign users access to</secondary>
      </indexterm>
    </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>
          <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>
          </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>
            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>
            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>
          </listitem>

          <listitem>
            <para>Create a local authentication account for specific
            foreign users, by creating entries in the Protection Database,
            the Kerberos Database, and the local password file.</para>
          </listitem>
      </itemizedlist>
      </para>

      <indexterm>
        <primary>cell</primary>

        <secondary>filespace configuration issues</secondary>
      </indexterm>

      <indexterm>
        <primary>configuring</primary>

        <secondary>filespace, issues</secondary>
      </indexterm>

      <indexterm>
        <primary>file tree</primary>

        <secondary>conventions</secondary>

        <tertiary>for configuring</tertiary>
      </indexterm>
    </sect2>
  </sect1>

  <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>

    <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>
    </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>

    <indexterm>
      <primary>AFS</primary>

      <secondary>root directory (/afs)</secondary>

      <tertiary>in cell filespace</tertiary>
    </indexterm>

    <indexterm>
      <primary>directories</primary>

      <secondary>/afs</secondary>
    </indexterm>

    <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>

      <indexterm>
        <primary>cell</primary>

        <secondary>name</secondary>

        <tertiary>at second level in file tree</tertiary>
      </indexterm>

      <indexterm>
        <primary>directories</primary>

        <secondary>/afs/<emphasis>cellname</emphasis></secondary>
      </indexterm>

      <indexterm>
        <primary>symbolic link</primary>

        <secondary>at second level of AFS pathname</secondary>
      </indexterm>
    </sect2>

    <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>
   '/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>

<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>

      <indexterm>
        <primary>file tree</primary>

        <secondary>conventions</secondary>

        <tertiary>third level</tertiary>
      </indexterm>

      <indexterm>
        <primary>directories</primary>

        <secondary>conventional under /afs/cellname</secondary>
      </indexterm>
    </sect2>

    <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>
          <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>
            </listitem>
          </varlistentry>

          <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>
            </listitem>
          </varlistentry>

          <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>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>
                  </listitem>

                  <listitem>
                    <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>
                  </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>
                  </listitem>
              </itemizedlist>
              </para>
            </listitem>
          </varlistentry>

          <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
              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>
            </listitem>
          </varlistentry>

          <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
              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>

          <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>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>

      <indexterm>
        <primary>volume name</primary>

        <secondary>conventions for</secondary>
      </indexterm>

      <indexterm>
        <primary>conventions</primary>

        <secondary>volume names</secondary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>separate for each top level directory</secondary>
      </indexterm>

      <indexterm>
        <primary>file tree</primary>

        <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>

    <indexterm>
      <primary>volume name</primary>

      <secondary>restrictions</secondary>
    </indexterm>

    <indexterm>
      <primary>restrictions</primary>

      <secondary>on volume names</secondary>
    </indexterm>

    <indexterm>
      <primary>volume name</primary>

      <secondary>two required</secondary>
    </indexterm>

    <indexterm>
      <primary>volume</primary>

      <secondary>root (root.afs and root.cell)</secondary>
    </indexterm>

    <indexterm>
      <primary>root volumes (root.afs and root.cell)</primary>
    </indexterm>

    <sect2 id="Header_55">
      <title>Assigning Volume Names</title>

      <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
            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>
          </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,
            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>
          </listitem>
      </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>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>

        <tgroup cols="4">
          <colspec colwidth="14*" />

          <colspec colwidth="28*" />

          <colspec colwidth="22*" />

          <colspec colwidth="36*" />

          <thead>
            <row>
              <entry><emphasis role="bold">Prefix</emphasis></entry>

              <entry><emphasis role="bold">Contents</emphasis></entry>

              <entry><emphasis role="bold">Example Name</emphasis></entry>

              <entry><emphasis role="bold">Example Mount
              Point</emphasis></entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry><emphasis role="bold">common.</emphasis></entry>

              <entry>popular programs and files</entry>

              <entry><emphasis role="bold">common.etc</emphasis></entry>

              <entry><emphasis
              role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
              role="bold">/common/etc</emphasis></entry>
            </row>

            <row>
              <entry><emphasis role="bold">src.</emphasis></entry>

              <entry>source code</entry>

              <entry><emphasis role="bold">src.afs</emphasis></entry>

              <entry><emphasis
              role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
              role="bold">/src/afs</emphasis></entry>
            </row>

            <row>
              <entry><emphasis role="bold">proj.</emphasis></entry>

              <entry>project data</entry>

              <entry><emphasis role="bold">proj.portafs</emphasis></entry>

              <entry><emphasis
              role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
              role="bold">/proj/portafs</emphasis></entry>
            </row>

            <row>
              <entry><emphasis role="bold">test.</emphasis></entry>

              <entry>testing or other temporary data</entry>

              <entry><emphasis role="bold">test.smith</emphasis></entry>

              <entry><emphasis
              role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
              role="bold">/usr/smith/test</emphasis></entry>
            </row>

            <row>
              <entry><emphasis role="bold">user.</emphasis></entry>

              <entry>user home directory data</entry>

              <entry><emphasis role="bold">user.terry</emphasis></entry>

              <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><emphasis role="bold">rs_aix42.bin</emphasis></entry>

              <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>

      <table id="TBLPREFIX-EXAMPLE" label="2">
        <title>Example volume-prefixing scheme</title>

        <tgroup cols="2">
          <colspec colwidth="14*" />

          <colspec colwidth="28*" />

          <colspec colwidth="22*" />

          <colspec colwidth="36*" />

          <thead>
            <row>
              <entry><emphasis role="bold">Example Name</emphasis></entry>

              <entry><emphasis role="bold">Example Mount
              Point</emphasis></entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry><emphasis role="bold">rs_aix42.bin</emphasis></entry>

              <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>
            </row>

            <row>
              <entry><emphasis role="bold">rs_aix42.etc</emphasis></entry>

              <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
              role="bold">/rs_aix42/usr</emphasis></entry>
            </row>

            <row>
              <entry><emphasis
              role="bold">rs_aix42.usr.afsws</emphasis></entry>

              <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">/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">/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">/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">/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">/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">/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">/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>
          <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>
          </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>
          </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>
          </listitem>
      </itemizedlist>
      </para>

      <indexterm>
        <primary>volume</primary>

        <secondary>grouping related on same partition</secondary>
      </indexterm>

      <indexterm>
        <primary>disk partition</primary>

        <secondary>grouping related volumes on</secondary>
      </indexterm>
    </sect2>

    <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>
          <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>
          </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>
          </listitem>
      </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>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>
        <primary>replication</primary>

        <secondary>appropriate volumes</secondary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>type to replicate</secondary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>where to place replicated</secondary>
      </indexterm>

      <indexterm>
        <primary>read-only volume</primary>

        <secondary>selecting site</secondary>
      </indexterm>
    </sect2>

    <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>
    </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
      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
      Instruction</link>.</para>

      <indexterm>
        <primary>server machine</primary>

        <secondary>configuration issues</secondary>
      </indexterm>

      <indexterm>
        <primary>configuring</primary>

        <secondary>file server machine, issues</secondary>
      </indexterm>

      <indexterm>
        <primary>roles for server machine</primary>

        <secondary>summary</secondary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>roles for</secondary>

        <tertiary>summary</tertiary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>first installed</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <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>
        <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
          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>
        </listitem>

        <listitem>
          <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>
        </listitem>
    </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>

    <indexterm>
      <primary>database server machine</primary>

      <secondary>reason to run three</secondary>
    </indexterm>

    <indexterm>
      <primary>distribution</primary>

      <secondary>of databases</secondary>
    </indexterm>

    <indexterm>
      <primary>databases, distributed</primary>
    </indexterm>

    <indexterm>
      <primary>distributed databases</primary>
    </indexterm>

    <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>
          <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>
          </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>
          </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>
          </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>
          </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>

      <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>

        <secondary>protecting directories on local disk</secondary>
      </indexterm>

      <indexterm>
        <primary>local disk</primary>

        <secondary>protecting on file server machine</secondary>
      </indexterm>
    </sect2>

    <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
      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
      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>

      <indexterm>
        <primary>server machine</primary>

        <secondary>monitoring</secondary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>

        <secondary>rebooting, about</secondary>
      </indexterm>

      <indexterm>
        <primary>rebooting</primary>

        <secondary>file server machine, limiting</secondary>
      </indexterm>

      <indexterm>
        <primary>weekly restart of BOS Server (automatic)</primary>

        <secondary>about</secondary>
      </indexterm>

      <indexterm>
        <primary>restart times for BOS Server</primary>

        <secondary>about</secondary>
      </indexterm>
    </sect2>

    <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
      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>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>

        <secondary>configuration issues</secondary>
      </indexterm>

      <indexterm>
        <primary>configuring</primary>

        <secondary>client machine, issues</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <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>

    <indexterm>
      <primary>client machine</primary>

      <secondary>files required on local disk</secondary>
    </indexterm>

    <indexterm>
      <primary>local disk</primary>

      <secondary>files required on client machine</secondary>
    </indexterm>

    <indexterm>
      <primary>file</primary>

      <secondary>required on client machine local disk</secondary>
    </indexterm>

    <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>
          <listitem>
            <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>
                </listitem>

                <listitem>
                  <para>The <emphasis role="bold">fstab</emphasis>
                  file</para>
                </listitem>

                <listitem>
                  <para>The <emphasis role="bold">mount</emphasis> command
                  binary</para>
                </listitem>

                <listitem>
                  <para>The <emphasis role="bold">umount</emphasis>
                  command binary</para>
                </listitem>
              </itemizedlist>
          </para>
          </listitem>

          <listitem>
            <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>
                </listitem>

                <listitem>
                  <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>
                </listitem>

                <listitem>
                  <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>
                </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>
    </sect2>

    <sect2 id="Header_66">
      <title>Enabling Access to Foreign Cells</title>

      <indexterm>
        <primary>client machine</primary>

        <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>

      <indexterm>
        <primary>at-sys (@sys) variable in pathnames</primary>
      </indexterm>

      <indexterm>
        <primary>sys (@sys) variable in pathnames</primary>
      </indexterm>

      <indexterm>
        <primary>variables</primary>

        <secondary>@sys in pathnames</secondary>
      </indexterm>
    </sect2>

    <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>
    </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>

      <indexterm>
        <primary>user account</primary>

        <secondary>configuration issues</secondary>
      </indexterm>
    </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
    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
    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>
        <listitem>
          <para>A Protection Database entry</para>
        </listitem>

        <listitem>
          <para>An Authentication Database entry</para>
        </listitem>

        <listitem>
          <para>A volume</para>
        </listitem>

        <listitem>
          <para>A home directory at which the volume is mounted</para>
        </listitem>

        <listitem>
          <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>
        </listitem>

        <listitem>
          <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>
        <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>
        </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
          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>
        </listitem>
    </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>
        <listitem>
          <para>Making UNIX and AFS UIDs match</para> </listitem>

        <listitem>
          <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>

    <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>
      <primary>username</primary>

      <secondary>choosing</secondary>
    </indexterm>

    <indexterm>
      <primary>user</primary>

      <secondary>name</secondary>

      <see>username</see>
    </indexterm>

    <indexterm>
      <primary>choosing</primary>

      <secondary>name</secondary>

      <tertiary>user</tertiary>
    </indexterm>

    <indexterm>
      <primary>anonymous user</primary>

      <secondary>AFS UID reserved</secondary>
    </indexterm>

    <indexterm>
      <primary>AFS UID</primary>

      <secondary>reserved</secondary>

      <tertiary>anonymous user</tertiary>
    </indexterm>

    <sect2 id="HDRWQ58">
      <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>

      <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>
      </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.
      <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>
          </listitem>

          <listitem>
            <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>
          </listitem>

          <listitem>
            <para>Spaces</para>
          </listitem>

          <listitem>
            <para>The newline character</para>
          </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
            role="bold">pat.admin</emphasis></para>
          </listitem>
      </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>
      </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>
          <listitem>
            <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>
          </listitem>
      </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>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>

        <secondary>part of volume name</secondary>
      </indexterm>

      <indexterm>
        <primary>choosing</primary>

        <secondary>name</secondary>

        <tertiary>user volume</tertiary>
      </indexterm>

      <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>
      </formalpara>

      <indexterm>
        <primary>mount point</primary>

        <secondary>choosing name for user volume</secondary>
      </indexterm>

      <indexterm>
        <primary>choosing</primary>

        <secondary>name</secondary>

        <tertiary>user volume mount point</tertiary>
      </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
        alternatives, see the following section.</para>
      </formalpara>

      <indexterm>
        <primary>directories</primary>

        <secondary>for grouping user home directories</secondary>
      </indexterm>

      <indexterm>
        <primary>user account</primary>

        <secondary>suggestions for grouping home directories</secondary>
      </indexterm>
    </sect2>

    <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.
      <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>
          </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>
          </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>
          </listitem>
      </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>
    </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
      linkend="HDRWQ201">Creating Backup Volumes</link>.</para>

      <indexterm>
        <primary>file</primary>

        <secondary>creating standard ones in new user account</secondary>
      </indexterm>

      <indexterm>
        <primary>user account</primary>

        <secondary>creating</secondary>

        <tertiary>standard files in</tertiary>
      </indexterm>

      <indexterm>
        <primary>creating</primary>

        <secondary>standard files in new user account</secondary>
      </indexterm>
    </sect2>

    <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>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>
          </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>
          </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>
          </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>

<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>

<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>

      <indexterm>
        <primary>group</primary>

        <secondary>AFS GID</secondary>
      </indexterm>

      <indexterm>
        <primary>group</primary>

        <secondary>restrictions</secondary>
      </indexterm>

      <indexterm>
        <primary>group</primary>

        <secondary>privacy flags</secondary>
      </indexterm>

      <indexterm>
        <primary>privacy flags on Protection Database entry</primary>
      </indexterm>
    </sect2>
  </sect1>

  <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
    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>

    <indexterm>
      <primary>system:administrators group</primary>

      <secondary>about</secondary>
    </indexterm>

    <indexterm>
      <primary>system:anyuser group</primary>

      <secondary>about</secondary>
    </indexterm>

    <indexterm>
      <primary>system:authuser group</primary>

      <secondary>about</secondary>
    </indexterm>

    <indexterm>
      <primary>group</primary>

      <secondary>system-defined</secondary>
    </indexterm>

    <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>

      <indexterm>
        <primary>AFS UID</primary>

        <secondary>reserved</secondary>

        <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>
          <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>
          </listitem>

          <listitem>
            <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>

      <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>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>

        <secondary>AFS separate from UNIX</secondary>
      </indexterm>

      <indexterm>
        <primary>AFS</primary>

        <secondary>authentication separate from UNIX</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <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>
        <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>
        </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>
        </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>

    <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
    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>

    <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>
    </note>

    <indexterm>
      <primary>commands</primary>

      <secondary>pagsh</secondary>
    </indexterm>

    <indexterm>
      <primary>pagsh command</primary>
    </indexterm>

    <indexterm>
      <primary>commands</primary>

      <secondary>klog with -setpag flag</secondary>
    </indexterm>

    <indexterm>
      <primary>klog command</primary>

      <secondary>with -setpag flag</secondary>
    </indexterm>

    <indexterm>
      <primary>PAG</primary>

      <secondary>creating with klog or pagsh command</secondary>
    </indexterm>

    <indexterm>
      <primary>creating</primary>

      <secondary>PAG with klog or pagsh command</secondary>
    </indexterm>

    <indexterm>
      <primary>process authentication group</primary>

      <secondary></secondary>

      <see>PAG</see>
    </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>
          <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>
          </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>
          </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>

      <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
      &lt;<emphasis role="bold">Ctrl-d</emphasis>&gt;, 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>

        <secondary>AFS version</secondary>
      </indexterm>
    </sect2>

    <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>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
            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>
          </listitem>

          <listitem>
            <para><anchor id="LIWQ66" />The utility obtains a PAG.</para>
          </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
            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>
                <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
                  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>
                </listitem>
            </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.
            <itemizedlist>
                <listitem>
                  <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>
          </listitem>
      </orderedlist>
      </para>

      <indexterm>
        <primary>local password file</primary>

        <secondary>when using AFS--modified login utility</secondary>
      </indexterm>

      <indexterm>
        <primary>login utility</primary>

        <secondary>AFS version's interaction with local password
        file</secondary>
      </indexterm>

      <indexterm>
        <primary>password</primary>

        <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>
          <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>
          </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>
          </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
            role="bold">passwd</emphasis> or equivalent).</para>
          </listitem>
      </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>

      <indexterm>
        <primary>local password file</primary>

        <secondary>when not using AFS-modified login utility</secondary>
      </indexterm>
    </sect2>

    <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>
          <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>
          </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>
          </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>

      <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>

        <secondary>displaying for user</secondary>
      </indexterm>

      <indexterm>
        <primary>tokens</primary>

        <secondary>command</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>tokens</secondary>
      </indexterm>

      <indexterm>
        <primary>listing</primary>

        <secondary>tokens held by issuer</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>klog</secondary>
      </indexterm>

      <indexterm>
        <primary>klog command</primary>
      </indexterm>

      <indexterm>
        <primary>server process</primary>

        <secondary>creating ticket (tokens) for</secondary>
      </indexterm>

      <indexterm>
        <primary>tickets</primary>

        <secondary></secondary>

        <see>tokens</see>
      </indexterm>

      <indexterm>
        <primary>tokens</primary>

        <secondary>creating for server process</secondary>
      </indexterm>

      <indexterm>
        <primary>authenticated identity</primary>

        <secondary>acquiring with klog command</secondary>
      </indexterm>

      <indexterm>
        <primary>unlog command</primary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>unlog</secondary>
      </indexterm>

      <indexterm>
        <primary>discarding</primary>

        <secondary>tokens</secondary>
      </indexterm>

      <indexterm>
        <primary>tokens</primary>

        <secondary>discarding with unlog command</secondary>
      </indexterm>
    </sect2>

    <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
      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>If the issuer is not authenticated in any cell:</para>

<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>

<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 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>
   % <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]
   User's (AFS ID 4286) tokens for afs@stateu.edu  [Expires Jun  3 1:34]
   User's (AFS ID 22) tokens for afs@def.com  [&gt;&gt;Expired&lt;&lt;]
       --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>

<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]
   User smith's tokens for krbtgt.ABC.COM@abc.com [Expires Jun  2 10:00]
     --End of list--
</programlisting>
    </sect2>

    <sect2 id="Header_82">
      <title>Setting Default Token Lifetimes for Users</title>

      <indexterm>
        <primary>tokens</primary>

        <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>
          <listitem>
            <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>
          </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>
          </listitem>
      </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>
      </note>
    </sect2>

    <sect2 id="Header_83">
      <title>Changing Passwords</title>

      <indexterm>
        <primary>password</primary>

        <secondary>changing in AFS</secondary>
      </indexterm>

      <indexterm>
        <primary>kpasswd command</primary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>kpasswd</secondary>
      </indexterm>

      <indexterm>
        <primary>kas commands</primary>

        <secondary>setpassword</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <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>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
      Passwords</link>.</para>
    </sect2>

    <sect2 id="Header_84">
      <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>

      <indexterm>
        <primary>password</primary>

        <secondary>expiration</secondary>
      </indexterm>

      <indexterm>
        <primary>password</primary>

        <secondary>lifetime</secondary>
      </indexterm>

      <indexterm>
        <primary>kas commands</primary>

        <secondary>setfields</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>kas setfields</secondary>
      </indexterm>

      <indexterm>
        <primary>Authentication Database</primary>

        <secondary>password lifetime, setting</secondary>
      </indexterm>

      <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>

      <indexterm>
        <primary>password</primary>

        <secondary>consequences of multiple failed authentication
        attempts</secondary>
      </indexterm>

      <indexterm>
        <primary>kas commands</primary>

        <secondary>setfields</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>kas setfields</secondary>
      </indexterm>

      <indexterm>
        <primary>authentication</primary>

        <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>

      <indexterm>
        <primary>password</primary>

        <secondary>checking quality of</secondary>
      </indexterm>

      <indexterm>
        <primary>kpasswd command</primary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>kpasswd</secondary>
      </indexterm>

      <indexterm>
        <primary>kas commands</primary>

        <secondary>setpassword</secondary>
      </indexterm>

      <indexterm>
        <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
      Administration Reference.</para>

      <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 is not a word</para>
          </listitem>

          <listitem>
            <para>The password contains both numbers and letters</para>
          </listitem>
      </itemizedlist>
      </para>
    </sect2>

    <sect2 id="HDRWQ70">
      <title>Support for Kerberos Authentication</title>

      <indexterm>
        <primary>Kerberos</primary>

        <secondary>support for in AFS</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>klog.krb</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>pagsh.krb</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>tokens.krb</secondary>
      </indexterm>

      <indexterm>
        <primary>klog.krb command</primary>
      </indexterm>

      <indexterm>
        <primary>pagsh.krb command</primary>
      </indexterm>

      <indexterm>
        <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>
      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>

  <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>

    <sect2 id="HDRWQ72">
      <title>Some Important Security Features</title>

      <indexterm>
        <primary>security</primary>

        <secondary>AFS features</secondary>
      </indexterm>

      <indexterm>
        <primary>AFS</primary>

        <secondary>security features</secondary>
      </indexterm>

      <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>
      </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>
      </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>

      <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>
      </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
      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
        Privilege</link>.</para>
      </formalpara>

      <formalpara>
        <title>Encrypted Network Communications</title>

        <indexterm>
          <primary>network</primary>

          <secondary>encrypted communication in AFS</secondary>
        </indexterm>

        <indexterm>
          <primary>encrypted network communication</primary>
        </indexterm>

        <indexterm>
          <primary>security</primary>

          <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>
      </formalpara>

      <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
            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>
          </listitem>

          <listitem>
            <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>
          </listitem>
      </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>
    </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>
          <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>
          </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>
          </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>
          </listitem>
      </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 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>
    </sect2>

    <sect2 id="HDRWQ74">
      <title>Improving Security in Your Cell</title>

      <indexterm>
        <primary>security</primary>

        <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>

      <formalpara>
        <title>User Accounts</title>

        <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>
            </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
              equivalent.</para>
            </listitem>
          </itemizedlist>
        </para>
      </formalpara>

      <formalpara>
        <title>Server Machines</title>

        <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
              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>
            </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
              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>

              <indexterm>
                <primary>root superuser</primary>

                <secondary>limiting logins</secondary>
              </indexterm>
            </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>
            </listitem>
          </itemizedlist>
        </para>
      </formalpara>

      <formalpara>
        <title>System Administrators</title>

        <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>
            </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>
            </listitem>

            <listitem>
              <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>
            </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>
            </listitem>
          </itemizedlist>
        </para>
      </formalpara>
    </sect2>

    <sect2 id="HDRWQ75">
      <title>A More Detailed Look at Mutual Authentication</title>

      <indexterm>
        <primary>mutual authentication</primary>
      </indexterm>

      <indexterm>
        <primary>distributed file system</primary>

        <secondary>security issues</secondary>
      </indexterm>

      <indexterm>
        <primary>shared secret</primary>
      </indexterm>

      <indexterm>
        <primary>server encryption key</primary>

        <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>

      <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
        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>

        <indexterm>
          <primary>ticket-granter</primary>
        </indexterm>

        <indexterm>
          <primary>server encryption key</primary>
        </indexterm>

        <indexterm>
          <primary>tokens</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:
        <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
              connection).</para>

              <indexterm>
                <primary>session key</primary>
              </indexterm>
            </listitem>

            <listitem>
              <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>
            </listitem>
        </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>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>
            </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>
            </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>
            <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
              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>
            </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>
            </listitem>
        </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>

    <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>
    </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>
    </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>
  </sect1>
</chapter>
