# Managing Volumes

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.

## Summary of Instructions

This chapter explains how to perform the following tasks by using the indicated commands:

Create read/write volume | vos create
Create read-only volume | vos addsite and vos release
Create 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
Display volume's name | fs listquota or fs examine
Display volume's ID number | fs examine or vos examine or vos listvol
Display partition's size and space available | vos partinfo
Display volume's location | fs whereis or vos examine
Create mount point | fs mkmount
Remove mount point | fs rmmount
Display mount point | fs lsmount
Move read/write volume | vos move
Synchronize VLDB with volume headers | vos syncvldb and vos syncserv
Set volume quota | fs setvol or fs setquota
Display volume quota | fs quota or fs listquota or fs examine
Display volume's current size | fs listquota or fs examine
Display list of volumes on a machine/partition | vos listvol
Remove read/write volume | vos remove and fs rmmount
Remove read-only volume | vos remove
Remove backup volume | vos remove and fs rmmount
Remove volume; no VLDB change | vos zap
Remove read-only site definition | vos remsite
Remove VLDB entry; no volume change | vos delentry
Dump volume | vos dump
Restore dumped volume | vos restore
Rename volume | vos rename, fs rmmount and fs mkmount
Unlock volume | vos unlock
Unlock multiple volumes | vos unlockvldb
Lock volume | vos lock

## About Volumes

An AFS volume 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 mount point, 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 About Mounting Volumes.

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 How Volumes Improve AFS Efficiency.

### The Three Types of Volumes

There are three types of volumes in AFS, as described in the following list:

- The single read/write version of a volume houses the modifiable versions of the files and directories in that volume. It is often referred to as the read/write source because volumes of the other two types are derived from it by a copying procedure called cloning. For instructions on creating read/write volumes, see Creating Read/write Volumes.

- A read-only volume is a copy of the read/write source volume and can exist at multiple sites (a site is a particular partition on a particular file server machine). Placing the same data at more than one site is called replication; see How Volumes Improve AFS Efficiency. 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 vos release 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 .readonly extension to the read/write source's name. For instructions on creating of read-only volumes, see Replicating Volumes (Creating Read-only Volumes).

- A backup 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 How Volumes Improve AFS Efficiency). A backup volume's name is derived by adding the .backup extension to the read/write source's name. For instructions on creating of backup volumes, see Creating Backup Volumes.

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

### How Volumes Improve AFS Efficiency

Volumes make your cell easier to manage and more efficient in the following three ways:

- 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 Moving Volumes.

- Volumes are the unit of replication in AFS. Replication 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 Replicating Volumes (Creating Read-only Volumes).

- 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 Creating Backup Volumes.

  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 Configuring the AFS Backup Systemand Backing Up and Restoring AFS Data.

### Volume Information in the VLDB

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.

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.

To display the VLDB entry for one or more volumes, use the vos listvldb command as described in To display VLDB entries. To display the VLDB entry for a single volume along with its volume header, use the vos examine command as described in To display one volume's VLDB entry and volume header. (See the following section for a description of the volume header.)

### The Information in Volume Headers

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.

To display the volume headers on one or more partitions, use the vos listvol command as described in To display volume headers. To display the VLDB entry for a single volume along with its volume header, use the vos examine command as described in To display one volume's VLDB entry and volume header.

### Keeping the VLDB and Volume Headers Synchronized

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 vos 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 vos operation halts prematurely. For instructions on resynchronizing them, see Synchronizing the VLDB and Volume Headers.

### About Mounting Volumes

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 mount point. 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.

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 /afs directory) and continuing to the file. When the Cache Manager encounters (or crosses) 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 root directory. 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.

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.

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

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.

### About Volume Names

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

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 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. For a list of other naming conventions, see Creating Volumes to Simplify Administration.

## Creating Read/write Volumes

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 vos create 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 fs mkmount command to mount the volume, and matches the mount point name. The following is also recorded in the volume header:

- An initial ACL associated with the volume's root directory. By default it grants all seven AFS access permissions to the system:administrators group. After you mount the volume, you can use the fs setacl command to add other entries and to remove or change the entry for the system:administrators group. See Setting ACL Entries.

- 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 -maxquota argument to the vos create command to set a different quota.

  To change the quota after creation, use the fs setquota command as described in Setting and Displaying Volume Quota and Current Size.

### To create (and mount) a read/write volume

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Verify that you have the a( administer), i( insert), and l( lookup) permissions on the ACL of the directory where you plan to mount the volume. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

3. 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 vos partinfo command.

   The partition-related statistics in this command's output do not always agree with the corresponding values in the output of the standard UNIX df 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 df 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.

          % vos partinfo <machine name> [<partition name>]

   where

   p

     Is the shortest acceptable abbreviation of partinfo.

   machine name

     Specifies the file server machine for which to display partition size and usage.

   partition name

     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.

4. Select a volume name, taking note of the information in About Volume Names.

5. Issue the vos create command to create the volume.

          % vos create <machine name> <partition name> <volume name> \
               [-maxquota <initial quota (KB)>]

   where

   cr

     Is the shortest acceptable abbreviation of create.

   machine name

     Specifies the file server machine on which to place the volume.

   partition name

     Specifies the disk partition on which to place the volume.

   volume name

     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 user and using the period to separate parts of the name.

   -maxquota

     Sets the volume's quota, as a number of kilobyte blocks. If you omit this argument, the quota is set to 5000 kilobyte blocks.

6. (Optional) Issue the fs mkmount command to mount the volume in the filespace. For complete syntax, see To create a regular or read/write mount point.

          % fs mkmount <directory> <volume name>

7. (Optional) Issue the fs lsmount command to verify that the mount point refers to the correct volume. Complete instructions appear in To display a mount point.

          % fs lsmount <directory>

8. (Optional) Issue the fs setvol command with the -offlinemsg 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 fs examine command.

          % fs setvol <dir/file path> -offlinemsg  <offline message>

   where

   sv

     Is an acceptable alias for setvol(and setv the shortest acceptable abbreviation).

   dir/file path

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

     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, /afs/.example.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.

   -offlinemsg

     Specifies up to 128 characters of auxiliary information to record in the volume header.

## About Clones and Cloning

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

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 vnode index. 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:

- A read-only volume that occupies the same partition as its read/write source (also known as a read-only clone), 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 Figure 1. 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.

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

### File Sharing Between the Read/write Source and a Clone Volume

## Replicating Volumes (Creating Read-only Volumes)

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

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

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 vos release 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.

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 (`New release` and `Old release`) 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 `Old release` flag, which potentially imposes a greater load on the sites marked with the `New release` flag. It is important to investigate and eliminate the cause of the failure and then to issue the vos release command as many times as necessary to complete the release without errors.

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 vos examine or vos listvldb command to display the VLDB entry. The VL Server sets the flags in concert with the Volume Server's operations, as follows:

1. Before the operation begins, the VL Server sets the `New release` flag on the read/write site definition in the VLDB entry and the `Old release` 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 `Not released`).

2. If necessary, the Volume Server creates a temporary copy (a clone) 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 `RClone` field of the source volume's VLDB entry.

3. 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 `New release`.

4. When all the read-only copies are successfully released, the VL Server clears all the `New release` 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.

