[openafs.git] / doc / xml / AdminGuide / auagd010.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="HDRWQ174">
  <title>Managing Volumes</title>

  <para>This chapter explains how to manage the volumes stored on file server machines. The volume is the designated unit of
  administration in AFS, so managing them is a large part of the administrator's duties.</para>

  <sect1 id="HDRWQ175">
    <title>Summary of Instructions</title>

    <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>

    <informaltable frame="none">
      <tgroup cols="2">
        <colspec colwidth="58*" />

        <colspec colwidth="42*" />

        <tbody>
          <row>
            <entry>Create read/write volume</entry>

            <entry><emphasis role="bold">vos create</emphasis></entry>
          </row>

          <row>
            <entry>Create read-only volume</entry>

            <entry><emphasis role="bold">vos addsite</emphasis> <emphasis role="bold">and</emphasis> <emphasis role="bold">vos
            release</emphasis></entry>
          </row>

          <row>
            <entry>Create backup volume</entry>

            <entry><emphasis role="bold">vos backup</emphasis></entry>
          </row>

          <row>
            <entry>Create many backup volumes at once</entry>

            <entry><emphasis role="bold">vos backupsys</emphasis></entry>
          </row>

          <row>
            <entry>Examine VLDB entry</entry>

            <entry><emphasis role="bold">vos listvldb</emphasis></entry>
          </row>

          <row>
            <entry>Examine volume header</entry>

            <entry><emphasis role="bold">vos listvol</emphasis></entry>
          </row>

          <row>
            <entry>Examine both VLDB entry and volume header</entry>

            <entry><emphasis role="bold">vos examine</emphasis></entry>
          </row>

          <row>
            <entry>Display volume's name</entry>

            <entry><emphasis role="bold">fs listquota</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs
            examine</emphasis></entry>
          </row>

          <row>
            <entry>Display volume's ID number</entry>

            <entry><emphasis role="bold">fs examine</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">vos
            examine</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">vos listvol</emphasis></entry>
          </row>

          <row>
            <entry>Display partition's size and space available</entry>

            <entry><emphasis role="bold">vos partinfo</emphasis></entry>
          </row>

          <row>
            <entry>Display volume's location</entry>

            <entry><emphasis role="bold">fs whereis</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">vos
            examine</emphasis></entry>
          </row>

          <row>
            <entry>Create mount point</entry>

            <entry><emphasis role="bold">fs mkmount</emphasis></entry>
          </row>

          <row>
            <entry>Remove mount point</entry>

            <entry><emphasis role="bold">fs rmmount</emphasis></entry>
          </row>

          <row>
            <entry>Display mount point</entry>

            <entry><emphasis role="bold">fs lsmount</emphasis></entry>
          </row>

          <row>
            <entry>Move read/write volume</entry>

            <entry><emphasis role="bold">vos move</emphasis></entry>
          </row>

          <row>
            <entry>Synchronize VLDB with volume headers</entry>

            <entry><emphasis role="bold">vos syncvldb</emphasis> <emphasis role="bold">and</emphasis> <emphasis role="bold">vos
            syncserv</emphasis></entry>
          </row>

          <row>
            <entry>Set volume quota</entry>

            <entry><emphasis role="bold">fs setvol</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs
            setquota</emphasis></entry>
          </row>

          <row>
            <entry>Display volume quota</entry>

            <entry><emphasis role="bold">fs quota</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs
            listquota</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs examine</emphasis></entry>
          </row>

          <row>
            <entry>Display volume's current size</entry>

            <entry><emphasis role="bold">fs listquota</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs
            examine</emphasis></entry>
          </row>

          <row>
            <entry>Display list of volumes on a machine/partition</entry>

            <entry><emphasis role="bold">vos listvol</emphasis></entry>
          </row>

          <row>
            <entry>Remove read/write volume</entry>

            <entry><emphasis role="bold">vos remove</emphasis> <emphasis role="bold">and</emphasis> <emphasis role="bold">fs
            rmmount</emphasis></entry>
          </row>

          <row>
            <entry>Remove read-only volume</entry>

            <entry><emphasis role="bold">vos remove</emphasis></entry>
          </row>

          <row>
            <entry>Remove backup volume</entry>

            <entry><emphasis role="bold">vos remove</emphasis> <emphasis role="bold">and</emphasis> <emphasis role="bold">fs
            rmmount</emphasis></entry>
          </row>

          <row>
            <entry>Remove volume; no VLDB change</entry>

            <entry><emphasis role="bold">vos zap</emphasis></entry>
          </row>

          <row>
            <entry>Remove read-only site definition</entry>

            <entry><emphasis role="bold">vos remsite</emphasis></entry>
          </row>

          <row>
            <entry>Remove VLDB entry; no volume change</entry>

            <entry><emphasis role="bold">vos delentry</emphasis></entry>
          </row>

          <row>
            <entry>Dump volume</entry>

            <entry><emphasis role="bold">vos dump</emphasis></entry>
          </row>

          <row>
            <entry>Restore dumped volume</entry>

            <entry><emphasis role="bold">vos restore</emphasis></entry>
          </row>

          <row>
            <entry>Rename volume</entry>

            <entry><emphasis role="bold">vos rename</emphasis>, <emphasis role="bold">fs rmmount</emphasis> <emphasis
            role="bold">and</emphasis> <emphasis role="bold">fs mkmount</emphasis></entry>
          </row>

          <row>
            <entry>Unlock volume</entry>

            <entry><emphasis role="bold">vos unlock</emphasis></entry>
          </row>

          <row>
            <entry>Unlock multiple volumes</entry>

            <entry><emphasis role="bold">vos unlockvldb</emphasis></entry>
          </row>

          <row>
            <entry>Lock volume</entry>

            <entry><emphasis role="bold">vos lock</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </sect1>

  <sect1 id="HDRWQ177">
    <title>About Volumes</title>

    <indexterm>
      <primary>volume</primary>

      <secondary>defined</secondary>
    </indexterm>

    <para>An AFS <emphasis>volume</emphasis> is a logical unit of disk space that functions like a container for the files in an AFS
    directory, keeping them all together on one partition of a file server machine. To make a volume's contents visible in the
    cell's file tree and accessible to users, you mount the volume at a directory location in the AFS filespace. The association
    between the volume and its location in the filespace is called a <emphasis>mount point</emphasis>, and because of AFS's internal
    workings it looks and acts just like a standard directory element. Users can access and manipulate a volume's contents in the
    same way they access and manipulate the contents of a standard UNIX directory. For more on the relationship between volumes and
    directories, see <link linkend="HDRWQ183">About Mounting Volumes</link>.</para>

    <para>Many of an administrator's daily activities involve manipulating volumes, since they are the basic storage and
    administrative unit of AFS. For a discussion of some of the ways volumes can make your job easier, see <link
    linkend="HDRWQ179">How Volumes Improve AFS Efficiency</link>.</para>

    <sect2 id="HDRWQ178">
      <title>The Three Types of Volumes</title>

      <para>There are three types of volumes in AFS, as described in the following list: <itemizedlist>
          <listitem>
            <para>The single <emphasis>read/write</emphasis> version of a volume houses the modifiable versions of the files and
            directories in that volume. It is often referred to as the <emphasis>read/write</emphasis> source because volumes of the
            other two types are derived from it by a copying procedure called <emphasis>cloning</emphasis>. For instructions on
            creating read/write volumes, see <link linkend="HDRWQ185">Creating Read/write Volumes</link>.</para>

            <indexterm>
              <primary>read/write volume</primary>

              <secondary>defined</secondary>
            </indexterm>
          </listitem>

          <listitem>
            <para>A <emphasis>read-only</emphasis> volume is a copy of the read/write source volume and can exist at multiple
            <emphasis>sites</emphasis> (a site is a particular partition on a particular file server machine). Placing the same data
            at more than one site is called <emphasis>replication</emphasis>; see <link linkend="HDRWQ179">How Volumes Improve AFS
            Efficiency</link>. As the name suggests, a read-only volume's contents do not change automatically as the read/write
            source changes, but only when an administrator issues the <emphasis role="bold">vos release</emphasis> command. For
            users to have a consistent view of the AFS filespace, all copies of the read-only volume must match each other and their
            read/write source. All read-only volumes share the same name, which is derived by adding the <emphasis
            role="bold">.readonly</emphasis> extension to the read/write source's name. For instructions on creating of read-only
            volumes, see <link linkend="HDRWQ192">Replicating Volumes (Creating Read-only Volumes)</link>.</para>

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

              <secondary>defined</secondary>
            </indexterm>

            <indexterm>
              <primary>site</primary>

              <secondary>volume, defined</secondary>
            </indexterm>

            <indexterm>
              <primary>volume</primary>

              <secondary>site, defined</secondary>
            </indexterm>
          </listitem>

          <listitem>
            <para>A <emphasis>backup</emphasis> volume is a clone of the read/write source volume and is stored at the same site as
            the source. A backup version is useful because it records the state of the read/write source at a certain time, allowing
            recovery of data that is later mistakenly changed or deleted (for further discussion see <link linkend="HDRWQ179">How
            Volumes Improve AFS Efficiency</link>). A backup volume's name is derived by adding the <emphasis
            role="bold">.backup</emphasis> extension to the read/write source's name. For instructions on creating of backup
            volumes, see <link linkend="HDRWQ201">Creating Backup Volumes</link>.</para>

            <indexterm>
              <primary>backup volume</primary>

              <secondary>defined</secondary>
            </indexterm>

            <note>
              <para>A backup volume is not the same as the backup of a volume transferred to tape using the AFS Backup System,
              although making a backup version of a volume is usually a stage in the process of backing up the volume to tape. For
              information on backing up a volume using the AFS Backup System, see <link linkend="HDRWQ296">Backing Up
              Data</link>.</para>
            </note>
          </listitem>
        </itemizedlist></para>

      <para>As noted, the three types of volumes are related to one another: read-only and backup volumes are both derived from a
      read/write volume through a process called cloning. Read-only and backup volumes are exact copies of the read/write source at
      the time they are created.</para>
    </sect2>

    <sect2 id="HDRWQ179">
      <title>How Volumes Improve AFS Efficiency</title>

      <indexterm>
        <primary>volume</primary>

        <secondary>benefits for efficiency</secondary>
      </indexterm>

      <para>Volumes make your cell easier to manage and more efficient in the following three ways: <itemizedlist>
          <listitem>
            <para>Volumes are easy to move between partitions, on the same or different machines, because they are by definition
            smaller than a partition. Perhaps the most common reasons to move volumes are to balance the load among file server
            machines or to take advantage of greater disk capacity on certain machines. You can move volumes as often as necessary
            without disrupting user access to their contents, because the move procedure makes the contents unavailable for only a
            few seconds. The automatic tracking of volume locations in the Volume Location Database (VLDB) assures that access
            remains transparent. For instructions on moving volumes, see <link linkend="HDRWQ226">Moving Volumes</link>.</para>

            <indexterm>
              <primary>volume</primary>

              <secondary>in load balancing</secondary>
            </indexterm>
          </listitem>

          <listitem>
            <para>Volumes are the unit of replication in AFS. <emphasis>Replication</emphasis> refers to creating a read-only clone
            from the read/write source and distributing of the clone to one or more sites. Replication improves system efficiency
            because more than one machine can fill requests for popular files. It also boosts system reliability by helping to keep
            data available in the face of machine or server process outage. In general, volumes containing popular application
            programs and other files that do not change often are the best candidates for replication, but you can replicate any
            read/write volume. See <link linkend="HDRWQ192">Replicating Volumes (Creating Read-only Volumes)</link>.</para>

            <indexterm>
              <primary>volume</primary>

              <secondary>as unit of replication</secondary>
            </indexterm>

            <indexterm>
              <primary>replication</primary>

              <secondary>defined</secondary>
            </indexterm>
          </listitem>

          <listitem>
            <indexterm>
              <primary>volume</primary>

              <secondary>as unit of backup</secondary>
            </indexterm>

            <para>Volumes are the unit of backup in AFS, in two senses. You can create a backup volume version to preserves the
            state of a read/write source volume at a specified time. You can mount the backup version in the AFS filespace, enabling
            users to restore data they have accidentally changed or deleted without administrator assistance, which frees you for
            more important jobs. If you make a new backup version of user volumes once a day (presumably overwriting the former
            backup), then users are always be able to retrieve the previous day's version of a file. For instructions, see <link
            linkend="HDRWQ201">Creating Backup Volumes</link>.</para>

            <para>Backup also refers to using the AFS Backup System to store permanent copies of volume contents on tape or in a
            special backup data. See <link linkend="HDRWQ248">Configuring the AFS Backup System</link>and <link
            linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ180">
      <title>Volume Information in the VLDB</title>

      <para>The Volume Location Database (VLDB) includes entries for every volume in a cell. Perhaps the most important information
      in the entry is the volume's location, which is key to transparent access to AFS data. When a user opens a file, the Cache
      Manager consults the Volume Location (VL) Server, which maintains the VLDB, for a list of the file server machines that house
      the volume containing the file. The Cache Manager then requests the file from the File Server running on one of the relevant
      file server machines. The file location procedure is invisible to the user, who only needs to know the file's pathname.</para>

      <indexterm>
        <primary>VLDB</primary>

        <secondary>volume entry</secondary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>entry in VLDB</secondary>
      </indexterm>

      <indexterm>
        <primary>entry in VLDB</primary>

        <secondary>for volume</secondary>
      </indexterm>

      <para>The VLDB volume entry for a read/write volume also contains the pertinent information about the read-only and backup
      versions, which do not have their own VLDB entries. (The rare exception is a read-only volume that has its own VLDB entry
      because its read/write source has been removed.) A volume's VLDB entry records the volume's name, the unique volume ID number
      for each version (read/write, read-only, backup, and releaseClone), a count of the number of sites that house a read/write or
      read-only version, and a list of the sites.</para>

      <para>To display the VLDB entry for one or more volumes, use the <emphasis role="bold">vos listvldb</emphasis> command as
      described in <link linkend="HDRWQ218">To display VLDB entries</link>. To display the VLDB entry for a single volume along with
      its <emphasis>volume header</emphasis>, use the <emphasis role="bold">vos examine</emphasis> command as described in <link
      linkend="HDRWQ222">To display one volume's VLDB entry and volume header</link>. (See the following section for a description
      of the volume header.)</para>
    </sect2>

    <sect2 id="HDRWQ181">
      <title>The Information in Volume Headers</title>

      <indexterm>
        <primary>volume</primary>

        <secondary>header</secondary>

        <see>volume header</see>
      </indexterm>

      <indexterm>
        <primary>volume header</primary>

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

      <para>Whereas all versions of a volume share one VLDB entry, each volume on an AFS server partition has its own volume header,
      a data structure that maps the files and directories in the volume to physical memory addresses on the partition that stores
      them. The volume header binds the volume's contents into a logical unit without requiring that they be stored in contiguous
      memory blocks. The volume header also records the following information about the volume, some of it redundant with the VLDB
      entry: name, volume ID number, type, size, status (online, offline, or busy), space quota, timestamps for creation date and
      date of last modification, and number of accesses during the current day.</para>

      <para>To display the volume headers on one or more partitions, use the <emphasis role="bold">vos listvol</emphasis> command as
      described in <link linkend="HDRWQ220">To display volume headers</link>. To display the VLDB entry for a single volume along
      with its volume header, use the <emphasis role="bold">vos examine</emphasis> command as described in <link
      linkend="HDRWQ222">To display one volume's VLDB entry and volume header</link>.</para>
    </sect2>

    <sect2 id="HDRWQ182">
      <title>Keeping the VLDB and Volume Headers Synchronized</title>

      <indexterm>
        <primary>synchrony of VLDB and volume headers</primary>

        <secondary>maintained by VL and Volume Servers</secondary>
      </indexterm>

      <indexterm>
        <primary>VLDB</primary>

        <secondary>synchronizing with volume headers</secondary>
      </indexterm>

      <indexterm>
        <primary>volume header</primary>

        <secondary>synchronizing with VLDB</secondary>
      </indexterm>

      <indexterm>
        <primary>maintaining</primary>

        <secondary>synchrony of VLDB with volume headers</secondary>
      </indexterm>

      <indexterm>
        <primary>VL Server</primary>

        <secondary>role in VLDB/volume header synchronization</secondary>
      </indexterm>

      <indexterm>
        <primary>Volume Server</primary>

        <secondary>role in VLDB/volume header synchronization</secondary>
      </indexterm>

      <para>It is vital that the information in the VLDB correspond to the status of the actual volumes on the servers (as recorded
      in volume headers) as much of the time as possible. If a volume's location information in the VLDB is incorrect, the Cache
      Manager cannot find access its contents. Whenever you issue a <emphasis role="bold">vos</emphasis> command that changes a
      volume's status, the Volume Server and VL Server cooperate to keep the volume header and VLDB synchronized. In rare cases, the
      header and VLDB can diverge, for instance because a <emphasis role="bold">vos</emphasis> operation halts prematurely. For
      instructions on resynchronizing them, see <link linkend="HDRWQ227">Synchronizing the VLDB and Volume Headers</link>.</para>
    </sect2>

    <sect2 id="HDRWQ183">
      <title>About Mounting Volumes</title>

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

        <secondary>defined</secondary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>mounting</secondary>

        <tertiary>about</tertiary>
      </indexterm>

      <indexterm>
        <primary>mounting</primary>

        <secondary>volume</secondary>

        <tertiary>about</tertiary>
      </indexterm>

      <para>To make a volume's contents visible in the cell's file tree and accessible to users, you mount the volume at a directory
      location in the AFS filespace. The association between the volume and its location in the filespace is called a
      <emphasis>mount point</emphasis>. An AFS mount point looks and functions like a regular UNIX file system directory, but
      structurally it is more like a symbolic link that tells the Cache Manager the name of the volume associated with the
      directory. A mount point looks and acts like a directory only because the Cache Manager knows how to interpret it.</para>

      <para>Consider the common case where the Cache Manager needs to retrieve a file requested by an application program. The Cache
      Manager traverses the file's complete pathname, starting at the AFS root (by convention mounted at the <emphasis
      role="bold">/afs</emphasis> directory) and continuing to the file. When the Cache Manager encounters (or
      <emphasis>crosses</emphasis>) a mount point during the traversal, it reads it to learn the name of the volume mounted at that
      directory location. After obtaining location information about the volume from the Volume Location (VL) Server, the Cache
      Manager fetches the indicated volume and opens its <emphasis>root directory</emphasis>. The root directory of a volume lists
      all the files, subdirectories, and mount points that reside in it. The Cache Manager scans the root directory listing for the
      next element in the pathname. It continues down the path, using this method to interpret any other mount points it encounters,
      until it reaches the volume that houses the requested file.</para>

      <indexterm>
        <primary>root directory</primary>
      </indexterm>

      <indexterm>
        <primary>Cache Manager</primary>

        <secondary>as interpreter of mount points</secondary>
      </indexterm>

      <para>Mount points act as the glue that connects the AFS file space, creating the illusion of a single, seamless file tree
      even when volumes reside on many different file server machines. A volume's contents are visible and accessible when the
      volume is mounted at a directory location, and are not accessible at all if the volume is not mounted.</para>

      <para>You can mount a volume at more than one location in the file tree, but this is not recommended for two reasons. First,
      it distorts the hierarchical nature of the filespace. Second, the Cache Manager can become confused about which pathname it
      followed to reach the file (causing unpredictable output from the <emphasis role="bold">pwd</emphasis> command, for example).
      However, if you mount a volume at more than one directory, the access control list (ACL) associated with the volume's root
      directory applies to all of the mount points.</para>

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

        <secondary>creating multiple per volume</secondary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>mounting</secondary>

        <tertiary>more than once</tertiary>
      </indexterm>

      <para>There are several types of mount points, each of which the Cache Manager handles in a different way and each of which is
      appropriate for a different purpose. See <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
    </sect2>

    <sect2 id="HDRWQ184">
      <title>About Volume Names</title>

      <indexterm>
        <primary>volume</primary>

        <secondary>name</secondary>

        <see>volume name</see>
      </indexterm>

      <indexterm>
        <primary>length restriction on volume names</primary>
      </indexterm>

      <para>A read/write volume's name can be up to 22 characters in length. The Volume Server automatically adds the <emphasis
      role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extensions to read-only and backup volumes
      respectively. Do not explicitly add the extensions to volume names, even if they are appropriate.</para>

      <para>It is conventional for a volume's name to indicate the type of data it houses. For example, it is conventional to name
      all user volumes <emphasis role="bold">user</emphasis>.username where username is the user's login name. Similarly, many cells
      elect to put system binaries in volumes with names that begin with the system type code. For a list of other naming
      conventions, see <link linkend="HDRWQ44">Creating Volumes to Simplify Administration</link>.</para>

      <indexterm>
        <primary>conventions</primary>

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

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

        <secondary>conventions</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ185">
    <title>Creating Read/write Volumes</title>

    <indexterm>
      <primary>creating</primary>

      <secondary>read/write volume</secondary>
    </indexterm>

    <indexterm>
      <primary>volume</primary>

      <secondary>read/write</secondary>

      <see>read/write volume</see>
    </indexterm>

    <indexterm>
      <primary>read/write volume</primary>

      <secondary>creating</secondary>
    </indexterm>

    <para>A read/write volume is the most basic type of volume, and must exist before you can create read-only or backup versions of
    it. When you issue the <emphasis role="bold">vos create</emphasis> command to create a read/write volume, the VL Server creates
    a VLDB entry for it which records the name you specify, assigns a read/write volume ID number, and reserves the next two
    consecutive volume ID numbers for read-only and backup versions that possibly are to be created later. At the same time, the
    Volume Server creates a volume header at the site you designate, allocating space on disk to record the name of the volume's
    root directory. The name is filled in when you issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the
    volume, and matches the mount point name. The following is also recorded in the volume header: <itemizedlist>
        <listitem>
          <para>An initial ACL associated with the volume's root directory. By default it grants all seven AFS access permissions to
          the <emphasis role="bold">system:administrators</emphasis> group. After you mount the volume, you can use the <emphasis
          role="bold">fs setacl</emphasis> command to add other entries and to remove or change the entry for the <emphasis
          role="bold">system:administrators</emphasis> group. See <link linkend="HDRWQ573">Setting ACL Entries</link>.</para>

          <indexterm>
            <primary>default</primary>

            <secondary>ACL</secondary>
          </indexterm>

          <indexterm>
            <primary>ACL</primary>

            <secondary>default on new volume</secondary>
          </indexterm>
        </listitem>

        <listitem>
          <para>A space quota, which limits the amount of disk space the read/write version of the volume can use on the file server
          partition. The default is of 5000 kilobyte blocks, but you can use the <emphasis role="bold">-maxquota</emphasis> argument
          to the <emphasis role="bold">vos create</emphasis> command to set a different quota.</para>

          <para>To change the quota after creation, use the <emphasis role="bold">fs setquota</emphasis> command as described in
          <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current Size</link>.</para>

          <indexterm>
            <primary>volume quota</primary>

            <secondary>default for new volume</secondary>
          </indexterm>

          <indexterm>
            <primary>default</primary>

            <secondary>volume quota</secondary>
          </indexterm>
        </listitem>
      </itemizedlist></para>

    <sect2 id="Header_212">
      <title>To create (and mount) a read/write volume</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Verify that you have the <emphasis role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>), <emphasis
          role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>), and <emphasis role="bold">l</emphasis>( <emphasis
          role="bold">lookup</emphasis>) permissions on the ACL of the directory where you plan to mount the volume. If necessary,
          issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link
          linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
   % <emphasis role="bold">fs listacl</emphasis> [&lt;<emphasis>dir/file path</emphasis>&gt;]</programlisting></para>

          <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
          role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
          role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
          role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>

          <indexterm>
            <primary>commands</primary>

            <secondary>vos partinfo</secondary>
          </indexterm>

          <indexterm>
            <primary>vos commands</primary>

            <secondary>partinfo</secondary>
          </indexterm>
        </listitem>

        <listitem id="LIWQ186">
          <para>Select a site (disk partition on a file server machine) for the new volume. To verify that
          the site has enough free space to house the volume (now, or if it grows to use its entire quota), issue the <emphasis
          role="bold">vos partinfo</emphasis> command.</para>

          <note>
            <para>The partition-related statistics in this command's output do not always agree with the corresponding values in the
            output of the standard UNIX <emphasis role="bold">df</emphasis> command. The statistics reported by this command can be
            up to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency.
            Also, on some operating systems, the <emphasis role="bold">df</emphasis> command's report of partition size includes
            reserved space not included in this command's calculation, and so is likely to be about 10% larger.</para>
          </note>

          <programlisting>
   % <emphasis role="bold">vos partinfo</emphasis> &lt;<emphasis>machine name</emphasis>&gt; [&lt;<emphasis>partition name</emphasis>&gt;]</programlisting>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">p</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">partinfo</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Specifies the file server machine for which to display partition size and usage.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">partition name</emphasis></term>

                <listitem>
                  <para>Names one partition for which to display partition size and usage. If you omit it, the output displays the
                  size and space available for all partitions on the machine.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem id="LIWQ187">
          <para>Select a volume name, taking note of the information in <link linkend="HDRWQ184">About Volume
          Names</link>.</para>

          <indexterm>
            <primary>vos commands</primary>

            <secondary>create</secondary>

            <tertiary>basic instructions</tertiary>
          </indexterm>

          <indexterm>
            <primary>commands</primary>

            <secondary>vos create</secondary>

            <tertiary>basic instructions</tertiary>
          </indexterm>
        </listitem>

        <listitem id="LIWQ188">
          <para>Issue the <emphasis role="bold">vos create</emphasis> command to create the volume.
          <programlisting>
   % <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; \
        [<emphasis role="bold">-maxquota</emphasis> &lt;<replaceable>initial quota (KB)</replaceable>&gt;]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">cr</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">create</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Specifies the file server machine on which to place the volume.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">partition name</emphasis></term>

                <listitem>
                  <para>Specifies the disk partition on which to place the volume.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume name</emphasis></term>

                <listitem>
                  <para>Names the volume. It can be up to 22 alphanumeric and punctuation characters in length. Your cell possibly
                  has naming conventions for volumes, such as beginning user volume names with the string <emphasis
                  role="bold">user</emphasis> and using the period to separate parts of the name.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-maxquota</emphasis></term>

                <listitem>
                  <para>Sets the volume's quota, as a number of kilobyte blocks. If you omit this argument, the quota is set to 5000
                  kilobyte blocks.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>

          <indexterm>
            <primary>mounting</primary>

            <secondary>read/write volume</secondary>
          </indexterm>

          <indexterm>
            <primary>read/write volume</primary>

            <secondary>mounting</secondary>
          </indexterm>

          <indexterm>
            <primary>commands</primary>

            <secondary>fs mkmount</secondary>
          </indexterm>

          <indexterm>
            <primary>fs commands</primary>

            <secondary>mkmount</secondary>

            <tertiary>for read/write volume</tertiary>
          </indexterm>
        </listitem>

        <listitem id="LIWQ189">
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount
          the volume in the filespace. For complete syntax, see <link linkend="HDRWQ212">To create a regular or read/write mount
          point</link>. <programlisting>
   % <emphasis role="bold">fs mkmount</emphasis> &lt;<emphasis>directory</emphasis>&gt; &lt;<emphasis>volume name</emphasis>&gt;</programlisting></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs lsmount</emphasis> command to verify
          that the mount point refers to the correct volume. Complete instructions appear in <link linkend="HDRWQ211">To display a
          mount point</link>. <programlisting>
   % <emphasis role="bold">fs lsmount</emphasis> &lt;<emphasis>directory</emphasis>&gt;</programlisting></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs setvol</emphasis> command with the
          <emphasis role="bold">-offlinemsg</emphasis> argument to record auxiliary information about the volume in its volume
          header. For example, you can record who owns the volume or where you have mounted it in the filespace. To display the
          information, use the <emphasis role="bold">fs examine</emphasis> command. <programlisting>
   % <emphasis role="bold">fs setvol</emphasis> &lt;<replaceable>dir/file path</replaceable>&gt; <emphasis role="bold">-offlinemsg </emphasis> &lt;<replaceable>offline message</replaceable>&gt;
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">sv</emphasis></term>

                <listitem>
                  <para>Is an acceptable alias for <emphasis role="bold">setvol</emphasis>(and <emphasis role="bold">setv</emphasis>
                  the shortest acceptable abbreviation).</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">dir/file path</emphasis></term>

                <listitem>
                  <para>Names the mount point of the volume with which to associate the message. Partial pathnames are interpreted
                  relative to the current working directory.</para>

                  <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to change
                  a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at
                  the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For further discussion
                  of the concept of read/write and read-only paths through the filespace, see <link linkend="HDRWQ209">The Rules of
                  Mount Point Traversal</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-offlinemsg</emphasis></term>

                <listitem>
                  <para>Specifies up to 128 characters of auxiliary information to record in the volume header.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ190">
    <title>About Clones and Cloning</title>

    <indexterm>
      <primary>cloning</primary>

      <secondary>defined</secondary>
    </indexterm>

    <indexterm>
      <primary>clone</primary>
    </indexterm>

    <indexterm>
      <primary>vnode index</primary>
    </indexterm>

    <indexterm>
      <primary>backup volume</primary>

      <secondary>space-saving nature of</secondary>
    </indexterm>

    <para>To create a backup or read-only volume, the Volume Server begins by <emphasis>cloning</emphasis> the read/write source
    volume to create a <emphasis>clone</emphasis>. The Volume Server creates the clone automatically when you issue the <emphasis
    role="bold">vos backup</emphasis> or <emphasis role="bold">vos backupsys</emphasis> command (for a backup volume) or the
    <emphasis role="bold">vos release</emphasis> command (for a read-only volume). No special action is required on your
    part.</para>

    <para>A clone is not a copy of the data in the read/write source volume, but rather a copy of the read/write volume's
    <emphasis>vnode index</emphasis>. The vnode index is a table of pointers between the files and directories in the volume and the
    physical disk blocks on the partition where the data resides. From the clone, backup and read-only volumes are created in the
    following manner: <itemizedlist>
        <listitem>
          <para>A read-only volume that occupies the same partition as its read/write source (also known as a <emphasis>read-only
          clone</emphasis>), and a backup volume, are created by attaching a volume header to the clone. These volumes initially
          consume very little disk space, because the clone portion (the vnode index) points to exactly the same files as the
          read/write volume, as illustrated in <link linkend="FIGWQ191">Figure 1</link>. The file sharing is possible only because
          the clone is on the same partition as the read/write source volume. When a file in the read/write volume is deleted, it is
          not actually removed from the partition, because the backup or read-only clone still points to it. Similarly, when a file
          in the read/write is changed, the entire original file is preserved on disk because the clone still points to it, and the
          read/write volume's vnode index changes to point to newly space for the changed file. When this happens, the backup or
          read-only volume is said to grow or start occupying actual disk space.</para>
        </listitem>

        <listitem>
          <para>A read-only volume that does not occupy the same site as the read/write source is a copy of the clone and of all of
          the data in the read/write source volume. It occupies the same amount of disk space as the read/write volume did at the
          time the read-only volume was created.</para>
        </listitem>
      </itemizedlist></para>

    <figure id="FIGWQ191" label="1">
      <title>File Sharing Between the Read/write Source and a Clone Volume</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="vnode.png" scale="50" />
        </imageobject>
      </mediaobject>
    </figure>

    <indexterm>
      <primary>replication</primary>

      <secondary>detailed discussion</secondary>
    </indexterm>

    <indexterm>
      <primary>volume</primary>

      <secondary>replicating</secondary>
    </indexterm>

    <indexterm>
      <primary>volume</primary>

      <secondary>read-only</secondary>

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

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

      <secondary>creating</secondary>
    </indexterm>

    <indexterm>
      <primary>creating</primary>

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

    <indexterm>
      <primary>cloning</primary>

      <secondary>for replication</secondary>
    </indexterm>

    <indexterm>
      <primary>read/write volume</primary>

      <secondary>cloning</secondary>

      <tertiary>for replication</tertiary>
    </indexterm>
  </sect1>

  <sect1 id="HDRWQ192">
    <title>Replicating Volumes (Creating Read-only Volumes)</title>

    <para><emphasis>Replication</emphasis> refers to creating a read-only copy of a read/write volume and distributing the copy to
    one or more additional file server machines. Replication makes a volume's contents accessible on more than one file server
    machine, which increases data availability. It can also increase system efficiency by reducing load on the network and File
    Server. Network load is reduced if a client machine's server preference ranks lead the Cache Manager to access the copy of a
    volume stored on the closest file server machine. Load on the File Server is reduced because it issues only one callback for all
    data fetched from a read-only volume, as opposed to a callback for each file fetched from a read/write volume. The single
    callback is sufficient for an entire read-only volume because the volume does not change except in response to administrator
    action, whereas each read/write file can change at any time.</para>

    <indexterm>
      <primary>stages in volume replication</primary>
    </indexterm>

    <indexterm>
      <primary>site definition stage in replication</primary>
    </indexterm>

    <indexterm>
      <primary>replication</primary>

      <secondary>site definition stage</secondary>
    </indexterm>

    <indexterm>
      <primary>release stage in replication</primary>
    </indexterm>

    <indexterm>
      <primary>replication</primary>

      <secondary>release stage</secondary>
    </indexterm>

    <para>Replicating a volume requires issuing two commands. First, use the <emphasis role="bold">vos addsite</emphasis> command to
    add one or more read-only site definitions to the volume's VLDB entry (a <emphasis>site</emphasis> is a particular partition on
    a file server machine). Then use the <emphasis role="bold">vos release</emphasis> command to clone the read/write source volume
    and distribute the clone to the defined read-only sites. You issue the <emphasis role="bold">vos addsite</emphasis> only once
    for each read-only site, but must reissue the <emphasis role="bold">vos release</emphasis> command every time the read/write
    volume's contents change and you want to update the read-only volumes.</para>

    <para>For users to have a consistent view of the file system, the release of updated volume contents to read-only sites must be
    atomic: either all read-only sites receive the new version of the volume, or all sites keep the version they currently have. The
    <emphasis role="bold">vos release</emphasis> command is designed to ensure that all copies of the volume's read-only version
    match both the read/write source and each other. In cases where problems such as machine or server process outages prevent
    successful completion of the release operation, AFS uses two mechanisms to alert you.</para>

    <indexterm>
      <primary>replication</primary>

      <secondary>determining success of</secondary>
    </indexterm>

    <indexterm>
      <primary>determining</primary>

      <secondary>success of replication</secondary>
    </indexterm>

    <indexterm>
      <primary>replication</primary>

      <secondary>need for all-or-nothing release</secondary>
    </indexterm>

    <indexterm>
      <primary>all-or-nothing release of read-only volumes</primary>
    </indexterm>

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

      <secondary>need for atomic release</secondary>
    </indexterm>

    <indexterm>
      <primary>releasing</primary>

      <secondary>read-only volume, need for atomicity</secondary>
    </indexterm>

    <indexterm>
      <primary>ReleaseClone</primary>
    </indexterm>

    <indexterm>
      <primary>replication</primary>

      <secondary>role of ReleaseClone</secondary>
    </indexterm>

    <indexterm>
      <primary>New release site flag in VLDB</primary>

      <secondary>as indicator of failed replication</secondary>
    </indexterm>

    <indexterm>
      <primary>Old release site flag in VLDB</primary>

      <secondary>as indicator of failed replication</secondary>
    </indexterm>

    <indexterm>
      <primary>clone</primary>

      <secondary>forcing creation of new</secondary>
    </indexterm>

    <indexterm>
      <primary>replication</primary>

      <secondary>forcing creation of new clone</secondary>
    </indexterm>

    <indexterm>
      <primary>vos commands</primary>

      <secondary>release</secondary>

      <tertiary>forcing new cloning with -f flag</tertiary>
    </indexterm>

    <indexterm>
      <primary>releasing</primary>

      <secondary>read-only volume, forcing new cloning</secondary>
    </indexterm>

    <para>First, the command interpreter generates an error message on the standard error stream naming each read-only site that did
    not receive the new volume version. Second, during the release operation the Volume Location (VL) Server marks site definitions
    in the VLDB entry with flags (<computeroutput>New release</computeroutput> and <computeroutput>Old release</computeroutput>)
    that indicate whether or not the site has the new volume version. If any flags remain after the operation completes, it was not
    successful. The Cache Manager refuses to access a read-only site marked with the <computeroutput>Old release</computeroutput>
    flag, which potentially imposes a greater load on the sites marked with the <computeroutput>New release</computeroutput> flag.
    It is important to investigate and eliminate the cause of the failure and then to issue the <emphasis role="bold">vos
    release</emphasis> command as many times as necessary to complete the release without errors.</para>

    <para>The pattern of site flags remaining in the volume's VLDB entry after a failed release operation can help determine the
    point at which the operation failed. Use the <emphasis role="bold">vos examine</emphasis> or <emphasis role="bold">vos
    listvldb</emphasis> command to display the VLDB entry. The VL Server sets the flags in concert with the Volume Server's
    operations, as follows: <orderedlist>
        <listitem>
          <para>Before the operation begins, the VL Server sets the <computeroutput>New release</computeroutput> flag on the
          read/write site definition in the VLDB entry and the <computeroutput>Old release</computeroutput> flag on read-only site
          definitions (unless the read-only site has been defined since the last release operation and has no actual volume, in
          which case its site flag remains <computeroutput>Not released</computeroutput>).</para>
        </listitem>

        <listitem>
          <para>If necessary, the Volume Server creates a temporary copy (a <emphasis>clone</emphasis>) of the read/write source
          called the ReleaseClone (see the following discussion of when the Volume Server does or does not create a new
          ReleaseClone.) It assigns the ReleaseClone its own volume ID number, which the VL Server records in the
          <computeroutput>RClone</computeroutput> field of the source volume's VLDB entry.</para>
        </listitem>

        <listitem>
          <para>The Volume Server distributes a copy of the ReleaseClone to each read-only site defined in the VLDB entry. As the
          site successfully receives the new clone, the VL Server sets the site's flag in the VLDB entry to <computeroutput>New
          release</computeroutput>.</para>
        </listitem>

        <listitem>
          <para>When all the read-only copies are successfully released, the VL Server clears all the <computeroutput>New
          release</computeroutput> site flags. The ReleaseClone is no longer needed, so the Volume Server deletes it and the VL
          Server erases its ID from the VLDB entry.</para>
        </listitem>
      </orderedlist></para>

    <para>By default, the Volume Server determines automatically whether or not it needs to create a new ReleaseClone: <itemizedlist>
        <listitem>
          <para>If there are no flags (<computeroutput>New release</computeroutput>, <computeroutput>Old release</computeroutput>,
          or <computeroutput>Not released</computeroutput>) on site definitions in the VLDB entry, the previous <emphasis
          role="bold">vos release</emphasis> command completed successfully and all read-only sites currently have the same volume.
          The Volume Server infers that the current <emphasis role="bold">vos release</emphasis> command was issued because the
          read/write volume has changed. The Volume Server creates a new ReleaseClone and distributes it to all of the read-only
          sites.</para>
        </listitem>

        <listitem>
          <para>If any site definition in the VLDB entry is marked with a flag, either the previous release operation did not
          complete successfully or a new read-only site was defined since the last release. The Volume Server does not create a new
          ReleaseClone, instead distributing the existing ReleaseClone to sites marked with the <computeroutput>Old
          release</computeroutput> or <computeroutput>Not released</computeroutput> flag. As previously noted, the VL Server marks
          each VLDB site definition with the <computeroutput>New release</computeroutput> flag as the site receives the
          ReleaseClone, and clears all flags after all sites successfully receive it.</para>
        </listitem>
      </itemizedlist></para>

    <para>To override the default behavior, forcing the Volume Server to create and release a new ReleaseClone to the read-only
    sites, include the <emphasis role="bold">-f</emphasis> flag. This is appropriate if, for example, the data at the read/write
    site has changed since the existing ReleaseClone was created during the previous release operation.</para>

    <sect2 id="HDRWQ193">
      <title>Using Read-only Volumes Effectively</title>

      <indexterm>
        <primary>criteria for replicating volumes</primary>
      </indexterm>

      <indexterm>
        <primary>replication</primary>

        <secondary>suitable types of volumes</secondary>
      </indexterm>

      <indexterm>
        <primary>suitability of volumes for replication</primary>
      </indexterm>

      <indexterm>
        <primary>read/write volume</primary>

        <secondary>types suitable for replication</secondary>
      </indexterm>

      <para>For maximum effectiveness, replicate only volumes that satisfy two criteria: <itemizedlist>
          <listitem>
            <para>The volume's contents are heavily used. Examples include a volume housing binary files for text editors or other
            popular application programs, and volumes mounted along heavily traversed directory paths such as the paths leading to
            user home directories. It is an inefficient use of disk space to replicate volumes for which the demand is low enough
            that a single File Server can easily service all requests.</para>
          </listitem>

          <listitem>
            <para>The volume's contents change infrequently. As noted, file system consistency demands that the contents of
            read-only volumes must match each other and their read/write source at all times. Each time the read/write volume
            changes, you must issue the <emphasis role="bold">vos release</emphasis> command to update the read-only volumes. This
            can become tedious (and easy to forget) if the read/write volume changes frequently.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>mounting</primary>

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

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

        <secondary>mounting</secondary>
      </indexterm>

      <para>Explicitly mounting a read-only volume (creating a mount point that names a volume with a <emphasis
      role="bold">.readonly</emphasis> extension) is not generally necessary or appropriate. The Cache Manager has a built-in bias
      to access the read-only version of a replicated volume whenever possible. As described in more detail in <link
      linkend="HDRWQ209">The Rules of Mount Point Traversal</link>, when the Cache Manager encounters a mount point it reads the
      volume name inside it and contacts the VL Server for a list of the sites that house the volume. In the normal case, if the
      mount point resides in a read-only volume and names a read/write volume (one that does not have a <emphasis
      role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension), the Cache Manager always attempts to
      access a read-only copy of the volume. Thus there is normally no reason to force the Cache Manager to access a read-only
      volume by mounting it explicitly.</para>

      <para>It is a good practice to place a read-only volume at the read/write site, for a couple of reasons. First, the read-only
      volume at the read/write site requires only a small amount of disk space, because it is a clone rather a copy of all of the
      data (see <link linkend="HDRWQ190">About Clones and Cloning</link>). Only if a large number of files are removed or changed in
      the read/write volume does the read-only copy occupy much disk space. That normally does not happen because the appropriate
      response to changes in a replicated read/write volume is to reclone it. The other reason to place a read-only volume at the
      read/write site is that the Cache Manager does not attempt to access the read/write version of a replicated volume if all
      read-only copies become inaccessible. If the file server machine housing the read/write volume is the only accessible machine,
      the Cache Manager can access the data only if there is a read-only copy at the read/write site.</para>

      <para>The number of read-only sites to define depends on several factors. Perhaps the main trade-off is between the level of
      demand for the volume's contents and how much disk space you are willing to use for multiple copies of the volume. Of course,
      each prospective read-only site must have enough available space to accommodate the volume. The limit on the number of
      read-only copies of a volume is determined by the maximum number of site definitions in a volume's VLDB entry, which is
      defined in the <emphasis> OpenAFS Release Notes</emphasis>. The site housing the read/write and backup versions of the volume
      counts as one site, and each read-only site counts as an additional site (even the read-only site defined on the same file
      server machine and partition as the read/write site counts as a separate site). Note also that the Volume Server permits only
      one read-only copy of a volume per file server machine.</para>
    </sect2>

    <sect2 id="Header_216">
      <title>Replication Scenarios</title>

      <indexterm>
        <primary>variations possible</primary>

        <secondary>in replication</secondary>
      </indexterm>

      <indexterm>
        <primary>replication</primary>

        <secondary>variations possible in</secondary>
      </indexterm>

      <indexterm>
        <primary>possible variations</primary>

        <secondary>on replication</secondary>
      </indexterm>

      <para>The instructions in the following section explain how to replicate a volume for which no read-only sites are currently
      defined. However, you can also use the instructions in other common situations: <itemizedlist>
          <listitem>
            <para>If you are releasing a new clone to sites that already exist, you can skip Step <link linkend="LIWQ196">2</link>.
            It can still be useful to issue the <emphasis role="bold">vos examine</emphasis> command, however, to verify that the
            desired read-only sites are defined.</para>
          </listitem>

          <listitem>
            <para>If you are adding new read-only sites to existing ones, perform all of the steps. In Step <link
            linkend="LIWQ197">3</link>, issue the <emphasis role="bold">vos addsite</emphasis> command for the new sites
            only.</para>
          </listitem>

          <listitem>
            <para>If you are defining sites but do not want to release a clone to them yet, stop after Step <link
            linkend="LIWQ197">3</link>and continue when you are ready.</para>
          </listitem>

          <listitem>
            <para>If you are removing one or more sites before releasing a new clone to the remaining sites, follow the instructions
            for site removal in <link linkend="HDRWQ235">Removing Volumes and their Mount Points</link>and then start with Step
            <link linkend="LIWQ198">4</link>.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ194">
      <title>To replicate a read/write volume (create a read-only volume)</title>

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

        <secondary>creating</secondary>

        <tertiary>instructions</tertiary>
      </indexterm>

      <indexterm>
        <primary>read/write volume</primary>

        <secondary>replication instructions</secondary>
      </indexterm>

      <orderedlist>
        <listitem id="LIWQ195">
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem id="LIWQ196">
          <para>Select one or more sites at which to replicate the volume. There are several factors to
          consider: <itemizedlist>
              <listitem>
                <para>How many sites are already defined. As previously noted, it is usually appropriate to define a read-only site
                at the read/write site. Also, the Volume Server permits only one read-only copy of a volume per file server machine.
                To display the volume's current sites, issue the <emphasis role="bold">vos examine</emphasis> command, which is
                described fully in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.
                <programlisting>
   % <emphasis role="bold">vos examine</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
