mirror of
https://git.openafs.org/openafs.git
synced 2025-01-18 23:10:58 +00:00
7dbb35a89f
Document that dynamic mount (/afs/.:mount) requires dynroot and fakestat on non-linux unix. Change-Id: I947edd30d510c7cc6840bc2cc74d0ef07b692afb Reviewed-on: http://gerrit.openafs.org/8739 Tested-by: BuildBot <buildbot@rampaginggeek.com> Reviewed-by: Chas Williams - CONTRACTOR <chas@cmf.nrl.navy.mil> Reviewed-by: Derrick Brashear <shadow@your-file-system.com> Reviewed-by: Ken Dreyer <ktdreyer@ktdreyer.com>
6902 lines
311 KiB
XML
6902 lines
311 KiB
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> <<replaceable>machine name</replaceable>>
|
|
</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> [<<emphasis>dir/file path</emphasis>>]</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> <<emphasis>machine name</emphasis>> [<<emphasis>partition name</emphasis>>]</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> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <<replaceable>volume name</replaceable>> \
|
|
[<emphasis role="bold">-maxquota</emphasis> <<replaceable>initial quota (KB)</replaceable>>]
|
|
</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> <<emphasis>directory</emphasis>> <<emphasis>volume name</emphasis>></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> <<emphasis>directory</emphasis>></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> <<replaceable>dir/file path</replaceable>> <emphasis role="bold">-offlinemsg </emphasis> <<replaceable>offline message</replaceable>>
|
|
</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> <<replaceable>machine name</replaceable>>
|
|
</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> <<replaceable>volume name or ID</replaceable>>
|
|
</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> <<replaceable>machine name</replaceable>> [<<replaceable>partition name</replaceable>>]
|
|
</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> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <<replaceable>volume name or ID</replaceable>>
|
|
</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> <<replaceable>machine name</replaceable>> <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> <<replaceable>volume name or ID</replaceable>> [<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> <<replaceable>volume name or ID</replaceable>>
|
|
</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> <<replaceable>machine name</replaceable>>
|
|
</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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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> <<replaceable>volume name or ID</replaceable>> 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> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> <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> <<replaceable>directory</replaceable>>
|
|
</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> <<replaceable>machine name</replaceable>>
|
|
</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> <<replaceable>common prefix on volume(s)</replaceable>>+] \
|
|
[<emphasis role="bold">-server</emphasis> <<replaceable>machine name</replaceable>>] [<emphasis role="bold">-partition</emphasis> <<replaceable>partition name</replaceable>>] \
|
|
[<emphasis role="bold">-exclude</emphasis>] [<emphasis role="bold">-xprefix</emphasis> <<replaceable>negative prefix on volume(s)</replaceable>>+] \
|
|
[<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> <<replaceable>directory</replaceable>>
|
|
</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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> [<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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> <emphasis
|
|
role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>>
|
|
</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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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> <<replaceable>directory</replaceable>>
|
|
</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>This feature is available with Windows and Linux based cache
|
|
managers by default. This feature is available with other Unix based
|
|
cache managers when the dynamic root (-dynroot) and fake stat
|
|
(-fakestat) modes are enabled.</para>
|
|
|
|
<para>Examples:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Windows:</emphasis>
|
|
\\afs\example.com%root.cell - Access a read/write volume directly</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Windows:</emphasis>
|
|
\\afs\example.com#root.cell - Access a read-only volume directly</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Unix:</emphasis>
|
|
/afs/.:mount/example.com:root.cell - Access a read/write volume directly</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Unix:</emphasis>
|
|
/afs/.:mount/example.com:root.cell.readonly - Access a read-only volume directly</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Unix:</emphasis>
|
|
/afs/.:mount/example.com:root.cell.backup - Access a backup volume directly</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> <<replaceable>volume name or ID</replaceable>>] [<emphasis
|
|
role="bold">-server</emphasis> <<replaceable>machine name</replaceable>>] \
|
|
[<emphasis role="bold">-partition</emphasis> <<replaceable>partition name</replaceable>>] [<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 -></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 -> 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> <<replaceable>machine name</replaceable>> [<<replaceable>partition name</replaceable>>] [<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-extended</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Displays all of the information displayed by the <emphasis role="bold">-long</emphasis> flag, plus tables of
|
|
statistics about reads and writes to the files in the volume. Do not combine this flag with the <emphasis
|
|
role="bold">-fast</emphasis> or <emphasis role="bold">-long</emphasis> flag.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>The output is ordered alphabetically by volume name and by default provides the following information on a single line
|
|
for each volume: <itemizedlist>
|
|
<listitem>
|
|
<para>Name</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Volume ID number</para>
|
|
|
|
<indexterm>
|
|
<primary>type flag for volume</primary>
|
|
|
|
<secondary>volume header</secondary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Type (the flag is <computeroutput>RW</computeroutput> for read/write, <computeroutput>RO</computeroutput> for
|
|
read-only, <computeroutput>BK</computeroutput> for backup)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Size in kilobytes (<computeroutput>1024</computeroutput> equals a megabyte)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Number of files in the volume, if the <emphasis role="bold">-extended</emphasis> flag is provided</para>
|
|
|
|
<indexterm>
|
|
<primary>status flags in volume header</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Status on the file server machine, which is one of the following: <variablelist>
|
|
<indexterm>
|
|
<primary>On-line status flag in volume header</primary>
|
|
</indexterm>
|
|
|
|
<varlistentry>
|
|
<term><computeroutput>On-line</computeroutput></term>
|
|
|
|
<listitem>
|
|
<para>The volume is completely accessible to Cache Managers.</para>
|
|
|
|
<indexterm>
|
|
<primary>Off-line status flag in volume header</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><computeroutput>Off-line</computeroutput></term>
|
|
|
|
<listitem>
|
|
<para>The volume is not accessible to Cache Managers, but does not seem to be corrupted. This status appears
|
|
while a volume is being dumped, for example.</para>
|
|
|
|
<indexterm>
|
|
<primary>needs salvage status flag in volume header</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><computeroutput>Off-line**needs salvage**</computeroutput></term>
|
|
|
|
<listitem>
|
|
<para>The volume is not accessible to Cache Managers, because it seems to be corrupted. Use the <emphasis
|
|
role="bold">bos salvage</emphasis> or <emphasis role="bold">salvager</emphasis> command to repair the
|
|
corruption.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>If the following message appears instead of the previously listed information, it indicates that a volume is not
|
|
accessible to Cache Managers or the <emphasis role="bold">vos</emphasis> command interpreter, for example because a clone is
|
|
being created.</para>
|
|
|
|
<programlisting>
|
|
**** Volume volume_ID is busy ****
|
|
</programlisting>
|
|
|
|
<para>If the following message appears instead of the previously listed information, it indicates that the File Server is
|
|
unable to attach the volume, perhaps because it is seriously corrupted. The <emphasis role="bold">FileLog</emphasis> and
|
|
<emphasis role="bold">VolserLog</emphasis> log files in the <emphasis role="bold">/usr/afs/logs</emphasis> directory on the
|
|
file server machine possibly provide additional information; use the <emphasis role="bold">bos getlog</emphasis> command to
|
|
display them.</para>
|
|
|
|
<programlisting>
|
|
**** Could not attach volume volume_ID ****
|
|
</programlisting>
|
|
|
|
<para>(For instructions on salvaging a corrupted or unattached volume, see <link linkend="HDRWQ232">Salvaging
|
|
Volumes</link>.)</para>
|
|
|
|
<para>The information about individual volumes is bracketed by summary lines. The first line of output specifies the number of
|
|
volumes in the listing. The last line of output summarizes the number of volumes that are online, offline, and busy, as in the
|
|
following example:</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">vos listvol fs2.example.com /vicepb</emphasis>
|
|
Total number of volumes on server fs2.example.com \
|
|
partition /vicepb : 66
|
|
sys 1969534847 RW 1582 K On-line
|
|
sys.backup 1969535105 BK 1582 K On-line
|
|
. . . . . .
|
|
. . . . . .
|
|
user.pat 1969534536 RW 17518 K On-line
|
|
user.pat.backup 1969534538 BK 17537 K On-line
|
|
Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
|
|
</programlisting>
|
|
|
|
<para><emphasis role="bold">Output with the -fast Flag</emphasis></para>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>listvol</secondary>
|
|
|
|
<tertiary>output with -fast flag</tertiary>
|
|
</indexterm>
|
|
|
|
<para>If you include the <emphasis role="bold">-fast</emphasis> flag displays only the volume ID number of each volume,
|
|
arranged in increasing numerical order, as in the following example. The final line (which summarizes the number of on-line,
|
|
off-line, and busy volumes) is omitted.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">vos listvol fs3.example.com /vicepa -f</emphasis>
|
|
Total number of volumes on server fs3.example.com \
|
|
partition /vicepa: 37
|
|
50489902
|
|
50489904
|
|
.
|
|
.
|
|
35970325
|
|
49732810
|
|
</programlisting>
|
|
|
|
<para><emphasis role="bold">Output with the -long Flag</emphasis></para>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>listvol</secondary>
|
|
|
|
<tertiary>output with -long flag</tertiary>
|
|
</indexterm>
|
|
|
|
<para>When you include the <emphasis role="bold">-long</emphasis> flag, , the output for each volume includes all of the
|
|
information in the default listing plus the following. Each item in this list corresponds to a separate line of output:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The file server machine and partition that house the volume, as determined by the command interpreter as the
|
|
command runs, rather than derived from the VLDB or the volume header.</para>
|
|
|
|
<indexterm>
|
|
<primary>read/write volume</primary>
|
|
|
|
<secondary>ID number in volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>read-only volume</primary>
|
|
|
|
<secondary>ID number in volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>backup volume</primary>
|
|
|
|
<secondary>ID number in volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>ReleaseClone volume</primary>
|
|
|
|
<secondary>ID number in volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>RWrite field in volume header</primary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>ROnly field in volume header</primary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>Backup field in volume header</primary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>RClone field in volume header</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The volume ID numbers associated with the various versions of the volume: read/write
|
|
(<computeroutput>RWrite</computeroutput>), read-only (<computeroutput>ROnly</computeroutput>), backup
|
|
(<computeroutput>Backup</computeroutput>), and ReleaseClone (<computeroutput>RClone</computeroutput>). One of them
|
|
matches the volume ID number that appears on the first line of the volume's output. If the value in the
|
|
<computeroutput>RWrite</computeroutput>, <computeroutput>ROnly</computeroutput>, or
|
|
<computeroutput>Backup</computeroutput> field is <computeroutput>0</computeroutput> (zero), there is no volume of that
|
|
type. If there is currently no ReleaseClone, the <computeroutput>RClone</computeroutput> field does not appear at
|
|
all.</para>
|
|
|
|
<indexterm>
|
|
<primary>volume quota</primary>
|
|
|
|
<secondary>recorded in volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>MaxQuota field in volume header</primary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The maximum space quota allotted to the read/write copy of the volume, expressed in kilobyte blocks in the
|
|
<computeroutput>MaxQuota</computeroutput> field.</para>
|
|
|
|
<indexterm>
|
|
<primary>creation date</primary>
|
|
|
|
<secondary>recorded in volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>Creation date in volume header</secondary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The date and time the volume was created, in the <computeroutput>Creation</computeroutput> field. If the volume
|
|
has been restored with the <emphasis role="bold">backup diskrestore</emphasis>, <emphasis role="bold">backup
|
|
volrestore</emphasis>, or <emphasis role="bold">vos restore</emphasis> command, this is the restore time.</para>
|
|
|
|
<indexterm>
|
|
<primary>update date</primary>
|
|
|
|
<secondary>recorded in volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>Last Update date in volume header</secondary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The date and time when the contents of the volume last changed, in the <computeroutput>Last
|
|
Update</computeroutput> field. For read-only and backup volumes, it matches the timestamp in the
|
|
<computeroutput>Creation</computeroutput> field.</para>
|
|
|
|
<indexterm>
|
|
<primary>access</primary>
|
|
|
|
<secondary>count, in volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>counter in header for number of accesses</secondary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The number of times the volume has been accessed for a fetch or store operation since the later of the two
|
|
following times: <itemizedlist>
|
|
<listitem>
|
|
<para>12:00 a.m. on the day the command is issued</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The last time the volume changed location</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>An example of the output when the <emphasis role="bold">-long</emphasis> flag is included:</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">vos listvol fs2.example.com b -long</emphasis>
|
|
Total number of volumes on server fs2.example.com
|
|
partition /vicepb: 66
|
|
. . . . . .
|
|
. . . . . .
|
|
user.pat 1969534536 RW 17518 K On-line
|
|
fs2.example.com /vicepb
|
|
RWrite 1969534536 ROnly 0 Backup 1969534538
|
|
MaxQuota 20000 K
|
|
Creation Mon Jun 12 09:02:25 1989
|
|
Last Update Thu Jan 4 17:39:34 1990
|
|
1573 accesses in the past day (i.e., vnode references)
|
|
user.pat.backup 1969534538 BK 17537 K On-line
|
|
fs2.example.com /vicepb
|
|
RWrite 1969534536 ROnly 0 Backup 1969534538
|
|
MaxQuota 20000 K
|
|
Creation Fri Jan 5 06:37:59 1990
|
|
Last Update Fri Jan 5 06:37:59 1990
|
|
0 accesses in the past day (i.e., vnode references)
|
|
. . . . .
|
|
. . . . .
|
|
Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
|
|
</programlisting>
|
|
|
|
<para><emphasis role="bold">Output with the -extended Flag</emphasis></para>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>listvol</secondary>
|
|
|
|
<tertiary>output with -extended flag</tertiary>
|
|
</indexterm>
|
|
|
|
<para>When you include the <emphasis role="bold">-extended</emphasis> flag, the output for each volume includes all of the
|
|
information reported with the <emphasis role="bold">-long</emphasis> flag, plus two tables of statistics: <itemizedlist>
|
|
<listitem>
|
|
<para>The table labeled <computeroutput>Raw Read/Write Stats</computeroutput> table summarizes the number of times the
|
|
volume has been accessed for reading or writing.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The table labeled <computeroutput>Writes Affecting Authorship</computeroutput> table contains information on
|
|
writes made to files and directories in the specified volume.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>An example of the output when the <emphasis role="bold">-extended</emphasis> flag is included:</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">vos listvol fs3.example.com a -extended</emphasis>
|
|
common.bboards 1969535592 RW 23149 K used 9401 files On-line
|
|
fs3.example.com /vicepa
|
|
RWrite 1969535592 ROnly 0 Backup 1969535594
|
|
MaxQuota 30000 K
|
|
Creation Mon Mar 8 14:26:05 1999
|
|
Last Update Mon Apr 26 09:20:43 1999
|
|
11533 accesses in the past day (i.e., vnode references)
|
|
Raw Read/Write Stats
|
|
|-------------------------------------------|
|
|
| Same Network | Diff Network |
|
|
|----------|----------|----------|----------|
|
|
| Total | Auth | Total | Auth |
|
|
|----------|----------|----------|----------|
|
|
Reads | 151 | 151 | 1092 | 1068 |
|
|
Writes | 3 | 3 | 324 | 324 |
|
|
|-------------------------------------------|
|
|
Writes Affecting Authorship
|
|
|-------------------------------------------|
|
|
| File Authorship | Directory Authorship|
|
|
|----------|----------|----------|----------|
|
|
| Same | Diff | Same | Diff |
|
|
|----------|----------|----------|----------|
|
|
0-60 sec | 92 | 0 | 100 | 4 |
|
|
1-10 min | 1 | 0 | 14 | 6 |
|
|
10min-1hr | 0 | 0 | 19 | 4 |
|
|
1hr-1day | 1 | 0 | 13 | 0 |
|
|
1day-1wk | 1 | 0 | 1 | 0 |
|
|
> 1wk | 0 | 0 | 0 | 0 |
|
|
|-------------------------------------------|
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ221">
|
|
<title>Displaying One Volume's VLDB Entry and Volume Header</title>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>VLDB entry</secondary>
|
|
|
|
<tertiary>with volume header</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>VLDB entry with volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>VLDB</primary>
|
|
|
|
<secondary>displaying entry</secondary>
|
|
|
|
<tertiary>with volume header</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>entry in VLDB</primary>
|
|
|
|
<secondary>displaying, with volume header</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>volume header</secondary>
|
|
|
|
<tertiary>with VLDB entry</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>volume header with VLDB entry</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume header</primary>
|
|
|
|
<secondary>displaying</secondary>
|
|
|
|
<tertiary>with VLDB entry</tertiary>
|
|
</indexterm>
|
|
|
|
<para>The <emphasis role="bold">vos examine</emphasis> command displays information from both the VLDB and the volume header
|
|
for a single volume. There is some redundancy in the information from the two sources, which allows you to compare the VLDB
|
|
and volume header.</para>
|
|
|
|
<para>Because the volume header for each version of a volume (read/write, read-only, and backup) is different, you can specify
|
|
which one to display. Include the <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis>
|
|
extension on the volume name or ID argument as appropriate. The information from the VLDB is the same for all three
|
|
versions.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos examine</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>examine</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ222">
|
|
<title>To display one volume's VLDB entry and volume header</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">vos examine</emphasis> command. <programlisting>
|
|
% <emphasis role="bold">vos examine</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">e</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">volume name or ID</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Identifies one volume either by its complete name or volume ID number. It can be a read/write, read-only, or
|
|
backup type. Use the <emphasis role="bold">.backup</emphasis> or <emphasis role="bold">.readonly</emphasis>
|
|
extension if appropriate.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>The top part of the output displays the same information from a volume header as the <emphasis role="bold">vos
|
|
listvol</emphasis> command with the <emphasis role="bold">-long</emphasis> flag, as described following the instructions in
|
|
<link linkend="HDRWQ220">To display volume headers</link>. If you specify the read-only version of the volume and it exists at
|
|
more than one site, the output includes all of them. The bottom part of the output lists the same information from the VLDB as
|
|
the <emphasis role="bold">vos listvldb</emphasis> command, as described following the instructions in <link
|
|
linkend="HDRWQ218">To display VLDB entries</link>.</para>
|
|
|
|
<para>Below is an example for a volume whose VLDB entry is currently locked.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">vos examine user.terry</emphasis>
|
|
user.terry 536870981 RW 3459 K On-line
|
|
fs3.example.com /vicepa
|
|
Write 5360870981 ROnly 0 Backup 536870983
|
|
MaxQuota 40000 K
|
|
Creation Mon Jun 12 15:22:06 1989
|
|
Last Update Fri Jun 16 09:34:35 1989
|
|
5719 accesses in the past day (i.e., vnode references)
|
|
RWrite: 5360870981 Backup: 536870983
|
|
number of sites -> 1
|
|
server fs3.example.com partition /vicepa RW Site
|
|
Volume is currently LOCKED
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ223">
|
|
<title>Displaying the Name or Location of the Volume that Contains a File</title>
|
|
|
|
<para>This section explains how to learn the name, volume ID number, or location of the volume that contains a file or
|
|
directory.</para>
|
|
|
|
<para>You can also use one piece of information about a volume (for example, its name) to obtain other information about it
|
|
(for example, its location). The following list points you to the relevant instructions: <itemizedlist>
|
|
<indexterm>
|
|
<primary>translating</primary>
|
|
|
|
<secondary>volume name to ID number</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>learning</primary>
|
|
|
|
<secondary>volume ID</secondary>
|
|
|
|
<tertiary>given volume name</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume name</primary>
|
|
|
|
<secondary>translating</secondary>
|
|
|
|
<tertiary>to volume ID number</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume ID number</primary>
|
|
|
|
<secondary>learning</secondary>
|
|
|
|
<tertiary>from volume name</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>examine</secondary>
|
|
|
|
<tertiary>to learn volume ID</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>translating</primary>
|
|
|
|
<secondary>volume ID number to name</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>learning</primary>
|
|
|
|
<secondary>volume name</secondary>
|
|
|
|
<tertiary>given volume ID number</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume name</primary>
|
|
|
|
<secondary>learning</secondary>
|
|
|
|
<tertiary>from volume ID number</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume ID number</primary>
|
|
|
|
<secondary>translating</secondary>
|
|
|
|
<tertiary>to volume name</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>examine</secondary>
|
|
|
|
<tertiary>to learn volume name</tertiary>
|
|
</indexterm>
|
|
|
|
<listitem>
|
|
<para>To use a volume's name to learn the volume ID numbers of all its existing versions, 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>
|
|
|
|
<para>You can also use the command to learn a volume's name by providing its ID number.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To use a volume's name or ID number to learn its location, use the <emphasis role="bold">vos listvldb</emphasis>
|
|
command as described in <link linkend="HDRWQ218">To display VLDB entries</link>.</para>
|
|
|
|
<indexterm>
|
|
<primary>translating</primary>
|
|
|
|
<secondary>volume name/ID number to volume location</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>learning</primary>
|
|
|
|
<secondary>volume location</secondary>
|
|
|
|
<tertiary>given volume name/ID number</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume name</primary>
|
|
|
|
<secondary>translating</secondary>
|
|
|
|
<tertiary>to volume location</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume ID number</primary>
|
|
|
|
<secondary>translating</secondary>
|
|
|
|
<tertiary>to volume location</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume location</primary>
|
|
|
|
<secondary>learning from volume name/ID number</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>listvldb</secondary>
|
|
|
|
<tertiary>to learn volume location</tertiary>
|
|
</indexterm>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>translating</primary>
|
|
|
|
<secondary>directory/file name to volume name</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>learning</primary>
|
|
|
|
<secondary>volume name</secondary>
|
|
|
|
<tertiary>given directory/file name</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>directory/file name</primary>
|
|
|
|
<secondary>translating to volume name</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume name</primary>
|
|
|
|
<secondary>learning</secondary>
|
|
|
|
<tertiary>from directory/file name</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs listquota</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>listquota</secondary>
|
|
</indexterm>
|
|
|
|
<sect3 id="HDRWQ224">
|
|
<title>To display the name of the volume that contains a file</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs listquota</emphasis> command. <programlisting>
|
|
% <emphasis role="bold">fs listquota</emphasis> [<<replaceable>dir/file path</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">lq</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is an acceptable alias for <emphasis role="bold">listquota</emphasis>(and <emphasis
|
|
role="bold">listq</emphasis> the shortest acceptable abbreviation).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">dir/file path</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names a directory or file housed in the volume for which to display the name. Partial pathnames are
|
|
interpreted relative to the current working directory, which is the default if this argument is omitted.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>The following is an example of the output:</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs listquota /afs/example.com/usr/terry</emphasis>
|
|
Volume Name Quota Used % Used Partition
|
|
user.terry 15000 5071 34% 86%
|
|
</programlisting>
|
|
|
|
<indexterm>
|
|
<primary>translating</primary>
|
|
|
|
<secondary>directory/file name to volume ID number</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>learning</primary>
|
|
|
|
<secondary>volume ID</secondary>
|
|
|
|
<tertiary>given directory/file name</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>directory/file name</primary>
|
|
|
|
<secondary>translating to volume ID number</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume ID number</primary>
|
|
|
|
<secondary>learning from directory/file name</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs examine</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>examine</secondary>
|
|
</indexterm>
|
|
</sect3>
|
|
|
|
<sect3 id="HDRWQ225">
|
|
<title>To display the ID number of the volume that contains a file</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs examine</emphasis> command. <programlisting>
|
|
% <emphasis role="bold">fs examine</emphasis> [<<replaceable>dir/file path</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">exa</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">dir/file path</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names a directory or file housed in the volume for which to display the volume ID. Partial pathnames are
|
|
interpreted relative to the current working directory, which is the default if this argument is omitted.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>The following example illustrates how the output reports the volume ID number in the
|
|
<computeroutput>vid</computeroutput> field.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs examine /afs/example.com/usr/terry</emphasis>
|
|
Volume status for vid = 50489902 named user.terry
|
|
Current maximum quota is 15000
|
|
Current blocks used are 5073
|
|
The partition has 46383 blocks available out of 333305
|
|
</programlisting>
|
|
|
|
<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>
|
|
|
|
<indexterm>
|
|
<primary>translating</primary>
|
|
|
|
<secondary>directory/file name to volume location</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>learning</primary>
|
|
|
|
<secondary>volume location</secondary>
|
|
|
|
<tertiary>given directory/file name</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>directory/file name</primary>
|
|
|
|
<secondary>translating to volume location</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume location</primary>
|
|
|
|
<secondary>learning from directory/file name</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>location</secondary>
|
|
|
|
<see>volume location</see>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs whereis</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>whereis</secondary>
|
|
</indexterm>
|
|
</sect3>
|
|
|
|
<sect3 id="Header_242">
|
|
<title>To display the location of the volume that contains a file</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs whereis</emphasis> command to display the name of the file server machine that
|
|
houses the volume containing a file or directory. <programlisting>
|
|
% <emphasis role="bold">fs whereis</emphasis> [<<replaceable>dir/file path</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">whe</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">whereis</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">dir/file path</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names a directory or file for which to report the location. Partial pathnames are interpreted relative to
|
|
the current working directory, which is the default if this argument is omitted.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<para>The output displays the file server machine that houses the volume containing the file, as in the following
|
|
example:</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs whereis /afs/example.com/user/terry</emphasis>
|
|
File /afs/example.com/usr/terry is on host fs2.example.com
|
|
</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you also want to know which partition houses the volume, first issue the <emphasis role="bold">fs
|
|
listquota</emphasis> command to display the volume's name. For complete syntax, see <link linkend="HDRWQ224">To display
|
|
the name of the volume that contains a file</link>. <programlisting>
|
|
% <emphasis role="bold">fs listquota</emphasis> [<<replaceable>dir/file path</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>Then issue the <emphasis role="bold">vos listvldb</emphasis> command, providing the volume name as the volume name
|
|
or ID argument. For complete syntax and a description of the output, see <link linkend="HDRWQ218">To display VLDB
|
|
entries</link>.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">vos listvldb</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ226">
|
|
<title>Moving Volumes</title>
|
|
|
|
<indexterm>
|
|
<primary>moving</primary>
|
|
|
|
<secondary>volume</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>moving</secondary>
|
|
</indexterm>
|
|
|
|
<para>There are three main reasons to move volumes: <itemizedlist>
|
|
<listitem>
|
|
<para>To place volumes on other partitions or machines temporarily while repairing or replacing a disk or file server
|
|
machine.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><indexterm>
|
|
<primary>disk partition</primary>
|
|
|
|
<secondary>moving volumes to reduce overcrowding</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>overcrowding of disk partition</primary>
|
|
|
|
<secondary>moving volumes to reduce</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>overcrowding of disk partition</primary>
|
|
|
|
<secondary>effect on users</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>failure</primary>
|
|
|
|
<secondary>of file storage due to full partition</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>file storage</primary>
|
|
|
|
<secondary>failed due to partition crowding</secondary>
|
|
</indexterm> To free space on a partition that is becoming overcrowded. One symptom of overcrowding is that users cannot
|
|
to save files even though the relevant volume is below its quota. The following error message confirms the problem:
|
|
<programlisting>
|
|
afs: failed to store file (partition full)
|
|
</programlisting></para>
|
|
|
|
<para>You can track available space on AFS server partitions by using the <emphasis role="bold">scout</emphasis> or
|
|
<emphasis role="bold">afsmonitor</emphasis> programs described in <link linkend="HDRWQ323">Monitoring and Auditing AFS
|
|
Performance</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A file server machine is becoming overloaded because it houses many more volumes than other machines of the same
|
|
size, or has volumes with more popular files in them.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>read/write volume</primary>
|
|
|
|
<secondary>moving</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>backup volume</primary>
|
|
|
|
<secondary>removed by read/write move</secondary>
|
|
</indexterm>
|
|
|
|
<para>To move a read/write volume, use the <emphasis role="bold">vos move</emphasis> command as described in the following
|
|
instructions. Before attempting to move the volume, the <emphasis role="bold">vos</emphasis> command interpreter verifies that
|
|
there is enough free space for it on the destination partition. If not, it does not attempt the move operation and prints the
|
|
following message.</para>
|
|
|
|
<programlisting>
|
|
vos: no space on target partition destination_part to move volume volume
|
|
</programlisting>
|
|
|
|
<para>To move a read-only volume, you actually remove the volume from the current site by issuing the <emphasis role="bold">vos
|
|
remove</emphasis> command as described in <link linkend="HDRWQ236">To remove a volume and unmount it</link>. Then define a new
|
|
site and release the volume to it by issuing the <emphasis role="bold">vos addsite</emphasis> and <emphasis role="bold">vos
|
|
release</emphasis> commands as described in <link linkend="HDRWQ194">To replicate a read/write volume (create a read-only
|
|
volume)</link>.</para>
|
|
|
|
<indexterm>
|
|
<primary>read-only volume</primary>
|
|
|
|
<secondary>moving</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>backup volume</primary>
|
|
|
|
<secondary>moving</secondary>
|
|
</indexterm>
|
|
|
|
<para>A backup volume always resides at the same site as its read/write source volume, so you cannot move a backup volume except
|
|
as part of moving the read/write source. The <emphasis role="bold">vos move</emphasis> command automatically deletes the backup
|
|
version when you move a read/write volume. To create a new backup volume at the new site as soon as the move operation
|
|
completes, issue the <emphasis role="bold">vos backup</emphasis> command as described in <link linkend="HDRWQ205">To create and
|
|
mount a backup volume</link>.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos move</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>move</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<sect2 id="Header_244">
|
|
<title>To move 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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">vos move</emphasis> command to move the volume. Type it on a single line; it appears
|
|
on multiple lines here only for legibility. <programlisting>
|
|
% <emphasis role="bold">vos move</emphasis> <<replaceable>volume name or ID</replaceable>> \ <<replaceable>machine name on source</replaceable>>
|
|
<<replaceable>partition name on source </replaceable>> \ <<replaceable>machine name on destination</replaceable>> <partition name on
|
|
destination>
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">m</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">move</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">volume name or ID</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the name or volume ID number of the read/write volume to move.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">machine name on source</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine currently housing the volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">partition name on source</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the partition currently housing the volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">machine name on destination</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine to which to move the volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">partition name on destination</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the partition to which to move the volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<note>
|
|
<para>It is best not to halt a <emphasis role="bold">vos move</emphasis> operation before it completes, because parts of
|
|
the volume can be left on both the source and destination machines. For more information, see the command's reference
|
|
page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">vos listvldb</emphasis> command to
|
|
confirm the success of the move. Complete instructions appear in <link linkend="HDRWQ218">To display VLDB entries</link>.
|
|
<programlisting>
|
|
% <emphasis role="bold">vos listvldb</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If a backup version existed at the read/write volume's previous site, create a new backup at the new site by issuing
|
|
the <emphasis role="bold">vos backup</emphasis> command, which is fully described in <link linkend="HDRWQ205">To create
|
|
and mount a backup volume</link>. <programlisting>
|
|
% <emphasis role="bold">vos backup</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ227">
|
|
<title>Synchronizing the VLDB and Volume Headers</title>
|
|
|
|
<indexterm>
|
|
<primary>VLDB</primary>
|
|
|
|
<secondary>synchronizing with volume headers</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume header</primary>
|
|
|
|
<secondary>synchronizing with VLDB</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>synchronizing VLDB and volume header</secondary>
|
|
</indexterm>
|
|
|
|
<para>AFS can provide transparent file access because the Volume Location Database (VLDB) constantly tracks volume locations.
|
|
When the Cache Manager needs a file, it contacts the Volume Location (VL) Server, which reads the VLDB for the current location
|
|
of the volume containing the file. Therefore, the VLDB must accurately reflect the state of volumes on the file server machines
|
|
at all times. The Volume Server and VL Server automatically update a volume's VLDB entry when its status changes during a
|
|
<emphasis role="bold">vos</emphasis> operation, by performing the following series of steps. <orderedlist>
|
|
<listitem id="LIWQ228">
|
|
<para>The VL Server locks the VLDB entry. The lock advises other operations not to manipulate any
|
|
of the volume versions (read/write, read-only, or backup), which prevents the inconsistency that can result from multiple
|
|
simultaneous operations.</para>
|
|
</listitem>
|
|
|
|
<listitem id="LIWQ229">
|
|
<para><indexterm>
|
|
<primary>intention flag in VLDB entry</primary>
|
|
</indexterm> <indexterm>
|
|
<primary>VLDB</primary>
|
|
|
|
<secondary>intention flag set by VL Server</secondary>
|
|
</indexterm>
|
|
The VL Server sets an <emphasis>intention flag</emphasis> in the VLDB entry that
|
|
indicates the kind of operation to be performed. This flag never appears in VLDB listings because it is for internal use
|
|
only. In case the operation terminates prematurely, this flag tells the Salvager which operation was interrupted. (The
|
|
Salvager then determines the steps necessary either to complete the operation or return the volume to a previous
|
|
consistent state. For more information on salvaging, see <link linkend="HDRWQ232">Salvaging Volumes</link>.)</para>
|
|
</listitem>
|
|
|
|
<listitem id="LIWQ230">
|
|
<para>The Volume Server manipulates the volume. It usually sets the
|
|
<computeroutput>Off-line</computeroutput> flag in the volume header, which makes the volume inaccessible to the File
|
|
Server and other Volume Server operations during the manipulation. When the operation completes, the volume is again
|
|
marked <computeroutput>On-line</computeroutput>.</para>
|
|
</listitem>
|
|
|
|
<listitem id="LIWQ231">
|
|
<para>The VL Server records any changes resulting from the operation in the VLDB entry. Once the
|
|
operation is complete, it removes the intention flag set in Step <link linkend="LIWQ229">2</link>and releases the lock set
|
|
in Step <link linkend="LIWQ228">1</link>.</para>
|
|
</listitem>
|
|
</orderedlist></para>
|
|
|
|
<para>If a <emphasis role="bold">vos</emphasis> operation fails while the Volume Server is manipulating the volume
|
|
(corresponding to Step <link linkend="LIWQ230">3</link>), the volume can be left in an intermediate state, which is termed
|
|
<emphasis>corruption</emphasis>. In this case, the <computeroutput>Off-line</computeroutput> or <computeroutput>Off-line**needs
|
|
salvage**</computeroutput> marker usually appears at the end of the first line of output from the <emphasis role="bold">vos
|
|
examine</emphasis> command. To repair the corruption, run the Salvager before attempting to resynchronize the VLDB and volume
|
|
headers. For salvaging instructions, see <link linkend="HDRWQ232">Salvaging Volumes</link>.</para>
|
|
|
|
<para>More commonly, an interruption while flags are being set or removed (corresponding to Step <link
|
|
linkend="LIWQ228">1</link>, Step <link linkend="LIWQ229">2</link>, or Step <link linkend="LIWQ231">4</link>) causes a
|
|
discrepancy between the VLDB and volume headers. To resynchronize the VLDB and volumes, use the <emphasis role="bold">vos
|
|
syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> commands. To achieve complete VLDB consistency, it is best
|
|
to run the <emphasis role="bold">vos syncvldb</emphasis> command on all file server machines in the cell, and then run the
|
|
<emphasis role="bold">vos syncserv</emphasis> command on all file server machines in the cell.</para>
|
|
|
|
<indexterm>
|
|
<primary>symptoms</primary>
|
|
|
|
<secondary>of VLDB/volume header desynchronization</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>desynchronization of VLDB/volume headers</primary>
|
|
|
|
<secondary>symptoms of</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>synchrony of VLDB and volume headers</primary>
|
|
|
|
<secondary>symptoms of lack of</secondary>
|
|
</indexterm>
|
|
|
|
<para>There are several symptoms that indicate a volume operation failed: <itemizedlist>
|
|
<listitem>
|
|
<para>Error messages on the standard error stream or in server process log files indicate that an operation terminated
|
|
abnormally. Perhaps you had to halt the operation before it completed (for instance, by using a signal such as <emphasis
|
|
role="bold">Ctrl-c</emphasis>), or a file server machine or server process was not functioning when the operation ran. To
|
|
determine if a machine or process is still not functioning, issue the <emphasis role="bold">bos status</emphasis> command
|
|
as described in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A subsequent <emphasis role="bold">vos</emphasis> operation fails because a previous failure left a VLDB entry
|
|
locked. Sometimes an error message reports that a volume is locked. To display a list of locked volumes, use the <emphasis
|
|
role="bold">-locked</emphasis> flag on the <emphasis role="bold">vos listvldb</emphasis> command as described in <link
|
|
linkend="HDRWQ217">Displaying VLDB Entries</link>.</para>
|
|
|
|
<para>If the only problem with a volume is that its VLDB entry is locked, you probably do not need to synchronize the
|
|
entire VLDB. Instead use the <emphasis role="bold">vos unlock</emphasis> or <emphasis role="bold">vos
|
|
unlockvldb</emphasis> command to unlock the entry, as described in <link linkend="HDRWQ247">Unlocking and Locking VLDB
|
|
Entries</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A subsequent <emphasis role="bold">vos</emphasis> operation fails because a previous failure left a volume marked as
|
|
offline. To check a volume's current status, check the first line of output from 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>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>synchrony of VLDB and volume headers</primary>
|
|
|
|
<secondary>restoring</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>restoring</primary>
|
|
|
|
<secondary>synchrony of VLDB and volume headers</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>desynchronization of VLDB/volume headers</primary>
|
|
|
|
<secondary>fixing</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>Salvager</primary>
|
|
|
|
<secondary>running before VLDB/volume header resynchronization</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>syncvldb</secondary>
|
|
|
|
<tertiary>effect</tertiary>
|
|
</indexterm>
|
|
|
|
<para>The <emphasis role="bold">vos syncvldb</emphasis> command corrects the information in the Volume Location Database (VLDB)
|
|
either about all volumes housed on a file server machine, about the volumes on just one partition, or about a single volume. If
|
|
checking about one or more partitions, the command contacts the Volume Server to obtain a list of the volumes that actually
|
|
reside on each partition. It then obtains the VLDB entry for each volume from the VL Server. It changes the VLDB entry as
|
|
necessary to reflect the state of the volume on the partition. For example, it creates or updates a VLDB entry when it finds a
|
|
volume for which the VLDB entry is missing or incomplete. However, if there is already a VLDB entry that defines a different
|
|
location for the volume, or there are irreconcilable conflicts with other VLDB entries, it instead writes a message about the
|
|
conflict to the standard error stream. The command never removes volumes from the file server machine.</para>
|
|
|
|
<para>When checking a single volume's VLDB entry, the command also automatically performs the operations invoked by the
|
|
<emphasis role="bold">vos syncserv</emphasis> command: it not only verifies that the VLDB entry is correct for the specified
|
|
volume type (read/write, backup, or read-only), but also checks that any related volume types mentioned in the VLDB entry
|
|
actually exist at the site listed in the entry.</para>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>syncserv</secondary>
|
|
|
|
<tertiary>effect</tertiary>
|
|
</indexterm>
|
|
|
|
<para>The <emphasis role="bold">vos syncserv</emphasis> command verifies that each volume type (read/write, read-only, and
|
|
backup) mentioned in a VLDB entry actually exists at the site indicated in the entry. It checks all VLDB entries that mention a
|
|
site either on any of a file server machine's partitions or on one partition. Note that command can end up inspecting sites
|
|
other than on the specified machine or partition, if there are read-only versions of the volume at sites other than the
|
|
read/write site.</para>
|
|
|
|
<para>The command alters any incorrect information in the VLDB, unless there is an irreconcilable conflict with other VLDB
|
|
entries. In that case, it writes a message to the standard error stream instead. The command never removes volumes from their
|
|
sites.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos syncvldb</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>syncvldb</secondary>
|
|
|
|
<tertiary>syntax</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos syncserv</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>syncserv</secondary>
|
|
|
|
<tertiary>syntax</tertiary>
|
|
</indexterm>
|
|
|
|
<sect2 id="Header_246">
|
|
<title>To synchronize the VLDB with volume headers</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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem id="LIVOL-SYNCVL">
|
|
<para>Issue the <emphasis role="bold">vos syncvldb</emphasis> command to make the VLDB reflect
|
|
the true state of all volumes on a machine or partition, or the state of one volume.</para>
|
|
|
|
<note>
|
|
<para>To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your
|
|
cell for the <emphasis role="bold">-server</emphasis> argument in turn and omitting the <emphasis
|
|
role="bold">-partition</emphasis> and <emphasis role="bold">-volume</emphasis> arguments, before proceeding to Step
|
|
<link linkend="LIVOL-SYNCSR">3</link>.</para>
|
|
</note>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">vos syncvldb -server</emphasis> <<replaceable>machine name</replaceable>> [<emphasis role="bold">-partition</emphasis> <<replaceable>partition name</replaceable>>] \
|
|
[<emphasis role="bold">-volume</emphasis> <<replaceable>volume name or ID</replaceable>>] [<emphasis role="bold">-verbose >></emphasis> file]
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">syncv</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">syncvldb</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-server</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine housing the volumes for which to verify VLDB entries. If you are also
|
|
providing the <emphasis role="bold">-volume</emphasis> argument, this argument must name the machine where the
|
|
volume actually resides.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-partition</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Identifies the partition (on the file server machine specified by the <emphasis
|
|
role="bold">-server</emphasis> argument) housing the volumes for which to verify VLDB entries. In general, it is
|
|
best to omit this argument so that either the VLDB entries for all volumes on a server machine are corrected (if
|
|
you do not provide the <emphasis role="bold">-volume</emphasis> argument), or so that you do not need to guarantee
|
|
that the partition actually houses the volume named by the <emphasis role="bold">-volume</emphasis>
|
|
argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-volume</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the name or volume ID number of a single volume for which to verify the VLDB entry.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-verbose >> file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the
|
|
machine on which you are issuing the command. The command often writes a large amount of output to the standard
|
|
output stream; writing it to a file enables you to examine the output more carefully.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
|
|
<listitem id="LIVOL-SYNCSR">
|
|
<para>Issue the <emphasis role="bold">vos syncserv</emphasis> command to inspect each volume
|
|
for which the VLDB lists a version at the specified site.</para>
|
|
|
|
<note>
|
|
<para>To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your
|
|
cell for the machine name argument in turn and omitting the partition name argument.</para>
|
|
</note>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">vos syncserv</emphasis> <<replaceable>machine name</replaceable>> [<<replaceable>partition name</replaceable>>] [<emphasis
|
|
role="bold">-v >></emphasis> file]
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">syncs</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">syncserv</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">machine name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine mentioned in each VLDB entry to check.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">partition name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Identifies the partition mentioned in each VLDB entry to check. If synchronizing the entire VLDB, omit this
|
|
argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-v >> file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the
|
|
machine on which you are issuing the command. The command often writes a large amount of output to the standard
|
|
output stream; writing it to a file enables you to examine the output more carefully.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ232">
|
|
<title>Salvaging Volumes</title>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>salvaging</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>corruption</primary>
|
|
|
|
<secondary>symptoms and types</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>symptoms</primary>
|
|
|
|
<secondary>volume corruption</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>symptoms of corruption</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>Salvager</primary>
|
|
|
|
<secondary>instructions for invoking</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>file server machine</primary>
|
|
|
|
<secondary>salvaging volumes</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>salvaging</primary>
|
|
|
|
<secondary>volumes</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>partition</primary>
|
|
|
|
<secondary>salvaging all volumes</secondary>
|
|
</indexterm>
|
|
|
|
<para>An unexpected interruption while the Volume Server or File Server is manipulating the data in a volume can leave the
|
|
volume in an intermediate state (<emphasis>corrupted</emphasis>), rather than just creating a discrepancy between the
|
|
information in the VLDB and volume headers. For example, the failure of the operation that saves changes to a file (by
|
|
overwriting old data with new) can leave the old and new data mixed together on the disk.</para>
|
|
|
|
<para>If an operation halts because the Volume Server or File Server exits unexpectedly, the BOS Server automatically shuts down
|
|
all components of the <emphasis role="bold">fs</emphasis> process and invokes the Salvager. The Salvager checks for and repairs
|
|
any inconsistencies it can. Sometimes, however, there are symptoms of the following sort, which indicate corruption serious
|
|
enough to create problems but not serious enough to cause the File Server component to fail. In these cases you can invoke the
|
|
Salvager yourself by issuing the <emphasis role="bold">bos salvage</emphasis> command. <itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Symptom:</emphasis> A file appears in the output of the <emphasis role="bold">ls</emphasis>
|
|
command, but attempts to access the file fail with messages indicating that it does not exist.</para>
|
|
|
|
<para><emphasis role="bold">Possible cause:</emphasis> The Volume Server or File Server exited in the middle of a
|
|
file-creation operation, after changing the directory structure, but before actually storing data. (Other possible causes
|
|
are that the ACL on the directory does not grant the permissions you need to access the file, or there is a process,
|
|
machine, or network outage. Check for these causes before assuming the file is corrupted.)</para>
|
|
|
|
<para><emphasis role="bold">Salvager's solution:</emphasis> Remove the file's entry from the directory structure.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Symptom:</emphasis> A volume is marked <computeroutput>Off-line</computeroutput> in the output
|
|
from the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands, or
|
|
attempts to access the volume fail.</para>
|
|
|
|
<para><emphasis role="bold">Possible cause:</emphasis> Two files or versions of a file are sharing the same disk blocks
|
|
because of an interrupted operation. The File Server and Volume Server normally refuse to attach volumes that exhibit this
|
|
type of corruption, because it can be very dangerous. If the Volume Server or File Server do attach the volume but are
|
|
unsure of the status of the affected disk blocks, they sometimes try to write yet more data there. When they cannot
|
|
perform the write, the data is lost. This effect can cascade, causing loss of all data on a partition.</para>
|
|
|
|
<para><emphasis role="bold">Salvager's solution:</emphasis> Delete the data from the corrupted disk blocks in preference
|
|
to losing an entire partition.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Symptom:</emphasis> There is less space available on the partition than you expect based on
|
|
the size statistic reported for each volume by the <emphasis role="bold">vos listvol</emphasis> command.</para>
|
|
|
|
<para><emphasis role="bold">Possible cause:</emphasis> There are orphaned files and directories. An
|
|
<emphasis>orphaned</emphasis> element is completely inaccessible because it is not referenced by any directory that can
|
|
act as its parent (is higher in the file tree). An orphaned element is not counted in the calculation of a volume's size
|
|
(or against its quota), even though it occupies space on the server partition.</para>
|
|
|
|
<para><emphasis role="bold">Salvager's solution:</emphasis> By default, print a message to the <emphasis
|
|
role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were found and the approximate number of
|
|
kilobytes they are consuming. You can use the <emphasis role="bold">-orphans</emphasis> argument to remove or attach
|
|
orphaned elements instead. See <link linkend="HDRWQ233">To salvage volumes</link>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>When you notice symptoms such as these, use the <emphasis role="bold">bos salvage</emphasis> command to invoke the
|
|
Salvager before corruption spreads. (Even though it operates on volumes, the command belongs to the <emphasis
|
|
role="bold">bos</emphasis> suite because the BOS Server must coordinate the shutdown and restart of the Volume Server and File
|
|
Server with the Salvager. It shuts them down before the Salvager starts, and automatically restarts them when the salvage
|
|
operation finishes.)</para>
|
|
|
|
<para>All of the AFS data stored on a file server machine is inaccessible during the salvage of one or more partitions. If you
|
|
salvage just one volume, it alone is inaccessible.</para>
|
|
|
|
<para>When processing one or more partitions, the command restores consistency to corrupted read/write volumes where possible.
|
|
For read-only or backup volumes, it inspects only the volume header: <itemizedlist>
|
|
<listitem>
|
|
<para>If the volume header is corrupted, the Salvager removes the volume completely and records the removal in its log
|
|
file, <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis>. Issue the <emphasis role="bold">vos release</emphasis> or
|
|
<emphasis role="bold">vos backup</emphasis> command to create the read-only or backup volume again.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the volume header is intact, the Salvager skips the volume (does not check for corruption in the contents).
|
|
However, if the File Server notices corruption as it initializes, it sometimes refuses to attach the volume or bring it
|
|
online. In this case, it is simplest to remove the volume by issuing the <emphasis role="bold">vos remove</emphasis> or
|
|
<emphasis role="bold">vos zap</emphasis> command. Then issue the <emphasis role="bold">vos release</emphasis> or <emphasis
|
|
role="bold">vos backup</emphasis> command to create it again.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>Combine the <emphasis role="bold">bos salvage</emphasis> command's arguments as indicated to salvage different numbers of
|
|
volumes: <itemizedlist>
|
|
<listitem>
|
|
<para>To salvage all volumes on a file server machine, combine the <emphasis role="bold">-server</emphasis> argument and
|
|
the <emphasis role="bold">-all</emphasis> flag.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To salvage all volumes on one partition, combine the <emphasis role="bold">-server</emphasis> and <emphasis
|
|
role="bold">-partition</emphasis> arguments.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To salvage only one read/write volume, combine the <emphasis role="bold">-server</emphasis>, <emphasis
|
|
role="bold">-partition</emphasis>, and <emphasis role="bold">-volume</emphasis> arguments. Only that volume is
|
|
inaccessible to Cache Managers, because the BOS Server does not shutdown the File Server and Volume Server processes
|
|
during the salvage of a single volume. Do not name a read-only or backup volume with the <emphasis
|
|
role="bold">-volume</emphasis> argument. Instead, remove the volume, using the <emphasis role="bold">vos remove</emphasis>
|
|
or <emphasis role="bold">vos zap</emphasis> command. Then create a new copy of the volume with the <emphasis
|
|
role="bold">vos release</emphasis> or <emphasis role="bold">vos backup</emphasis> command.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>The Salvager always writes a trace to the <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file on the file
|
|
server machine where it runs. To record the trace in another file as well (either in AFS or on the local disk of the machine
|
|
where you issue the <emphasis role="bold">bos salvage</emphasis> command), name the file with the <emphasis
|
|
role="bold">-file</emphasis> argument. Or, to display the trace on the standard output stream as it is written to the <emphasis
|
|
role="bold">/usr/afs/logs/SalvageLog</emphasis> file, include the <emphasis role="bold">-showlog</emphasis> flag.</para>
|
|
|
|
<para>By default, multiple Salvager subprocesses run in parallel: one for each partition up to four, and four subprocesses for
|
|
four or more partitions. To increase or decrease the number of subprocesses running in parallel, provide a positive integer
|
|
value for the <emphasis role="bold">-parallel</emphasis> argument.</para>
|
|
|
|
<para>If there is more than one server partition on a physical disk, the Salvager by default salvages them serially to avoid the
|
|
inefficiency of constantly moving the disk head from one partition to another. However, this strategy is often not ideal if the
|
|
partitions are configured as logical volumes that span multiple disks. To force the Salvager to salvage logical volumes in
|
|
parallel, provide the string <emphasis role="bold">all</emphasis> as the value for the <emphasis
|
|
role="bold">-parallel</emphasis> argument. Provide a positive integer to specify the number of subprocesses to run in parallel
|
|
(for example, <emphasis role="bold">-parallel 5all</emphasis> for five subprocesses), or omit the integer to run up to four
|
|
subprocesses, depending on the number of logical volumes being salvaged.</para>
|
|
|
|
<para>The Salvager creates temporary files as it runs, by default writing them to the partition it is salvaging. The number of
|
|
files can be quite large, and if the partition is too full to accommodate them, the Salvager terminates without completing the
|
|
salvage operation (it always removes the temporary files before exiting). Other Salvager subprocesses running at the same time
|
|
continue until they finish salvaging all other partitions where there is enough disk space for temporary files. To complete the
|
|
interrupted salvage, reissue the command against the appropriate partitions, adding the <emphasis role="bold">-tmpdir</emphasis>
|
|
argument to redirect the temporary files to a local disk directory that has enough space.</para>
|
|
|
|
<para>The <emphasis role="bold">-orphans</emphasis> argument controls how the Salvager handles orphaned files and directories
|
|
that it finds on server partitions it is salvaging. An orphaned element is completely inaccessible because it is not referenced
|
|
by the vnode of any directory that can act as its parent (is higher in the filespace). Orphaned objects occupy space on the
|
|
server partition, but do not count against the volume's quota.</para>
|
|
|
|
<para>During the salvage, the output of the <emphasis role="bold">bos status</emphasis> command reports the following auxiliary
|
|
status for the <emphasis role="bold">fs</emphasis> process:</para>
|
|
|
|
<programlisting>
|
|
Salvaging file system
|
|
</programlisting>
|
|
|
|
<indexterm>
|
|
<primary>bos commands</primary>
|
|
|
|
<secondary>salvage</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>bos salvage</secondary>
|
|
</indexterm>
|
|
|
|
<sect2 id="HDRWQ233">
|
|
<title>To salvage volumes</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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">bos salvage</emphasis> command to salvage one or more volumes. <programlisting>
|
|
% <emphasis role="bold">bos salvage -server</emphasis> <<replaceable>machine name</replaceable>> [<emphasis role="bold">-partition</emphasis> <<replaceable>salvage partition</replaceable>>] \
|
|
[<emphasis role="bold">-volume</emphasis> <<replaceable>salvage volume number or volume name</replaceable>>] \
|
|
[<emphasis role="bold">-file</emphasis> salvage log output file] [<emphasis role="bold">-all</emphasis>] [<emphasis
|
|
role="bold">-showlog</emphasis>] \
|
|
[<emphasis role="bold">-parallel</emphasis> <<replaceable># of max parallel partition salvaging</replaceable>>] \
|
|
[<emphasis role="bold">-tmpdir</emphasis> <<replaceable>directory to place tmp files</replaceable>>] \
|
|
[<emphasis role="bold">-orphans</emphasis> <<emphasis role="bold">ignore</emphasis> | <emphasis role="bold">remove</emphasis> | <emphasis
|
|
role="bold">attach</emphasis> >]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-server</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine on which to salvage volumes. This argument can be combined either with the
|
|
<emphasis role="bold">-all</emphasis> flag, the <emphasis role="bold">-partition</emphasis> argument, or both the
|
|
<emphasis role="bold">-partition</emphasis> and <emphasis role="bold">-volume</emphasis> arguments.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-partition</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names a single partition on which to salvage all volumes. The <emphasis role="bold">-server</emphasis>
|
|
argument must be provided along with this one.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-volume</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the name or volume ID number of one read/write volume to salvage. Combine this argument with the
|
|
<emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the complete pathname of a file into which to write a trace of the salvage operation, in addition
|
|
to the <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file on the server machine. If the file pathname
|
|
is local, the trace is written to the specified file on the local disk of the machine where the <emphasis
|
|
role="bold">bos salvage</emphasis> command is issued. If the <emphasis role="bold">-volume</emphasis> argument is
|
|
included, the file can be in AFS, though not in the volume being salvaged. Do not combine this argument with the
|
|
<emphasis role="bold">-showlog</emphasis> flag.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-all</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Salvages all volumes on all of the partitions on the machine named by the <emphasis
|
|
role="bold">-server</emphasis> argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-showlog</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Displays the trace of the salvage operation on the standard output stream, as well as writing it to the
|
|
<emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-parallel</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the maximum number of Salvager subprocesses to run in parallel. Provide one of three values:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>An integer from the range <emphasis role="bold">1</emphasis> to <emphasis role="bold">32</emphasis>. A
|
|
value of <emphasis role="bold">1</emphasis> means that a single Salvager process salvages the partitions
|
|
sequentially.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The string <emphasis role="bold">all</emphasis> to run up to four Salvager subprocesses in parallel on
|
|
partitions formatted as logical volumes that span multiple physical disks. Use this value only with such
|
|
logical volumes.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The string <emphasis role="bold">all</emphasis> followed immediately (with no intervening space) by an
|
|
integer from the range <emphasis role="bold">1</emphasis> to <emphasis role="bold">32</emphasis>, to run the
|
|
specified number of Salvager subprocesses in parallel on partitions formatted as logical volumes. Use this
|
|
value only with such logical volumes.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>The BOS Server never starts more Salvager subprocesses than there are partitions, and always starts only one
|
|
process to salvage a single volume. If this argument is omitted, up to four Salvager subprocesses run in
|
|
parallel.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-tmpdir</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the full pathname of a local disk directory to which the Salvager process writes temporary files
|
|
as it runs. By default, it writes them to the partition it is currently salvaging.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-orphans</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Controls how the Salvager handles orphaned files and directories. Choose one of the following three values:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">ignore</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Leaves the orphaned objects on the disk, but prints a message to the <emphasis
|
|
role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were found and the
|
|
approximate number of kilobytes they are consuming. This is the default if you omit the <emphasis
|
|
role="bold">-orphans</emphasis> argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">remove</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Removes the orphaned objects, and prints a message to the <emphasis
|
|
role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were removed and the
|
|
approximate number of kilobytes they were consuming.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">attach</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Attaches the orphaned objects by creating a reference to them in the vnode of the volume's root
|
|
directory. Since each object's actual name is now lost, the Salvager assigns each one a name of the
|
|
following form: <simplelist>
|
|
<member><emphasis role="bold">_ _ORPHANFILE_ _.</emphasis> index for files</member>
|
|
|
|
<member><emphasis role="bold">_ _ORPHANDIR_ _.</emphasis> index for directories</member>
|
|
</simplelist></para>
|
|
|
|
<para>where index is a two-digit number that uniquely identifies each object. The orphans are charged
|
|
against the volume's quota and appear in the output of the <emphasis role="bold">ls</emphasis> command
|
|
issued against the volume's root directory.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ234">
|
|
<title>Setting and Displaying Volume Quota and Current Size</title>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>quota</secondary>
|
|
|
|
<see>volume quota</see>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>default</primary>
|
|
|
|
<secondary>volume quota</secondary>
|
|
</indexterm>
|
|
|
|
<para>Every AFS volume has an associated quota which limits the volume's size. The default quota for a newly created volume is
|
|
5,000 kilobyte blocks (slightly less that 5 MB). When a volume reaches its quota, the File Server rejects attempts to create new
|
|
files or directories in it. If an application is writing data into an existing file in a full volume, the File Server allows a
|
|
defined overage (by default, 1 MB). (You can use the <emphasis role="bold">fileserver</emphasis> command's <emphasis
|
|
role="bold">-spare</emphasis> or <emphasis role="bold">-pctspare</emphasis> argument to change the default overage; see the
|
|
command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.)</para>
|
|
|
|
<para>To set a quota other than 5000 KB as you create a volume, include the <emphasis role="bold">-maxquota</emphasis> argument
|
|
to the <emphasis role="bold">vos create</emphasis> command, as described in <link linkend="HDRWQ185">Creating Read/write
|
|
Volumes</link>. To modify an existing volume's quota, issue either the <emphasis role="bold">fs setquota</emphasis> or the
|
|
<emphasis role="bold">fs setvol</emphasis> command as described in the following instructions. Do not set an existing volume's
|
|
quota lower than its current size.</para>
|
|
|
|
<para>In general, smaller volumes are easier to administer than larger ones. If you need to move volumes, say for load-balancing
|
|
purposes, it is easier to find enough free space on other partitions for small volumes. Move operations complete more quickly
|
|
for small volumes, reducing the potential for outages or other errors to interrupt the move. AFS supports a maximum volume size,
|
|
which can vary for different AFS releases; see the <emphasis> OpenAFS Release Notes</emphasis> for the version you are using.
|
|
Also, the size of a partition or logical places an absolute limit on volume size, because a volume cannot span multiple
|
|
partitions or logical volumes.</para>
|
|
|
|
<para>It is generally safe to overpack partitions by putting more volumes on them than can actually fit if all the volumes reach
|
|
their maximum quota. However, only experience determines to what degree overpacking works in your cell. It depends on what kind
|
|
of quota you assign to volumes (particularly user volumes, which are more likely than system volumes to grow unpredictably) and
|
|
how much information people generate and store in comparison to their quota.</para>
|
|
|
|
<para>There are several commands that display a volume's quota, as described in the following instructions. They differ in how
|
|
much related information they produce.</para>
|
|
|
|
<sect2 id="Header_250">
|
|
<title>To set quota for a single volume</title>
|
|
|
|
<indexterm>
|
|
<primary>maximum volume quota</primary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>setting</primary>
|
|
|
|
<secondary>volume quota</secondary>
|
|
|
|
<tertiary>on single volume</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume quota</primary>
|
|
|
|
<secondary>setting</secondary>
|
|
|
|
<tertiary>on single volume</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs setquota</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>setquota</secondary>
|
|
</indexterm>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
|
|
<emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
|
|
the members of the system:administrators group</link>. <programlisting>
|
|
% <emphasis role="bold">pts membership system:administrators</emphasis>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs setquota</emphasis> command to set the volume's maximum quota. <programlisting>
|
|
% <emphasis role="bold">fs setquota</emphasis> [<<replaceable>dir/file path</replaceable>>] <emphasis role="bold">-max</emphasis> <<replaceable>max quota in kbytes</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">sq</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is an acceptable alias for <emphasis role="bold">setquota</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">dir/file path</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names a file or directory in the volume for which to set the indicated quota. Partial pathnames are
|
|
interpreted relative to the current working directory, which is the default if you omit this argument.</para>
|
|
|
|
<para>Specify the read/write path to the file or directory, 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">max quota in kbytes</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Sets the volume's quota, expressed in kilobyte blocks ( <emphasis role="bold">1024</emphasis> equals a
|
|
megabyte). A value of <emphasis role="bold">0</emphasis> grants an unlimited quota, but the size of the partition
|
|
imposes an absolute limit. You must include the <emphasis role="bold">-max</emphasis> switch if omitting the
|
|
dir/file path argument (to set the quota on the volume that houses the current working directory).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_251">
|
|
<title>To set maximum quota on one or more volumes</title>
|
|
|
|
<indexterm>
|
|
<primary>setting</primary>
|
|
|
|
<secondary>volume quota</secondary>
|
|
|
|
<tertiary>on multiple volumes</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume quota</primary>
|
|
|
|
<secondary>setting</secondary>
|
|
|
|
<tertiary>on multiple volumes</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs setvol</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>setvol</secondary>
|
|
</indexterm>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
|
|
<emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
|
|
the members of the system:administrators group</link>. <programlisting>
|
|
% <emphasis role="bold">pts membership system:administrators</emphasis>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs setvol</emphasis> command to set the quota on one or more volumes.
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setvol</emphasis> [<<replaceable>dir/file path</replaceable>>+] <emphasis role="bold">-max</emphasis> <<replaceable>disk space quota in 1K units</replaceable>>
|
|
</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>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">dir/file path</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names one file or directory that resides in each volume for which to set the indicated quota. Partial
|
|
pathnames are interpreted relative to the current working directory, which is the default if you omit this
|
|
argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">disk space quota in 1K units</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Sets the maximum quota on each volume, expressed in kilobytes blocks ( <emphasis role="bold">1024</emphasis>
|
|
equals a megabyte). A value of <emphasis role="bold">0</emphasis> grants an unlimited quota, but the size of the
|
|
partition does impose an absolute limit.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs quota</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>quota</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>volume quota</secondary>
|
|
|
|
<tertiary>percent used</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume quota</primary>
|
|
|
|
<secondary>displaying</secondary>
|
|
|
|
<tertiary>percent used</tertiary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_252">
|
|
<title>To display percent quota used</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs quota</emphasis> command. <programlisting>
|
|
% <emphasis role="bold">fs quota</emphasis> [<<replaceable>dir/file path</replaceable>>+]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">q</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">quota</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">dir/file path</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names a directory or file in each volume for which to display percent quota used. Partial pathnames are
|
|
interpreted relative to the current working directory, which is the default if you omit this argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>The following example illustrates the output produced by this command:</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs quota /afs/example.com/usr/terry</emphasis>
|
|
34% of quota used.
|
|
</programlisting>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs listquota</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>listquota</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>volume quota</secondary>
|
|
|
|
<tertiary>with volume size</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume quota</primary>
|
|
|
|
<secondary>displaying</secondary>
|
|
|
|
<tertiary>with volume size</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>volume size</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>size, displaying</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_253">
|
|
<title>To display quota, current size, and other information</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs listquota</emphasis> command. <programlisting>
|
|
% <emphasis role="bold">fs listquota</emphasis> [<<replaceable>dir/file path</replaceable>>+]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">lq</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is an alias for <emphasis role="bold">listquota</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">dir/file path</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names a directory or file in each volume for which to display quota along with volume name and current space
|
|
usage. Partial pathnames are interpreted relative to the current working directory, which is the default if you
|
|
omit this argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>As illustrated in the following example, the output reports the volume's name, its quota and current size (both in
|
|
kilobyte units), the percent quota used, and the percentage of space on the volume's host partition that is used.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs listquota /afs/example.com/usr/terry</emphasis>
|
|
Volume Name Quota Used % Used Partition
|
|
user.terry 15000 5071 34% 86%
|
|
</programlisting>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>volume quota</secondary>
|
|
|
|
<tertiary>with volume & partition info</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>volume size</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume quota</primary>
|
|
|
|
<secondary>displaying</secondary>
|
|
|
|
<tertiary>with volume &partition info</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>displaying</primary>
|
|
|
|
<secondary>disk partition size</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>disk partition</primary>
|
|
|
|
<secondary>displaying size of single</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs examine</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>examine</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_254">
|
|
<title>To display quota, current size, and more partition information</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs examine</emphasis> command. <programlisting>
|
|
% <emphasis role="bold">fs examine</emphasis> [<<replaceable>dir/file path</replaceable>>+]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">exa</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">dir/file path</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names a directory or file in each volume for which to display quota information and information about the
|
|
host partition. Partial pathnames are interpreted relative to the current working directory, which is the default
|
|
if you omit this argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>As illustrated in the following example, the output displays the volume's volume ID number and name, its quota and
|
|
current size (both in kilobyte units), and the free and total number of kilobyte blocks on the volume's host partition.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs examine /afs/example.com/usr/terry</emphasis>
|
|
Volume status for vid = 50489902 named user.terry
|
|
Current maximum quota is 15000
|
|
Current blocks used are 5073
|
|
The partition has 46383 blocks available out of 333305
|
|
</programlisting>
|
|
|
|
<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>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ235">
|
|
<title>Removing Volumes and their Mount Points</title>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>removing</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<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>removing</primary>
|
|
|
|
<secondary>volume</secondary>
|
|
</indexterm>
|
|
|
|
<para>To remove a volume from its site and its record from the VLDB, use the <emphasis role="bold">vos remove</emphasis>
|
|
command. Use it to remove any of the three types of volumes; the effect depends on the type. <itemizedlist>
|
|
<listitem>
|
|
<para><indexterm>
|
|
<primary>read/write volume</primary>
|
|
|
|
<secondary>removing</secondary>
|
|
|
|
<tertiary>effect of</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>backup volume</primary>
|
|
|
|
<secondary>removed by read/write removal</secondary>
|
|
</indexterm> If you indicate the read/write volume by specifying the volume's base name without a <emphasis
|
|
role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension, the command removes both the
|
|
read/write and associated backup volume from the partition that houses them. You do not need to provide the <emphasis
|
|
role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, because there can be only one
|
|
read/write site. The site information is also removed from the VLDB entry, and the site count (reported by the <emphasis
|
|
role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvldb</emphasis> commands as <computeroutput>number of
|
|
sites</computeroutput>) decrements by one. The read/write and backup volume ID numbers no longer appear in the output from
|
|
the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvldb</emphasis> commands, but they are
|
|
preserved internally. Read-only sites, if any, are not affected, but cannot be changed unless a read/write site is again
|
|
defined. The entire VLDB entry is removed if there are no read-only sites.</para>
|
|
|
|
<para>If there are no read-only copies left, it is best to remove the volume's mount point to prevent attempts to access
|
|
the volume's contents. Do not remove the mount point if copies of the read-only volume remain.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you indicate a read-only volume by including the <emphasis role="bold">.readonly</emphasis> extension on its
|
|
name, it is removed from the partition that houses it, and the corresponding site information is removed from the VLDB
|
|
entry. The site count reported by the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos
|
|
listvldb</emphasis> commands as <computeroutput>number of sites</computeroutput> decrements by one for each volume you
|
|
remove.</para>
|
|
|
|
<indexterm>
|
|
<primary>read-only volume</primary>
|
|
|
|
<secondary>removing</secondary>
|
|
|
|
<tertiary>effect of</tertiary>
|
|
</indexterm>
|
|
|
|
<para>If there is more than one read-only site, you must include the <emphasis role="bold">-server</emphasis> argument
|
|
(and optionally <emphasis role="bold">-partition</emphasis> argument) to specify the site from which to remove the volume.
|
|
If there is only one read-only site, the volume name is sufficient; if no read/write volume exists in this case, the
|
|
entire VLDB entry is removed.</para>
|
|
|
|
<para>It is not generally appropriate to remove the volume's mount point when removing a read-only volume, especially if
|
|
the read/write version of the volume still exists. If the read/write version no longer exists, remove the mount point as
|
|
described in Step <link linkend="LIWQ239">5</link>of <link linkend="HDRWQ236">To remove a volume and unmount
|
|
it</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you indicate a backup volume by including the <emphasis role="bold">.backup</emphasis> extension on its name, it
|
|
is removed from the partition that houses it and its site information is removed from the VLDB entry. You do not need to
|
|
provide the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, because
|
|
there can be only one backup site. The backup volume ID number no longer appears in the output from the <emphasis
|
|
role="bold">vos examine</emphasis> or <emphasis role="bold">vos listvldb</emphasis> command, but is preserved
|
|
internally.</para>
|
|
|
|
<para>In the standard configuration, there is a separate mount point for the backup version of a user volume. Remember to
|
|
remove the mount point to prevent attempt to access the nonexistent volume's contents.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<sect2 id="Header_256">
|
|
<title>Other Removal Commands</title>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>removing</secondary>
|
|
|
|
<tertiary>alternate commands</tertiary>
|
|
</indexterm>
|
|
|
|
<para>The <emphasis role="bold">vos remove</emphasis> command is almost always the appropriate way to remove a volume, because
|
|
it automatically removes a volume's VLDB entry and both the volume header and all data from the partition. If either the VLDB
|
|
entry or volume header does not exist, it is sometimes necessary to use other commands that remove only the remaining element.
|
|
Do not use these commands in the normal case when both the VLDB entry and the volume header exist, because by definition they
|
|
create discrepancies between them. For details on the commands' syntax, see their reference pages in the <emphasis> OpenAFS
|
|
Administration Reference</emphasis>.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos zap</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>zap</secondary>
|
|
</indexterm>
|
|
|
|
<para>The <emphasis role="bold">vos zap</emphasis> command removes a volume from its site by removing the volume header and
|
|
volume data for which a VLDB entry no longer exists. You can tell a VLDB entry is missing if the <emphasis role="bold">vos
|
|
listvol</emphasis> command displays the volume header but the <emphasis role="bold">vos examine</emphasis> or <emphasis
|
|
role="bold">vos listvldb</emphasis> command cannot locate the VLDB entry. You must run this command to correct the
|
|
discrepancy, because the <emphasis role="bold">vos syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis>
|
|
commands never remove volume headers.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos remsite</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>remsite</secondary>
|
|
</indexterm>
|
|
|
|
<para>The <emphasis role="bold">vos remsite</emphasis> command removes a read-only site definition from the VLDB without
|
|
affecting the volume on the file server machine. Use this command when you have mistakenly issued the <emphasis
|
|
role="bold">vos addsite</emphasis> command to define a read-only site, but have not yet issued the <emphasis role="bold">vos
|
|
release</emphasis> command to release the volume to the site. If you have actually released a volume to the site, use the
|
|
<emphasis role="bold">vos remove</emphasis> command instead.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos delentry</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>delentry</secondary>
|
|
</indexterm>
|
|
|
|
<para>The <emphasis role="bold">vos delentry</emphasis> command removes the entire VLDB entry that mentions the volume you
|
|
specify. If versions of the volume actually exist on file server machines, they are not affected. This command is useful if
|
|
you know for certain that a volume removal was not recorded in the VLDB (perhaps you used the <emphasis role="bold">vos
|
|
zap</emphasis> command during an emergency), and do not want to take the time to resynchronize the entire VLDB with the
|
|
<emphasis role="bold">vos syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> commands.</para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ236">
|
|
<title>To remove a volume and unmount it</title>
|
|
|
|
<indexterm>
|
|
<primary>read/write volume</primary>
|
|
|
|
<secondary>removing</secondary>
|
|
|
|
<tertiary>instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If removing the volume's mount point, verify that you have the <emphasis role="bold">d</emphasis>( <emphasis
|
|
role="bold">delete</emphasis>) permission on its parent directory's ACL. 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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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 id="LIWQ237">
|
|
|
|
<para><emphasis role="bold">(Optional)</emphasis> Dump the volume to a file or to tape, in case you want to restore it
|
|
later. To copy the volume's contents to a file, use the <emphasis role="bold">vos dump</emphasis> command as instructed in
|
|
<link linkend="HDRWQ240">Dumping and Restoring Volumes</link>. You can then copy the file to tape using a third-party
|
|
backup utility or an archiving utility such as the UNIX <emphasis role="bold">tar</emphasis> command.</para>
|
|
|
|
<para>Alternatively, use the AFS Backup System to create a tape copy. In this case, it can be convenient to create a
|
|
temporary volume set that includes only the volume of interest. Temporary volume sets are not recorded in the Backup
|
|
Database, and so do not clutter database with records for volume sets that you use only once. For instructions, see <link
|
|
linkend="HDRWQ301">To create a dump</link>.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos remove</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>remove</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem id="LIWQ238">
|
|
<para>Issue the <emphasis role="bold">vos remove</emphasis> command to remove the volume. If
|
|
removing a read-only volume from multiple sites, repeat the command for each one. <programlisting>
|
|
% <emphasis role="bold">vos remove</emphasis> [<emphasis role="bold">-server</emphasis> machine name>] [<emphasis role="bold">-partition</emphasis> <<replaceable>partition name</replaceable>>] \
|
|
<emphasis role="bold">-id</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">remo</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">remove</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-server</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the file server machine on which the volume resides. It is necessary only when the <emphasis
|
|
role="bold">-id</emphasis> argument names a read-only volume that exists at multiple sites.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-partition</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the partition on machine name where the volume resides. It is necessary only when the <emphasis
|
|
role="bold">-id</emphasis> argument names a read-only volume that exists at multiple sites. Provide the <emphasis
|
|
role="bold">-server</emphasis> argument along with this one.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-id</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Identifies the volume to remove, either by its complete name or volume ID number. If identifying a read-only
|
|
or backup volume by name, include the appropriate extension ( <emphasis role="bold">.readonly</emphasis> or
|
|
<emphasis role="bold">.backup</emphasis>).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs rmmount</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>rmmount</secondary>
|
|
|
|
<tertiary>when removing volume</tertiary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem id="LIWQ239">
|
|
<para>If you are removing the last existing version of the volume, issue the <emphasis
|
|
role="bold">fs rmmount</emphasis> command remove the corresponding mount point. Complete instructions appear in <link
|
|
linkend="HDRWQ236">To remove a volume and unmount it</link>.</para>
|
|
|
|
<para>If you are removing a backup volume that is mounted in the conventional way (at a subdirectory of its read/write
|
|
volume's root directory), then removing the source volume's mount point in this step is sufficient to remove the backup
|
|
volume's mount point. If you mounted the backup at a completely separate directory, you need to repeat this step for the
|
|
backup volume's mount point.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">fs rmmount</emphasis> <<replaceable>directory</replaceable>>
|
|
</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">(Optional)</emphasis> If you created a dump file in Step <link linkend="LIWQ237">3</link>,
|
|
transfer it to tape. The preferred method is to use the AFS Backup System, which is described in <link
|
|
linkend="HDRWQ248">Configuring the AFS Backup System</link>and <link linkend="HDRWQ283">Backing Up and Restoring AFS
|
|
Data</link>.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ240">
|
|
<title>Dumping and Restoring Volumes</title>
|
|
|
|
<indexterm>
|
|
<primary>dumping</primary>
|
|
|
|
<secondary>volumes</secondary>
|
|
|
|
<tertiary>without using AFS Backup System</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>dumping without AFS Backup System</secondary>
|
|
</indexterm>
|
|
|
|
<para><emphasis>Dumping</emphasis> a volume with the <emphasis role="bold">vos dump</emphasis> command converts its contents
|
|
into ASCII format and writes them to the file you specify. The <emphasis role="bold">vos restore</emphasis> command places a
|
|
dump file's contents into a volume after converting them into the volume format appropriate for the indicated file server
|
|
machine.</para>
|
|
|
|
<sect2 id="Header_259">
|
|
<title>About Dumping Volumes</title>
|
|
|
|
<indexterm>
|
|
<primary>read/write volume</primary>
|
|
|
|
<secondary>dumping</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>read-only volume</primary>
|
|
|
|
<secondary>dumping</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>backup volume</primary>
|
|
|
|
<secondary>dumping</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>availability of data</primary>
|
|
|
|
<secondary>interrupted by dumping</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>data</primary>
|
|
|
|
<secondary>availability interrupted by dumping</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>dumping</primary>
|
|
|
|
<secondary>volumes</secondary>
|
|
|
|
<tertiary>reasons</tertiary>
|
|
</indexterm>
|
|
|
|
<para>Dumping a volume can be useful in several situations, including the following: <itemizedlist>
|
|
<listitem>
|
|
<para>You want to back it up to tape, perhaps by using a third-party backup utility. To facilitate this type of backup
|
|
operation, the <emphasis role="bold">vos dump</emphasis> command can write to a named pipe. To learn about using the AFS
|
|
Backup System instead, see <link linkend="HDRWQ248">Configuring the AFS Backup System</link>and <link
|
|
linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You are removing the volume from your cell (perhaps because its owner is leaving your cell). The <emphasis
|
|
role="bold">vos dump</emphasis> command enables you to create a copy for safekeeping without incurring the overhead of
|
|
the Backup System. For complete instructions on removing a volume, see <link linkend="HDRWQ235">Removing Volumes and
|
|
their Mount Points</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You want to create a copy of the volume for safekeeping on a non-AFS server partition, perhaps while you move the
|
|
actual volume to another machine or perform maintenance tasks on the partition that houses the volume.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You need to replace a corrupted read/write volume. If an uncorrupted read-only or backup version of the volume
|
|
exists, dump it and restore the data into the read/write volume, overwriting the corrupted contents.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You want to copy or transfer the contents of the volume to another cell. You cannot use the <emphasis
|
|
role="bold">vos move</emphasis> command, because AFS supports volume moves only between file server machines that belong
|
|
to the same cell.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You want to have another read/write copy of the volume's contents. The second volume must have a different name
|
|
than the original one. If you want the contents of the two volumes to remain identical, you must update them both
|
|
manually. AFS provides no facility for keeping read/write volumes synchronized in this way.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You want a copy of only the files and directories in the volume with modification time stamps after a certain
|
|
date. The <emphasis role="bold">vos dump</emphasis> command can create an incremental dump file as described in Step
|
|
<link linkend="LIWQ241">3</link>of the following instructions.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>full dump</primary>
|
|
|
|
<secondary>creating using vos command</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>incremental dump</primary>
|
|
|
|
<secondary>creating using vos command</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>dumping</primary>
|
|
|
|
<secondary>volumes</secondary>
|
|
|
|
<tertiary>using vos command</tertiary>
|
|
</indexterm>
|
|
|
|
<para>You can use the <emphasis role="bold">vos dump</emphasis> command to create a <emphasis>full dump</emphasis>, which
|
|
contains the complete contents of the volume at the time you issue the command, or an <emphasis>incremental dump</emphasis>,
|
|
which contains only those files and directories with modification timestamps (as displayed by the <emphasis role="bold">ls
|
|
-l</emphasis> command) that are later than a date and time you specify. See Step <link linkend="LIWQ241">3</link>of the
|
|
following instructions.</para>
|
|
|
|
<para>Dumping a volume does not change its VLDB entry or permanently affect its status on the file server machine, but the
|
|
volume's contents are inaccessible during the dump operation. To avoid interrupting access to the volume, it is generally best
|
|
to dump the volume's backup version, just after using the <emphasis role="bold">vos backup</emphasis> or <emphasis
|
|
role="bold">vos backupsys</emphasis> command to create a new backup version.</para>
|
|
|
|
<para>If you do not provide a filename into which to write the dump, the <emphasis role="bold">vos dump</emphasis> command
|
|
directs the output to the standard output stream. You can pipe it directly to the <emphasis role="bold">vos restore</emphasis>
|
|
command if you wish.</para>
|
|
|
|
<para>Because a volume dump file is in ASCII format, you can read its contents using a text editor or a command such as the
|
|
<emphasis role="bold">cat</emphasis> command. However, dump files sometimes contain special characters that do not have
|
|
alphanumeric correlates, which can cause problems for some display programs.</para>
|
|
|
|
<para>By default, the <emphasis role="bold">vos</emphasis> command interpreter consults the Volume Location Database (VLDB) to
|
|
learn the volume's location, so the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
|
|
arguments are not required. If the <emphasis role="bold">-id</emphasis> argument identifies a read-only volume that resides at
|
|
multiple sites, then the command dumps the version from just one of them (normally, the one listed first in the volume's VLDB
|
|
entry as reported by the <emphasis role="bold">vos examine</emphasis> or <emphasis role="bold">vos listvldb</emphasis>
|
|
command). To dump the read-only volume from a particular site, use the <emphasis role="bold">-server</emphasis> and <emphasis
|
|
role="bold">-partition</emphasis> arguments to specify the site. To bypass the VLDB lookup entirely, provide a volume ID
|
|
number (rather than a volume name) as the value for the <emphasis role="bold">-id</emphasis> argument, along with the
|
|
<emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. This makes it possible to
|
|
dump a volume for which there is no VLDB entry.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos dump</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>dump</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_260">
|
|
<title>To dump a 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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Verify that you have the permissions necessary to create the dump file. If placing it in AFS, you must have the
|
|
<emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) permission on the ACL of the file's
|
|
directory. 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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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 id="LIWQ241">
|
|
<para>Issue the <emphasis role="bold">vos dump</emphasis> command to dump the volume.
|
|
<programlisting>
|
|
% <emphasis role="bold">vos dump -id</emphasis> <<replaceable>volume name or ID</replaceable>> [<emphasis role="bold">-time</emphasis> <<replaceable>dump from time</replaceable>>] [<emphasis
|
|
role="bold">-file</emphasis> <<replaceable>arg</replaceable>>] [<emphasis role="bold">-server</emphasis> <<replaceable>server</replaceable>>] [<emphasis
|
|
role="bold">-partition</emphasis> <<replaceable>partition</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-id</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Identifies the volume to be dumped by its complete name or volume ID number. If you want to dump the
|
|
read-only or backup version, specify its volume ID number or add the appropriate extension ( <emphasis
|
|
role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis>) to the name.</para>
|
|
|
|
<para>To bypass the normal VLDB lookup of the volume's location, provide the volume ID number and combine this
|
|
argument with the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
|
|
arguments.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-time</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies whether the dump is full or incremental. Omit this argument to create a full dump, or provide one
|
|
of three acceptable values: <itemizedlist>
|
|
<listitem>
|
|
<para>The value <emphasis role="bold">0</emphasis>(zero) to create a full dump.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A date in the format mm <emphasis role="bold">/</emphasis> dd <emphasis role="bold">/</emphasis> yyyy
|
|
(month, day and year) to create an incremental dump that includes only files and directories with
|
|
modification timestamps later than midnight (12:00 a.m.) on the indicated date. Valid values for the year
|
|
range from <emphasis role="bold">1970</emphasis> to <emphasis role="bold">2037</emphasis>; higher values are
|
|
not valid because the latest possible date in the standard UNIX representation is in 2038. The command
|
|
interpreter automatically reduces later dates to the maximum value. An example is <emphasis
|
|
role="bold">01/13/1999</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A date and time in the format <emphasis role="bold">"</emphasis> mm <emphasis role="bold">/</emphasis>
|
|
dd <emphasis role="bold">/</emphasis> yyyy hh <emphasis role="bold">:</emphasis> MM <emphasis
|
|
role="bold">"</emphasis> to create an incremental dump that includes only files and directories with
|
|
modification timestamps later than the specified date and time. The date format is the same as for a date
|
|
alone. Express the time as hours and minutes (hh:MM) in 24-hour format (for example, <emphasis
|
|
role="bold">20:30</emphasis> is 8:30 p.m.). Surround the entire expression with double quotes (" ") because
|
|
it contains a space. An example is <emphasis role="bold">"01/13/1999 22:30"</emphasis>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the pathname of the file to which to write the dump. The file can be in AFS, but not in the volume
|
|
being dumped. A partial pathname is interpreted relative to the current working directory. Omit this argument to
|
|
direct the dump to the standard output stream.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-server</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the file server machine on which the volume resides. Provide the <emphasis
|
|
role="bold">-partition</emphasis> argument along with this one.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-partition</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the partition on which the volume resides. Provide the <emphasis role="bold">-server</emphasis>
|
|
argument along with this one.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_261">
|
|
<title>About Restoring Volumes</title>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>restoring</secondary>
|
|
|
|
<tertiary>with vos restore command</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>restoring</primary>
|
|
|
|
<secondary>volumes without using AFS Backup System</secondary>
|
|
</indexterm>
|
|
|
|
<para>Although you can dump any of the three types of volumes (read/write, read-only, or backup), you can restore a dump file
|
|
to the file system only as a read/write volume, using the <emphasis role="bold">vos restore</emphasis> command. The command
|
|
automatically translates the dump file's contents from ASCII back into the volume format appropriate for the file server
|
|
machine that stores the restored version. As with the <emphasis role="bold">vos dump</emphasis> command, you can restore a
|
|
dump file via a named pipe, which facilitates interoperation with third-party backup utilities.</para>
|
|
|
|
<para>You can restore the contents of a dump file in one of two basic ways. In either case, you must restore a full dump of
|
|
the volume before restoring any incremental dumps. Any incremental dumps that you then restore must have been created after
|
|
the full dump. If there is more than one incremental dump, you must restore them in the order they were created. <itemizedlist>
|
|
<listitem>
|
|
<para>You can restore volume data into a brand new volume with a new name and at a location that you specify. See <link
|
|
linkend="HDRWQ242">To restore a dump into a new volume and mount it</link>.</para>
|
|
|
|
<para>You can assign a volume ID number as you restore the volume, though it is best to have the Volume Server allocate
|
|
a volume number automatically. The most common reason for specifying the volume ID is that a volume's VLDB entry has
|
|
disappeared for some reason, but you know the former read/write volume ID number and want to reuse it.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You can restore volume data into an existing volume (usually the one that was previously dumped), overwriting its
|
|
current contents. This is convenient if the current contents are corrupted or otherwise incorrect, because it allows you
|
|
to replace them with a coherent version from the past or from one of the volume's clones. See <link
|
|
linkend="HDRWQ244">To restore a dump file, overwriting an existing volume</link>.</para>
|
|
|
|
<para>Provide the <emphasis role="bold">-overwrite</emphasis> argument to preconfirm that you wish to overwrite the
|
|
volume's contents, and to specify whether you are restoring a full or incremental dump. If you omit the <emphasis
|
|
role="bold">-overwrite</emphasis> argument, the Volume Server generates the following prompt to confirm that you want to
|
|
overwrite the existing volume with either a full ( <emphasis role="bold">f</emphasis>) or incremental ( <emphasis
|
|
role="bold">i</emphasis>) dump:</para>
|
|
|
|
<programlisting>
|
|
Do you want to do a full/incremental restore or abort? [fia](a):
|
|
</programlisting>
|
|
|
|
<para>If you pipe in the dump file via the standard input stream instead of using the <emphasis
|
|
role="bold">-file</emphasis> argument to name it, you must include the <emphasis role="bold">-overwrite</emphasis>
|
|
argument because there is nowhere for the Volume Server to display the prompt in this case.</para>
|
|
|
|
<para>You can move the volume to a new site as you overwrite it with a full dump, by using the <emphasis
|
|
role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments to specify the new site. You
|
|
cannot move the volume when restoring an incremental dump.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>The <emphasis role="bold">vos restore</emphasis> command sets the restored volume's creation date in the volume header
|
|
to the time of the restore operation, as reported in the <computeroutput>Creation</computeroutput> field in the output from
|
|
the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos restore</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>restore</secondary>
|
|
|
|
<tertiary>to create new volume</tertiary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ242">
|
|
<title>To restore a dump into a new volume and mount it</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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Verify that you have permissions needed to read the dump file and to mount the new volume. If the dump file resides
|
|
in AFS, you need the <emphasis role="bold">r</emphasis>( <emphasis role="bold">read</emphasis>) permission on the ACL of
|
|
its directory. You need 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 mounting the new 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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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>Select a site (disk partition on a file server machine) for the new volume. If your cell groups different types of
|
|
volumes onto different file server machines, that can guide your decision. It often makes sense to put the volume on the
|
|
emptiest partition that meets your other criteria. To display how much space is 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>. <programlisting>
|
|
% <emphasis role="bold">vos partinfo</emphasis> <<replaceable>machine name</replaceable>> [<<replaceable>partition name</replaceable>>]
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem id="LIWQ243">
|
|
<para>Issue the <emphasis role="bold">vos restore</emphasis> command to create a new volume and
|
|
restore the dump file into it. Type it on a single line; it appears on multiple lines here only for legibility.
|
|
<programlisting>
|
|
% <emphasis role="bold">vos restore</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> \
|
|
<<replaceable>name of volume to be restored</replaceable>> \
|
|
[<emphasis role="bold">-file</emphasis> <<replaceable>dump file</replaceable>>] [<emphasis role="bold">-id</emphasis> <<replaceable>volume ID</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">res</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">restore</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">machine name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine on which to create the new volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">partition name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the partition on which to create the new volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">name of volume to be restored</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the new read/write volume, which must not already have a VLDB entry. It can be up to 22 characters in
|
|
length.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the dump file to restore. Partial pathnames are interpreted with respect to the current working
|
|
directory. Omit this argument if using a pipe to read in the dump file from the standard input stream.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-volume</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the new volume's ID number. It is appropriate only if you are restoring a volume that no longer
|
|
exists and want to use the volume ID number it had previously.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs mkmount</secondary>
|
|
|
|
<tertiary>when restoring volume</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>mkmount</secondary>
|
|
|
|
<tertiary>when restoring volume</tertiary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the new volume, making its contents
|
|
accessible. Complete instructions appear in <link linkend="HDRWQ212">To create a regular or read/write mount point</link>.
|
|
<programlisting>
|
|
% <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>>
|
|
</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> <<replaceable>directory</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos restore</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>restore</secondary>
|
|
|
|
<tertiary>to overwrite volume</tertiary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ244">
|
|
<title>To restore a dump file, overwriting an existing 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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Verify that you have permissions needed to read the dump file. If it resides in AFS, you need the <emphasis
|
|
role="bold">r</emphasis>( <emphasis role="bold">read</emphasis>) permission on the ACL of its directory. 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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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>Restore the contents of the dump file into a read/write volume, overwriting the current contents. The volume retains
|
|
its current volume ID number. Type it on a single line; it appears on multiple lines here only for legibility.
|
|
<programlisting>
|
|
% <emphasis role="bold">vos restore</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> \
|
|
<<replaceable>name of volume to be restored</replaceable>> \
|
|
[<emphasis role="bold">-file</emphasis> <<replaceable>dump file</replaceable>>] [<emphasis role="bold">-id</emphasis> <<replaceable>volume ID</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">res</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">restore</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">machine name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine where the volume already exists, or the machine to which to move it. In the
|
|
latter case, the value for the <emphasis role="bold">-overwrite</emphasis> argument must be <emphasis
|
|
role="bold">full</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">partition name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the partition where the volume already exists, or the partition to which to move it. In the latter
|
|
case, the value for the <emphasis role="bold">-overwrite</emphasis> argument must be <emphasis
|
|
role="bold">full</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">name of volume to be restored</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the read/write volume to overwrite with the contents of the dump file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the dump file to restore. Partial pathnames are interpreted with respect to the current working
|
|
directory. Omit this argument if using a pipe to read in the dump file from the standard input stream; in this
|
|
case, you must provide the <emphasis role="bold">-overwrite</emphasis> argument.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-overwrite</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Preconfirms that you want to overwrite the existing volume and specifies which type of dump file you are
|
|
restoring. Provide one of the following values: <itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">f</emphasis> or <emphasis role="bold">full</emphasis> if restoring a full dump
|
|
file</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">i</emphasis> or <emphasis role="bold">incremental</emphasis> if restoring an
|
|
incremental dump file. This value is not acceptable if you are moving the volume while restoring it.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">a</emphasis> to terminate the restore operation</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the volume is replicated, issue the <emphasis role="bold">vos release</emphasis> command to release the newly
|
|
restored contents to read-only sites. Complete instructions appear in <link linkend="HDRWQ192">Replicating Volumes
|
|
(Creating Read-only Volumes)</link>. <programlisting>
|
|
% <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">vos backup</emphasis> command to create a new backup version of the volume. Complete
|
|
instructions appear in <link linkend="HDRWQ201">Creating Backup Volumes</link>. <programlisting>
|
|
% <emphasis role="bold">vos backup</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ245">
|
|
<title>Renaming Volumes</title>
|
|
|
|
<indexterm>
|
|
<primary>renaming</primary>
|
|
|
|
<secondary>volume</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>renaming</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>changing</primary>
|
|
|
|
<secondary>volume name</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>volume name</primary>
|
|
|
|
<secondary>changing</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<para>You can use the <emphasis role="bold">vos rename</emphasis> command to rename a volume. For example, it is appropriate to
|
|
rename a user's home volume if you use the <emphasis role="bold">user.</emphasis> username convention for user volume names and
|
|
you change the username. (For complete instructions for changing usernames, see <link linkend="HDRWQ518">Changing
|
|
Usernames</link>.)</para>
|
|
|
|
<indexterm>
|
|
<primary>read/write volume</primary>
|
|
|
|
<secondary>changing name of</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>read-only volume</primary>
|
|
|
|
<secondary>changing name of</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>backup volume</primary>
|
|
|
|
<secondary>changing name of</secondary>
|
|
</indexterm>
|
|
|
|
<para>The <emphasis role="bold">vos rename</emphasis> command accepts only read/write volume names, but automatically changes
|
|
the names of the associated read-only and backup volumes. As directed in the following instructions, you need to replace the
|
|
volume's current mount point with a new one that reflects the name change.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos rename</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>rename</secondary>
|
|
|
|
<tertiary>basic instructions</tertiary>
|
|
</indexterm>
|
|
|
|
<sect2 id="HDRWQ246">
|
|
<title>To rename a 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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Verify that you have the <emphasis role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>), <emphasis
|
|
role="bold">d</emphasis>( <emphasis role="bold">delete</emphasis>), and <emphasis role="bold">i</emphasis>( <emphasis
|
|
role="bold">insert</emphasis>) access permissions for the directory in which you are replacing the volume's 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> [<<replaceable>dir/file path</replaceable>>]
|
|
</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 id="LIVOL-REN">
|
|
<para>Issue the <emphasis role="bold">vos rename</emphasis> command to rename the volume.
|
|
<programlisting>
|
|
% <emphasis role="bold">vos rename</emphasis> <<replaceable>old volume name</replaceable>> <<replaceable>new volume name</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">ren</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">rename</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">old volume name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the current name of a read/write volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">new volume name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the new name for the volume. It cannot be more than 22 characters in length.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<para>If there is no Volume Location Database (VLDB) entry for the specified current volume name, the command fails with
|
|
the following error message:</para>
|
|
|
|
<programlisting>
|
|
vos: Could not find entry for volume old_volume_name.
|
|
</programlisting>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs rmmount</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>rmmount</secondary>
|
|
|
|
<tertiary>when renaming volume</tertiary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs rmmount</emphasis> command to remove the mount point that refers to the volume's
|
|
old name. Complete instructions appear in <link linkend="HDRWQ215">To remove a mount point</link>. <programlisting>
|
|
% <emphasis role="bold">fs rmmount</emphasis> <<replaceable>directory</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>fs mkmount</secondary>
|
|
|
|
<tertiary>when renaming volume</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>fs commands</primary>
|
|
|
|
<secondary>mkmount</secondary>
|
|
|
|
<tertiary>when renaming volume</tertiary>
|
|
</indexterm>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">fs mkmount</emphasis> to create a mount point that indicates the volume's new name.
|
|
Complete instructions appear in <link linkend="HDRWQ212">To create a regular or read/write mount point</link>.
|
|
<programlisting>
|
|
% <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> [<emphasis
|
|
role="bold">-rw</emphasis>]
|
|
</programlisting></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ247">
|
|
<title>Unlocking and Locking VLDB Entries</title>
|
|
|
|
<para>As detailed in <link linkend="HDRWQ227">Synchronizing the VLDB and Volume Headers</link>, The Volume Location (VL) Server
|
|
locks the Volume Location Database (VLDB) entry for a volume before the Volume Server executes any operation on it. No other
|
|
operation can affect a volume with a locked VLDB entry, so the lock prevents the inconsistency or corruption that can result
|
|
from multiple simultaneous operations on a volume.</para>
|
|
|
|
<indexterm>
|
|
<primary>locking</primary>
|
|
|
|
<secondary>VLDB entry</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>VLDB</primary>
|
|
|
|
<secondary>locking/unlocking entry</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>entry in VLDB</primary>
|
|
|
|
<secondary>locking/unlocking</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>unlocking</primary>
|
|
|
|
<secondary>VLDB entry</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>locked VLDB entry</primary>
|
|
|
|
<secondary>unlocking</secondary>
|
|
</indexterm>
|
|
|
|
<para>To verify that a VLDB entry is locked, issue the <emphasis role="bold">vos listvldb</emphasis> command as described in
|
|
<link linkend="HDRWQ218">To display VLDB entries</link>. The command has a <emphasis role="bold">-locked</emphasis> flag that
|
|
displays locked entries only. If the VLDB entry is locked, the string <computeroutput>Volume is currently
|
|
LOCKED</computeroutput> appears on the last line of the volume's output.</para>
|
|
|
|
<para>To lock a VLDB entry yourself, use the <emphasis role="bold">vos lock</emphasis> command. This is useful when you suspect
|
|
something is wrong with a volume and you want to prevent any changes to it while you are investigating the problem.</para>
|
|
|
|
<para>To unlock a locked VLDB entry, issue the <emphasis role="bold">vos unlock</emphasis> command, which unlocks a single VLDB
|
|
entry, or the <emphasis role="bold">vos unlockvldb</emphasis> command, which unlocks potentially many entries. This is useful
|
|
when a volume operation fails prematurely and leaves a VLDB entry locked, preventing you from acting to correct the problems
|
|
resulting from the failure.</para>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos lock</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>lock</secondary>
|
|
</indexterm>
|
|
|
|
<sect2 id="Header_267">
|
|
<title>To lock a VLDB entry</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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">vos lock</emphasis> to lock the entry. <programlisting>
|
|
% <emphasis role="bold">vos lock</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">lo</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">lock</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">volume name or ID</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Identifies the volume to be locked, either by its complete name or volume ID number. It can be any of the
|
|
three versions of the volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos unlock</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>unlock</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_268">
|
|
<title>To unlock a single VLDB entry</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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">vos unlock</emphasis> command to unlock the entry. <programlisting>
|
|
% <emphasis role="bold">vos unlock</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">unlock</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 volume to be unlocked, either by its complete name or volume ID number. It can be any of the
|
|
three versions of the volume.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>vos unlockvldb</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>vos commands</primary>
|
|
|
|
<secondary>unlockvldb</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_269">
|
|
<title>To unlock multiple VLDB entries</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> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">vos unlockvldb</emphasis> command to unlock the desired entries. <programlisting>
|
|
% <emphasis role="bold">vos unlockvldb</emphasis> [<<replaceable>machine name</replaceable>>] [<<replaceable>partition name</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">unlockv</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">unlockvldb</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">machine name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies a file server machine. Provide this argument alone to unlock all VLDB entries that mention the
|
|
machine in a site definition. Omit both this argument and the partition name argument to unlock all VLDB
|
|
entries.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">partition name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies a partition. Provide this argument alone to unlock all VLDB entries that mention the partition (on
|
|
any machine) in a site definition. Omit both this argument and the machine name argument to unlock all VLDB
|
|
entries.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|