Displaying Information About Volumes

Displaying Information About Volumes
	Chapter 5. Managing 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

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

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

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

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

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

Note

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

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


Mounting Volumes		Moving Volumes