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