</programlisting></para>

                <para>The final lines of output display the volume's site definitions from the VLDB.</para>
              </listitem>

              <listitem>
                <para>Whether your cell dedicates any file server machines to housing read-only volumes only. In general, only very
                large cells use read-only server machines.</para>
              </listitem>

              <listitem>
                <para>Whether a site has enough free space to accommodate the volume. A read-only volume requires the same amount of
                space as the read/write version (unless it is at the read/write site itself). The first line of output from the
                <emphasis role="bold">vos examine</emphasis> command displays the read/write volume's current size in kilobyte
                blocks, as shown in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.</para>

                <para>To display the amount of space available on a file server machine's partitions, use the <emphasis
                role="bold">vos partinfo</emphasis> command, which is described fully in <link linkend="HDRWQ185">Creating
                Read/write Volumes</link>.</para>

                <programlisting>
   % <emphasis role="bold">vos partinfo</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>partition name</replaceable>&gt;]
</programlisting>
              </listitem>
            </itemizedlist></para>

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

            <secondary>defining site for in VLDB</secondary>
          </indexterm>

          <indexterm>
            <primary>defining</primary>

            <secondary>read-only site in VLDB</secondary>
          </indexterm>

          <indexterm>
            <primary>adding</primary>

            <secondary>read-only site definition in VLDB</secondary>
          </indexterm>

          <indexterm>
            <primary>VLDB</primary>

            <secondary>defining read-only site in</secondary>
          </indexterm>

          <indexterm>
            <primary>commands</primary>

            <secondary>vos addsite</secondary>
          </indexterm>

          <indexterm>
            <primary>vos commands</primary>

            <secondary>addsite</secondary>
          </indexterm>
        </listitem>

        <listitem id="LIWQ197">
          <para>Issue the <emphasis role="bold">vos addsite</emphasis> command to define each new read-only
          site in the VLDB. <programlisting>
   % <emphasis role="bold">vos addsite</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; &lt;<replaceable>volume name or ID</replaceable>&gt;
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">ad</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">addsite</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Defines the file server machine for the new site.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">partition name</emphasis></term>

                <listitem>
                  <para>Names a disk partition on the machine machine name.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume name or ID</emphasis></term>

                <listitem>
                  <para>Identifies the read/write volume to be replicated, either by its complete name or its volume ID
                  number.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem id="LIWQ198">
          <para><emphasis role="bold">(Optional)</emphasis> Verify that the <emphasis
          role="bold">fs</emphasis> process (which incorporates the Volume Server) is functioning normally on each file server
          machine where you have defined a read-only site, and that the <emphasis role="bold">vlserver</emphasis> process (the
          Volume Location Server) is functioning correctly on each database server machine. Knowing that they are functioning
          eliminates two possible sources of failure for the release. Issue the <emphasis role="bold">bos status</emphasis> command
          on each file server machine housing a read-only site for this volume and on each database server machine. The command is
          described fully in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>.
          <programlisting>
   % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs vlserver</emphasis>
