doc/man-pages/pod1/vos_examine.pod.in

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