3 vos_examine - Shows volume header and VLDB entry information for a volume
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>]
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>]
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>]
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>]
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.
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.
42 =include fragments/volsize-caution.pod
48 =item B<-id> <I<volume name or ID>>
50 Specifies either the complete name or volume ID number of the volume,
51 which can be read/write, read-only, or backup.
55 Displays statistics about read and write operations on files and
56 directories in the volume.
60 Shows information in a format suitable for machine parsing.
62 =item B<-cell> <I<cell name>>
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)>.
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
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)>.
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
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.
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.
102 Prints the online help for this command. All other valid options are
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
118 Basic information about the specified volume (displayed on a single
133 Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
138 Size in kilobytes (C<1024> equals a megabyte)
142 Number of files in the volume, if the B<-extended> flag is provided
146 Status on the file server machine, which is one of the following:
152 The volume is completely accessible to Cache Managers.
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
160 =item Off-line**needs salvage**
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
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.
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.
188 The maximum space quota allotted to the read/write copy of the volume,
189 expressed in kilobyte blocks in the C<MaxQuota> field.
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.
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.
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.
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:
220 12:00 a.m. on the day the command is issued
224 The last time the volume changed location
230 When the B<-extended> flag is included, two tables appear next:
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
242 The table labeled C<Writes Affecting Authorship> contains information on
243 writes made to files and directories in the specified volume.
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
252 **** Volume <volume_ID> is busy ****
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.
261 **** Could not attach volume <volume_ID> ****
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:
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.
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.
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 -> >>.
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:
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.
306 Indicates that a vos release command did not complete successfully,
307 leaving the previous, obsolete version of the volume at this site.
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.
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:
323 =item Volume is locked for a move operation
325 Indicates that the volume was locked due to a B<vos move> or a B<vos
326 convertROtoRW> command.
328 =item Volume is locked for a release operation
330 Indicates that the volume was locked due to a B<vos release> command.
332 =item Volume is locked for a backup operation
334 Indicates that the volume was locked due to a B<vos backup> command.
336 =item Volume is locked for a delete/misc operation
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.
342 =item Volume is locked for a dump/restore operation
344 Indicates that the volume was locked due to a B<vos dump> or B<vos restore>
351 For further discussion of the C<New release> and C<Old release> flags, see
356 The following example shows output for the Example Corporation volume called
357 C<usr> with two read-only replication sites (this volume is mounted at the
358 F</afs/example.com/usr> directory). For the sake of illustration, the output
359 shows the volume as locked.
362 usr 536870981 RW 3459 K On-line
363 fs2.example.com /vicepb
364 RWrite 5360870981 ROnly 536870982 Backup 536870983
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
372 server fs1.example.com partition /vicepa RO Site
373 server fs3.example.com partition /vicepa RO Site
374 server fs2.example.com partition /vicepb RW Site
375 Volume is currently LOCKED
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.
380 % vos examine -id user.terry -extended
381 user.terry 354287190 RW 2302 K used 119 files On-line
382 fs4.example.com /vicepc
383 RWrite 354287190 ROnly 0 Backup 354287192
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)
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
413 server fs4.example.com partition /vicepc RW Site
415 =head1 PRIVILEGE REQUIRED
421 L<backup_diskrestore(8)>,
422 L<backup_volrestore(8)>,
434 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
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.