vos_examine - Display volume state and location information
vos examine -id <volume name or ID> [-extended] [-format] [-cell <cell name>] [-noauth] [-auth] [-localauth] [-encrypt [<yes|no>]] [-verbose] [-noresolve] [-config <configuration file>] [-help]
The vos examine command (alias vos volinfo) formats and displays state and location information for one or more volumes specified by the -id argument. The location information is obtained from the Location Service. The state information is obtained from the File Server.
To only display the volume state information, use the vos_listvol(1) command. To only display the volume location information use the vos_listloc(1) command.
Currently, the maximum partition size and volume quota is 16 zettabytes (2^74 bytes). Note that tools such as fs_listquota(1) can only report sizes up to 2 terabytes (2^41 bytes) when accessing a volume housed on an IBM AFS or OpenAFS File Server.
Specifies either the complete name or volume ID number of the volume, which can be read/write, read-only, or backup.
Displays extensive statistics about access patterns for the volume. The statistics include the number of reads and writes to files in the volume, and how recently files and directories have been updated by their owners or other users.
Displays information in a format suitable for machine parsing. Each field is separated by a single tab character.
Names the cell in which to run the command. Do not combine this argument with the -localauth flag. For more details, see vos(1).
Assigns the unprivileged identity anonymous to the issuer.
Do not combine this flag with the -localauth flag.
For more details,
see vos(1).
Obtains an authentication token using the server encryption key with the highest key version number in the local /etc/yfs/server/KeyFileExt file. The resulting token never expires and has Super User privileges. Do not combine this flag with the -cell argument or -noauth flag. For more details, see vos(1).
Use the calling user's tokens from the kernel or as obtained using the active Kerberos ticket granting ticket to communicate with the Volume Server and Location Service. This is the default if neither -localauth nor -noauth is given.
Since this option is the default, it is usually not useful for running single command line operations. However, it can be useful when running commands via vos_interactive(1) or vos_source(1), since otherwise it would be impossible to switch from, for example, -localauth back to using regular tokens during a bulk operation.
Produces on the standard output stream a detailed trace of the command's execution. If this argument is omitted, only warnings and error messages appear.
Enables or disables encrytion for the command so that the operation's results are not transmitted across the network in clear text.
Shows all servers as IP addresses instead of the reverse DNS lookup hostname.
-noresolve useful when troubleshooting no such volume and volume moved errors.
Set the location of the configuration file to be used. The default file is /etc/yfs/yfs-client.conf.
Prints the online help for this command. All other valid options are ignored.
The first nine lines of the output display volume state information. This is is followed by volume location information. If -extended is specified the volume statistics will be displayed before the volume location information.
Basic information about the specified volume (displayed on a single line):
Name
Volume ID number
Type (the flag is RW for read/write,
RO for read-only,
BK for backup)
Status on the file server machine, which is one of the following:
The volume is completely accessible to Cache Managers.
The volume is not accessible to Cache Managers, but does not seem to be corrupted. For example, this status appears while a volume is being dumped without cloning.
The volume is not accessible to Cache Managers, because it seems to be corrupted. Use the bos_salvage(8) or salvager(8) command to repair the corruption.
The File Server and partition from which the vos examine command is obtaining the volume state (and statistics) information.
The volume ID numbers associated with the various versions of the volume: read/write (RWrite),
read-only (ROnly),
and backup (Backup).
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 ID number assigned to that type.
If there is a current ReleaseClone,
an additional field,
RClone,
will display the volume ID number of the temporary ReleaseClone volume.
The appearance of the RClone field normally indicates that a release operation is in progress or did not complete successfully.
The MaxQuota field displays the maximum space quota allotted to the read/write copy of the volume,
expressed in kilobyte blocks.
The Used field displays the allocated size,
expressed in kilobyte blocks.
The FileCount field displays the nuumber of files in the volume.
The Creation field displays the date and time the volume was created.
If the volume has been restored with the backup_diskrestore(8),
backup_volrestore(8),
or vos_restore(1) commands,
this is the restore time.
For a read-only volume, this is the last release time. For a backup volume, this is the last backup time.
The Copy field displays the date and time this copy of this volume was created.
This is the time when the volume was created on the File Server and partition from which statistics are obtained.
For read/write volumes, it is the date and time of initial creation if the volume has never been moved or restored, or the date and time of the most recent move or restore operation.
For read-only volumes, it is the date and time of the initial vos_release(1) command that copied the volume data to the File Server and partition.
For backup volumes,
it is the date and time of the initial vos_backupsys(1) command on the specified File Server and partition.
It will match the Creation field.
The copy date is not stored in volume dumps and cannot be restored or migrated to another File Server or partition.
The Backup field displays the date and time the last time a read/write volume had a .backup volume created or updated.
If there is no backup volume the string "Never" will be displayed.
For read-only volumes this field will always display "Never".
For backup volumes this field will match the Creation field.
The Last Access field displays the date and time when the contents of the volume last accessed.
For backup volumes, the date and time will indicate the last access at the time of the most recent "vos backup"|vos_backup(1)> command. This field is not updated.
The Last Update field displays the date and time when the contents of the volume last changed.
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
For backup volumes, this value will always be zero.
When the -extended flag is included, two tables appear next:
The table labeled Raw Read/Write Stats contains information on the number of reads (fetches) and writes (stores) made on the specified volume.
The table labeled Writes Affecting Authorship contains information on writes made to files and directories in the specified volume.
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(1) 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 /var/log/yfs directory on the File Server can provide additional information; use the bos_getlog(8) command to display their contents.
**** Could not attach volume <volume_ID> ****
Following a blank line, location information is displayed. Each item in this list corresponds to a separate line in the output:
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:
Indicates that the vos_release(1) command has not been issued since the vos_addsite(1) command was used to define the read-only site.
Indicates that a vos_release(1) command did not complete successfully, leaving the previous, obsolete version of the volume at this site.
Indicates that a vos_release(1) command did not complete successfully, but that this site did receive the correct new version of the volume.
If the volume is locked, the string Volume is currently LOCKED, as well as one or more of the following strings:
Indicates that the volume was locked due to a vos_move(1) or a vos_convertROtoRW(1) command.
Indicates that the volume was locked due to a vos_release(1) command.
Indicates that the volume was locked due to a vos_backup(1) command.
Indicates that the volume was locked due to a vos_delentry(1), vos_addsite(1), vos_remsite(1), vos_changeloc(1), vos_syncloc(1), vos_syncfs(1), vos_rename(1), or vos_lock(1) command.
Indicates that the volume was locked due to a vos_dump(1) or vos_restore(1) command. command.
For further discussion of the New release and Old release flags, see vos_release(1).
The following example shows output for the volume called usr with two read-only replication sites (this volume is mounted at the /afs/your-cell-name.com/usr directory). For the sake of illustration, the output shows a volume locked for a vos_dump(1) operation.
% vos examine usr
usr 536870981 RW 3459 K On-line
fs2.your-cell-name.com /vicepb
RWrite 5360870981 ROnly 536870982 Backup 536870983
MaxQuota 40000 K
Used 514 K
FileCount 2
Creation Mon Jun 12 15:22:06 1989
Copy 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 ROnly: 536870982 Backup: 536870983
number of sites -> 3
server fs1.your-cell-name.com partition /vicepa RO Site
server fs3.your-cell-name.com partition /vicepa RO Site
server fs2.your-cell-name.com partition /vicepb RW Site
Volume is currently LOCKED for a dump/restore operation
The following example shows the output for the volume user.terry using the -extended flag. The volume has no read-only replication sites.
% vos examine -id user.terry -extended
user.terry 354287190 RW On-line
fs4.your-cell-name.com /vicepc
RWrite 354287190 ROnly 0 Backup 354287192
MaxQuota 5000 K
Used 2302 K
FileCount 119
Creation Wed Nov 25 17:38:57 1992
Copy Wed Nov 25 17:38:57 1992
Last Update Tue Dec 15 10:46:20 1992
598 accesses in the past day (i.e., vnode references)
Raw Read/Write Stats
|----------------------
| Total | Auth |
|----------|----------|
Reads | 55 | 55 |
Writes | 95 | 95 |
|----------------------
Writes Affecting Authorship
|---------------------|
| File |Directory |
|----------|----------|
0-60 sec | 38 | 21 |
1-10 min | 2 | 7 |
10min-1hr | 0 | 1 |
1hr-1day | 1 | 5 |
1day-1wk | 0 | 0 |
> 1wk | 0 | 0 |
|---------------------|
RWrite: 354287190 Backup: 354287192
number of sites -> 1
server fs4.your-cell-name.com partition /vicepc RW Site
None
backup_diskrestore(8), backup_volrestore(8), bos_getlog(8), bos_salvage(8), salvager(8), vos(1), vos_convertROtoRW(1), vos_dump(1), vos_listvol(1), vos_listloc(1), vos_lock(1), vos_release(1), vos_restore(1), vos_unlock(1), vos_unlockall(1)
IBM Corporation 2000. http://www.ibm.com/ All Rights Reserved.
This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)
"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)
The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).
"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).
"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.