By default, the Volume Server determines automatically whether or not it needs to create a new ReleaseClone:

- If there are no flags (`New release`, `Old release`, or `Not released`) on site definitions in the VLDB entry, the previous vos release command completed successfully and all read-only sites currently have the same volume. The Volume Server infers that the current vos release 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.

- 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 `Old release` or `Not released` flag. As previously noted, the VL Server marks each VLDB site definition with the `New release` flag as the site receives the ReleaseClone, and clears all flags after all sites successfully receive it.

To override the default behavior, forcing the Volume Server to create and release a new ReleaseClone to the read-only sites, include the -f 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.

### Using Read-only Volumes Effectively

For maximum effectiveness, replicate only volumes that satisfy two criteria:

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

- 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 vos release command to update the read-only volumes. This can become tedious (and easy to forget) if the read/write volume changes frequently.

Explicitly mounting a read-only volume (creating a mount point that names a volume with a .readonly 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 The Rules of Mount Point Traversal, 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 .readonly or .backup 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.

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 About Clones and Cloning). 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.

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 OpenAFS Release Notes. 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.

### Replication Scenarios

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:

- If you are releasing a new clone to sites that already exist, you can skip Step 2. It can still be useful to issue the vos examine command, however, to verify that the desired read-only sites are defined.

- If you are adding new read-only sites to existing ones, perform all of the steps. In Step 3, issue the vos addsite command for the new sites only.

- If you are defining sites but do not want to release a clone to them yet, stop after Step 3and continue when you are ready.

- If you are removing one or more sites before releasing a new clone to the remaining sites, follow the instructions for site removal in Removing Volumes and their Mount Pointsand then start with Step 4.

### To replicate a read/write volume (create a read-only volume)

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Select one or more sites at which to replicate the volume. There are several factors to consider:

   - 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 vos examine command, which is described fully in Displaying One Volume's VLDB Entry and Volume Header.

            % vos examine <volume name or ID>

     The final lines of output display the volume's site definitions from the VLDB.

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

   - 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 vos examine command displays the read/write volume's current size in kilobyte blocks, as shown in Displaying One Volume's VLDB Entry and Volume Header.

     To display the amount of space available on a file server machine's partitions, use the vos partinfo command, which is described fully in Creating Read/write Volumes.

            % vos partinfo <machine name> [<partition name>]

3. Issue the vos addsite command to define each new read-only site in the VLDB.

          % vos addsite <machine name> <partition name> <volume name or ID>

   where

   ad

     Is the shortest acceptable abbreviation of addsite.

   machine name

     Defines the file server machine for the new site.

   partition name

     Names a disk partition on the machine machine name.

   volume name or ID

     Identifies the read/write volume to be replicated, either by its complete name or its volume ID number.

4. (Optional) Verify that the fs 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 vlserver 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 bos status 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 Displaying Process Status and Information from the BosConfig File.

          % bos status <machine name> fs vlserver

5. Issue the vos release command to clone the read/write source volume and distribute the clone to each read-only site.

          % vos release <volume name or ID> [-f]

   where

   rel

     Is the shortest acceptable abbreviation of release.

   volume name or ID

     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 .readonly extension. All read-only copies share the same read-only volume ID number.

   -f

     Creates and releases a brand new clone.

6. (Optional) Issue the vos examine command to verify that no site definition in the VLDB entry is marked with an `Old release` or `New release` flag. The command is described fully in Displaying One Volume's VLDB Entry and Volume Header.

          % vos examine <volume name or ID>

If any flags appear in the output from Step 6, repeat Steps 4and 5until the Volume Server does not produce any error messages during the release operation and the flags no longer appear. Do not issue the vos release command when you know that the read/write site or any read-only site is inaccessible due to network, machine or server process outage.

## Creating Backup Volumes

A backup volume is a clone that resides at the same site as its read/write source (to review the concept of cloning, see About Clones and Cloning). Creating a backup version of a volume has two purposes:

- 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 Backing Up Data.

- 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 Making the Contents of Backup Volumes Available to Users.

### Backing Up Multiple Volumes at Once

The vos backupsys 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.

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 -server and -partition arguments) or presence in the volume name of one of a set of specified character strings (the -prefix, -exclude, and -xprefix options).

To clone only volumes that reside on one file server machine, include the -server argument. To clone only volumes that reside on one partition, combine the -server and -partition arguments. The -partition 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.

Combine the -prefix, -exclude, and -xprefix options (with or without the -server and -partition arguments) in the indicated ways to select volumes based on character strings contained in their names:

- 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 user. or includes the string afs), use the -prefix argument or combine the -xprefix and -exclude options.

- 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 -xprefix argument or combine the -prefix and -exclude options.

- 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 -prefix and -xprefix arguments. The command creates a list of all volumes that match the -prefix argument and then removes from the list the volumes that match the -xprefix argument. For effective results, the strings specified by the -xprefix argument must designate a subset of the volumes specified by the -prefix argument.

  If the -exclude flag is combined with the -prefix and -xprefix arguments, the command creates a list of all volumes that do not match the -prefix argument and then adds to the list any volumes that match the -xprefix argument. As when the -exclude flag is not used, the result is effective only if the strings specified by the -xprefix argument designate a subset of the volumes specified by the -prefix argument.

The -prefix and -xprefix arguments both accept multiple values, which can be used to define disjoint groups of volumes. Each value can be one of two types:

1. 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).

2. A regular expression, which matches volumes whose names contain the expressions. Place a caret ( ^) at the beginning of the expression, and enclose the entire string in single quotes ( ' '). Explaining regular expressions is outside the scope of this reference page; see the UNIX manual page for regexp(5) or (for a brief introduction) Defining and Displaying Volume Sets and Volume Entries. As an example, the following expression matches volumes that have the string aix anywhere in their names:

         -prefix '^.*aix'

To display a list of the volumes to be cloned, without actually cloning them, include the -dryrun flag. To display a statement that summarizes the criteria being used to select volume, include the -verbose flag.

To back up a single volume, use the vos backup command, which employs a more streamlined technique for finding a single volume.

### Automating Creation of Backup Volumes

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.

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 a file server machine, which eliminates the need for an administrator to initiate the backup operation.

The following example command creates a cron process called backupusers in the /usr/afs/local/BosConfig file on the machine fs3.example.com. 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 user. The -localauth flag enables the process to invoke the privileged vos backupsys command while unauthenticated. Note that the -cmd argument specifies a complete pathname for the vos binary, because the PATH environment variable for the BOS Server (running as the local superuser root) generally does not include the path to AFS binaries.

       % bos create fs3.example.com backupusers cron\
      -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" "1:00"

### Making the Contents of Backup Volumes Available to Users

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 OldFiles and Backup. 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.

If you do create and mount backup volumes for your users, inform users of their existence. The OpenAFS User 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 read/write volume quota.

### To create and mount a backup volume

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Verify that you have the insert( i) and administer( a) permissions on the ACL of the directory in which you wish to mount the volume. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

3. Issue the vos backup command to create a backup version of a read/write source volume. The message shown confirms the success of the backup operation.

          % vos backup <volume name or ID> Created backup volume for volume name or ID

   where

   backup

     Must be typed in full.

   volume name or ID

     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 .backup extension. It has its own volume ID number.

