doc/man-pages/pod1/vos_examine.pod

   1 =head1 NAME
   2
   3 vos_examine - Shows volume header and VLDB entry information for a volume
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<vos examine> S<<< B<-id> <I<volume name or ID>> >>> [B<-extended>]
  11     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>] [B<-verbose>]
  12     [B<-help>]
  13
  14 B<vos e> S<<< B<-i> <I<volume name or ID>> >>> [B<-e>] S<<< [B<-c> <I<cell name>>] >>>
  15     [B<-n>] [B<-l>] [B<-v>] [B<-h>]
  16
  17 B<vos volinfo> S<<< B<-i> <I<volume name or ID>> >>> [B<-e>] [-c <I<cell name>>]
  18     [B<-n>] [B<-l>] [B<-v>] [B<-h>]
  19
  20 B<vos v> S<<< B<-i> <I<volume name or ID>> >>> [B<-e>] S<<< [B<-c> <I<cell name>>] >>>
  21     [B<-n>] [B<-l>] [B<-v>] [B<-h>]
  22
  23 =for html
  24 </div>
  25
  26 =head1 DESCRIPTION
  27
  28 The B<vos examine> command formats and displays information from the
  29 Volume Location Database (VLDB) entry and the volume header of the volume
  30 specified by the B<-id> argument.
  31
  32 To display the volume header only, use the B<vos listvol> command. To
  33 display information from the VLDB only, use the B<vos listvldb> command.
  34
  35 =head1 CAUTIONS
  36
  37 Currently, the maximum size of a volume is 2 terabytes (2^31 bytes).
  38
  39 =head1 OPTIONS
  40
  41 =over 4
  42
  43 =item B<-id> <I<volume name or ID>>
  44
  45 Specifies either the complete name or volume ID number of the volume,
  46 which can be read/write, read-only, or backup.
  47
  48 =item B<-extended>
  49
  50 Display statistics about read and write operations on files and
  51 directories in the volume.
  52
  53 =item B<-cell> <I<cell name>>
  54
  55 Names the cell in which to run the command. Do not combine this argument
  56 with the B<-localauth> flag. For more details, see L<vos(1)>.
  57
  58 =item B<-noauth>
  59
  60 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
  61 combine this flag with the B<-localauth> flag. For more details, see
  62 L<vos(1)>.
  63
  64 =item B<-localauth>
  65
  66 Constructs a server ticket using a key from the local
  67 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
  68 to the Volume Server and Volume Location Server during mutual
  69 authentication. Do not combine this flag with the B<-cell> argument or
  70 B<-noauth> flag. For more details, see L<vos(1)>.
  71
  72 =item B<-verbose>
  73
  74 Produces on the standard output stream a detailed trace of the command's
  75 execution. If this argument is omitted, only warnings and error messages
  76 appear.
  77
  78 =item B<-help>
  79
  80 Prints the online help for this command. All other valid options are
  81 ignored.
  82
  83 =back
  84
  85 =head1 OUTPUT
  86
  87 The first seven lines of the output show information from the volume
  88 header and the remaining lines come from the VLDB. Each item in the
  89 following list corresponds to a line of output derived from the volume
  90 header.
  91
  92 =over 4
  93
  94 =item *
  95
  96 Basic information about the specified volume (displayed on a single
  97 line):
  98
  99 =over 4
 100
 101 =item *
 102
 103 Name
 104
 105 =item *
 106
 107 Volume ID number
 108
 109 =item *
 110
 111 Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
 112 backup)
 113
 114 =item *
 115
 116 Size in kilobytes (C<1024> equals a megabyte)
 117
 118 =item *
 119
 120 Number of files in the volume, if the B<-extended> flag is provided
 121
 122 =item *
 123
 124 Status on the file server machine, which is one of the following:
 125
 126 =over 4
 127
 128 =item On-line
 129
 130 The volume is completely accessible to Cache Managers.
 131
 132 =item Off-line
 133
 134 The volume is not accessible to Cache Managers, but does not seem to be
 135 corrupted. This status appears while a volume is being dumped, for
 136 example.
 137
 138 =item Off-line**needs salvage**
 139
 140 The volume is not accessible to Cache Managers, because it seems to be
 141 corrupted. Use the B<bos salvage> or B<salvager> command to repair the
 142 corruption.
 143
 144 =back
 145
 146 =back
 147
 148 =item *
 149
 150 The file server machine and partition that house the volume, as determined
 151 by the command interpreter as the command runs, rather than derived from
 152 the VLDB or the volume header.
 153
 154 =item *
 155
 156 The volume ID numbers associated with the various versions of the volume:
 157 read/write (C<RWrite>), read-only (C<ROnly>), backup (C<Backup>), and
 158 ReleaseClone (C<RClone>). One of them matches the volume ID number that
 159 appears on the first line of the volume's output. If the value in the
 160 C<RWrite>, C<ROnly>, or C<Backup> field is C<0> (zero), there is no volume
 161 of that type. If there is currently no ReleaseClone, the C<RClone> field
 162 does not appear at all.
 163
 164 =item *
 165
 166 The maximum space quota allotted to the read/write copy of the volume,
 167 expressed in kilobyte blocks in the C<MaxQuota> field.
 168
 169 =item *
 170
 171 The date and time the volume was created, in the C<Creation> field. If the
 172 volume has been restored with the B<backup diskrestore>, B<backup
 173 volrestore>, or B<vos restore> command, this is the restore time.
 174
 175 =item *
 176
 177 The date and time when the contents of the volume last changed, in the
 178 C<Last Update> field. For read-only and backup volumes, it matches the
 179 timestamp in the C<Creation> field.
 180
 181 =item *
 182
 183 The number of times the volume has been accessed for a fetch or store
 184 operation since the later of the two following times:
 185
 186 =over 4
 187
 188 =item *
 189
 190 12:00 a.m. on the day the command is issued
 191
 192 =item *
 193
 194 The last time the volume changed location
 195
 196 =back
 197
 198 =back
 199
 200 When the B<-extended> flag is included, two tables appear next:
 201
 202 =over 4
 203
 204 =item *
 205
 206 The table labeled C<Raw Read/Write Stats> contains information on the
 207 number of reads (fetches) and writes (stores) made on the specified
 208 volume.
 209
 210 =item *
 211
 212 The table labeled C<Writes Affecting Authorship> contains information on
 213 writes made to files and directories in the specified volume.
 214
 215 =back
 216
 217 If the following message appears instead of the previously listed
 218 information, it indicates that a volume is not accessible to Cache
 219 Managers or the B<vos> command interpreter, for example because a clone is
 220 being created.
 221
 222    **** Volume <volume_ID> is busy ****
 223
 224 If the following message appears instead of the previously listed
 225 information, it indicates that the File Server is unable to attach the
 226 volume, perhaps because it is seriously corrupted. The F<FileLog> and
 227 F<VolserLog> log files in the F</usr/afs/logs> directory on the file
 228 server machine possibly provide additional information; use the B<bos
 229 getlog> command to display them.
 230
 231    **** Could not attach volume <volume_ID> ****
 232
 233 Following a blank line, information from the VLDB entry appears.  Each
 234 item in this list corresponds to a separate line in the output:
 235
 236 =over 4
 237
 238 =item *
 239
 240 The base (read/write) volume name. The read-only and backup versions have
 241 the same name with a C<.readonly> and C<.backup> extension, respectively.
 242
 243 =item *
 244
 245 The volume ID numbers allocated to the versions of the volume that
 246 actually exist, in fields labeled C<RWrite> for the read/write, C<ROnly>
 247 for the read-only, C<Backup> for the backup, and C<RClone> for the
 248 ReleaseClone. (If a field does not appear, the corresponding version of
 249 the volume does not exist.) The appearance of the C<RClone> field normally
 250 indicates that a release operation did not complete successfully; the
 251 C<Old release> and C<New release> flags often also appear on one or more
 252 of the site definition lines described just following.
 253
 254 =item *
 255
 256 The number of sites that house a read/write or read-only copy of the
 257 volume, following the string C<< number of sites -> >>.
 258
 259 =item *
 260
 261 A line for each site that houses a read/write or read-only copy of the
 262 volume, specifying the file server machine, partition, and type of volume
 263 (C<RW> for read/write or C<RO> for read-only). If a backup version exists,
 264 it is understood to share the read/write site.  Several flags can appear
 265 with a site definition:
 266
 267 =over 4
 268
 269 =item Not released
 270
 271 Indicates that the vos release command has not been issued since the B<vos
 272 addsite> command was used to define the read-only site.
 273
 274 =item Old release
 275
 276 Indicates that a vos release command did not complete successfully,
 277 leaving the previous, obsolete version of the volume at this site.
 278
 279 =item New release
 280
 281 Indicates that a vos release command did not complete successfully, but
 282 that this site did receive the correct new version of the volume.
 283
 284 =back
 285
 286 =item *
 287
 288 If the VLDB entry is locked, the string C<Volume is currently LOCKED>.
 289
 290 =back
 291
 292 For further discussion of the C<New release> and C<Old release> flags, see
 293 L<vos_release(1)>.
 294
 295 =head1 EXAMPLES
 296
 297 The following example shows output for the ABC Corporation volume called
 298 C<usr> with two read-only replication sites (this volume is mounted at the
 299 F</afs/abc.com/usr> directory). For the sake of illustration, the output
 300 shows the volume as locked.
 301
 302    % vos examine usr
 303    usr                           536870981 RW   3459 K On-line
 304         fs2.abc.com /vicepb
 305         RWrite 5360870981   ROnly 536870982   Backup 536870983
 306         MaxQuota      40000 K
 307         Creation    Mon Jun 12 15:22:06 1989
 308         Last Update Fri Jun 16 09:34:35 1989
 309         5719 accesses in the past day (i.e., vnode references)
 310         RWrite: 5360870981   ROnly: 536870982   Backup: 536870983
 311         number of sites -> 3
 312            server fs1.abc.com partition /vicepa RO Site
 313            server fs3.abc.com partition /vicepa RO Site
 314            server fs2.abc.com partition /vicepb RW Site
 315         Volume is currently LOCKED
 316
 317 The following example shows the output for the volume C<user.terry> using
 318 the B<-extended> flag. The volume has no read-only replication sites.
 319
 320    % vos examine -id user.terry -extended
 321    user.terry         354287190 RW    2302 K used 119 files On-line
 322        fs4.abc.com /vicepc
 323        RWrite 354287190 ROnly          0 Backup 354287192
 324        MaxQuota       5000 K
 325        Creation    Wed Nov 25 17:38:57 1992
 326        Last Update Tue Dec 15 10:46:20 1992
 327        598 accesses in the past day (i.e., vnode references)
 328                          Raw Read/Write Stats
 329              |-------------------------------------------|
 330              |    Same Network     |    Diff Network     |
 331              |----------|----------|----------|----------|
 332              |  Total   |   Auth   |   Total  |   Auth   |
 333              |----------|----------|----------|----------|
 334    Reads     |       55 |       55 |       38 |       38 |
 335    Writes    |       95 |       95 |        0 |        0 |
 336              |-------------------------------------------|
 337                       Writes Affecting Authorship
 338              |-------------------------------------------|
 339              |   File Authorship   | Directory Authorship|
 340              |----------|----------|----------|----------|
 341              |   Same   |   Diff   |    Same  |   Diff   |
 342              |----------|----------|----------|----------|
 343    0-60 sec  |       38 |        0 |       21 |        1 |
 344    1-10 min  |        2 |        0 |        7 |        0 |
 345    10min-1hr |        0 |        0 |        1 |        0 |
 346    1hr-1day  |        1 |        0 |        5 |        1 |
 347    1day-1wk  |        0 |        0 |        0 |        0 |
 348    > 1wk     |        0 |        0 |        0 |        0 |
 349              |-------------------------------------------|
 350        RWrite: 354287190    Backup: 354287192
 351        number of sites -> 1
 352           server fs4.abc.com partition /vicepc RW Site
 353
 354 =head1 PRIVILEGE REQUIRED
 355
 356 None
 357
 358 =head1 SEE ALSO
 359
 360 L<backup_diskrestore(8)>,
 361 L<backup_volrestore(8)>,
 362 L<bos_getlog(8)>,
 363 L<bos_salvage(8)>,
 364 L<salvager(8)>,
 365 L<vos(1)>,
 366 L<vos_listvol(1)>,
 367 L<vos_listvldb(1)>,
 368 L<vos_release(1)>,
 369 L<vos_restore(1)>
 370
 371 =head1 COPYRIGHT
 372
 373 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 374
 375 This documentation is covered by the IBM Public License Version 1.0.  It was
 376 converted from HTML to POD by software written by Chas Williams and Russ
 377 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.