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