![[Return to Library]](../books.gif)
![[Contents]](../toc.gif)
![[Previous Topic]](../prev.gif)
![[Bottom of Topic]](../bot.gif)
![[Next Topic]](../next.gif)
![[Index]](../index.gif)
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.
| Create a ReadWrite volume | vos create |
| Create a ReadOnly volume | vos addsite and/or vos release |
| Create a Backup volume | vos backup |
| Create many Backup volumes at once | vos backupsys |
| Examine VLDB entry | vos listvldb |
| Examine volume header | vos listvol |
| Examine both VLDB entry and volume header | vos examine |
| Learn a volume's name | fs listquota or fs examine |
| Learn a volume's ID number | fs examine or vos examine or vos listvol |
| List partition's size and space available | vos partinfo |
| Learn a volume's location | fs whereis or vos examine |
| Create a mount point | fs mkmount |
| Remove a mount point | fs rmmount |
| Examine a mount point | fs lsmount |
| Move a ReadWrite volume | vos move |
| Synchronize VLDB and volumes | vos syncvldb and vos syncserv |
| Set volume quota | fs setvol or fs setquota |
| Examine volume quota | fs quota or fs listquota or fs examine |
| Learn a volume's current size | fs listquota or fs examine |
| List all volumes on a machine/partition | vos listvol |
| Remove a ReadWrite volume | vos remove and fs rmmount |
| Remove a ReadOnly volume | vos remove |
| Remove a Backup volume | vos remove and fs rmmount |
| Remove a volume; no VLDB change | vos zap |
| Remove a mistaken ReadOnly site definition | vos remsite |
| Remove a VLDB entry; no volume change | vos delentry |
| Dump a volume | vos dump |
| Restore a dumped volume | vos restore |
| Rename a volume | vos rename, fs rmmount and fs mkmount |
| Unlock a volume | vos unlock |
| Unlock multiple volumes | vos unlockvldb |
| Lock a volume | vos lock |
A volume is a logical unit of disk space that functions like a container for the files in a 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 certain directory location in the file tree. This association (or link) between the volume and its file tree location is referred to as a mount point, and because of AFS's internal workings it looks and acts just like a standard directory element. Thus users can access and manipulate a volume's contents in the same ways they access and manipulate the contents of a standard UNIX directory. For more on the relationship between volumes and directories, see About Mounting Volumes.
Many of your daily activities involve manipulating volumes, since they are the basic storage and administrative unit of AFS. Some of the ways volumes can make your job easier are explained in How Volumes Improve System Efficiency.
There are three types of volumes in AFS: ReadWrite, ReadOnly, and Backup. These types are described below:
| Note: | 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 Backing Up Data. |
As the preceding paragraphs indicate, the three types of volumes are related to one another: ReadOnly and Backup volumes are both derived from a ReadWrite volume through a process called cloning. ReadOnly and Backup volumes are exact copies of the ReadWrite source at the time they are created. Thus the different types can be thought of as different versions of a volume.
The use of volumes makes your cell easier to manage and more efficient in three ways:
The Volume Location Database (VLDB) records information about all volumes in a cell. One of the most important pieces of information found in the VLDB is the volume location. Whenever a user requests a file, the Cache Manager contacts the Volume Location (VL) Server, which maintains the VLDB, in order to learn which file server machine is housing the volume that contains the file. The Cache Manager can then request the file from the File Server running on that file server machine. This automatic location of volumes means that access is transparent in AFS and users do not have to keep track of file location.
There is an entry in the VLDB for each ReadWrite volume that also contains information about the ReadOnly and Backup versions of the volume. ReadOnly and Backup volumes do not have their own VLDB entries. (The exception to this rule is that a ReadOnly volume has its own VLDB entry if its ReadWrite source has been removed.)
The following information is available from a VLDB entry:
The vos listvldb command displays much of the information from the VLDB. The vos examine command also displays VLDB information in combination with volume header information. For descriptions of their output, see Displaying Information About Volumes.
While there is only a single VLDB entry for each ReadWrite volume and its ReadOnly and Backup versions, there is a separate volume header at the site of each copy of a volume no matter its version. The volume header is the volume in a sense -- it is a data structure that records the physical memory addresses on the partition that store the files in the volume. The volume header binds all the files into a logical unit without requiring that they be stored in contiguous memory blocks. In addition to data location, the volume header stores other information about the volume, some of it redundant with the VLDB, so that the Volume Server can access the information even when the VLDB is unavailable.
The information in the volume header includes the following:
An access is defined as a fetch or store operation on any file system object stored in the volume.
The Volume Server determines the client machine's network by comparing the network portion of the IP address to the server machine's, based on the class of network (A, B, or C). If the network portion of the IP addresses match, it is the same network; otherwise, it is considered a different network.
The vos listvol command displays information from the volume header. The vos examine command also displays information from the volume header, in combination with VLDB information. For descriptions of their output, see Displaying Information About Volumes.
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 the VL Server gives the Cache Manager an incorrect volume location, the latter cannot find the volume. To keep the VLDB accurate, all vos commands that affect volume status automatically record the change in the appropriate VLDB entry.
Whenever you issue a command that changes volume status, the Volume Server and VL Server cooperate in the following sequence of steps:
If vos operations end prematurely, it is possible for the VLDB and the volumes on file server machines to get out of sync. How to resynchronize them is explained in Synchronizing the VLDB and Volume Headers.
If you want a volume's contents to be visible and accessible to users, you must mount the volume at a directory location in your cell's file tree. When you mount a volume, you create an association between the volume and a directory location; this association is called a mount point. To mount a volume, you must have insert (i) and administer (a) permissions in the directory where the mount point is to be created.
An AFS mount point appears and functions like a regular UNIX file system directory, but structurally it is simply a one-line file that indicates the name of the volume associated with the directory. A mount point appears and acts just like a directory because of the way the Cache Manager handles it.
Consider the common case where the Cache Manager needs to retrieve a file requested by a user's application program. In order to determine where the file resides, the Cache Manager has to traverse the file's complete pathname, starting at the root /afs directory and continuing all the way to the file itself. When the Cache Manager encounters a mount point during the traversal, it reads it to learn which volume is associated with that directory location. The Cache Manager then looks in the indicated volume and fetches its root directory. The root directory of a volume lists all the files, subdirectories, and mount points that reside in the volume. The Cache Manager looks up the next element in the pathname in the root directory listing, continuing to interpret any further mount points it encounters until it reaches the volume that houses the requested file.
It is the Cache Manager's ability to interpret mount points that makes them look and act just like directory elements. Mount points act as the glue that connects the file system tree together, 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.
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 file tree. Second, it can confuse the Cache Manager about which pathname it followed in order to reach the file (causing unpredictable output from the pwd command, for example). If you mount a volume at more than one directory, the ACL associated with the root directory of the volume applies to all of its mount points.
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 Mounting Volumes.
You can choose any name for a volume that best indicates its contents to you, keeping two restrictions in mind:
One convention is to name all user volumes user.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. More conventions for volume names are presented in Creating Volumes.
A ReadWrite volume is the most basic type of volume, and must exist before you can create ReadOnly or Backup versions of it. When you issue the vos create command to create a ReadWrite volume, several AFS server processes perform the following actions:
After creating a volume, use the fs mkmount command to mount it at a directory location in the file system, as directed in the following instructions. Until you do, the volume's contents are inaccessible.
% bos listusers <machine name>
% fs listacl [<dir/file path>]
Members of the system:administrators group always implicitly have the administer (a) and by default also the lookup (l) permission on every ACL and can use the fs setacl command to grant other rights as necessary.
| Note: | The partition size reported by this command does not necessarily match the figure reported by the standard UNIX df command. The total reported by the df command includes some reserved space that this command does not, and so is often about 10% larger. |
% vos partinfo <machine name> [<partition name>]
where
% vos create <machine name> <partition name> <volume name> \
[-maxquota <initial quota (KB)>]
where
% fs mkmount <directory> <volume name>
where
% fs lsmount <directory>
% fs setvol <dir/file path> -offlinemsg <offline message>
Two defaults are set when a ReadWrite volume is created with the vos create command:
After you have created and mounted a volume, you can change the default ACL on its root directory and the default quota at any time. Use the fs setacl command to set the ACL, removing the system:administrators group if desired; see Setting ACL Entries. To change the volume's quota, use the fs setquota command as instructed in Setting and Listing Volume Quota and Current Size.
During the creation of Backup and ReadOnly volumes, a clone is created from the ReadWrite source volume; this process is referred to as cloning. The creation of a clone is completely internal to the commands that create ReadOnly and Backup volumes; you never need to create a clone manually as a step in the creation of ReadOnly or Backup volumes.
A clone is not a copy of the data in the ReadWrite source volume, but rather a copy of the ReadWrite volume's vnode index. A vnode index is a table of pointers between each file in the volume and the physical disk blocks where that file's data resides on the partition. From the clone, Backup and ReadOnly volumes are created in the following manner:
Figure 1. File Sharing Between ReadWrite and Backup/ReadOnly Clone Volumes
 |