4. (Optional) Issue the fs mkmount to mount the backup volume. While this step is optional, Cache Managers cannot access the volume's contents if it is not mounted.

          % fs mkmount <directory> <volume name> .backup

   where

   mk

     Is the shortest acceptable abbreviation of mkmount.

   directory

     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.

   volume name.backup

     Is the full name of the backup volume.

5. (Optional) Issue the fs lsmount command to verify that the mount point refers to the correct volume. Complete instructions appear in To display a mount point.

          % fs lsmount <directory>

### To create multiple backup volumes at once

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Issue the vos backupsys 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 Backing Up Multiple Volumes at Once.

          % vos backupsys [-prefix <common prefix on volume(s)>+] \
               [-server <machine name>] [-partition <partition name>] \
               [-exclude] [-xprefix <negative prefix on volume(s)>+] \
               [-dryrun] [-verbose]

   where

   backups

     Is the shortest acceptable abbreviation of backupsys.

   -prefix

     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 -server, -partition, -exclude, and -xprefix options.

   -server

     Specifies the file server machine housing the volumes to backup. Can be combined with any combination of the -prefix, -partition, -exclude, and -xprefix options.

   -partition

     Specifies the partition housing the volumes you wish to backup. Can be combined with any combination of the -prefix, -server, -exclude, and -xprefix options.

   -exclude

     Indicates that all volumes except those indicated with the -prefix argument are to be backed up. The -prefix argument must be provided along with this one. Can also be combined with any combination of the -prefix, -server, and -partition arguments; or with both the -prefix and -xprefix arguments, but not with the -xprefix argument alone.

   -xprefix

     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 -prefix, -server, and -partition arguments; in addition, it can be combined with both the -prefix and -exclude options, but not with the -exclude flag alone.

   -dryrun

     Displays on the standard output stream a list of the volumes to be cloned, without actually cloning them.

   -verbose

     Displays on the standard output stream a statement that summarizes the criteria being used to select volumes, if combined with the -dryrun flag; otherwise, traces the cloning operation for each volume.

## Mounting Volumes

Mount points make the contents of AFS volumes visible and accessible in the AFS filespace, as described in About Mounting Volumes. 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.

### The Rules of Mount Point Traversal

The Cache Manager observes three basic rules as it traverses the AFS filespace and encounters mount points:

- Rule 1: Access Backup and Read-only Volumes When Specified

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

- Rule 2: Follow the Read-only Path When Possible

  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 read-only path through the filespace, accessing read-only volumes when they are available.

  The Cache Manager starts on the read-only path in the first place because it always accesses a read-only copy of the root.afs volume if it exists; the volume is mounted at the root of a cell's AFS filespace (named /afs by convention). That is, if the root.afs 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 root.afs and root.cell 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 /afs and /afs/cellname directories, respectively.

