NAME

vos_examine - Display volume state and location information

SYNOPSIS

vos examine -id <volume name or ID> [-extended] [-format] [-cell <cell name>] [-noauth] [-auth] [-localauth] [-encrypt [<yes|no>]] [-verbose] [-noresolve] [-config <configuration file>] [-help]

DESCRIPTION

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 command. To only display the volume location information use the vos listloc command.

CAUTIONS

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.

OPTIONS

-id <volume name or ID>

Specifies either the complete name or volume ID number of the volume, which can be read/write, read-only, or backup.

-extended

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.

-format

Displays information in a format suitable for machine parsing. Each field is separated by a single tab character.

-cell <cell name>

Names the cell in which to run the command. Do not combine this argument with the -localauth flag. For more details, see vos.

-noauth

Assigns the unprivileged identity anonymous to the issuer. Do not combine this flag with the -localauth flag. For more details, see vos.

-localauth

Obtains an authentication token using the server encryption key with the highest key version number in the local /etc/yfs/server/KeyFileEx 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.

-auth

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 or vos source, since otherwise it would be impossible to switch from, for example, -localauth back to using regular tokens during a bulk operation.

-verbose

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.

-encrypt [<yes|no>]

Enables or disables encrytion for the command so that the operation's results are not transmitted across the network in clear text.

-noresolve

Shows all servers as IP addresses instead of the reverse DNS lookup hostname. -noresolve useful when troubleshooting no such volume and volume moved errors.

-config <configuration file>

Set the location of the configuration file to be used. The default file is /etc/yfs/yfs-client.conf.

-help

Prints the online help for this command. All other valid options are ignored.

OUTPUT

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.

When the -extended flag is included, two tables appear next:

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 /var/log/yfs directory on the File Server can provide additional information; use the bos getlog 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:

For further discussion of the New release and Old release flags, see vos release.

EXAMPLES

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

PRIVILEGE REQUIRED

None

SEE ALSO

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)

COPYRIGHT

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.

ACKNOWLEDGEMENTS

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