Replication is the creation of a clone of the ReadWrite volume and the distribution of the clone to one or more sites. Replication increases system efficiency and boosts data availability by making a volume's contents accessible on more than one file server machine.
A replicated volume takes up as much disk space as its source ReadWrite volume unless it is placed on the same partition as its source. That is why it is recommended that you place a ReadOnly volume at the same site as the ReadWrite source. This ReadOnly clone provides all of the benefits of a stand-alone ReadOnly volume but takes up less disk space.
It is best to replicate only volumes containing files and directories that satisfy the following criteria:
In AFS, replicating a volume is a two stage process:
It is important to know if replication (Stage 2 in particular) is completely successful or not because all copies of the ReadOnly version must be identical to one another and to their ReadWrite source. The point of replicating a volume is to allow the Cache Manager to access the copy of the volume that is easiest to reach at a given time while guaranteeing that the data retrieved does not vary depending on which copy the Cache Manager reaches.
To guarantee that all the ReadOnly copies match each other and the ReadWrite version, Stage 2 must be all-or-nothing: either all ReadOnly sites receive the new version or they all keep the version they already have. If an error occurs during the execution of vos release command (corresponding to Stage 2), an error message tells you which of the defined ReadOnly sites did not receive the new version.
You can also determine if a release is successful by checking for the presence of two flags (Old release and New release) in the VLDB entry. The Volume Server and VL Server set these flags for their own use as they execute sub-steps in Stage 2, but the flags can serve as a useful failure signal. The Volume Server and VL Server set the flag as follows (these substages are internal and do not correspond to any action on your part after you issue the vos release command):
The presence of New release or Old release flags or the ReleaseClone ID in the VLDB after the completion of Stage 2 indicates that the release was not successful.
You must fix the problem; otherwise, it is quite possible that Cache Managers access different versions of a volume on different file server machines.
The best solution if a release is incomplete is to continue issuing the vos release command until the Old release and New release flags and the ReleaseClone ID no longer appear in the VLDB entry. You can examine the VLDB entry with the vos examine command (described in Step 2 of the instructions below).
By default, the Volume Server does not try to make a new clone every time you issue the vos release command. Instead, its behavior depends on whether or not all of the ReadOnly sites have identical copies of the volume:
It is often wise to create a new clone no matter what the status of copies at the ReadOnly sites. To do this, use the -f flag to the vos release command.
Because replication is a two stage process, you can choose to perform only some of the steps depending upon the current situation:
When the Cache Manager encounters the mount point for a ReadWrite volume, it contacts the VL Server to learn where the volume resides. If the mount point is regular and resides in a ReadOnly volume, the Cache Manager also checks if the volume exists in a ReadOnly version. If it does, the Cache Manager attempts to access any of the available ReadOnly copies of that volume. This is referred to as following a ReadOnly path. Using files on ReadOnly volumes puts less of a load on the File Server because only one callback is required per ReadOnly volume as opposed to a callback per file for ReadWrite volumes. The Cache Manager gets on a ReadOnly path by default because it is biased toward accessing the ReadOnly version of root.afs if it is available. (For more information about the rules that the Cache Manager follows when accessing volumes, see The Rules of Mount Point Traversal.)
Explicitly mounting a ReadOnly volume (creating a mount point that indicates the ReadOnly rather than the ReadWrite version of a volume) is not generally necessary nor is it recommended. The Cache Manager finds the ReadOnly version of a volume even though it is not itself mounted.
Place a ReadOnly copy of a volume at the ReadWrite site, because the Cache Manager does not switch to using the ReadWrite volume when all other ReadOnly volumes become unavailable. Furthermore, a ReadOnly copy located at the ReadWrite site does not consume much disk space because the two volumes share inodes when possible. (The ReadOnly volume requires as much disk space as the ReadWrite volume only if the latter changes drastically.)
Only one ReadOnly volume can be placed on any single server.
% bos listusers <machine name>
% vos examine <volume name or ID>
where
The last lines in the output display the volume's current sites. An example of the output is shown in Examining Both the VLDB Entry and Volume Header for a Volume.
% vos partinfo <machine name> [<partition name>]
% vos addsite <machine name> <partition name> <volume name or ID>
where
% bos status <machine name> fs vlserver
% vos release <volume name or ID> [-f]
where
% vos listvldb <volume name or ID>
As explained in How Volumes Improve System Efficiency, backing up a volume refers to creating a clone of the ReadWrite version of a volume and placing it at the same site as the ReadWrite version. Creating a Backup version of a volume has two purposes:
| Note: | Creating a Backup volume is not the same as permanent storage of the data in that volume on tape; however, making a Backup volume is one step in the latter task. To learn about the AFS Backup System, see Configuring the AFS Backup System and Backing Up and Restoring AFS Data. |
The vos backupsys command creates a Backup version of many ReadWrite volumes at once. This command is useful when preparing for large-scale backups to tape (for information about the AFS Backup System, see Configuring the AFS Backup System and Backing Up and Restoring AFS Data). Combine the command's argument as indicated to create a Backup version of different groups of volumes:
To backup a single volume, use the vos backup command, which employs a more streamlined technique for finding a single volume.
Most cells find that it is best to make a new Backup version of each volume every day at the same time. A time when usage is low is preferable, because making the Backup causes the ReadWrite volume to be unavailable momentarily.
You can either issue the necessary the vos backupsys or vos backup commands at the console or create a cron entry in the BosConfig file on each file server where you want to back up volumes. Recall from The Types of Processes that a cron process is one that executes only at the time you specify. The advantage of using a cron process is that the backups can be made during a low-usage period without requiring a system administrator to be present to issue commands.
The following example command would create a cron process called backupusers in the BosConfig file on the machine fs3.abc.com. The process would execute every day at 1:00 a.m., making a Backup version of every volume in the file system whose name started with the string user. The -localauth flag is necessary so that the process, which runs unauthenticated, is allowed to execute the privileged vos backupsys command. Note that it is necessary to provide the complete pathname of the command to be executed.
% bos create fs3.abc.com backupusers cron \
-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" "1:00"
Unlike ReadOnly volumes, it does make sense to mount Backup volumes to make their contents available to users. The most sensible place to mount the Backup version of a user volume is at a subdirectory of the user's home directory (Step 4 below explains how to mount a Backup volume). By making each user's Backup volume available in this way, the user can restore files accidentally deleted or changed since the last Backup was made, without having to request help from you.
Suitable names for this directory might be OldFiles or Backup. The subdirectory looks just like the user's own home directory, with all files and subdirectories in the same relative positions.
If you do create and mount Backup volumes for your users, inform users of their existence. The AFS User's Guide 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 cp 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 ReadWrite volume quota.
% bos listusers <machine name>
% fs listacl [<dir/file path>]
Members of the system:administrators group always implicitly have the administer (a) and by default also the lookup (l) permission on every ACL and can use the fs setacl command to grant other rights as necessary.
% vos backup <volume name or ID> Created backup volume for volume name or ID
where
% fs mkmount <directory> <volume name>.backup
where
% fs lsmount <directory>
% bos listusers <machine name>
% vos backupsys [-prefix <common prefix on volume(s)>] \
[-server <machine name>] [-partition <partition name>] \
[-exclude]
where
The reasons it is necessary to mount a volume, and what the Cache Manager does when it encounters a mount point during pathname interpretation are explained in About Mounting Volumes. This section provides additional information on mount points, including information on the rules of mount point traversal, a discussion of the three types of mount points, their purposes, and how to distinguish between them, and instructions for creating, removing, and examining mount points.
This section contains information on the rules that the Cache Manager follows as it traverses the AFS mount points. There are three basic rules:
When the Cache Manager encounters a mount point that specifies a volume with either a .readonly or a .backup extension, it accesses that type of volume only. If a mount point does not have either a .backup or .readonly extension, the Cache Manager uses Rules 2 and 3.
For example, the Cache Manager never accesses the ReadWrite version of a volume if the mount point names the Backup version. If the specified version is inaccessible, the Cache Manager reports an error.
The Cache Manager has a built-in bias toward accessing a ReadOnly copy of the root.afs volume which corresponds to the top-level /afs directory. If a ReadOnly copy of root.afs is available, it is accessed in preference to the ReadWrite volume. When the Cache Manager encounters a mount point located in a ReadOnly volume, it attempts to access a ReadOnly copy of the volume that the mount point references; if the referenced volume is not replicated, it accesses the ReadWrite volume. The Cache Manager is thus forced onto a "ReadOnly path" because while on it the Cache Manager accesses ReadOnly versions when available, and accesses the ReadWrite volume only when no ReadOnly copies exist, increasing system performance and improving file availability.
| Note: | You must replicate both the root.afs and root.cell volumes (corresponding to the /afs and /afs/cellname directories, respectively) to ensure the Cache Manager's access to the other replicated volumes in your cell. |
When the Cache Manager encounters a mount point in a ReadWrite volume, the Cache Manager only attempts to access a ReadWrite volume referenced by that mount point; failing this, the access attempt fails. While the Cache Manager traverses ReadWrite volumes, it is said to be following the "ReadWrite path;" once on a ReadWrite path, the Cache Manager cannot return to a ReadOnly path. (but see the discussion of cellular mount points in The Three Types of Mount Points.)
There are three types of mount points, each of which is appropriate for different purposes and each of which follows the rules of mount point traversal to a different extent:
The vast majority of your mount points are regular mount points without any extension. Using regular mount points as much as possible promotes the most efficient use of both replicated and nonreplicated volumes and, assuming your volumes are distributed in a balanced manner, the most efficient use of your system resources.
This is because there are normally multiple ReadOnly copies of a volume but only one ReadWrite version. It makes sense to access one of the more numerous ReadOnly copies when available, rather than a single ReadWrite version. And since a regular mount point does not force access to ReadOnly volumes if they do not exist, the Cache Manager still accesses the ReadWrite volume when on a ReadWrite path or when it encounters a regular mount point and there are no ReadOnly copies of the referenced volume.
To create a regular mount point, use the fs mkmount command.
| Note: | You must replicate all volumes that the Cache Manager needs to access while traversing the path to a replicated volume; if there is no ReadOnly version of a given volume, the Cache Manager switches onto a ReadWrite path and does not access ReadOnly volumes mounted lower in the filespace. |
It is conventional to create only one ReadWrite mount point in your file tree, to mount your cell's root.cell volume at the second level just below the /afs directory. The root.cell volume with a regular mount point at the same level]. The two mount points are typically distinguished by the placement of a period at the start of the ReadWrite mount point's name.
The existence of a ReadWrite mount point in the file tree--the one for root.cell--is sufficient to put the Cache Manager on a ReadWrite path all the way down the pathnames in your cell when a user needs to access ReadWrite volumes specifically. Meanwhile, the existence of a regular mount point for root.cell allows the Cache Manager to follow the ReadOnly path when possible.
Mounting a ReadOnly or Backup volume with a ReadWrite mount point is possible, but unnecessary. If the mount point references one of those versions explicitly, then the Cache Manager accesses it explicitly, ignoring whether their mount point is regular or ReadWrite. (See Rule 1.)
You designate a mount point as ReadWrite by using the -rw flag on the fs mkmount command. By convention, you also put a period at the front of the mount point name. See the instructions in the following section.
It is conventional to place cellular mount points only at the second level in your cell's file tree, just below the /afs directory, to mount the root.cell volumes of foreign cells that you wish to make visible to your cell's users. It is possible to create cellular mount points (mount foreign volumes) at other levels in the tree; however, doing so is not recommended as it is easy for users to become confused if the Cache Manager switches from cell to cell at different points in a pathname.
Cellular mount points can be either regular or ReadWrite:
To create a regular cellular mount point, you use the -cell argument to specify the cell name.
To create a ReadWrite cellular mount point, use the -cell argument to specify the cell name and add the -rw flag. Because this is not recommended, no example of it is provided.
You can distinguish regular and ReadWrite mount points from one another in two ways:
If a mount point is cellular, then the cell name and a colon appears just in front of the volume name in the output from the fs lsmount command. (The pound sign or percent sign also appears, with the same meaning as for non-cellular mount points.)
The following examples show how these indicators work together:
% fs lsmount /afs/abc.com/usr/terry '/afs/abc.com/usr/terry' is a mount point for volume '#user.terry' % fs lsmount /afs/.abc.com '/afs/.abc.com' is a mount point for volume '%abc.com:root.cell' % fs lsmount /afs/abc.com '/afs/abc.com' is a mount point for volume '#abc.com:root.cell'
The first mount point is a regular, non-cellular mount point; the second mount point is a ReadWrite, cellular mount point; the third mount point is a regular, cellular mount point. The volume root.cell is mounted in both ways so that when users want to make sure that they access the ReadWrite version of root.cell, they specify /afs/.abc.com; if they do not care which version of the volume they access, they specify /afs/abc.com and rely on the mount point traversal rules to get them to the appropriate version (in this case the ReadOnly version).
% fs listacl [<dir/file path>]
% fs mkmount <directory> <volume name>
where
% fs listacl [<dir/file path>]
% fs mkmount .<directory> <volume name> -rw
where
% fs listacl [<dir/file path>]
% fs mkmount <directory> <volume name> <cell name>
where
% fs listacl [<dir/file path>]
Members of the system:administrators group always implicitly have the administer (a) and by default also the lookup (l) permission on every ACL and can use the fs setacl command to grant other rights as necessary.
% fs rmmount <directory>
where
% fs lsmount <directory>
where
Examples of the output from this command appear in the introduction to this section. If directory is not a mount point, an error message appears. In that case, examine the directory's parent directory to discover if it is a mount point.
Creating a mount point in foreign cells is accomplished in the same way as creating a mount point in the local cell.
This section contains instructions for using commands to access information about volumes. Some of these commands allow you to examine information from the VLDB, the volume header, or both; these commands require that you know the volume's name or volume ID. Other commands provide volume information even if you only know the name of a file or directory in the volume. Though this information is more limited in scope, it does provide you with the information to map file and directory names to volume names and ID numbers.
Instructions for listing a volume's quota are provided in Setting and Listing Volume Quota and Current Size.
The vos listvldb 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:
% vos listvldb [<volume name or ID>] [-server <machine name>] \
[-partition <partition name>] [-locked]
where
The output of the command includes:
An example of this command and its output:
% vos listvldb user.terry
user.terry
RWrite: 50489902 ROnly 0 Backup: 50489904
number of sites -> 1
server fs3.abc.com partition /vicepa RW Site
The vos listvol command displays the volume header for every volume on a file server machine or for a specified partition on that file server machine. To get this information, the vos listvol commands contacts the Volume Server on the specified machine. You can control the amount of information displayed by including the -fast, the -long, or the -extended flag; see the definition and examples below.
To see the volume header of one volume only, use the vos examine command, described in Examining Both the VLDB Entry and Volume Header for a Volume.
% vos listvol <machine name> [<partition name>] [-fast] [-long] [-extended]
where
Output with the -fast Flag
When you use the -fast flag, the output displays only the volume ID number of each volume, and reports the total number of volumes in the listing.
An example of the output when the -fast flag is included:
% vos listvol fs3.abc.com /vicepa -f
Total number of volumes on server fs3.abc.com \
partition /vicepa: 37
50489902
50489904
.
.
35970325
49732810
Output with No Flags
When you do not use the -fast, the -long, or the -extended flag, the information includes the volume's
The first line of the output tells how many volumes appear in the listing, and the last line how many of those are on-line, off-line, and busy.
An example of the output when no flags are included:
% vos listvol fs2.abc.com b
Total number of volumes on server fs2.abc.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
When you include the -long flag, the output gives additional information:
An example of the output when the -long flag is included:
% vos listvol fs2.abc.com b -long
Total number of volumes on server fs2.abc.com
partition /vicepb: 66
. . . . . .
. . . . . .
user.pat 1969534536 RW 17518 K On-line
fs2.abc.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.abc.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
Output with the -extended Flag
When you include the -extended flag, the output contains the following two statistical tables entitled Raw Read/Write Stats and Writes Affecting Authorship. These tables provide the following information:
| Note: | Diff Network versus Same Network is determined by comparing the network portion of the IP address based on the class of network (A, B, or C). If the network portion of the IP addresses for the client and server match, it is the same network; otherwise, it is considered a different network. |
An example of the output when the -extended flag is included:
% vos listvol fs3.abc.com a -extended
common.bboards 1969535592 RW 23149 K used 9401 files On-line
fs3.abc.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 |
|-------------------------------------------|
The vos examine 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.
| Note: | Because this command retrieves information from the volume header, you need to specify which version of the volume you are interested in (that is, add the .readonly or .backup extension if necessary). The information from the VLDB is the same no matter which version you look at. An error message results if the ReadWrite version no longer exists and you forget to specify the .readonly or .backup extension. |
% vos examine <volume name or ID>
where
The top part of the output lists the same information from a volume header as when you issue the vos listvol command with the -long flag. The bottom part of the output lists the same information from the VLDB as when you issue the vos listvldb command. See Displaying the VLDB Entry for One or More Volumes and Examining the Volume Header for One or More Volumes, respectively.
Below is an example for a volume whose VLDB entry is currently locked. If it were not locked, the "LOCKED" line would not appear.
% vos examine user.terry
user.terry 536870981 RW 3459 K On-line
fs3.abc.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)
LOCKED
RWrite: 5360870981 Backup: 536870983
number of sites -> 1
server fs3.abc.com partition /vicepa RW Site
The commands listed below are used to help you obtain information about a volume when you know only a few things about it, such as the name of a file in it, or its volume ID number.
% fs listquota [<dir/file path>]
where
The following is an example of the output:
% fs listquota /afs/abc.com/usr/terry Volume Name Quota Used % Used Partition user.terry 15000 5071 34% 86%
% fs examine [<dir/file path>]
where
An example of the output from this command:
% fs examine /afs/abc.com/usr/terry 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
| Note: | The partition-related numbers that appear in the last line of this output do not always agree with the corresponding numbers in the output of the standard UNIX df command. The df output reflects the state of partitions exactly when the command is issued. The numbers in this command's output can be as much as five minutes old, as the Cache Manager polls the File Server for partition information at that frequency. In addition, the partition size reported by the UNIX df command includes some reserved space that does not show up in this report of partition size and so it is likely to be about 10% larger. |
% vos examine <volume name or ID>
% vos listvol <machine name> [<partition name>]
% fs listquota [<dir/file path>]
% vos listvldb <volume name or ID>
% vos listvldb <volume name or ID>
There are three main reasons to move volumes:
afs: failed to store file (partition full)
You can track the amount of a partition's space in use by using the AFS monitoring program called Scout, other AFS commands, and UNIX commands. For more information on the Scout program, see Monitoring and Auditing AFS Performance.
ReadWrite volumes are the only ones you can actually move, using the vos move command. It is not possible to move the Backup version of a volume. When you move a ReadWrite volume, the Backup version is deleted automatically. You are strongly encouraged to replace the deleted Backup version with a new one at the new site. To move a copy of the ReadOnly version of a volume from one site to another, you actually remove it from the current site (following the instructions in Removing Volumes and their Mount Points) and then release a new clone of the ReadWrite source volume to the newly defined ReadOnly site (following the instructions in Creating and Releasing ReadOnly Volumes (Replication)).
| Note: | You cannot move a ReadWrite volume to a partition if that partition does not
have enough space to house that volume. The vos move command
warns you if a partition does not have enough space to contain a volume using
the following message:
vos: no space on target partition dest_part to move volume volume |
% bos listusers <machine name>
% vos move <volume name or ID> \
<machine name on source> <partition name on source> \
<machine name on destination> <partition name on destination>
where
| Note: | Unless you have a very good reason for doing so, do not interrupt a vos move command in progress. For more information, see the command's reference page in the AFS Command Reference Manual. |
% vos listvldb <volume name or ID>
% vos backup <volume name or ID>
AFS provides transparent file access to its users because the VLDB constantly tracks volume locations. Whenever the Cache Manager needs a file, it contacts the VL Server in order to learn the current location of the volume containing the file. Therefore, the VLDB must accurately reflect the state of volumes on the file server machines as much as possible.
To keep the VLDB accurate, all vos commands that affect volume status automatically record the change in the appropriate VLDB entry. Whenever you issue a command that changes volume status, the Volume Server and VL Server follow the steps listed in Keeping the VLDB and Volume Headers Synchronized.
Several symptoms and situations can alert you that a vos operation did not complete normally, with the probable result that the VLDB is out of sync with volumes on the servers. The symptoms and situations include:
If a vos operation fails while flags are being set or removed (corresponding to Step 1, Step 2, and Step 4 in Keeping the VLDB and Volume Headers Synchronized), then a discrepancy between VLDB and volumes can result. You can resynchronize the VLDB and volumes by using the vos syncvldb and vos syncserv commands.
If a vos operation fails while the Volume Server is actually manipulating the volume (corresponding to Step 3 in Keeping the VLDB and Volume Headers Synchronized), then it is not enough to just synchronize the VLDB and the volume headers: the volume is possibly corrupted (left in an intermediate state). You must run the Salvager before attempting to resynchronize the VLDB and volume headers. For instructions, see Salvaging Volumes.
This command examines the volume header of each on-line volume on the file server machine (or, a single partition on the machine) that you specify. It looks at the VLDB entry that references that volume, to check that the VLDB properly records the volume's actual status at the site. If the VLDB is incorrect, this command alters it. It can even create VLDB entries if there is no entry for an on-line volume. The command has two other effects:
This command examines every VLDB entry that mentions a site on the file server machine (and optionally, partition) that you specify. It verifies that the VLDB information is correct compared to the state of the volume at the site. There are several kinds of discrepancies it can solve:
| Note: | For best results, run both of these commands on every file server machine, in the order specified in the following instructions. If you do not, you cannot be sure that the entire VLDB accurately reflects the state of volumes on every file server machine. However, it is possible to run one command without the other, and to run them on selected machines or partitions only. |
If the only problem with a volume is that its VLDB entry is locked, it is probably not necessary to resynchronize an entire partition. Use the vos unlock or vos unlockvldb command instead. For more information on these commands, see Unlocking and Locking VLDB Entries.
% bos listusers <machine name>
| Note: | For best results, repeat this command on every file server machine in your cell, before Step 3. |
% vos syncvldb <machine name> [<partition name>] [-v >> file]
where
| Note: | For best results, repeat this command on every file server machine in your cell, after Step 2. |
% vos syncserv <machine name> [<partition name>] [-v >> file]
where
If the command interpreter cannot access a server machine, it generates the following message and continues trying to contact the other file server machines.
Transaction call time out for server 'server_name'
A failure or interruption during certain stages of a volume operation can corrupt the data in volumes actually corrupted, rather than just creating a discrepancy between the information in the VLDB and volume headers. If the Volume Server or File Server exits unexpectedly while manipulating data, the data is sometimes left in an intermediate state. 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.
Normally, the BOS Server automatically invokes the Salvager component whenever the Volume Server or File Server fails. 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 manually.
Possible cause: 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.
Salvager's solution: Remove the file's entry from the directory structure.
Possible cause: 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 possibly try to write yet more data there. When they cannot perform the write, they data is lost. This effect can cascade, causing loss all data on a partition.
Salvager's solution: Delete data from the corrupted disk blocks in preference to losing an entire partition.