- Rule 3: Once on a Read/write Path, Stay There

  If a mount point resides in a read/write volume and the volume name does not have a .readonly or a .backup 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 read/write path and cannot switch back to the read-only path unless mount point explicitly names a volume with a .readonly extension. (Cellular mount points are an important exception to this rule, as explained in the following discussion.

### The Three Types of Mount Points

AFS uses three types of mount points, each appropriate for a different purpose because of how the Cache Manager handles them.

- When the Cache Manager crosses a regular mount point, it obeys all three of the mount point traversal rules previously described.

  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").

  To create a regular mount point, use the fs mkmount command as described in To create a regular or read/write mount point.

  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.

- When the Cache Manager crosses a read/write 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 .readonly or .backup 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.

  It is conventional to create only one read/write mount point in a cell's filespace, using it to mount the cell's root.cell volume just below the AFS filespace root (by convention, /afs/.cellname). As indicated, it is conventional to place a period at the start of the read/write mount point's name (for example, /afs/.example.com). The period distinguishes the read/write mount point from the regular mount point for the root.cell 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 ls command unless the -a flag is included, essentially hiding it from regular users who have no use for it.

  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 root.cell volume puts the Cache Manager on a read-only path most of the time.

  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 .readonly or .backup extension.

  To create a read/write mount point, use the -rw flag on the fs mkmount command as described in To create a regular or read/write mount point.

- When the Cache Manager crosses a cellular 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.

  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.

  It is conventional to create cellular mount points only at the second level in a cell's filespace, using them to mount foreign cells' root.cell volumes just below the AFS filespace root (by convention, at /afs/foreign_cellname). 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 /usr/vice/etc/CellServDB file, as described in Maintaining Knowledge of Database Server Machines.

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

  To create a regular cellular mount point, use the -cell argument to specify the cell name, as described in To create a cellular mount point.

To examine a mount point, use the fs lsmount command as described in To display a mount point. The command's output uses distinct notation to identify regular, read/write, and cellular mount points. To remove a mount point, use the fs rmmount command as described in To remove a mount point.

### Creating a mount point in a foreign cell

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 fs mkmount 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 fs mkmount command's -cell argument always specifies the cell in which the volume resides, not the cell in which to create the mount point.

### To display a mount point

1. Issue the fs lsmount command.

          % fs lsmount <directory>

   where

   ls

     Is the shortest acceptable abbreviation of lsmount.

   directory

     Names the mount point to display.

If the specified directory is a mount point, the output is of the following form:

       'directory' is a mount point for volume 'volume name'

For a regular mount point, a number sign (`#`) precedes the volume name string, as in the following example command issued on a client machine in the example.com cell.

       % fs lsmount /afs/example.com/usr/terry
       '/afs/example.com/usr/terry' is a mount point for volume '#user.terry'

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

       % fs lsmount /afs/.example.com
       '/afs/.example.com' is a mount point for volume '%root.cell'

For a cellular mount point, a cell name and colon (`:`) 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 example.com cell.

       % fs lsmount /afs/example.org
       '/afs/example.org' is a mount point for volume '#example.org:root.cell'

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 example.com cell.

       % fs lsmount /afs/example
       '/afs/example' is a symbolic link, leading to a mount point for volume '#root.cell'

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

       'directory' is not a mount point.

If the output is garbled, it is possible that the mount point has become corrupted in the local cache. Use the fs flushmount command as described in To flush one or more mount points. This forces the Cache Manager to refetch the mount point.

### To create a regular or read/write mount point

1. Verify that you have the i( insert) and a( administer) permissions on the ACL of the directory where you are placing the mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

2. Issue the fs mkmount command to create the mount point. Include the -rw flag if creating a read/write mount point.

          % fs mkmount <directory> <volume name> [-rw]

   where

   mk

     Is the shortest acceptable abbreviation for mkmount.

   directory

     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.

     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, /afs/.example.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.

   volume name

     Specifies the volume's full name, including the .backup or .readonly extension for a backup or read-only volume, if appropriate.

   -rw

     Creates a read/write mount point.

### To create a cellular mount point

1. Verify that you have the i( insert) and a( administer) permissions on the ACL of the directory where you are placing the mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

   Substitute your cell's name for cellname.

          % cd /afs/.cellname
          % fs mkmount new_cells root.afs
          % cd new_cells

3. Issue the fs mkmount command with the -cell argument to create a cellular mount point. Repeat the command for each cellular mount point as required.

          % fs mkmount <directory> <volume name> -cell <cell name>

   where

   mk

     Is the shortest acceptable abbreviation for mkmount.

   directory

     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 root.cell volume, the standard value for this argument is the cell's complete Internet domain name.

   volume name

     Specifies the volume's full name, usually root.cell for a cellular mount point.

   -cell

     Specifies the complete Internet domain name of the cell in which the volume resides.

4. If you performed the instructions in Step 2, issue the vos release command to release the new version of the root.afs volume to its read-only sites. (This command requires that you be listed in your cell's /usr/afs/etc/UserList file. If necessary, verify by issuing the bos listusers command, which is fully described in To display the users in the UserList file.)

   Also issue the fs checkvolumes command to force the local Cache Manager to access the new replica of the root.afs volume. If desired, you can also remove the temporary new_cells mount point from the /afs/.cellname directory.

          % vos release root.afs
          % fs checkvolumes
          % cd /afs/.cellname
          % fs rmmount new_cells

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

### To remove a mount point

1. Verify that you have the d( delete) permission on the ACL of the directory from which you are removing the mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

2. Issue the fs rmmount command to remove the mount point. The volume still exists, but its contents are inaccessible if this is the only mount point for it.

          % fs rmmount <directory>

   where

   rm

     Is the shortest acceptable abbreviation of rmmount.

   directory

     Names the mount point to remove. A partial pathname is interpreted relative to the current working directory.

     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, /afs/.example.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.

### To access volumes directly by volume ID

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.

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.

Examples:

- Windows: \\afs\example.com%root.cell - Access a read/write volume directly

- Windows: \\afs\example.com#root.cell - Access a read-only volume directly

- Unix: /afs/.:mount/example.com:root.cell - Access a read/write volume directly

- Unix: /afs/.:mount/example.com:root.cell.readonly - Access a read-only volume directly

- Unix: /afs/.:mount/example.com:root.cell.backup - Access a backup volume directly

## Displaying Information About Volumes

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.

For instructions on displaying a volume's quota, see Setting and Displaying Volume Quota and Current Size.

### Displaying VLDB Entries

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:

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

- 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 -server argument.

- 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 -partition argument.

- To display every VLDB entry that mentions a certain partition on a certain file server machine as the site of a volume, combine the -server and -partition arguments.

- To display a single VLDB entry, specify a volume name or ID number with the -name argument.

- To display the VLDB entry only for volumes with locked VLDB entries, use the -locked flag with any of the site definitions mentioned previously.

### To display VLDB entries

1. Issue the vos listvldb command.

          % vos listvldb [-name <volume name or ID>] [-server <machine name>] \
               [-partition <partition name>] [-locked]

   where

   listvl

     Is the shortest acceptable abbreviation of listvldb.

   -name

     Identifies one volume either by its complete name or volume ID number. Do not combine this argument with the -server or -partition arguments.

   -server

     Specifies a file server machine. Combine this argument with the -partition argument if desired, but not with the -name argument.

   -partition

     Specifies a partition. Combine this argument with the -server argument if desired, but not with the -name argument.

   -locked

     Displays only locked VLDB entries. Combine this flag with any of the other options.

The VLDB entry for each volume includes the following information:

- The base (read/write) volume name. The read-only and backup versions have the same name with a .readonly and .backup extension, respectively.

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

- The number of sites that house a read/write or read-only copy of the volume, following the string `number of sites ->`.

- 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 (`RW` for read/write or `RO` 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:

  `Not released`

    Indicates that the vos release command has not been issued since the vos addsite command was used to define the read-only site.

  `Old release`

    Indicates that a vos release command did not complete successfully, leaving the previous, obsolete version of the volume at this site.

  `New release`

    Indicates that a vos release command did not complete successfully, but that this site did receive the correct new version of the volume.

- If the VLDB entry is locked, the string `Volume is currently LOCKED`.

For further discussion of the `New release` and `Old release` flags, see Replicating Volumes (Creating Read-only Volumes).

An example of this command and its output for a single volume:

       % vos listvldb user.terry
       user.terry
           RWrite: 50489902    Backup: 50489904
           number of sites -> 1
              server fs3.example.com partition /vicepc RW Site

### Displaying Volume Headers

The vos listvol command displays the volume header for every volume on one or all partitions on a file server machine. The vos 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 -fast, the -long, or the -extended flags described following the instructions in To display volume headers.

To display a single volume's volume header of one volume only, use the vos examine command as described in Displaying One Volume's VLDB Entry and Volume Header.

### To display volume headers

1. Issue the vos listvol command.

          % vos listvol <machine name> [<partition name>] [-fast] [-long] [-extended]

   where

   listvo

     Is the shortest acceptable abbreviation of listvol.

   machine name

     Names the file server machine for which to display volume headers. Provide this argument alone or with the partition name argument.

   partition name

     Names one partition on the file server machine named by the machine name argument, which must be provided along with this one.

   -fast

     Displays only the volume ID numbers of relevant volumes. Do not combine this flag with the -long or -extended flag.

   -long

     Displays more detailed information about each volume. Do not combine this flag with the -fast or -extended flag.

   -extended

     Displays all of the information displayed by the -long flag, plus tables of statistics about reads and writes to the files in the volume. Do not combine this flag with the -fast or -long flag.

The output is ordered alphabetically by volume name and by default provides the following information on a single line for each volume:

- Name

- Volume ID number

- Type (the flag is `RW` for read/write, `RO` for read-only, `BK` for backup)

- Size in kilobytes (`1024` equals a megabyte)

- Number of files in the volume, if the -extended flag is provided

- Status on the file server machine, which is one of the following:

  `On-line`

    The volume is completely accessible to Cache Managers.

  `Off-line`

    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.

  `Off-line**needs salvage**`

    The volume is not accessible to Cache Managers, because it seems to be corrupted. Use the bos salvage or salvager command to repair the corruption.

If the following message appears instead of the previously listed information, it indicates that a volume is not accessible to Cache Managers or the vos command interpreter, for example because a clone is being created.

       **** Volume volume_ID is busy ****

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 FileLog and VolserLog log files in the /usr/afs/logs directory on the file server machine possibly provide additional information; use the bos getlog command to display them.

       **** Could not attach volume volume_ID ****

(For instructions on salvaging a corrupted or unattached volume, see Salvaging Volumes.)

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:

       % vos listvol  fs2.example.com /vicepb
       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

Output with the -fast Flag

If you include the -fast 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.

       % vos listvol fs3.example.com /vicepa -f
       Total number of volumes on server fs3.example.com  \
                                           partition /vicepa: 37
       50489902
       50489904
          .
          .
       35970325
       49732810

Output with the -long Flag

When you include the -long 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:

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

- The volume ID numbers associated with the various versions of the volume: read/write (`RWrite`), read-only (`ROnly`), backup (`Backup`), and ReleaseClone (`RClone`). One of them matches the volume ID number that appears on the first line of the volume's output. If the value in the `RWrite`, `ROnly`, or `Backup` field is `0` (zero), there is no volume of that type. If there is currently no ReleaseClone, the `RClone` field does not appear at all.

- The maximum space quota allotted to the read/write copy of the volume, expressed in kilobyte blocks in the `MaxQuota` field.

- The date and time the volume was created, in the `Creation` field. If the volume has been restored with the backup diskrestore, backup volrestore, or vos restore command, this is the restore time.

- The date and time when the contents of the volume last changed, in the `Last Update` field. For read-only and backup volumes, it matches the timestamp in the `Creation` field.

- The number of times the volume has been accessed for a fetch or store operation since the later of the two following times:

  - 12:00 a.m. on the day the command is issued

  - The last time the volume changed location

An example of the output when the -long flag is included:

       % vos listvol fs2.example.com b -long
       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

Output with the -extended Flag

When you include the -extended flag, the output for each volume includes all of the information reported with the -long flag, plus two tables of statistics:

- The table labeled `Raw Read/Write Stats` table summarizes the number of times the volume has been accessed for reading or writing.

- The table labeled `Writes Affecting Authorship` table contains information on writes made to files and directories in the specified volume.

An example of the output when the -extended flag is included:

       % vos listvol fs3.example.com a -extended
       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 |
                 |-------------------------------------------|

### Displaying One Volume's VLDB Entry and Volume Header

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.

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 .readonly or .backup extension on the volume name or ID argument as appropriate. The information from the VLDB is the same for all three versions.

### To display one volume's VLDB entry and volume header

1. Issue the vos examine command.

          % vos examine <volume name or ID>

   where

   e

     Is the shortest acceptable abbreviation of examine.

   volume name or ID

     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 .backup or .readonly extension if appropriate.

The top part of the output displays the same information from a volume header as the vos listvol command with the -long flag, as described following the instructions in To display volume headers. 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 vos listvldb command, as described following the instructions in To display VLDB entries.

Below is an example for a volume whose VLDB entry is currently locked.

       % vos examine user.terry
       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

### Displaying the Name or Location of the Volume that Contains a File

This section explains how to learn the name, volume ID number, or location of the volume that contains a file or directory.

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:

- To use a volume's name to learn the volume ID numbers of all its existing versions, use the vos examine command as described in To display one volume's VLDB entry and volume header.

  You can also use the command to learn a volume's name by providing its ID number.

- To use a volume's name or ID number to learn its location, use the vos listvldb command as described in To display VLDB entries.

#### To display the name of the volume that contains a file

1. Issue the fs listquota command.

          % fs listquota [<dir/file path>]

   where

   lq

     Is an acceptable alias for listquota(and listq the shortest acceptable abbreviation).

   dir/file path

     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.

The following is an example of the output:

       % fs listquota /afs/example.com/usr/terry
       Volume Name     Quota    Used    % Used   Partition
       user.terry      15000    5071       34%         86%

#### To display the ID number of the volume that contains a file

1. Issue the fs examine command.

          % fs examine [<dir/file path>]

   where

   exa

     Is the shortest acceptable abbreviation of examine.

   dir/file path

     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.

The following example illustrates how the output reports the volume ID number in the `vid` field.

       % fs examine /afs/example.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

The partition-related statistics in this command's output do not always agree with the corresponding values in the output of the standard UNIX df 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 df 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.

#### To display the location of the volume that contains a file

1. Issue the fs whereis command to display the name of the file server machine that houses the volume containing a file or directory.

          % fs whereis [<dir/file path>]

   where

   whe

     Is the shortest acceptable abbreviation of whereis.

   dir/file path

     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.

   The output displays the file server machine that houses the volume containing the file, as in the following example:

          % fs whereis /afs/example.com/user/terry
          File /afs/example.com/usr/terry is on host fs2.example.com

2. If you also want to know which partition houses the volume, first issue the fs listquota command to display the volume's name. For complete syntax, see To display the name of the volume that contains a file.

          % fs listquota [<dir/file path>]

   Then issue the vos listvldb command, providing the volume name as the volume name or ID argument. For complete syntax and a description of the output, see To display VLDB entries.

          % vos listvldb <volume name or ID>

## Moving Volumes

There are three main reasons to move volumes:

- To place volumes on other partitions or machines temporarily while repairing or replacing a disk or file server machine.

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

         afs: failed to store file (partition full)

  You can track available space on AFS server partitions by using the scout or afsmonitor programs described in Monitoring and Auditing AFS Performance.

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

To move a read/write volume, use the vos move command as described in the following instructions. Before attempting to move the volume, the vos 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.

       vos: no space on target partition destination_part to move volume volume

To move a read-only volume, you actually remove the volume from the current site by issuing the vos remove command as described in To remove a volume and unmount it. Then define a new site and release the volume to it by issuing the vos addsite and vos release commands as described in To replicate a read/write volume (create a read-only volume).

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 vos move 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 vos backup command as described in To create and mount a backup volume.

### To move a read/write volume

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Issue the vos move command to move the volume. Type it on a single line; it appears on multiple lines here only for legibility.

          % vos move <volume name or ID> \ <machine name on source>
                 <partition name on source > \ <machine name on destination> <partition name on
                 destination>

   where

   m

     Is the shortest acceptable abbreviation of move.

   volume name or ID

     Specifies the name or volume ID number of the read/write volume to move.

   machine name on source

     Names the file server machine currently housing the volume.

   partition name on source

     Names the partition currently housing the volume.

   machine name on destination

     Names the file server machine to which to move the volume.

   partition name on destination

     Names the partition to which to move the volume.

   It is best not to halt a vos move 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 OpenAFS Administration Reference.

3. (Optional) Issue the vos listvldb command to confirm the success of the move. Complete instructions appear in To display VLDB entries.

          % vos listvldb <volume name or ID>

4. If a backup version existed at the read/write volume's previous site, create a new backup at the new site by issuing the vos backup command, which is fully described in To create and mount a backup volume.

          % vos backup <volume name or ID>

## Synchronizing the VLDB and Volume Headers

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 vos operation, by performing the following series of steps.

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

2. The VL Server sets an intention flag 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 Salvaging Volumes.)

3. The Volume Server manipulates the volume. It usually sets the `Off-line` 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 `On-line`.

4. 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 2and releases the lock set in Step 1.

If a vos operation fails while the Volume Server is manipulating the volume (corresponding to Step 3), the volume can be left in an intermediate state, which is termed corruption. In this case, the `Off-line` or `Off-line**needs salvage**` marker usually appears at the end of the first line of output from the vos examine command. To repair the corruption, run the Salvager before attempting to resynchronize the VLDB and volume headers. For salvaging instructions, see Salvaging Volumes.

More commonly, an interruption while flags are being set or removed (corresponding to Step 1, Step 2, or Step 4) causes a discrepancy between the VLDB and volume headers. To resynchronize the VLDB and volumes, use the vos syncvldb and vos syncserv commands. To achieve complete VLDB consistency, it is best to run the vos syncvldb command on all file server machines in the cell, and then run the vos syncserv command on all file server machines in the cell.

There are several symptoms that indicate a volume operation failed:

- 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 Ctrl-c), 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 bos status command as described in Displaying Process Status and Information from the BosConfig File.

- A subsequent vos 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 -locked flag on the vos listvldb command as described in Displaying VLDB Entries.

  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 vos unlock or vos unlockvldb command to unlock the entry, as described in Unlocking and Locking VLDB Entries.

- A subsequent vos 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 vos examine command as described in Displaying One Volume's VLDB Entry and Volume Header.

The vos syncvldb 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.

When checking a single volume's VLDB entry, the command also automatically performs the operations invoked by the vos syncserv 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.

The vos syncserv 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.

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.

### To synchronize the VLDB with volume headers

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Issue the vos syncvldb command to make the VLDB reflect the true state of all volumes on a machine or partition, or the state of one volume.

   To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your cell for the -server argument in turn and omitting the -partition and -volume arguments, before proceeding to Step 3.

          % vos syncvldb -server <machine name> [-partition <partition name>] \
               [-volume <volume name or ID>] [-verbose >> file]

   where

   syncv

     Is the shortest acceptable abbreviation of syncvldb.

   -server

     Names the file server machine housing the volumes for which to verify VLDB entries. If you are also providing the -volume argument, this argument must name the machine where the volume actually resides.

   -partition

     Identifies the partition (on the file server machine specified by the -server 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 -volume argument), or so that you do not need to guarantee that the partition actually houses the volume named by the -volume argument.

   -volume

     Specifies the name or volume ID number of a single volume for which to verify the VLDB entry.

   -verbose >> file

     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.

3. Issue the vos syncserv command to inspect each volume for which the VLDB lists a version at the specified site.

   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.

          % vos syncserv <machine name> [<partition name>] [-v >> file]

   where

   syncs

     Is the shortest acceptable abbreviation of syncserv.

   machine name

     Names the file server machine mentioned in each VLDB entry to check.

   partition name

     Identifies the partition mentioned in each VLDB entry to check. If synchronizing the entire VLDB, omit this argument.

   -v >> file

     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.

## Salvaging Volumes

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 (corrupted), 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.

If an operation halts because the Volume Server or File Server exits unexpectedly, the BOS Server automatically shuts down all components of the fs 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 bos salvage command.

- Symptom: A file appears in the output of the ls command, but attempts to access the file fail with messages indicating that it does not exist.

  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. (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.)

  Salvager's solution: Remove the file's entry from the directory structure.

- Symptom: A volume is marked `Off-line` in the output from the vos examine and vos listvol commands, or attempts to access the volume fail.

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

  Salvager's solution: Delete the data from the corrupted disk blocks in preference to losing an entire partition.

- Symptom: There is less space available on the partition than you expect based on the size statistic reported for each volume by the vos listvol command.

  Possible cause: There are orphaned files and directories. An orphaned 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.

  Salvager's solution: By default, print a message to the /usr/afs/logs/SalvageLog file reporting how many orphans were found and the approximate number of kilobytes they are consuming. You can use the -orphans argument to remove or attach orphaned elements instead. See To salvage volumes.

When you notice symptoms such as these, use the bos salvage command to invoke the Salvager before corruption spreads. (Even though it operates on volumes, the command belongs to the bos 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.)

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.

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:

- If the volume header is corrupted, the Salvager removes the volume completely and records the removal in its log file, /usr/afs/logs/SalvageLog. Issue the vos release or vos backup command to create the read-only or backup volume again.

- 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 vos remove or vos zap command. Then issue the vos release or vos backup command to create it again.

Combine the bos salvage command's arguments as indicated to salvage different numbers of volumes:

- To salvage all volumes on a file server machine, combine the -server argument and the -all flag.

- To salvage all volumes on one partition, combine the -server and -partition arguments.

- To salvage only one read/write volume, combine the -server, -partition, and -volume 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 -volume argument. Instead, remove the volume, using the vos remove or vos zap command. Then create a new copy of the volume with the vos release or vos backup command.

The Salvager always writes a trace to the /usr/afs/logs/SalvageLog 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 bos salvage command), name the file with the -file argument. Or, to display the trace on the standard output stream as it is written to the /usr/afs/logs/SalvageLog file, include the -showlog flag.

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 -parallel argument.

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 all as the value for the -parallel argument. Provide a positive integer to specify the number of subprocesses to run in parallel (for example, -parallel 5all for five subprocesses), or omit the integer to run up to four subprocesses, depending on the number of logical volumes being salvaged.

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 -tmpdir argument to redirect the temporary files to a local disk directory that has enough space.

