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