</programlisting></para>

          <indexterm>
            <primary>releasing</primary>

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

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

            <secondary>releasing</secondary>
          </indexterm>

          <indexterm>
            <primary>commands</primary>

            <secondary>vos release</secondary>

            <tertiary>basic instructions</tertiary>
          </indexterm>

          <indexterm>
            <primary>vos commands</primary>

            <secondary>release</secondary>

            <tertiary>basic instructions</tertiary>
          </indexterm>
        </listitem>

        <listitem id="LIWQ199">
          <para>Issue the <emphasis role="bold">vos release</emphasis> command to clone the read/write source
          volume and distribute the clone to each read-only site. <programlisting>
   % <emphasis role="bold">vos release</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt; [<emphasis role="bold">-f</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">rel</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">release</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume name or ID</emphasis></term>

                <listitem>
                  <para>Identifies the read/write volume to clone, either by its complete name or volume ID number. The read-only
                  version is given the same name with a <emphasis role="bold">.readonly</emphasis> extension. All read-only copies
                  share the same read-only volume ID number.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-f</emphasis></term>

                <listitem>
                  <para>Creates and releases a brand new clone.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem id="LIWQ200">
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">vos examine</emphasis> command to verify
          that no site definition in the VLDB entry is marked with an <computeroutput>Old release</computeroutput> or
          <computeroutput>New release</computeroutput> flag. The command is described fully in <link linkend="HDRWQ221">Displaying
          One Volume's VLDB Entry and Volume Header</link>. <programlisting>
   % <emphasis role="bold">vos examine</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
</programlisting></para>
        </listitem>
      </orderedlist>

      <para>If any flags appear in the output from Step <link linkend="LIWQ200">6</link>, repeat Steps <link
      linkend="LIWQ198">4</link>and <link linkend="LIWQ199">5</link>until the Volume Server does not produce any error messages
      during the release operation and the flags no longer appear. Do not issue the <emphasis role="bold">vos release</emphasis>
      command when you know that the read/write site or any read-only site is inaccessible due to network, machine or server process
      outage.</para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ201">
    <title>Creating Backup Volumes</title>

    <indexterm>
      <primary>read/write volume</primary>

      <secondary>cloning</secondary>

      <tertiary>for backup version</tertiary>
    </indexterm>

    <indexterm>
      <primary>cloning</primary>

      <secondary>for backup</secondary>
    </indexterm>

    <indexterm>
      <primary>creating</primary>

      <secondary>backup volume</secondary>
    </indexterm>

    <indexterm>
      <primary>volume</primary>

      <secondary>backup</secondary>

      <see>backup volume</see>
    </indexterm>

    <indexterm>
      <primary>backup volume</primary>

      <secondary>creating</secondary>
    </indexterm>

    <para>A <emphasis>backup volume</emphasis> is a clone that resides at the same site as its read/write source (to review the
    concept of cloning, see <link linkend="HDRWQ190">About Clones and Cloning</link>). Creating a backup version of a volume has two
    purposes: <itemizedlist>
        <listitem>
          <para>It is by convention the first step when dumping a volume's contents to tape with the AFS Backup System. A volume is
          inaccessible while it is being dumped, so instead of dumping the read/write volume, you create and dump a backup version.
          Users do not normally access the backup version, so it is unlikely that the dump will disturb them. For more details, see
          <link linkend="HDRWQ296">Backing Up Data</link>.</para>
        </listitem>

        <listitem>
          <para>It enables users to restore mistakenly deleted or changed data themselves, freeing you for more crucial tasks. The
          backup version captures the state of its read/write source at the time the backup is made, and its contents cannot change.
          Mount the backup version in the filespace so that users can restore a file to its state at the time you made the backup.
          See <link linkend="HDRWQ204">Making the Contents of Backup Volumes Available to Users</link>.</para>
        </listitem>
      </itemizedlist></para>

    <indexterm>
      <primary>creating</primary>

      <secondary>multiple backup volumes at once</secondary>
    </indexterm>

    <indexterm>
      <primary>volume</primary>

      <secondary>creating backup version of many at once</secondary>
    </indexterm>

    <indexterm>
      <primary>backup volume</primary>

      <secondary>creating multiple at once</secondary>
    </indexterm>

    <sect2 id="HDRWQ202">
      <title>Backing Up Multiple Volumes at Once</title>

      <para>The <emphasis role="bold">vos backupsys</emphasis> command creates a backup version of many read/write volumes at once.
      This command is useful when preparing for large-scale backups to tape using the AFS Backup System.</para>

      <para>To clone every read/write volume listed in the VLDB, omit all of the command's options. Otherwise, combine the command's
      options to clone various groups of volumes. The options use one of two basic criteria to select volumes: location (the
      <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments) or presence in the volume
      name of one of a set of specified character strings (the <emphasis role="bold">-prefix</emphasis>, <emphasis
      role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options).</para>

      <para>To clone only volumes that reside on one file server machine, include the <emphasis role="bold">-server</emphasis>
      argument. To clone only volumes that reside on one partition, combine the <emphasis role="bold">-server</emphasis> and
      <emphasis role="bold">-partition</emphasis> arguments. The <emphasis role="bold">-partition</emphasis> argument can also be
      used alone to clone volumes that reside on the indicated partition on every file server machine. These arguments can be
      combined with those that select volumes based on their names.</para>

      <para>Combine the <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-exclude</emphasis>, and <emphasis
      role="bold">-xprefix</emphasis> options (with or without the <emphasis role="bold">-server</emphasis> and <emphasis
      role="bold">-partition</emphasis> arguments) in the indicated ways to select volumes based on character strings contained in
      their names: <itemizedlist>
          <listitem>
            <para>To clone every read/write volume at the specified location whose name includes one of a set of specified character
            strings (for example, begins with <emphasis role="bold">user.</emphasis> or includes the string <emphasis
            role="bold">afs</emphasis>), use the <emphasis role="bold">-prefix</emphasis> argument or combine the <emphasis
            role="bold">-xprefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options.</para>
          </listitem>

          <listitem>
            <para>To clone every read/write volume at the specified location except those whose name includes one of a set of
            specified character strings, use the <emphasis role="bold">-xprefix</emphasis> argument or combine the <emphasis
            role="bold">-prefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options.</para>
          </listitem>

          <listitem>
            <para>To clone every read/write volume at the specified location whose name includes one of one of a set of specified
            character strings, except those whose names include one of a different set of specified character strings, combine the
            <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments. The command creates a
            list of all volumes that match the <emphasis role="bold">-prefix</emphasis> argument and then removes from the list the
            volumes that match the <emphasis role="bold">-xprefix</emphasis> argument. For effective results, the strings specified
            by the <emphasis role="bold">-xprefix</emphasis> argument must designate a subset of the volumes specified by the
            <emphasis role="bold">-prefix</emphasis> argument.</para>

            <para>If the <emphasis role="bold">-exclude</emphasis> flag is combined with the <emphasis
            role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments, the command creates a list of
            all volumes that do not match the <emphasis role="bold">-prefix</emphasis> argument and then adds to the list any
            volumes that match the <emphasis role="bold">-xprefix</emphasis> argument. As when the <emphasis
            role="bold">-exclude</emphasis> flag is not used, the result is effective only if the strings specified by the <emphasis
            role="bold">-xprefix</emphasis> argument designate a subset of the volumes specified by the <emphasis
            role="bold">-prefix</emphasis> argument.</para>
          </listitem>
        </itemizedlist></para>

      <para>The <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments both accept
      multiple values, which can be used to define disjoint groups of volumes. Each value can be one of two types: <orderedlist>
          <listitem>
            <para>A simple character string, which matches volumes whose name begin with the string. All characters are interpreted
            literally (that is, characters that potentially have special meaning to the command shell, such as the period, have only
            their literal meaning).</para>
          </listitem>

          <listitem>
            <para>A regular expression, which matches volumes whose names contain the expressions. Place a caret ( <emphasis
            role="bold">^</emphasis>) at the beginning of the expression, and enclose the entire string in single quotes ( <emphasis
            role="bold">'</emphasis> <emphasis role="bold">'</emphasis>). Explaining regular expressions is outside the scope of
            this reference page; see the UNIX manual page for <emphasis role="bold">regexp(5)</emphasis> or (for a brief
            introduction) <link linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</link>. As an example, the
            following expression matches volumes that have the string <emphasis role="bold">aix</emphasis> anywhere in their names:
            <programlisting>
  <emphasis role="bold">-prefix '^.*aix'</emphasis>
          </programlisting></para>
          </listitem>
        </orderedlist></para>

      <para>To display a list of the volumes to be cloned, without actually cloning them, include the <emphasis
      role="bold">-dryrun</emphasis> flag. To display a statement that summarizes the criteria being used to select volume, include
      the <emphasis role="bold">-verbose</emphasis> flag.</para>

      <para>To back up a single volume, use the <emphasis role="bold">vos backup</emphasis> command, which employs a more
      streamlined technique for finding a single volume.</para>

      <indexterm>
        <primary>automating</primary>

        <secondary>creation of backup volumes</secondary>
      </indexterm>

      <indexterm>
        <primary>backup volume</primary>

        <secondary>automating creation of</secondary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>automating creation of backup version</secondary>
      </indexterm>

      <indexterm>
        <primary>backup volume</primary>

        <secondary>suggested schedule for creation of</secondary>
      </indexterm>

      <indexterm>
        <primary>scheduling</primary>

        <secondary>creation of backup volumes</secondary>
      </indexterm>

      <indexterm>
        <primary>cron-type server process</primary>

        <secondary>used to automate volume backup</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ203">
      <title>Automating Creation of Backup Volumes</title>

      <para>Most cells find that it is best to make a new backup version of relevant volumes each day. It is best to create the
      backup versions at a time when usage is low, because the backup operation causes the read/write volume to be unavailable
      momentarily.</para>

      <para>You can either issue the necessary the <emphasis role="bold">vos backupsys</emphasis> or <emphasis role="bold">vos
      backup</emphasis> commands at the console or create a <emphasis role="bold">cron</emphasis> entry in the <emphasis
      role="bold">BosConfig</emphasis> file on a file server machine, which eliminates the need for an administrator to initiate the
      backup operation.</para>

      <para>The following example command creates a <emphasis role="bold">cron</emphasis> process called <emphasis
      role="bold">backupusers</emphasis> in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file on the machine
      <emphasis role="bold">fs3.example.com</emphasis>. The process runs every day at 1:00 a.m. to create a backup version of every
      volume in the cell whose name starts with the string <emphasis role="bold">user</emphasis>. The <emphasis
      role="bold">-localauth</emphasis> flag enables the process to invoke the privileged <emphasis role="bold">vos
      backupsys</emphasis> command while unauthenticated. Note that the <emphasis role="bold">-cmd</emphasis> argument specifies a
      complete pathname for the <emphasis role="bold">vos</emphasis> binary, because the PATH environment variable for the BOS
      Server (running as the local superuser <emphasis role="bold">root</emphasis>) generally does not include the path to AFS
      binaries. <programlisting>
   % <emphasis role="bold">bos create fs3.example.com backupusers cron</emphasis>\ 
  <emphasis role="bold">-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" "1:00"</emphasis>
</programlisting></para>

      <indexterm>
        <primary>mounting</primary>

        <secondary>backup volume</secondary>
      </indexterm>

      <indexterm>
        <primary>backup volume</primary>

        <secondary>mounting</secondary>
      </indexterm>

      <indexterm>
        <primary>OldFiles directory</primary>

        <secondary>as mount point for backup volume</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ204">
      <title>Making the Contents of Backup Volumes Available to Users</title>

      <para>As noted, a backup volume preserves the state of the read/write source at the time the backup is created. Many cells
      choose to mount backup volumes so that users can access and restore data they have accidentally deleted or changed since the
      last backup was made, without having to request help from administrators. The most sensible place to mount the backup version
      of a user volume is at a subdirectory of the user's home directory. Suitable names for this directory include <emphasis
      role="bold">OldFiles</emphasis> and <emphasis role="bold">Backup</emphasis>. The subdirectory looks just like the user's own
      home directory as it was at the time the backup was created, with all files and subdirectories in the same relative
      positions.</para>

      <para>If you do create and mount backup volumes for your users, inform users of their existence. The <emphasis> OpenAFS User
      Guide</emphasis> does not mention backup volumes because making them available to users is optional. Explain to users how
      often you make a new backup, so they know what they can recover. Remind them also that the data in their backup volume cannot
      change; however, they can use the standard UNIX <emphasis role="bold">cp</emphasis> command to copy it into their home volume
      and modify it there. Reassure users that the data in their backup volumes does not count against their read/write volume
      quota.</para>
    </sect2>

    <sect2 id="HDRWQ205">
      <title>To create and mount a backup volume</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Verify that you have the <emphasis role="bold">insert</emphasis>( <emphasis role="bold">i</emphasis>) and <emphasis
          role="bold">administer</emphasis>( <emphasis role="bold">a</emphasis>) permissions on the ACL of the directory in which
          you wish to mount the volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully
          described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
   % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
</programlisting></para>

          <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
          role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
          role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
          role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>

          <indexterm>
            <primary>commands</primary>

            <secondary>vos backup</secondary>
          </indexterm>

          <indexterm>
            <primary>vos commands</primary>

            <secondary>backup</secondary>
          </indexterm>
        </listitem>

        <listitem id="LIWQ206">
          <para>Issue the <emphasis role="bold">vos backup</emphasis> command to create a backup version of a
          read/write source volume. The message shown confirms the success of the backup operation. <programlisting>
   % <emphasis role="bold">vos backup</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt; Created backup volume for volume name or ID
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">backup</emphasis></term>

                <listitem>
                  <para>Must be typed in full.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume name or ID</emphasis></term>

                <listitem>
                  <para>Identifies the read/write volume to back up, either by its complete name or volume ID number. The backup
                  volume has the same name with the addition of the <emphasis role="bold">.backup</emphasis> extension. It has its
                  own volume ID number.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>

          <indexterm>
            <primary>commands</primary>

            <secondary>fs mkmount</secondary>

            <tertiary>when mounting backup volume</tertiary>
          </indexterm>

          <indexterm>
            <primary>fs commands</primary>

            <secondary>mkmount</secondary>

            <tertiary>when mounting backup volume</tertiary>
          </indexterm>
        </listitem>

        <listitem id="LIWQ207">
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs
          mkmount</emphasis> to mount the backup volume. While this step is optional, Cache Managers cannot access the volume's
          contents if it is not mounted. <programlisting>
   % <emphasis role="bold">fs mkmount</emphasis> &lt;<replaceable>directory</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; <emphasis
                role="bold">.backup</emphasis>
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">mk</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">mkmount</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">directory</emphasis></term>

                <listitem>
                  <para>Names the mount point to create. Do not create a file or directory of the same name beforehand. Partial
                  pathnames are interpreted relative to the current working directory. For the backup version of a user volume, the
                  conventional location is the user's home directory.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume name</emphasis>.backup</term>

                <listitem>
                  <para>Is the full name of the backup volume.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs lsmount</emphasis> command to verify
          that the mount point refers to the correct volume. Complete instructions appear in <link linkend="HDRWQ211">To display a
          mount point</link>. <programlisting>
   % <emphasis role="bold">fs lsmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
</programlisting></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>commands</primary>

        <secondary>vos backupsys</secondary>
      </indexterm>

      <indexterm>
        <primary>vos commands</primary>

        <secondary>backupsys</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_223">
      <title>To create multiple backup volumes at once</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">vos backupsys</emphasis> command to create a backup version of every read/write
          volume that shares the same prefix or site. The effects of combining the three arguments are described in <link
          linkend="HDRWQ202">Backing Up Multiple Volumes at Once</link>. <programlisting>
   % <emphasis role="bold">vos backupsys</emphasis> [<emphasis role="bold">-prefix</emphasis> &lt;<replaceable>common prefix on volume(s)</replaceable>&gt;+] \ 
        [<emphasis role="bold">-server</emphasis> &lt;<replaceable>machine name</replaceable>&gt;] [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>partition name</replaceable>&gt;] \
        [<emphasis role="bold">-exclude</emphasis>] [<emphasis role="bold">-xprefix</emphasis> &lt;<replaceable>negative prefix on volume(s)</replaceable>&gt;+] \
        [<emphasis role="bold">-dryrun</emphasis>] [<emphasis role="bold">-verbose</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">backups</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">backupsys</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-prefix</emphasis></term>

                <listitem>
                  <para>Specifies one or more simple character strings or regular expressions of any length; a volume whose name
                  includes the string is placed on the list of volumes to be cloned. Include field separators (such as periods) if
                  appropriate. This argument can be combined with any combination of the <emphasis role="bold">-server</emphasis>,
                  <emphasis role="bold">-partition</emphasis>, <emphasis role="bold">-exclude</emphasis>, and <emphasis
                  role="bold">-xprefix</emphasis> options.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-server</emphasis></term>

                <listitem>
                  <para>Specifies the file server machine housing the volumes to backup. Can be combined with any combination of the
                  <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-partition</emphasis>, <emphasis
                  role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-partition</emphasis></term>

                <listitem>
                  <para>Specifies the partition housing the volumes you wish to backup. Can be combined with any combination of the
                  <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-server</emphasis>, <emphasis
                  role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-exclude</emphasis></term>

                <listitem>
                  <para>Indicates that all volumes except those indicated with the <emphasis role="bold">-prefix</emphasis> argument
                  are to be backed up. The <emphasis role="bold">-prefix</emphasis> argument must be provided along with this one.
                  Can also be combined with any combination of the <emphasis role="bold">-prefix</emphasis>, <emphasis
                  role="bold">-server</emphasis>, and <emphasis role="bold">-partition</emphasis> arguments; or with both the
                  <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments, but not with the
                  <emphasis role="bold">-xprefix</emphasis> argument alone.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-xprefix</emphasis></term>

                <listitem>
                  <para>Specifies one or more simple character strings or regular expressions of any length; a volume whose name
                  does not include the string is placed on the list of volumes to be cloned. Can be combined with any combination of
                  the <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-server</emphasis>, and <emphasis
                  role="bold">-partition</emphasis> arguments; in addition, it can be combined with both the <emphasis
                  role="bold">-prefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options, but not with the <emphasis
                  role="bold">-exclude</emphasis> flag alone.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-dryrun</emphasis></term>

                <listitem>
                  <para>Displays on the standard output stream a list of the volumes to be cloned, without actually cloning
                  them.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-verbose</emphasis></term>

                <listitem>
                  <para>Displays on the standard output stream a statement that summarizes the criteria being used to select
                  volumes, if combined with the <emphasis role="bold">-dryrun</emphasis> flag; otherwise, traces the cloning
                  operation for each volume.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ208">
    <title>Mounting Volumes</title>

    <indexterm>
      <primary>mounting</primary>

      <secondary>volume</secondary>

      <tertiary>general instructions</tertiary>
    </indexterm>

    <para>Mount points make the contents of AFS volumes visible and accessible in the AFS filespace, as described in <link
    linkend="HDRWQ183">About Mounting Volumes</link>. This section discusses in more detail how the Cache Manager handles mount
    points as it traverses the filespace. It describes the three types of mount points, their purposes, and how to distinguish
    between them, and provides instructions for creating, removing, and examining mount points.</para>

    <sect2 id="HDRWQ209">
      <title>The Rules of Mount Point Traversal</title>

      <para>The Cache Manager observes three basic rules as it traverses the AFS filespace and encounters mount points:
      <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Rule 1:</emphasis> Access Backup and Read-only Volumes When Specified</para>

            <para>When the Cache Manager encounters a mount point that specifies a volume with either a <emphasis
            role="bold">.readonly</emphasis> or a <emphasis role="bold">.backup</emphasis> extension, it accesses that type of
            volume only. If a mount point does not have either a <emphasis role="bold">.backup</emphasis> or <emphasis
            role="bold">.readonly</emphasis> extension, the Cache Manager uses Rules 2 and 3.</para>

            <para>For example, the Cache Manager never accesses the read/write version of a volume if the mount point names the
            backup version. If the specified version is inaccessible, the Cache Manager reports an error.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Rule 2:</emphasis> Follow the Read-only Path When Possible</para>

            <para>If a mount point resides in a read-only volume and the volume that it references is replicated, the Cache Manager
            attempts to access a read-only copy of the volume; if the referenced volume is not replicated, the Cache Manager
            accesses the read/write copy. The Cache Manager is thus said to prefer a <emphasis>read-only</emphasis> path through the
            filespace, accessing read-only volumes when they are available.</para>

            <para>The Cache Manager starts on the read-only path in the first place because it always accesses a read-only copy of
            the <emphasis role="bold">root.afs</emphasis> volume if it exists; the volume is mounted at the root of a cell's AFS
            filespace (named <emphasis role="bold">/afs</emphasis> by convention). That is, if the <emphasis
            role="bold">root.afs</emphasis> volume is replicated, the Cache Manager attempts to access a read-only copy of it rather
            than the read/write copy. This rule then keeps the Cache Manager on a read-only path as long as each successive volume
            is replicated. The implication is that both the <emphasis role="bold">root.afs</emphasis> and <emphasis
            role="bold">root.cell</emphasis> volumes must be replicated for the Cache Manager to access replicated volumes mounted
            below them in the AFS filespace. The volumes are conventionally mounted at the <emphasis role="bold">/afs</emphasis> and
            <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable> directories, respectively.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Rule 3:</emphasis> Once on a Read/write Path, Stay There</para>

            <para>If a mount point resides in a read/write volume and the volume name does not have a <emphasis
            role="bold">.readonly</emphasis> or a <emphasis role="bold">.backup</emphasis> extension, the Cache Manager attempts to
            access only the a read/write version of the volume. The access attempt fails with an error if the read/write version is
            inaccessible, even if a read-only version is accessible. In this situation the Cache Manager is said to be on a
            <emphasis>read/write path</emphasis> and cannot switch back to the read-only path unless mount point explicitly names a
            volume with a <emphasis role="bold">.readonly</emphasis> extension. (Cellular mount points are an important exception to
            this rule, as explained in the following discussion.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ210">
      <title>The Three Types of Mount Points</title>

      <para>AFS uses three types of mount points, each appropriate for a different purpose because of how the Cache Manager handles
      them. <itemizedlist>
          <listitem>
            <para>When the Cache Manager crosses a <emphasis>regular</emphasis> mount point, it obeys all three of the mount point
            traversal rules previously described.</para>

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

              <secondary></secondary>

              <see>mount point</see>
            </indexterm>

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

              <secondary>regular</secondary>

              <tertiary>described</tertiary>
            </indexterm>

            <para>AFS performs best when the vast majority of mount points in the filespace are regular, because the mount point
            traversal rules promote the most efficient use of both replicated and nonreplicated volumes. Because there are likely to
            be multiple read-only copies of a replicated volume, it makes sense for the Cache Manager to access one of them rather
            than the single read/write version, and the second rule leads it to do so. If a volume is not replicated, the third rule
            means that the Cache Manager still accesses the read/write volume when that is the only type available. In other words,
            a regular mount point does not force the Cache Manager always to access read-only volumes (it is explicitly not a
            "read-only mount point").</para>

            <para>To create a regular mount point, use the <emphasis role="bold">fs mkmount</emphasis> command as described in <link
            linkend="HDRWQ212">To create a regular or read/write mount point</link>.</para>

            <note>
              <para>To enable the Cache Manager to access the read-only version of a replicated volume named by a regular mount
              point, all volumes that are mounted above it in the pathname must also be replicated. That is the only way the Cache
              Manager can stay on a read-only path to the target volume.</para>
            </note>
          </listitem>

          <listitem>
            <para>When the Cache Manager crosses a <emphasis>read/write</emphasis> mount point, it attempts to access only the
            volume version named in the mount point. If the volume name is the base (read/write) form, without a <emphasis
            role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension, the Cache Manager accesses the
            read/write version of the volume, even if it is replicated. In other words, the Cache Manager disregards the second
            mount point traversal rule when crossing a read/write mount point: it switches to the read/write path through the
            filespace.</para>

            <indexterm>
              <primary>read/write mount point</primary>

              <secondary></secondary>

              <see>mount point</see>
            </indexterm>

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

              <secondary>read/write</secondary>

              <tertiary>described</tertiary>
            </indexterm>

            <para>It is conventional to create only one read/write mount point in a cell's filespace, using it to mount the cell's
            <emphasis role="bold">root.cell</emphasis> volume just below the AFS filespace root (by convention, <emphasis
            role="bold">/afs/.</emphasis><replaceable>cellname</replaceable>). As indicated, it is conventional to place a period at
            the start of the read/write mount point's name (for example, <emphasis role="bold">/afs/.example.com</emphasis>). The period
            distinguishes the read/write mount point from the regular mount point for the <emphasis role="bold">root.cell</emphasis>
            volume at the same level. This is the only case in which it is conventional to create two mount points for the same
            volume. A desirable side effect of this naming convention for this read/write mount point is that it does not appear in
            the output of the UNIX <emphasis role="bold">ls</emphasis> command unless the <emphasis role="bold">-a</emphasis> flag
            is included, essentially hiding it from regular users who have no use for it.</para>

            <para>The existence of a single read/write mount point at this point in the filespace provides access to the read/write
            version of every volume when necessary, because it puts the Cache Manager on a read/write path right at the top of the
            filespace. At the same time, the regular mount point for the <emphasis role="bold">root.cell</emphasis> volume puts the
            Cache Manager on a read-only path most of the time.</para>

            <para>Using a read/write mount point for a read-only or backup volume is acceptable, but unnecessary. The first rule of
            mount point traversal already specifies that the Cache Manager accesses them if the volume name in a regular mount point
            has a <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension.</para>

            <para>To create a read/write mount point, use the <emphasis role="bold">-rw</emphasis> flag on the <emphasis
            role="bold">fs mkmount</emphasis> command as described in <link linkend="HDRWQ212">To create a regular or read/write
            mount point</link>.</para>
          </listitem>

          <listitem>
            <para>When the Cache Manager crosses a <emphasis>cellular</emphasis> mount point, it accesses the indicated volume in
            the specified cell, which is normally a foreign cell. (If the mount point does not name a cell along with the volume,
            the Cache Manager accesses the volume in the cell where the mount point resides.) When crossing a regular cellular mount
            point, the Cache Manager disregards the third mount point traversal rule. Instead, it accesses a read-only version of
            the volume if it is replicated, even if the volume that houses the mount point is read/write.</para>

            <para>It is inappropriate to circumvent this behavior by creating a read/write cellular mount point, because traversing
            the read/write path imposes an unfair load on the foreign cell's file server machines. The File Server must issue a
            callback for each file fetched from the read/write volume, rather than single callback required for a read-only volume.
            In any case, only a cell's own administrators generally need to access the read/write versions of replicated
            volumes.</para>

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

              <secondary></secondary>

              <see>mount point</see>
            </indexterm>

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

              <secondary>cellular</secondary>

              <tertiary>described</tertiary>
            </indexterm>

            <indexterm>
              <primary>mounting</primary>

              <secondary>foreign volume in local cell</secondary>
            </indexterm>

            <para>It is conventional to create cellular mount points only at the second level in a cell's filespace, using them to
            mount foreign cells' <emphasis role="bold">root.cell</emphasis> volumes just below the AFS filespace root (by
            convention, at <emphasis role="bold">/afs/</emphasis><replaceable>foreign_cellname</replaceable>). The mount point
            enables local users to access the foreign cell's filespace, assuming they have the necessary permissions on the ACL of
            the volume's root directory and that there is an entry for the foreign cell in each local client machine's <emphasis
            role="bold">/usr/vice/etc/CellServDB</emphasis> file, as described in <link linkend="HDRWQ406">Maintaining Knowledge of
            Database Server Machines</link>.</para>

            <para>Creating cellular mount points at other levels in the filespace and mounting foreign volumes other than the
            <emphasis role="bold">root.cell</emphasis> volume is not generally appropriate. It can be confusing to users if the
            Cache Manager switches between cells at various points in a pathname.</para>

            <para>To create a regular cellular mount point, use the <emphasis role="bold">-cell</emphasis> argument to specify the
            cell name, as described in <link linkend="HDRWQ213">To create a cellular mount point</link>.</para>
          </listitem>
        </itemizedlist></para>

      <para>To examine a mount point, use the <emphasis role="bold">fs lsmount</emphasis> command as described in <link
      linkend="HDRWQ211">To display a mount point</link>. The command's output uses distinct notation to identify regular,
      read/write, and cellular mount points. To remove a mount point, use the <emphasis role="bold">fs rmmount</emphasis> command as
      described in <link linkend="HDRWQ215">To remove a mount point</link>.</para>
    </sect2>

    <sect2 id="Header_227">
      <title>Creating a mount point in a foreign cell</title>

      <para>Creating a mount point in a foreign cell's filespace (as opposed to mounting a foreign volume in the local cell) is
      basically the same as creating a mount point in the local filespace. The differences are that the <emphasis role="bold">fs
      mkmount</emphasis> command's directory argument specifies a pathname in the foreign cell rather than the local cell, and you
      must have the required permissions on the ACL of the foreign directory where you are creating the mount point. The <emphasis
      role="bold">fs mkmount</emphasis> command's <emphasis role="bold">-cell</emphasis> argument always specifies the cell in which
      the volume resides, not the cell in which to create the mount point.</para>
    </sect2>

    <sect2 id="HDRWQ211">
      <title>To display a mount point</title>

      <indexterm>
        <primary>displaying</primary>

        <secondary>mount point</secondary>
      </indexterm>

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

        <secondary>displaying</secondary>
      </indexterm>

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

        <secondary>distinguishing different types</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>fs lsmount</secondary>
      </indexterm>

      <indexterm>
        <primary>fs commands</primary>

        <secondary>lsmount</secondary>
      </indexterm>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">fs lsmount</emphasis> command. <programlisting>
   % <emphasis role="bold">fs lsmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">ls</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">lsmount</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">directory</emphasis></term>

                <listitem>
                  <para>Names the mount point to display.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>If the specified directory is a mount point, the output is of the following form:</para>

      <programlisting>
   'directory' is a mount point for volume 'volume name'
</programlisting>

      <para>For a regular mount point, a number sign (<computeroutput>#</computeroutput>) precedes the volume name string, as in the
      following example command issued on a client machine in the <emphasis role="bold">example.com</emphasis> cell.</para>

      <programlisting>
   % <emphasis role="bold">fs lsmount /afs/example.com/usr/terry</emphasis>
   '/afs/example.com/usr/terry' is a mount point for volume '#user.terry'
</programlisting>

      <para>For a read/write mount point, a percent sign (<computeroutput>%</computeroutput>) precedes the volume name string, as in
      the following example command issued on a client machine in the <emphasis role="bold">example.com</emphasis> cell. The cell's
      administrators have followed the convention of preceding the read/write mount point's name with a period.</para>

      <programlisting>
   % <emphasis role="bold">fs lsmount /afs/.example.com</emphasis>
   '/afs/.example.com' is a mount point for volume '%root.cell'
</programlisting>

      <para>For a cellular mount point, a cell name and colon (<computeroutput>:</computeroutput>) follow the number or percent sign
      and precede the volume name string, as in the following example command issued on a client machine in the <emphasis
      role="bold">example.com</emphasis> cell.</para>

      <programlisting>
   % <emphasis role="bold">fs lsmount /afs/example.org</emphasis>
   '/afs/example.org' is a mount point for volume '#example.org:root.cell'
</programlisting>

      <para>For a symbolic link to a mount point, the output is of the form shown in the following example command issued on a
      client machine in the <emphasis role="bold">example.com</emphasis> cell.</para>

      <programlisting>
   % <emphasis role="bold">fs lsmount /afs/example</emphasis>
   '/afs/example' is a symbolic link, leading to a mount point for volume '#root.cell'
</programlisting>

      <para>If the directory is not a mount point or is not in AFS, the output reads as follows.</para>

      <programlisting>
   'directory' is not a mount point.
</programlisting>

      <para>If the output is garbled, it is possible that the mount point has become corrupted in the local cache. Use the <emphasis
      role="bold">fs flushmount</emphasis> command as described in <link linkend="HDRWQ413">To flush one or more mount
      points</link>. This forces the Cache Manager to refetch the mount point.</para>
    </sect2>

    <sect2 id="HDRWQ212">
      <title>To create a regular or read/write mount point</title>

      <indexterm>
        <primary>creating</primary>

        <secondary>read/write or regular mount point</secondary>
      </indexterm>

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

        <secondary>creating read/write or regular</secondary>
      </indexterm>

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

        <secondary>regular</secondary>

        <tertiary>creating</tertiary>
      </indexterm>

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

        <secondary>read/write</secondary>

        <tertiary>creating</tertiary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>fs mkmount</secondary>

        <tertiary>general instructions</tertiary>
      </indexterm>

      <indexterm>
        <primary>fs commands</primary>

        <secondary>mkmount</secondary>

        <tertiary>general instructions</tertiary>
      </indexterm>

      <orderedlist>
        <listitem>
          <para>Verify that you have the <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) and <emphasis
          role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where you
          are placing the mount point. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully
          described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
   % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to create the mount point. Include the <emphasis
          role="bold">-rw</emphasis> flag if creating a read/write mount point. <programlisting>
   % <emphasis role="bold">fs mkmount</emphasis> &lt;<replaceable>directory</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; [<emphasis
                role="bold">-rw</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">mk</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation for <emphasis role="bold">mkmount</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">directory</emphasis></term>

                <listitem>
                  <para>Names the mount point to create. A file or directory with the same name cannot already exist. A partial
                  pathname is interpreted relative to the current working directory.</para>

                  <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create
                  a new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period
                  before the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>).
                  For further discussion of the concept of read/write and read-only paths through the filespace, see <link
                  linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume name</emphasis></term>

                <listitem>
                  <para>Specifies the volume's full name, including the <emphasis role="bold">.backup</emphasis> or <emphasis
                  role="bold">.readonly</emphasis> extension for a backup or read-only volume, if appropriate.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-rw</emphasis></term>

                <listitem>
                  <para>Creates a read/write mount point.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="HDRWQ213">
      <title>To create a cellular mount point</title>

      <indexterm>
        <primary>creating</primary>

        <secondary>cellular mount point</secondary>
      </indexterm>

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

        <secondary>creating cellular</secondary>
      </indexterm>

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

        <secondary>cellular</secondary>

        <tertiary>creating</tertiary>
      </indexterm>

      <orderedlist>
        <listitem>
          <para>Verify that you have the <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) and <emphasis
          role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where you
          are placing the mount point. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully
          described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
   % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
</programlisting></para>
        </listitem>

        <listitem id="LIWQ214">
          <para>If you are mounting one or more foreign cells' <emphasis role="bold">root.cell</emphasis>
          volume at the second level in your filespace and your cell's <emphasis role="bold">root.afs</emphasis> volume is
          replicated, you must create a temporary mount point for the <emphasis role="bold">root.afs</emphasis> volume's read/write
          version in a directory on which the ACL grants you the <emphasis role="bold">i</emphasis> and <emphasis
          role="bold">a</emphasis> permissions. The following command creates a mount point called <emphasis
          role="bold">new_cells</emphasis> in your cell's <emphasis role="bold">/afs/.</emphasis><replaceable>cellname</replaceable>
          directory (the entry point to the read/write path in your cell).</para>

          <para>Substitute your cell's name for cellname.</para>

          <programlisting>
   % <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable>
   % <emphasis role="bold">fs mkmount new_cells root.afs</emphasis>
   % <emphasis role="bold">cd new_cells</emphasis>
</programlisting>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command with the <emphasis role="bold">-cell</emphasis>
          argument to create a cellular mount point. Repeat the command for each cellular mount point as required. <programlisting>
   % <emphasis role="bold">fs mkmount</emphasis> &lt;<replaceable>directory</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; <emphasis
                role="bold">-cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">mk</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation for <emphasis role="bold">mkmount</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">directory</emphasis></term>

                <listitem>
                  <para>Names the mount point to create. A file or directory with the same name cannot already exist. A partial
                  pathname is interpreted relative to the current working directory. If you are mounting a foreign cell's <emphasis
                  role="bold">root.cell</emphasis> volume, the standard value for this argument is the cell's complete Internet
                  domain name.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume name</emphasis></term>

                <listitem>
                  <para>Specifies the volume's full name, usually <emphasis role="bold">root.cell</emphasis> for a cellular mount
                  point.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-cell</emphasis></term>

                <listitem>
                  <para>Specifies the complete Internet domain name of the cell in which the volume resides.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>If you performed the instructions in Step <link linkend="LIWQ214">2</link>, issue the <emphasis role="bold">vos
          release</emphasis> command to release the new version of the <emphasis role="bold">root.afs</emphasis> volume to its
          read-only sites. (This command requires that you be listed in your cell's <emphasis
          role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, verify by issuing the <emphasis role="bold">bos
          listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the users in the UserList
          file</link>.)</para>

          <para>Also issue the <emphasis role="bold">fs checkvolumes</emphasis> command to force the local Cache Manager to access
          the new replica of the <emphasis role="bold">root.afs</emphasis> volume. If desired, you can also remove the temporary
          <emphasis role="bold">new_cells</emphasis> mount point from the <emphasis
          role="bold">/afs/.</emphasis><replaceable>cellname</replaceable> directory.</para>

          <programlisting>
   % <emphasis role="bold">vos release root.afs</emphasis>
   % <emphasis role="bold">fs checkvolumes</emphasis>
   % <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable>
   % <emphasis role="bold">fs rmmount new_cells</emphasis>
</programlisting>

          <para>For your users to access a newly mounted foreign cell, you must also create an entry for it in each client machine's
          local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file and either reboot the machine or use the <emphasis
          role="bold">fs newcell</emphasis> command to insert the entry directly into its kernel memory. See the instructions in
          <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="HDRWQ215">
      <title>To remove a mount point</title>

      <indexterm>
        <primary>removing</primary>

        <secondary>mount point</secondary>
      </indexterm>

      <indexterm>
        <primary>unmounting</primary>

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

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

        <secondary>removing</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>fs rmmount</secondary>
      </indexterm>

      <indexterm>
        <primary>fs commands</primary>

        <secondary>rmmount</secondary>
      </indexterm>

      <orderedlist>
        <listitem>
          <para>Verify that you have the <emphasis role="bold">d</emphasis>( <emphasis role="bold">delete</emphasis>) permission on
          the ACL of the directory from which you are removing the mount point. If necessary, issue the <emphasis role="bold">fs
          listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
   % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
</programlisting></para>

          <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
          role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
          role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
          role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">fs rmmount</emphasis> command to remove the mount point. The volume still exists,
          but its contents are inaccessible if this is the only mount point for it. <programlisting>
   % <emphasis role="bold">fs rmmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">rm</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">rmmount</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">directory</emphasis></term>

                <listitem>
                  <para>Names the mount point to remove. A partial pathname is interpreted relative to the current working
                  directory.</para>

                  <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete
                  a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before
                  the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For
                  further discussion of the concept of read/write and read-only paths through the filespace, see <link
                  linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2>
      <title>To access volumes directly by volume ID</title>

      <indexterm>
        <primary>volume</primary>

        <secondary>direct access</secondary>
      </indexterm>

      <para>You can directly access volumes by volume IDs. This is only
      recommended for temporary access to a volume. For example, if you
      have recently restored a volume from a backup, you can use this
      syntax to quickly access the volume without mounting it.</para>
      <para>Examples:</para>
      <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Windows:</emphasis>
            \\afs\example.com#root.cell</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Unix:</emphasis>
            /afs/.:mount/example.com#root.cell</para>
          </listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ216">
    <title>Displaying Information About Volumes</title>

    <indexterm>
      <primary>displaying</primary>

      <secondary>volume information</secondary>
    </indexterm>

    <indexterm>
      <primary>volume</primary>

      <secondary>displaying information about</secondary>
    </indexterm>

    <para>This section explains how to display information about volumes. If you know a volume's name or volume ID number, there are
    commands for displaying its VLDB entry, its volume header, or both. Other commands display the name or location of the volume
    that contains a specified file or directory.</para>

    <para>For instructions on displaying a volume's quota, see <link linkend="HDRWQ234">Setting and Displaying Volume Quota and
    Current Size</link>.</para>

    <sect2 id="HDRWQ217">
      <title>Displaying VLDB Entries</title>

      <indexterm>
        <primary>displaying</primary>

        <secondary>volume's VLDB entry</secondary>
      </indexterm>

      <indexterm>
        <primary>VLDB</primary>

        <secondary>displaying volume entry</secondary>
      </indexterm>

      <indexterm>
        <primary>volume entry (VLDB)</primary>

        <secondary>displaying</secondary>
      </indexterm>

      <indexterm>
        <primary>locked VLDB entry</primary>

        <secondary>displaying</secondary>
      </indexterm>

      <para>The <emphasis role="bold">vos listvldb</emphasis> command displays the VLDB entry for the volumes indicated by the
      combination of arguments you provide. The possibilities are listed here from most to least inclusive: <itemizedlist>
          <listitem>
            <para>To display every entry in the VLDB, provide no arguments. It can take a long time to generate the output,
            depending on the number of entries.</para>
          </listitem>

          <listitem>
            <para>To display every VLDB entry that mentions a specific file server machine as the site of a volume, specify the
            machine's name with the <emphasis role="bold">-server</emphasis> argument.</para>
          </listitem>

          <listitem>
            <para>To display every VLDB entry that mentions a certain partition on any file server machine as the site of a volume,
            specify the partition name with the <emphasis role="bold">-partition</emphasis> argument.</para>
          </listitem>

          <listitem>
            <para>To display every VLDB entry that mentions a certain partition on a certain file server machine as the site of a
            volume, combine the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
            arguments.</para>
          </listitem>

          <listitem>
            <para>To display a single VLDB entry, specify a volume name or ID number with the <emphasis role="bold">-name</emphasis>
            argument.</para>
          </listitem>

          <listitem>
            <para>To display the VLDB entry only for volumes with locked VLDB entries, use the <emphasis
            role="bold">-locked</emphasis> flag with any of the site definitions mentioned previously.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>commands</primary>

        <secondary>vos listvldb</secondary>

        <tertiary>syntax</tertiary>
      </indexterm>

      <indexterm>
        <primary>vos commands</primary>

        <secondary>listvldb</secondary>

        <tertiary>syntax</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ218">
      <title>To display VLDB entries</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">vos listvldb</emphasis> command. <programlisting>
   % <emphasis role="bold">vos listvldb</emphasis> [<emphasis role="bold">-name</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;] [<emphasis
                role="bold">-server</emphasis> &lt;<replaceable>machine name</replaceable>&gt;] \
        [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>partition name</replaceable>&gt;] [<emphasis role="bold">-locked</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">listvl</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvldb</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-name</emphasis></term>

                <listitem>
                  <para>Identifies one volume either by its complete name or volume ID number. Do not combine this argument with the
                  <emphasis role="bold">-server</emphasis> or <emphasis role="bold">-partition</emphasis> arguments.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-server</emphasis></term>

                <listitem>
                  <para>Specifies a file server machine. Combine this argument with the <emphasis role="bold">-partition</emphasis>
                  argument if desired, but not with the <emphasis role="bold">-name</emphasis> argument.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-partition</emphasis></term>

                <listitem>
                  <para>Specifies a partition. Combine this argument with the <emphasis role="bold">-server</emphasis> argument if
                  desired, but not with the <emphasis role="bold">-name</emphasis> argument.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-locked</emphasis></term>

                <listitem>
                  <para>Displays only locked VLDB entries. Combine this flag with any of the other options.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>The VLDB entry for each volume includes the following information: <itemizedlist>
          <listitem>
            <para>The base (read/write) volume name. The read-only and backup versions have the same name with a <emphasis
            role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extension, respectively.</para>
          </listitem>

          <listitem>
            <para>The volume ID numbers allocated to the versions of the volume that actually exist, in fields labeled
            <computeroutput>RWrite</computeroutput> for the read/write, <computeroutput>ROnly</computeroutput> for the read-only,
            <computeroutput>Backup</computeroutput> for the backup, and <computeroutput>RClone</computeroutput> for the
            ReleaseClone. (If a field does not appear, the corresponding version of the volume does not exist.) The appearance of
            the <computeroutput>RClone</computeroutput> field normally indicates that a release operation did not complete
            successfully; the <computeroutput>Old release</computeroutput> and <computeroutput>New release</computeroutput> flags
            often also appear on one or more of the site definition lines described just following.</para>

            <indexterm>
              <primary>site</primary>

              <secondary>count in VLDB</secondary>
            </indexterm>

            <indexterm>
              <primary>VLDB</primary>

              <secondary>site count for volume</secondary>
            </indexterm>
          </listitem>

          <listitem>
            <para>The number of sites that house a read/write or read-only copy of the volume, following the string
            <computeroutput>number of sites -&gt;</computeroutput>.</para>

            <indexterm>
              <primary>type flag for volume</primary>

              <secondary>VLDB entry</secondary>
            </indexterm>

            <indexterm>
              <primary>VLDB</primary>

              <secondary>volume type flags</secondary>
            </indexterm>

            <indexterm>
              <primary>release</primary>

              <secondary>status flags on site definitions in VLDB entry</secondary>
            </indexterm>

            <indexterm>
              <primary>VLDB</primary>

              <secondary>release status flags in volume entry</secondary>
            </indexterm>

            <indexterm>
              <primary>status flag</primary>

              <secondary>release, on site definitions in VLDB entry</secondary>
            </indexterm>
          </listitem>

          <listitem>
            <para>A line for each site that houses a read/write or read-only copy of the volume, specifying the file server machine,
            partition, and type of volume (<computeroutput>RW</computeroutput> for read/write or <computeroutput>RO</computeroutput>
            for read-only). If a backup version exists, it is understood to share the read/write site. Several flags can appear with
            a site definition: <variablelist>
                <indexterm>
                  <primary>Not released</primary>

                  <secondary>status flag on site definition in VLDB entry</secondary>
                </indexterm>

                <varlistentry>
                  <term><computeroutput>Not released</computeroutput></term>

                  <listitem>
                    <para>Indicates that the <emphasis role="bold">vos release</emphasis> command has not been issued since the
                    <emphasis role="bold">vos addsite</emphasis> command was used to define the read-only site.</para>

                    <indexterm>
                      <primary>Old release</primary>

                      <secondary>status flag on site definition in VLDB entry</secondary>
                    </indexterm>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><computeroutput>Old release</computeroutput></term>

                  <listitem>
                    <para>Indicates that a <emphasis role="bold">vos release</emphasis> command did not complete successfully,
                    leaving the previous, obsolete version of the volume at this site.</para>

                    <indexterm>
                      <primary>New release</primary>

                      <secondary>status flag on site definition in VLDB entry</secondary>
                    </indexterm>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><computeroutput>New release</computeroutput></term>

                  <listitem>
                    <para>Indicates that a <emphasis role="bold">vos release</emphasis> command did not complete successfully, but
                    that this site did receive the correct new version of the volume.</para>
                  </listitem>
                </varlistentry>
              </variablelist></para>
          </listitem>

          <listitem>
            <para>If the VLDB entry is locked, the string <computeroutput>Volume is currently LOCKED</computeroutput>.</para>
          </listitem>
        </itemizedlist></para>

      <para>For further discussion of the <computeroutput>New release</computeroutput> and <computeroutput>Old
      release</computeroutput> flags, see <link linkend="HDRWQ192">Replicating Volumes (Creating Read-only Volumes)</link>.</para>

      <para>An example of this command and its output for a single volume:</para>

      <programlisting>
   % <emphasis role="bold">vos listvldb user.terry</emphasis>
   user.terry
       RWrite: 50489902    Backup: 50489904
       number of sites -&gt; 1
          server fs3.example.com partition /vicepc RW Site
</programlisting>
    </sect2>

    <sect2 id="HDRWQ219">
      <title>Displaying Volume Headers</title>

      <indexterm>
        <primary>displaying</primary>

        <secondary>volume header</secondary>
      </indexterm>

      <indexterm>
        <primary>volume header</primary>

        <secondary>displaying</secondary>

        <tertiary>only</tertiary>
      </indexterm>

      <para>The <emphasis role="bold">vos listvol</emphasis> command displays the volume header for every volume on one or all
      partitions on a file server machine. The <emphasis role="bold">vos</emphasis> command interpreter obtains the information from
      the Volume Server on the specified machine. You can control the amount of information displayed by including one of the
      <emphasis role="bold">-fast</emphasis>, the <emphasis role="bold">-long</emphasis>, or the <emphasis
      role="bold">-extended</emphasis> flags described following the instructions in <link linkend="HDRWQ220">To display volume
      headers</link>.</para>

      <para>To display a single volume's volume header of one volume only, use the <emphasis role="bold">vos examine</emphasis>
      command as described in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.</para>

      <indexterm>
        <primary>commands</primary>

        <secondary>vos listvol</secondary>

        <tertiary>syntax</tertiary>
      </indexterm>

      <indexterm>
        <primary>vos commands</primary>

        <secondary>listvol</secondary>

        <tertiary>syntax</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ220">
      <title>To display volume headers</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">vos listvol</emphasis> command. <programlisting>
   % <emphasis role="bold">vos listvol</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>partition name</replaceable>&gt;] [<emphasis
                role="bold">-fast</emphasis>] [<emphasis role="bold">-long</emphasis>] [<emphasis role="bold">-extended</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">listvo</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvol</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Names the file server machine for which to display volume headers. Provide this argument alone or with the
                  partition name argument.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">partition name</emphasis></term>

                <listitem>
                  <para>Names one partition on the file server machine named by the machine name argument, which must be provided
                  along with this one.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-fast</emphasis></term>

                <listitem>
                  <para>Displays only the volume ID numbers of relevant volumes. Do not combine this flag with the <emphasis
                  role="bold">-long</emphasis> or <emphasis role="bold">-extended</emphasis> flag.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-long</emphasis></term>

                <listitem>
                  <para>Displays more detailed information about each volume. Do not combine this flag with the <emphasis
                  role="bold">-fast</emphasis> or <emphasis role="bold">-extended</emphasis> flag.</para>