The -orphans 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.

During the salvage, the output of the bos status command reports the following auxiliary status for the fs process:

       Salvaging file system

### To salvage volumes

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Issue the bos salvage command to salvage one or more volumes.

          % bos salvage  -server <machine name>  [-partition <salvage partition>]  \
                         [-volume <salvage volume number or volume name>]  \
                         [-file salvage log output file]  [-all]  [-showlog]  \
                         [-parallel <# of max parallel partition salvaging>]  \
                         [-tmpdir <directory to place tmp files>]  \
                         [-orphans <ignore | remove | attach >]

   where

   -server

     Names the file server machine on which to salvage volumes. This argument can be combined either with the -all flag, the -partition argument, or both the -partition and -volume arguments.

   -partition

     Names a single partition on which to salvage all volumes. The -server argument must be provided along with this one.

   -volume

     Specifies the name or volume ID number of one read/write volume to salvage. Combine this argument with the -server and -partition arguments.

   -file

     Specifies the complete pathname of a file into which to write a trace of the salvage operation, in addition to the /usr/afs/logs/SalvageLog 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 bos salvage command is issued. If the -volume argument is included, the file can be in AFS, though not in the volume being salvaged. Do not combine this argument with the -showlog flag.

   -all

     Salvages all volumes on all of the partitions on the machine named by the -server argument.

   -showlog

     Displays the trace of the salvage operation on the standard output stream, as well as writing it to the /usr/afs/logs/SalvageLog file.

   -parallel

     Specifies the maximum number of Salvager subprocesses to run in parallel. Provide one of three values:

     - An integer from the range 1 to 32. A value of 1 means that a single Salvager process salvages the partitions sequentially.

     - The string all 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.

     - The string all followed immediately (with no intervening space) by an integer from the range 1 to 32, to run the specified number of Salvager subprocesses in parallel on partitions formatted as logical volumes. Use this value only with such logical volumes.

     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.

   -tmpdir

     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.

   -orphans

     Controls how the Salvager handles orphaned files and directories. Choose one of the following three values:

     ignore

       Leaves the orphaned objects on the disk, but prints a message to the /usr/afs/logs/SalvageLog file reporting how many orphans were found and the approximate number of kilobytes they are consuming. This is the default if you omit the -orphans argument.

     remove

       Removes the orphaned objects, and prints a message to the /usr/afs/logs/SalvageLog file reporting how many orphans were removed and the approximate number of kilobytes they were consuming.

     attach

       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:

       - _ _ORPHANFILE_ _. index for files
       - _ _ORPHANDIR_ _. index for directories

       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 ls command issued against the volume's root directory.

## Setting and Displaying Volume Quota and Current Size

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 fileserver command's -spare or -pctspare argument to change the default overage; see the command's reference page in the OpenAFS Administration Reference.)

To set a quota other than 5000 KB as you create a volume, include the -maxquota argument to the vos create command, as described in Creating Read/write Volumes. To modify an existing volume's quota, issue either the fs setquota or the fs setvol command as described in the following instructions. Do not set an existing volume's quota lower than its current size.

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 OpenAFS Release Notes 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.

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.

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.

### To set quota for a single volume

1. Verify that you belong to the system:administrators group. If necessary, issue the pts membership command, which is fully described in To display the members of the system:administrators group.

          % pts membership system:administrators

2. Issue the fs setquota command to set the volume's maximum quota.

          % fs setquota [<dir/file path>] -max <max quota in kbytes>

   where

   sq

     Is an acceptable alias for setquota.

   dir/file path

     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.

     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, /afs/.example.com). For further discussion of the concept of read/write and read-only paths through the filespace, see The Rules of Mount Point Traversal.

   max quota in kbytes

     Sets the volume's quota, expressed in kilobyte blocks ( 1024 equals a megabyte). A value of 0 grants an unlimited quota, but the size of the partition imposes an absolute limit. You must include the -max switch if omitting the dir/file path argument (to set the quota on the volume that houses the current working directory).

### To set maximum quota on one or more volumes

1. Verify that you belong to the system:administrators group. If necessary, issue the pts membership command, which is fully described in To display the members of the system:administrators group.

          % pts membership system:administrators

2. Issue the fs setvol command to set the quota on one or more volumes.

          % fs setvol [<dir/file path>+] -max <disk space quota in 1K units>

   where

   sv

     Is an acceptable alias for setvol.

   dir/file path

     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.

   disk space quota in 1K units

     Sets the maximum quota on each volume, expressed in kilobytes blocks ( 1024 equals a megabyte). A value of 0 grants an unlimited quota, but the size of the partition does impose an absolute limit.

### To display percent quota used

1. Issue the fs quota command.

          % fs quota [<dir/file path>+]

   where

   q

     Is the shortest acceptable abbreviation of quota.

   dir/file path

     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.

The following example illustrates the output produced by this command:

       % fs quota /afs/example.com/usr/terry
       34% of quota used.

### To display quota, current size, and other information

1. Issue the fs listquota command.

          % fs listquota [<dir/file path>+]

   where

   lq

     Is an alias for listquota.

   dir/file path

     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.

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.

       % fs listquota /afs/example.com/usr/terry
       Volume Name     Quota    Used    % Used   Partition
       user.terry      15000    5071       34%         86%

### To display quota, current size, and more partition information

1. Issue the fs examine command.

          % fs examine [<dir/file path>+]

   where

   exa

     Is the shortest acceptable abbreviation of examine.

   dir/file path

     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.

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.

       % fs examine /afs/example.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

The partition-related statistics in this command's output do not always agree with the corresponding values in the output of the standard UNIX df 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 df 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.

## Removing Volumes and their Mount Points

To remove a volume from its site and its record from the VLDB, use the vos remove command. Use it to remove any of the three types of volumes; the effect depends on the type.

- If you indicate the read/write volume by specifying the volume's base name without a .readonly or .backup 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 -server and -partition 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 vos examine and vos listvldb commands as `number of sites`) decrements by one. The read/write and backup volume ID numbers no longer appear in the output from the vos examine and vos listvldb 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.

  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.

- If you indicate a read-only volume by including the .readonly 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 vos examine and vos listvldb commands as `number of sites` decrements by one for each volume you remove.

  If there is more than one read-only site, you must include the -server argument (and optionally -partition 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.

  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 5of To remove a volume and unmount it.

- If you indicate a backup volume by including the .backup 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 -server and -partition arguments, because there can be only one backup site. The backup volume ID number no longer appears in the output from the vos examine or vos listvldb command, but is preserved internally.

  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.

### Other Removal Commands

The vos remove 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 OpenAFS Administration Reference.

The vos zap 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 vos listvol command displays the volume header but the vos examine or vos listvldb command cannot locate the VLDB entry. You must run this command to correct the discrepancy, because the vos syncvldb and vos syncserv commands never remove volume headers.

The vos remsite 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 vos addsite command to define a read-only site, but have not yet issued the vos release command to release the volume to the site. If you have actually released a volume to the site, use the vos remove command instead.

The vos delentry 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 vos zap command during an emergency), and do not want to take the time to resynchronize the entire VLDB with the vos syncvldb and vos syncserv commands.

### To remove a volume and unmount it

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. If removing the volume's mount point, verify that you have the d( delete) permission on its parent directory's ACL. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

3. (Optional) 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 vos dump command as instructed in Dumping and Restoring Volumes. You can then copy the file to tape using a third-party backup utility or an archiving utility such as the UNIX tar command.

   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 To create a dump.

4. Issue the vos remove command to remove the volume. If removing a read-only volume from multiple sites, repeat the command for each one.

          % vos remove [-server machine name>] [-partition <partition name>] \
                      -id <volume name or ID>

   where

   remo

     Is the shortest acceptable abbreviation of remove.

   -server

     Specifies the file server machine on which the volume resides. It is necessary only when the -id argument names a read-only volume that exists at multiple sites.

   -partition

     Specifies the partition on machine name where the volume resides. It is necessary only when the -id argument names a read-only volume that exists at multiple sites. Provide the -server argument along with this one.

   -id

     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 ( .readonly or .backup).

5. If you are removing the last existing version of the volume, issue the fs rmmount command remove the corresponding mount point. Complete instructions appear in To remove a volume and unmount it.

   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.

          % fs rmmount <directory>

6. (Optional) If you created a dump file in Step 3, transfer it to tape. The preferred method is to use the AFS Backup System, which is described in Configuring the AFS Backup Systemand Backing Up and Restoring AFS Data.

## Dumping and Restoring Volumes

Dumping a volume with the vos dump command converts its contents into ASCII format and writes them to the file you specify. The vos restore command places a dump file's contents into a volume after converting them into the volume format appropriate for the indicated file server machine.

### About Dumping Volumes

Dumping a volume can be useful in several situations, including the following:

- You want to back it up to tape, perhaps by using a third-party backup utility. To facilitate this type of backup operation, the vos dump command can write to a named pipe. To learn about using the AFS Backup System instead, see Configuring the AFS Backup Systemand Backing Up and Restoring AFS Data.

- You are removing the volume from your cell (perhaps because its owner is leaving your cell). The vos dump 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 Removing Volumes and their Mount Points.

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

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

- You want to copy or transfer the contents of the volume to another cell. You cannot use the vos move command, because AFS supports volume moves only between file server machines that belong to the same cell.

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

- You want a copy of only the files and directories in the volume with modification time stamps after a certain date. The vos dump command can create an incremental dump file as described in Step 3of the following instructions.

You can use the vos dump command to create a full dump, which contains the complete contents of the volume at the time you issue the command, or an incremental dump, which contains only those files and directories with modification timestamps (as displayed by the ls -l command) that are later than a date and time you specify. See Step 3of the following instructions.

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 vos backup or vos backupsys command to create a new backup version.

If you do not provide a filename into which to write the dump, the vos dump command directs the output to the standard output stream. You can pipe it directly to the vos restore command if you wish.

Because a volume dump file is in ASCII format, you can read its contents using a text editor or a command such as the cat command. However, dump files sometimes contain special characters that do not have alphanumeric correlates, which can cause problems for some display programs.

By default, the vos command interpreter consults the Volume Location Database (VLDB) to learn the volume's location, so the -server and -partition arguments are not required. If the -id 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 vos examine or vos listvldb command). To dump the read-only volume from a particular site, use the -server and -partition 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 -id argument, along with the -server and -partition arguments. This makes it possible to dump a volume for which there is no VLDB entry.

### To dump a volume

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Verify that you have the permissions necessary to create the dump file. If placing it in AFS, you must have the i( insert) permission on the ACL of the file's directory. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

3. Issue the vos dump command to dump the volume.

          % vos dump -id <volume name or ID> [-time <dump from time>] [-file <arg>] [-server <server>] [-partition <partition>]

   where

   -id

     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 ( .readonly or .backup) to the name.

     To bypass the normal VLDB lookup of the volume's location, provide the volume ID number and combine this argument with the -server and -partition arguments.

   -time

     Specifies whether the dump is full or incremental. Omit this argument to create a full dump, or provide one of three acceptable values:

     - The value 0(zero) to create a full dump.

     - A date in the format mm / dd / 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 1970 to 2037; 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 01/13/1999.

     - A date and time in the format " mm / dd / yyyy hh : MM " 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, 20:30 is 8:30 p.m.). Surround the entire expression with double quotes (" ") because it contains a space. An example is "01/13/1999 22:30".

   -file

     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.

   -server

     Specifies the file server machine on which the volume resides. Provide the -partition argument along with this one.

   -partition

     Specifies the partition on which the volume resides. Provide the -server argument along with this one.

### About Restoring Volumes

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 vos restore 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 vos dump command, you can restore a dump file via a named pipe, which facilitates interoperation with third-party backup utilities.

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.

- You can restore volume data into a brand new volume with a new name and at a location that you specify. See To restore a dump into a new volume and mount it.

  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.

- 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 To restore a dump file, overwriting an existing volume.

  Provide the -overwrite 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 -overwrite argument, the Volume Server generates the following prompt to confirm that you want to overwrite the existing volume with either a full ( f) or incremental ( i) dump:

         Do you want to do a full/incremental restore or abort? [fia](a):

  If you pipe in the dump file via the standard input stream instead of using the -file argument to name it, you must include the -overwrite argument because there is nowhere for the Volume Server to display the prompt in this case.

  You can move the volume to a new site as you overwrite it with a full dump, by using the -server and -partition arguments to specify the new site. You cannot move the volume when restoring an incremental dump.

The vos restore command sets the restored volume's creation date in the volume header to the time of the restore operation, as reported in the `Creation` field in the output from the vos examine and vos listvol commands.

### To restore a dump into a new volume and mount it

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. 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 r( read) permission on the ACL of its directory. You need the i( insert) and a( administer) permissions on the ACL of the directory where you are mounting the new volume. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

3. 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 vos partinfo command, which is described fully in Creating Read/write Volumes.

          % vos partinfo <machine name> [<partition name>]

4. Issue the vos restore 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.

          % vos restore <machine name> <partition name> \
                          <name of volume to be restored> \
                          [-file <dump file>] [-id <volume ID>]

   where

   res

     Is the shortest acceptable abbreviation of restore.

   machine name

     Names the file server machine on which to create the new volume.

   partition name

     Names the partition on which to create the new volume.

   name of volume to be restored

     Names the new read/write volume, which must not already have a VLDB entry. It can be up to 22 characters in length.

   -file

     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.

   -volume

     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.

5. Issue the fs mkmount command to mount the new volume, making its contents accessible. Complete instructions appear in To create a regular or read/write mount point.

          % fs mkmount <directory> <volume name>

6. (Optional) Issue the fs lsmount command to verify that the mount point refers to the correct volume. Complete instructions appear in To display a mount point.

          % fs lsmount <directory>

### To restore a dump file, overwriting an existing volume

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Verify that you have permissions needed to read the dump file. If it resides in AFS, you need the r( read) permission on the ACL of its directory. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

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

          % vos restore <machine name> <partition name>  \
                        <name of volume to be restored>   \
                        [-file <dump file>] [-id <volume ID>]

   where

   res

     Is the shortest acceptable abbreviation of restore.

   machine name

     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 -overwrite argument must be full.

   partition name

     Names the partition where the volume already exists, or the partition to which to move it. In the latter case, the value for the -overwrite argument must be full.

   name of volume to be restored

     Names the read/write volume to overwrite with the contents of the dump file.

   -file

     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 -overwrite argument.

   -overwrite

     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:

     - f or full if restoring a full dump file

     - i or incremental if restoring an incremental dump file. This value is not acceptable if you are moving the volume while restoring it.

     - a to terminate the restore operation

4. If the volume is replicated, issue the vos release command to release the newly restored contents to read-only sites. Complete instructions appear in Replicating Volumes (Creating Read-only Volumes).

          % vos release <volume name or ID>

5. Issue the vos backup command to create a new backup version of the volume. Complete instructions appear in Creating Backup Volumes.

          % vos backup <volume name or ID>

## Renaming Volumes

You can use the vos rename command to rename a volume. For example, it is appropriate to rename a user's home volume if you use the user. username convention for user volume names and you change the username. (For complete instructions for changing usernames, see Changing Usernames.)

The vos rename 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.

### To rename a volume

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Verify that you have the a( administer), d( delete), and i( insert) access permissions for the directory in which you are replacing the volume's mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

          % fs listacl [<dir/file path>]

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

3. Issue the vos rename command to rename the volume.

          % vos rename <old volume name> <new volume name>

   where

   ren

     Is the shortest acceptable abbreviation of rename.

   old volume name

     Is the current name of a read/write volume.

   new volume name

     Is the new name for the volume. It cannot be more than 22 characters in length.

   If there is no Volume Location Database (VLDB) entry for the specified current volume name, the command fails with the following error message:

          vos: Could not find entry for volume old_volume_name.

4. Issue the fs rmmount command to remove the mount point that refers to the volume's old name. Complete instructions appear in To remove a mount point.

          % fs rmmount <directory>

5. Issue the fs mkmount to create a mount point that indicates the volume's new name. Complete instructions appear in To create a regular or read/write mount point.

          % fs mkmount <directory> <volume name> [-rw]

## Unlocking and Locking VLDB Entries

As detailed in Synchronizing the VLDB and Volume Headers, 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.

To verify that a VLDB entry is locked, issue the vos listvldb command as described in To display VLDB entries. The command has a -locked flag that displays locked entries only. If the VLDB entry is locked, the string `Volume is currently LOCKED` appears on the last line of the volume's output.

To lock a VLDB entry yourself, use the vos lock 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.

To unlock a locked VLDB entry, issue the vos unlock command, which unlocks a single VLDB entry, or the vos unlockvldb 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.

### To lock a VLDB entry

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Issue the vos lock to lock the entry.

          % vos lock <volume name or ID>

   where

   lo

     Is the shortest acceptable abbreviation of lock.

   volume name or ID

     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.

### To unlock a single VLDB entry

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Issue the vos unlock command to unlock the entry.

          % vos unlock <volume name or ID>

   where

   unlock

     Must be typed in full.

   volume name or ID

     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.

### To unlock multiple VLDB entries

1. Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

          % bos listusers <machine name>

2. Issue the vos unlockvldb command to unlock the desired entries.

          % vos unlockvldb [<machine name>] [<partition name>]

   where

   unlockv

     Is the shortest acceptable abbreviation of unlockvldb.

   machine name

     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.

   partition name

     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.